@paneui/cli 0.0.16 → 0.0.18

package/dist/commands/create.js

@@ -198,7 +198,7 @@ Options:
                       the shell band above the iframe — "who is asking, why".
                       Max 280 chars after trim; a single \\n is allowed for a
                       two-line message; other control chars are rejected. Pass
-                      this whenever the artifact itself doesn't make the
+                      this whenever the pane itself doesn't make the
                       request self-explanatory.
   --input-data <v>    This instance's seed data — a JSON object (file path or
                       inline JSON), validated by the relay against the template

package/dist/commands/demo.js

@@ -34,7 +34,7 @@ export const demoHelp = `pane demo — take the 60-second guided tour
 Usage:
   pane demo [options]
 
-Creates a short-lived pane with the built-in tutorial artifact, opens its URL
+Creates a short-lived pane from the built-in tutorial template, opens its URL
 in your browser (or prints it if none is available), then runs a tiny agent
 loop right here in your terminal that watches the session and reacts to each
 thing you do in the pane. Every event you trigger is echoed to this terminal

package/dist/commands/records.js

@@ -27,6 +27,11 @@ Verbs:
        --data <path|json> [--if-match <version>]
   delete <pane-id> <collection> <record-key>
        [--if-match <version>] [--yes]
+  delete-collection <pane-id> <collection>
+       [--yes]
+       Drop a WHOLE collection — all its records + the collection row.
+       Owner-only. Collection names are immutable (no rename): to "rename",
+       delete the old collection and write under the new name.
   watch  <pane-id>
        [--collection <name>]... [--since-seq <name>=<n>]...
 
@@ -43,7 +48,7 @@ export async function runRecords(args) {
         return;
     }
     if (verb === undefined) {
-        fail("missing verb — pane records <list|get|upsert|update|delete|watch>", "invalid_args");
+        fail("missing verb — pane records <list|get|upsert|update|delete|delete-collection|watch>", "invalid_args");
     }
     const sub = {
         positionals: args.positionals.slice(1),
@@ -64,10 +69,12 @@ export async function runRecords(args) {
             return runUpdate(sub);
         case "delete":
             return runDelete(sub);
+        case "delete-collection":
+            return runDeleteCollection(sub);
         case "watch":
             return runWatch(sub);
         default:
-            fail(`unknown verb '${verb}' — pane records <list|get|upsert|update|delete|watch>`, "invalid_args");
+            fail(`unknown verb '${verb}' — pane records <list|get|upsert|update|delete|delete-collection|watch>`, "invalid_args");
     }
 }
 // ---------------------------------------------------------------------------
@@ -199,6 +206,24 @@ async function runDelete(args) {
     }
 }
 // ---------------------------------------------------------------------------
+// delete-collection — drop a whole collection (all rows + the collection row)
+// ---------------------------------------------------------------------------
+async function runDeleteCollection(args) {
+    assertKnownFlags(args, ["url", "api-key"], ["yes", "help"], "pane records delete-collection");
+    const [paneId, collection] = args.positionals;
+    if (!paneId || !collection) {
+        fail("usage: pane records delete-collection <pane-id> <collection>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        await client.deleteRecordCollection(paneId, collection);
+        printJson({ deleted: true, collection });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
 // watch — stream record deltas as JSON-lines
 // ---------------------------------------------------------------------------
 async function runWatch(args) {

package/dist/commands/template-records.js

@@ -29,6 +29,11 @@ Verbs:
        --data <path|json> [--if-match <version>]
   delete <template-id|slug> <collection> <record-key>
        [--if-match <version>] [--yes]
+  delete-collection <template-id|slug> <collection>
+       [--yes]
+       Drop a WHOLE collection — all its records + the collection row.
+       Owner-only. Collection names are immutable (no rename): to "rename",
+       delete the old collection and write under the new name.
 
 Output (stdout): single JSON object per command.
 Errors on stderr: {"error":{"code","message"}} with non-zero exit.`;
@@ -39,7 +44,7 @@ export async function runTemplateRecords(args) {
         return;
     }
     if (verb === undefined) {
-        fail("missing verb — pane template-records <list|get|upsert|update|delete>", "invalid_args");
+        fail("missing verb — pane template-records <list|get|upsert|update|delete|delete-collection>", "invalid_args");
     }
     const sub = {
         positionals: args.positionals.slice(1),
@@ -60,8 +65,10 @@ export async function runTemplateRecords(args) {
             return runUpdate(sub);
         case "delete":
             return runDelete(sub);
+        case "delete-collection":
+            return runDeleteCollection(sub);
         default:
-            fail(`unknown verb '${verb}' — pane template-records <list|get|upsert|update|delete>`, "invalid_args");
+            fail(`unknown verb '${verb}' — pane template-records <list|get|upsert|update|delete|delete-collection>`, "invalid_args");
     }
 }
 async function runList(args) {
@@ -177,6 +184,21 @@ async function runDelete(args) {
         failFromError(e);
     }
 }
