@paneui/cli 0.0.12 → 0.0.14

package/dist/commands/upgrade.js

@@ -0,0 +1,67 @@
+// `pane upgrade <pane-id>` — re-pin a live pane to another version of its
+// template, swapping design + content in place (#267).
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { printJson, fail, failFromError } from "../output.js";
+const KNOWN_FLAGS = ["template-version"];
+const KNOWN_BOOLS = ["force"];
+export const upgradeHelp = `pane upgrade — re-pin a live pane to another template version
+
+Usage:
+  pane upgrade <pane-id> [--template-version <n>] [--force]
+
+Re-points an existing, live pane at a different version of the SAME template
+(POST /v1/panes/:id/upgrade). This swaps the pane's HTML (design) and its
+event/input/record schemas (content contract) in place — the human keeps the
+same URL, no new pane is created. Use it after appending a new template
+version with 'pane template version <id|slug> --template ...'.
+
+Events already on disk are never rewritten — each keeps the template version
+it was authored under, so the prior history still renders.
+
+By default the relay runs a strict schema-compat gate: if the target version's
+schema narrows the pane's current one (a removed collection, a newly-required
+field, a tightened type), the upgrade is refused with a
+'schema_incompatible_upgrade' error whose details.breaks lists what would
+break. Pass --force to apply the upgrade anyway, accepting that events written
+under the old schema may no longer validate.
+
+Note: the re-pin takes effect on the relay immediately and emits a
+'system.template.updated' event, but an already-open pane tab is not
+force-reloaded in v1 — the new version renders the next time the URL is loaded.
+
+Options:
+  --template-version <n>  Target version number. Defaults to the template's
+                          latest version.
+  --force                 Override the strict schema-compat gate (compat=force).
+  --url <url>             Relay base URL (overrides PANE_URL).
+  --api-key <key>         Agent API key (overrides PANE_API_KEY).
+  -h, --help              Show this help.
+
+Output (stdout, JSON):
+  { pane_id, template_version_id, template_version, upgraded, breaks, compat }`;
+export async function runUpgrade(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane upgrade");
+    const paneId = args.positionals[0];
+    if (!paneId)
+        fail("missing <pane-id>", "invalid_args");
+    const opts = {};
+    const versionRaw = args.flags.get("template-version");
+    if (versionRaw !== undefined) {
+        const version = Number(versionRaw);
+        if (!Number.isInteger(version) || version < 1) {
+            fail("--template-version must be a positive integer", "invalid_args");
+        }
+        opts.template_version = version;
+    }
+    if (args.bools.has("force"))
+        opts.compat = "force";
+    const client = makeClient(args);
+    try {
+        const res = await client.upgradePane(paneId, opts);
+        printJson(res);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/index.js

@@ -31,6 +31,7 @@ import { runState, stateHelp } from "./commands/state.js";
 import { runSend, sendHelp } from "./commands/send.js";
 import { runWatch, watchHelp } from "./commands/watch.js";
 import { runDelete, deleteHelp } from "./commands/delete.js";
+import { runUpgrade, upgradeHelp } from "./commands/upgrade.js";
 import { runParticipant, participantHelp } from "./commands/participant.js";
 import { runShare, shareHelp } from "./commands/share.js";
 import { runTemplate, artifactHelp } from "./commands/template.js";
@@ -62,6 +63,9 @@ Pane commands (operate on the core noun — a live UI channel):
   send <id>         Emit an agent event into a pane.
   watch <id>        Stream a pane's events as JSON-lines on stdout.
   delete <id>       Close/delete a pane (DELETE /v1/panes/:id).
+  upgrade <id>      Re-pin a live pane to another version of its template —
+                    swap design + content in place, same URL (--template-version
+                    <n>, --force to override the schema-compat gate).
   participant       Manage participant URLs on an existing pane
     <list|new|revoke> (list | mint a fresh URL | revoke one URL).
   share <id>        Share a pane by identity: invite humans by email
@@ -147,6 +151,8 @@ const BOOLEAN_FLAGS = new Set([
     "link",
     "invite-only",
     "list",
+    // `pane upgrade --force`: override the strict schema-compat gate.
+    "force",
 ]);
 async function main() {
     const rawArgv = process.argv.slice(2);
@@ -182,6 +188,7 @@ async function main() {
         send: sendHelp,
         watch: watchHelp,
         delete: deleteHelp,
+        upgrade: upgradeHelp,
         participant: participantHelp,
         share: shareHelp,
         // Other noun groups.
@@ -236,6 +243,9 @@ async function main() {
         case "delete":
             await runDelete(args);
             break;
+        case "upgrade":
+            await runUpgrade(args);
+            break;
         case "participant":
             await runParticipant(args);
             break;

package/dist/version.js

@@ -8,4 +8,4 @@
 // Keep this in lockstep with packages/cli/package.json's `version` field;
 // they're consulted in different places (here for the runtime header,
 // package.json for npm publish + dependency resolution).
-export const VERSION = "0.0.12";
+export const VERSION = "0.0.14";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paneui/cli",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "Command-line client for the Pane relay: create panes, inspect state, send and watch events.",
   "license": "MIT",
   "type": "module",
@@ -41,7 +41,7 @@
     "test:unit": "vitest run"
   },
   "dependencies": {
-    "@paneui/core": "^0.0.12",
+    "@paneui/core": "^0.0.14",
     "qrcode-terminal": "^0.12.0"
   },
   "devDependencies": {