Migrate an App to the package contract

Move an App saved as module, ui, and styles strings onto the package contract, keep its data and URL, and know what changes for its code.

Apps are packages now: a package.json, a server.js, and optionally a ui.js, a styles.css, and the files they import, saved as one files map. An App saved before packages, as module, ui, and styles strings with an exported manifest, keeps running as it is and still accepts those fields on update. Nothing forces a migration. Migrate when you want npm dependencies, more than one file, or the same contract the docs describe.

A migration is one save: the App’s whole tree as files with migrate_contract: true. The App’s id, URL, data, shares, Routines, Webhooks, secrets, and History stay. Its description comes from package.json from then on, and its connector approvals stay only for the tools package.json declares; see the map below. The App keeps serving its current revision while the package builds, and only a published build switches it over.

Before you start

Read the current source. Over MCP, get_app_source({ app_id }) returns source.module, source.ui, source.styles, and the revision you will send back as expected_revision. Over HTTP, GET /app/<id>/source with the user’s chrm_user_* bearer returns the same fields and an ETag to send as If-Match. From the CLI, charming apps source <id> --out <dir> writes module.js, ui.js, and styles.css to a directory. Keep that copy: an App whose manifest.$schema is not a dated app-manifest URL has no History revision it can return to after migrating, so the copy is its only way back.

Saves on the package contract need a signed-in user’s token and an idempotency key. An App-scoped chrm_app_* token from an anonymous create cannot migrate; pair the user’s account first.

Map the old shape onto files

kv, assets, log, and the imported fetch carry the same semantics and limits as the bindings they replace. Call them inside a route handler, not at module initialization.

Two shapes have no package equivalent. charming:browser/* permission imports that the old capabilities.imports carried for camera, microphone, geolocation, clipboard reading, screen capture, and MIDI need no import at all: Charming finds those calls in ui.js at publish time. device-motion, ambient-light, and storage stay as side-effect imports in ui.js, for example import 'charming:browser/[email protected]'.

A worked migration

Before, as module and ui strings:

// module
export const manifest = {
  $schema: 'https://charm.ing/schema/app-manifest/2026-10-16.json',
  id: 'todo',
  meta: { name: 'Todo' },
  capabilities: { imports: ['charming:storage/[email protected]'] },
};
export const routes = [
  {
    op: 'list',
    method: 'GET',
    annotations: { readOnlyHint: true },
    handler: async (_input, { env }) => (await env.storage.get('todos')) ?? [],
  },
];

// ui
const api = window.charming.api('todo');
const root = document.getElementById('app');
async function render() {
  root.textContent = JSON.stringify(await api.list());
}
render();
window.charming.onStateChange(render);

After, as three files:

{
  "name": "todo",
  "version": "1.0.0",
  "description": "A todo list.",
  "type": "module",
  "dependencies": {},
  "charming": { "name": "Todo" }
}

// server.js
import { kv } from 'charming:storage/[email protected]';

export const routes = [
  {
    op: 'list',
    method: 'GET',
    annotations: { readOnlyHint: true },
    handler: async () => (await kv.get('todos')) ?? [],
  },
];

// ui.js
import { api, onStateChange } from 'charming:ui/[email protected]';

const root = document.getElementById('app');
async function render() {
  root.textContent = JSON.stringify(await api.list());
}
render();
onStateChange(render);

Save the migration

Every path sends the whole tree, migrate_contract: true, the desired-source revision, and a fresh idempotency key.

Over MCP:

update_app({
  app_id: "<uuid>",
  files: { "package.json": "...", "server.js": "...", "ui.js": "..." },
  migrate_contract: true,
  expected_revision: <revision from get_app_source>,
  idempotency_key: "todo-migrate-001"
})

Over HTTP, with the ETag from GET /app/<id>/source:

jq -n --rawfile p package.json --rawfile s server.js --rawfile u ui.js \
  '{files: {"package.json": $p, "server.js": $s, "ui.js": $u}, migrate_contract: true}' \
  | curl -sS -i -X PUT https://charm.ing/app/<id> \
      -H "Authorization: Bearer $TOKEN" -H 'If-Match: "<etag>"' \
      -H 'Content-Type: application/json' \
      -H 'Idempotency-Key: todo-migrate-001' -d @-

From the CLI, after charming auth login:

charming apps update <id> --files ./todo --migrate-contract --dry-run
charming apps update <id> --files ./todo --migrate-contract

The save returns an accepted build (HTTP 202 with buildId and statusUrl; the MCP result carries buildId). Poll get_app_build({ build_id }) or GET /api/v1/app-builds/<buildId> until state is published. The App keeps serving the old revision until then. A failed build names the error kind and, when available, the file, line, and column; the App is unchanged, so fix the file and save again with a fresh key.

A save without migrate_contract: true on an App that is still on the earlier contract is refused with contract_migration_required. A save with module on an App that has already migrated is refused with invalid_request over MCP and app_build_unsupported over HTTP: once migrated, every save is files or path edits.

After the migration

• get_app_source returns the tree as source.files; source.module, source.ui, and source.styles mirror server.js, ui.js, and styles.css.
• Exact edits name a path (server.js, lib/text.js) instead of a bucket.
• History lists the migration as a new revision. Restoring a revision from before it is an explicit recovery action: Charming validates that source under its own contract and publishes it as a fresh revision, so the App goes back to the earlier contract. Only revisions on a dated app-manifest contract can be restored this way; an App on an undated manifest has none, so for it the migration is one-way apart from re-creating it from the copy you kept. Source saves never roll a contract back on their own.
• Copies of the App, including Template copies, carry the package tree.
• charming dev does not run package Apps yet; test through the published URL and charming apps call.

Errors on the way