+async function runDeleteCollection(args) {
+    assertKnownFlags(args, ["url", "api-key"], ["yes", "help"], "pane template-records delete-collection");
+    const [templateId, collection] = args.positionals;
+    if (!templateId || !collection) {
+        fail("usage: pane template-records delete-collection <template-id|slug> <collection>", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        await client.deleteTemplateRecordCollection(templateId, collection);
+        printJson({ deleted: true, collection });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
 function parseIntFlag(args, name, defaultValue, bounds = {}) {
     const raw = args.flags.get(name);
     if (raw === undefined)

package/dist/commands/template.js

@@ -24,6 +24,7 @@ const CREATE_FLAGS = [
     "event-schema",
     "input-schema",
     "record-schema",
+    "template-record-schema",
     "icon-emoji",
 ];
 const SET_ICON_FLAGS = ["template-id", "emoji", "image"];
@@ -34,6 +35,7 @@ const VERSION_FLAGS = [
     "event-schema",
     "input-schema",
     "record-schema",
+    "template-record-schema",
 ];
 const UPDATE_FLAGS = ["name", "slug", "description", "tags"];
 const NO_FLAGS = [];
@@ -76,8 +78,9 @@ Subcommands:
                        [--event-schema <path|json>] [--slug <s>]
                        [--description <d>] [--tags <t1,t2>]
                        [--input-schema <path|json>]
-                       [--record-schema <path|json>] [--template-type <t>]
-                       [--icon-emoji <emoji>]
+                       [--record-schema <path|json>]
+                       [--template-record-schema <path|json>]
+                       [--template-type <t>] [--icon-emoji <emoji>]
       Creates a named template. Prints { template_id, slug, version }.
       --icon-emoji sets a single-emoji icon at create time; use 'set-icon'
       with --image to attach an uploaded image icon afterwards.
@@ -85,7 +88,9 @@ Subcommands:
   pane template version <id|slug> --template <path|inline>
                         [--event-schema <path|json>]
                         [--input-schema <path|json>]
-                        [--record-schema <path|json>] [--template-type <t>]
+                        [--record-schema <path|json>]
+                        [--template-record-schema <path|json>]
+                        [--template-type <t>]
       Appends a new immutable version. Prints { template_id, version }.
 
   pane template update <id|slug> [--name <n>] [--slug <s>]
@@ -217,6 +222,17 @@ Options:
                       The relay validates the document and rejects anything
                       malformed at create time. See 'pane skill show' (the
                       "Records" section) for the full grammar.
+  --template-record-schema <v>
+                      JSON Schema 2020-12 document declaring this template's
+                      TEMPLATE-level record collections — a file path, or
+                      inline JSON. Optional; omit for a template with no
+                      template-level collections. Same "x-pane-collections"
+                      grammar as --record-schema, but the collections it
+                      declares are shared across every pane of the template
+                      (one collection per template) instead of per-pane.
+                      Without it, 'pane template-records upsert' is rejected
+                      with "template declares no template-level record
+                      collections" — set this first to bootstrap the feature.
   --icon-emoji <e>    Single-emoji icon for the template (create only).
   --template-type <t> "html-inline" (default) or "html-ref".
   --url <url>         Relay base URL (overrides PANE_URL).
@@ -300,6 +316,32 @@ function resolveRecordSchema(args) {
         fail(e instanceof Error ? e.message : String(e), "invalid_args");
     }
 }
+/**
+ * Resolve the optional --template-record-schema — file path or inline JSON.
+ * Must be an object (a JSON Schema 2020-12 document with an
+ * `x-pane-collections` extension), same grammar as --record-schema, but
+ * declares TEMPLATE-level (shared across all panes of the template) record
+ * collections rather than per-pane ones. Absent → returns `undefined` so the
+ * caller omits `template_record_schema` from the request entirely (template
+ * has no template-level record collections). The relay runs the full shape +
+ * collection validation; this helper only does the obvious "is it an object"
+ * pre-check so a typo surfaces locally.
+ */
+function resolveTemplateRecordSchema(args) {
+    const raw = args.flags.get("template-record-schema");
+    if (raw === undefined)
+        return undefined;
+    try {
+        const v = resolveJson(raw, "--template-record-schema");
+        if (v === null || typeof v !== "object" || Array.isArray(v)) {
+            fail("--template-record-schema must be a JSON object", "invalid_args");
+        }
+        return v;
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e), "invalid_args");
+    }
+}
 /** Parse a comma-separated --tags flag into a string array. */
 function resolveTags(args) {
     const raw = args.flags.get("tags");
@@ -321,6 +363,7 @@ async function runTemplateCreate(args) {
     const eventSchema = resolveEventSchema(args);
     const inputSchema = resolveInputSchema(args);
     const recordSchema = resolveRecordSchema(args);
+    const templateRecordSchema = resolveTemplateRecordSchema(args);
     const tags = resolveTags(args);
     const slug = args.flags.get("slug");
     const description = args.flags.get("description");
@@ -346,6 +389,11 @@ async function runTemplateCreate(args) {
     // `undefined` would still add the key.
     if (recordSchema !== undefined)
         candidate["record_schema"] = recordSchema;
+    // template_record_schema is OMITTED entirely when --template-record-schema is
+    // absent — a template with no template-level record collections. Setting it
+    // to `undefined` would still add the key.
+    if (templateRecordSchema !== undefined)
+        candidate["template_record_schema"] = templateRecordSchema;
     const iconEmoji = args.flags.get("icon-emoji");
     if (iconEmoji !== undefined)
         candidate["icon_emoji"] = iconEmoji;
@@ -380,6 +428,7 @@ async function runTemplateVersion(args) {
     const eventSchema = resolveEventSchema(args);
     const inputSchema = resolveInputSchema(args);
     const recordSchema = resolveRecordSchema(args);
+    const templateRecordSchema = resolveTemplateRecordSchema(args);
     const candidate = {
         source,
         type,
@@ -395,6 +444,12 @@ async function runTemplateVersion(args) {
     // serialise as null and read as "intentionally cleared" on the wire.
     if (recordSchema !== undefined)
         candidate["record_schema"] = recordSchema;
+    // template_record_schema is OMITTED entirely when --template-record-schema is
+    // absent — same rationale as record_schema above. Including the key as
+    // undefined would serialise as null and read as "intentionally cleared" on
+    // the wire.
+    if (templateRecordSchema !== undefined)
+        candidate["template_record_schema"] = templateRecordSchema;
     const parsed = createArtifactVersionSchema.safeParse(candidate);
     if (!parsed.success) {
         const issue = parsed.error.issues[0];

package/dist/commands/update.js

@@ -0,0 +1,194 @@
+// `pane update <pane-id>` — in-place edit of instance-level pane fields (#502)
+// via PATCH /v1/panes/:id. Mirrors the create flags for the editable subset
+// (everything that is per-pane rather than per-template).
+import { updatePaneSchema } from "@paneui/core";
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { resolveJson } from "../input.js";
+import { printJson, fail, failFromError } from "../output.js";
+const KNOWN_FLAGS = [
+    "ttl",
+    "expires-at",
+    "input-data",
+    "title",
+    "preamble",
+    "metadata",
+    "tags",
+    "icon-emoji",
+    "icon-attachment-id",
+];
+// `--clear-icon-emoji` / `--clear-icon-attachment-id` set the corresponding
+// field to `null` on the wire (drops the per-pane override; the pane falls back
+// to the template's icon).
+const KNOWN_BOOLS = ["clear-icon-emoji", "clear-icon-attachment-id"];
+const SCHEMA_PATH_TO_FLAG = {
+    ttl: "--ttl",
+    expires_at: "--expires-at",
+    input_data: "--input-data",
+    title: "--title",
+    preamble: "--preamble",
+    metadata: "--metadata",
+    tags: "--tags",
+    icon_emoji: "--icon-emoji",
+    icon_attachment_id: "--icon-attachment-id",
+};
+function schemaPathToFlag(path) {
+    const dotted = path.map(String).join(".");
+    for (let i = path.length; i > 0; i--) {
+        const prefix = path.slice(0, i).map(String).join(".");
+        const flag = SCHEMA_PATH_TO_FLAG[prefix];
+        if (flag !== undefined)
+            return flag;
+    }
+    return dotted;
+}
+export const updateHelp = `pane update — edit instance-level fields on a live pane
+
+Usage:
+  pane update <pane-id> [options]
+
+Edits a live pane in place (PATCH /v1/panes/:id). The pane keeps its id, URL,
+event log, and template pin — only the per-instance fields listed below change.
+Pass at least one flag; ttl and --expires-at are mutually exclusive.
+
+The relay revalidates --input-data against the pane's current template
+version's input_schema (the pane may have been upgraded since create), and
+runs the same attachment-access checks as 'pane create'.
+
+Lifecycle:
+  --ttl <seconds>         Reset the pane's lifetime to now + <seconds>. Clamped
+                          against the relay's MAX_TTL_SECONDS cap; exceeding it
+                          is rejected (not silently truncated).
+  --expires-at <iso>      Set expires_at to a specific ISO-8601 timestamp.
+                          Must be in the future and within MAX_TTL_SECONDS
+                          from now. Mutually exclusive with --ttl.
+
+Display:
+  --title <text>          New tab title. Same length/control-char rules as
+                          create.
+  --preamble <text>       New preamble (the context band above the iframe).
+                          Max 280 chars after trim; one \\n permitted.
+  --icon-emoji <e>        Set per-pane icon to a single emoji grapheme.
+  --icon-attachment-id <id>
+                          Set per-pane icon to a ready raster-image
+                          attachment (png/jpeg/webp/gif).
+  --clear-icon-emoji      Clear the emoji override; fall back to the
+                          template's icon.
+  --clear-icon-attachment-id
+                          Clear the attachment override; fall back to the
+                          template's icon.
+
+Data:
+  --input-data <path|json>  Replace the pane's input_data wholesale (JSON file
+                          path or inline JSON). Revalidated against the pinned
+                          template version's input_schema.
+  --metadata <path|json>  Replace the pane's metadata wholesale.
+  --tags <t1,t2,...>      Replace the per-pane tags (the relay merges them with
+                          the template's tags, deduped). ≤20 tags, ≤50 chars
+                          each; 'favorite' / 'favorites' are reserved.
+
+Other:
+  --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):
+  The full new pane state — same shape as 'pane show <id>' — plus an
+  \`updated_fields\` array naming which fields actually changed.`;
+export async function runUpdate(args) {
+    assertKnownFlags(args, KNOWN_FLAGS, KNOWN_BOOLS, "pane update");
+    const paneId = args.positionals[0];
+    if (!paneId)
+        fail("missing <pane-id>", "invalid_args");
+    const candidate = {};
+    const ttlRaw = args.flags.get("ttl");
+    const expiresAtRaw = args.flags.get("expires-at");
+    if (ttlRaw !== undefined && expiresAtRaw !== undefined) {
+        fail("--ttl and --expires-at are mutually exclusive — pass one or the other", "invalid_args");
+    }
+    if (ttlRaw !== undefined) {
+        const ttl = Number(ttlRaw);
+        if (!Number.isFinite(ttl))
+            fail("--ttl must be a number", "invalid_args");
+        candidate["ttl"] = ttl;
+    }
+    if (expiresAtRaw !== undefined) {
+        candidate["expires_at"] = expiresAtRaw;
+    }
+    const titleRaw = args.flags.get("title");
+    if (titleRaw !== undefined)
+        candidate["title"] = titleRaw;
+    const preambleRaw = args.flags.get("preamble");
+    if (preambleRaw !== undefined)
+        candidate["preamble"] = preambleRaw;
+    const inputDataRaw = args.flags.get("input-data");
+    if (inputDataRaw !== undefined) {
+        try {
+            candidate["input_data"] = resolveJson(inputDataRaw, "--input-data");
+        }
+        catch (e) {
+            fail(e instanceof Error ? e.message : String(e), "invalid_args");
+        }
+    }
+    const metaRaw = args.flags.get("metadata");
+    if (metaRaw !== undefined) {
+        try {
+            candidate["metadata"] = resolveJson(metaRaw, "--metadata");
+        }
+        catch (e) {
+            fail(e instanceof Error ? e.message : String(e), "invalid_args");
+        }
+    }
+    const tagsRaw = args.flags.get("tags");
+    if (tagsRaw !== undefined) {
+        const tags = tagsRaw
+            .split(",")
+            .map((t) => t.trim())
+            .filter((t) => t !== "");
+        // Empty list explicitly = caller passed `--tags ""`; send [] so the relay
+        // wipes per-pane tags down to just the template inheritance.
+        candidate["tags"] = tags;
+    }
+    // Icon overrides. The set-flag and the clear-flag for the same field are
+    // contradictory — refuse rather than silently picking one.
+    const iconEmojiRaw = args.flags.get("icon-emoji");
+    const clearIconEmoji = args.bools.has("clear-icon-emoji");
+    if (iconEmojiRaw !== undefined && clearIconEmoji) {
+        fail("--icon-emoji and --clear-icon-emoji are mutually exclusive", "invalid_args");
+    }
+    if (iconEmojiRaw !== undefined)
+        candidate["icon_emoji"] = iconEmojiRaw;
+    if (clearIconEmoji)
+        candidate["icon_emoji"] = null;
+    const iconAttachmentRaw = args.flags.get("icon-attachment-id");
+    const clearIconAttachment = args.bools.has("clear-icon-attachment-id");
+    if (iconAttachmentRaw !== undefined && clearIconAttachment) {
+        fail("--icon-attachment-id and --clear-icon-attachment-id are mutually exclusive", "invalid_args");
+    }
+    if (iconAttachmentRaw !== undefined) {
+        candidate["icon_attachment_id"] = iconAttachmentRaw;
+    }
+    if (clearIconAttachment)
+        candidate["icon_attachment_id"] = null;
+    // Bail before the round trip if nothing was supplied — the relay would
+    // reject this with `invalid_request` anyway, but a local message names the
+    // CLI flags the user knows.
+    if (Object.keys(candidate).length === 0) {
+        fail("pass at least one field to update (see --help for the full list)", "invalid_args");
+    }
+    const parsed = updatePaneSchema.safeParse(candidate);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        const where = issue && issue.path.length > 0 ? schemaPathToFlag(issue.path) : "request";
+        fail(`invalid update request: ${where}: ${issue ? issue.message : "validation failed"}`, "invalid_args", parsed.error.flatten());
+    }
+    const req = parsed.data;
+    const client = makeClient(args);
+    try {
+        const res = await client.updatePane(paneId, req);
+        printJson(res);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/index.js

@@ -32,6 +32,7 @@ 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 { runUpdate, updateHelp } from "./commands/update.js";
 import { runParticipant, participantHelp } from "./commands/participant.js";
 import { runShare, shareHelp } from "./commands/share.js";
 import { runTemplate, artifactHelp } from "./commands/template.js";
@@ -66,6 +67,10 @@ Pane commands (operate on the core noun — a live UI channel):
   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).
+  update <id>       Edit instance-level fields in place (PATCH /v1/panes/:id):
+                    --ttl / --expires-at, --title, --preamble, --input-data,
+                    --metadata, --tags, --icon-emoji, --icon-attachment-id
+                    (and matching --clear-icon-* flags). Same URL.
   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
@@ -80,9 +85,14 @@ Other noun groups:
                     Doubles as an end-to-end smoke test of your install.
   template          Reusable, versioned UI templates
                     (create | version | update | search | list | show | delete).
+  records           Per-pane mutable collections — todo lists, checklists,
+                    kanban cards, comments (list | get | upsert | update |
+                    delete | delete-collection | watch), keyed by a stable
+                    record_key.
   template-records  Owner-curated content scoped to a Template head
-                    (list | get | upsert | update | delete), visible to
-                    every pane derived from any version of the template.
+                    (list | get | upsert | update | delete |
+                    delete-collection), visible to every pane derived from
+                    any version of the template.
   key               YOUR agent's API key (list | revoke).
   taste             YOUR agent's freeform UI taste notes
                     (get | set | clear) — presentation preferences the agent
@@ -153,6 +163,10 @@ const BOOLEAN_FLAGS = new Set([
     "list",
     // `pane upgrade --force`: override the strict schema-compat gate.
     "force",
+    // `pane update --clear-icon-*`: drop the per-pane icon override (the field
+    // becomes null and the pane falls back to the template's icon).
+    "clear-icon-emoji",
+    "clear-icon-attachment-id",
 ]);
 async function main() {
     const rawArgv = process.argv.slice(2);
@@ -189,6 +203,7 @@ async function main() {
         watch: watchHelp,
         delete: deleteHelp,
         upgrade: upgradeHelp,
+        update: updateHelp,
         participant: participantHelp,
         share: shareHelp,
         // Other noun groups.
@@ -246,6 +261,9 @@ async function main() {
         case "upgrade":
             await runUpgrade(args);
             break;
+        case "update":
+            await runUpdate(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.16";
+export const VERSION = "0.0.18";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paneui/cli",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "Command-line client for the Pane relay: create panes, inspect state, send and watch events.",
   "license": "MIT",
   "type": "module",
@@ -41,11 +41,11 @@
     "test:unit": "vitest run"
   },
   "dependencies": {
-    "@paneui/core": "^0.0.16",
+    "@paneui/core": "^0.0.18",
     "qrcode-terminal": "^0.12.0"
   },
   "devDependencies": {
-    "@types/node": "^25.9.1",
+    "@types/node": "^25.9.2",
     "@types/qrcode-terminal": "^0.12.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.8"