@paneui/cli 0.0.14 → 0.0.16

package/dist/commands/create.js

@@ -14,6 +14,7 @@ const KNOWN_FLAGS = [
     "version",
     "event-schema",
     "input-schema",
+    "record-schema",
     "title",
     "preamble",
     "input-data",
@@ -22,6 +23,7 @@ const KNOWN_FLAGS = [
     "metadata",
     "callback",
     "context-key",
+    "tags",
     "icon-emoji",
     "icon-attachment-id",
 ];
@@ -59,6 +61,7 @@ const SCHEMA_PATH_TO_FLAG = {
     "template.source": "--template",
     "template.event_schema": "--event-schema",
     "template.input_schema": "--input-schema",
+    "template.record_schema": "--record-schema",
 };
 function schemaPathToFlag(path) {
     const dotted = path.map(String).join(".");
@@ -82,7 +85,8 @@ A pane is one use of an template. Supply the template in ONE of two ways:
     pane create --template-id <id|slug> [--version <n>] [--input-data <v>]
 
   Inline form — a one-off template, defined on this call:
-    pane create --template <path|inline> [--event-schema <path|json>] [options]
+    pane create --template <path|inline> [--event-schema <path|json>]
+                [--record-schema <path|json>] [options]
 
 Exactly one of --template-id / --template must be given.
 
@@ -106,7 +110,19 @@ Template (choose one):
   --event-schema <v>  Inline-form event schema. A .json file, or inline JSON.
                       Optional with --template. Omit for a view-only template
                       (a report/dashboard the human only views — no page/agent
-                      events). Ignored with --template-id.
+                      events). Rejected with --template-id (the schema comes
+                      from the pinned template version there).
+
+                      Pane has TWO data primitives — pick the right one before
+                      designing the schema. Events (this flag) are an
+                      append-only journal: forms, approvals, surveys, pickers,
+                      doc reviews. RECORDS (--record-schema, below) are a
+                      mutable collection: todo lists, shopping lists,
+                      checklists, kanban boards, comment threads, inventories.
+                      If the page shows more than one mutable item and the
+                      current state matters more than the history of edits,
+                      you want records. See the "Records" section of
+                      \`pane skill show\` for the decision table.
 
                       Shape — an object with an "events" map, keyed by event
                       type. Each entry declares who may emit it and the JSON
@@ -135,6 +151,42 @@ Template (choose one):
                       page via window.pane.downloadBlob. Without it, attachment
                       refs in --input-data are silently unreachable. See
                       docs/SPEC.md and #208.
+  --record-schema <v> Inline-form record schema — declares the per-pane
+                      mutable collections this template exposes (todos,
+                      comments, line items, etc.). A .json file, or inline
+                      JSON. Optional with --template; omit for an event-only
+                      one-off. Rejected with --template-id (the schema comes
+                      from the pinned template version there).
+
+                      Shape — a JSON Schema 2020-12 document with an
+                      "x-pane-collections" extension mapping collection names
+                      to { schema, write, delete }. \`write\` is a non-empty
+                      subset of {agent, page}; \`delete\` is a non-empty
+                      subset of {agent, page, author}.
+                          {
+                            "$schema": "https://json-schema.org/draft/2020-12/schema",
+                            "$defs": {
+                              "Todo": {
+                                "type": "object",
+                                "properties": {
+                                  "text": { "type": "string" },
+                                  "done": { "type": "boolean" }
+                                },
+                                "required": ["text"]
+                              }
+                            },
+                            "x-pane-collections": {
+                              "todos": {
+                                "schema": { "$ref": "#/$defs/Todo" },
+                                "write":  ["page", "agent"],
+                                "delete": ["author"]
+                              }
+                            }
+                          }
+                      See 'pane skill show' (the "Records" section) for the
+                      full grammar. Use \`pane records …\` to mutate rows in
+                      a live pane, and \`pane template-records …\` for
+                      template-level (cross-pane) curated rows.
 
 Options:
   --title <text>      Tab title shown to the human (max 80 chars, single
@@ -172,6 +224,13 @@ Options:
                       meaningful when the calling agent is claimed by a
                       human; omit otherwise. Allowed chars: A-Za-z0-9_:.-,
                       max 256.
+  --tags <t1,t2,...>  Per-pane filter tags (comma-separated). Merged with the
+                      template's tags (deduped) and snapshotted onto the pane;
+                      they drive the human's Panes-tab tag filter. Use for an
+                      instance-specific axis on top of the template's tags —
+                      e.g. a PR-review template tagged \`pr-review\`, with the
+                      repo per pane: \`--tags cp-backend\`. (\`favorite\`/
+                      \`favorites\` are reserved; ≤20 tags, ≤50 chars each.)
   --icon-emoji <e>    Per-pane icon override — a single emoji grapheme. NULL/
                       omitted = inherit the template's icon.
   --icon-attachment-id <id>
@@ -213,6 +272,9 @@ export async function runCreate(args) {
         if (args.flags.get("input-schema") !== undefined) {
             fail("--input-schema is incompatible with --template-id — the input schema comes from the pinned template version. Author the schema on the template (`pane template create --input-schema …`) instead.", "invalid_args");
         }
+        if (args.flags.get("record-schema") !== undefined) {
+            fail("--record-schema is incompatible with --template-id — the record collections come from the pinned template version. Author the schema on the template (`pane template create --record-schema …`) instead.", "invalid_args");
+        }
         // --name / --slug name the inline form's auto-created template. The
         // reference form inherits the existing Template.name/slug, so they have
         // no meaning here — reject rather than silently ignore.
@@ -246,6 +308,7 @@ export async function runCreate(args) {
         //    See #208.
         const schemaVal = args.flags.get("event-schema");
         const inputSchemaVal = args.flags.get("input-schema");
+        const recordSchemaVal = args.flags.get("record-schema");
         const templateType = (args.flags.get("template-type") ?? "html-inline");
         if (templateType !== "html-inline" && templateType !== "html-ref") {
             fail("--template-type must be 'html-inline' or 'html-ref'", "invalid_args");
@@ -301,6 +364,22 @@ export async function runCreate(args) {
                 fail(e instanceof Error ? e.message : String(e), "invalid_args");
             }
         }
+        // --record-schema: declares the inline template's per-pane record
+        // collections. Absent → no collections (event-only one-off). The relay
+        // does the full validation; we only check it parses as an object so a
+        // typo surfaces locally rather than as a generic "expected object".
+        if (recordSchemaVal !== undefined) {
+            try {
+                const v = resolveJson(recordSchemaVal, "--record-schema");
+                if (v === null || typeof v !== "object" || Array.isArray(v)) {
+                    fail("--record-schema must be a JSON object", "invalid_args");
+                }
+                inlineArtifact["record_schema"] = v;
+            }
+            catch (e) {
+                fail(e instanceof Error ? e.message : String(e), "invalid_args");
+            }
+        }
         candidate["template"] = inlineArtifact;
     }
     // --title — passthrough, no client-side requiredness. The relay is the
@@ -370,6 +449,19 @@ export async function runCreate(args) {
     if (contextKey !== undefined) {
         candidate["context_key"] = contextKey;
     }
+    // --tags — per-pane filter tags, comma-separated. Merged (deduped) with the
+    // template's tags by the relay and snapshotted onto the pane. Useful for an
+    // instance-specific axis (e.g. the repo a PR-review pane is for) on top of
+    // the template's tags. The relay enforces the limits + reserved names.
+    const tagsRaw = args.flags.get("tags");
+    if (tagsRaw !== undefined) {
+        const tags = tagsRaw
+            .split(",")
+            .map((t) => t.trim())
+            .filter((t) => t !== "");
+        if (tags.length > 0)
+            candidate["tags"] = tags;
+    }
     // Per-pane icon override. Passthrough — the relay validates the emoji
     // (single grapheme) and the attachment (ready raster image, accessible to
     // the agent), so a bad value panes as a schema/route rejection rather than

package/dist/commands/template.js

@@ -23,6 +23,7 @@ const CREATE_FLAGS = [
     "template-type",
     "event-schema",
     "input-schema",
+    "record-schema",
     "icon-emoji",
 ];
 const SET_ICON_FLAGS = ["template-id", "emoji", "image"];
@@ -32,6 +33,7 @@ const VERSION_FLAGS = [
     "template-type",
     "event-schema",
     "input-schema",
+    "record-schema",
 ];
 const UPDATE_FLAGS = ["name", "slug", "description", "tags"];
 const NO_FLAGS = [];
@@ -73,7 +75,8 @@ Subcommands:
   pane template create --name <n> --template <path|inline>
                        [--event-schema <path|json>] [--slug <s>]
                        [--description <d>] [--tags <t1,t2>]
-                       [--input-schema <path|json>] [--template-type <t>]
+                       [--input-schema <path|json>]
+                       [--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'
@@ -81,7 +84,8 @@ Subcommands:
 
   pane template version <id|slug> --template <path|inline>
                         [--event-schema <path|json>]
-                        [--input-schema <path|json>] [--template-type <t>]
+                        [--input-schema <path|json>]
+                        [--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>]
@@ -149,6 +153,17 @@ Options:
                       report/dashboard the human only views — no page/agent
                       events).
 
+                      Pane has TWO data primitives — pick the right one before
+                      designing the schema. Events (this flag) are an
+                      append-only journal: forms, approvals, surveys, pickers,
+                      doc reviews. RECORDS (--record-schema, below) are a
+                      mutable collection: todo lists, shopping lists,
+                      checklists, kanban boards, comment threads, inventories.
+                      If the page shows more than one mutable item and the
+                      current state matters more than the history of edits,
+                      you want records. See the "Records" section of
+                      \`pane skill show\` for the decision table.
+
                       Shape — an object with an "events" map, keyed by event
                       type. Each entry declares who may emit it and the JSON
                       Schema for its payload:
@@ -169,6 +184,39 @@ Options:
                       emit against it. See docs/SPEC.md for the full grammar.
   --input-schema <v>  JSON Schema for this template's per-pane input_data —
                       a file path, or inline JSON. Optional.
+  --record-schema <v> JSON Schema 2020-12 document declaring this template's
+                      per-pane record collections — a file path, or inline
+                      JSON. Optional; omit for an event-only template (no
+                      mutable collections).
+
+                      Shape — a JSON Schema doc with an "x-pane-collections"
+                      extension mapping collection names to { schema, write,
+                      delete } entries. \`write\` is a non-empty subset of
+                      {agent, page}; \`delete\` is a non-empty subset of
+                      {agent, page, author}.
+                          {
+                            "$schema": "https://json-schema.org/draft/2020-12/schema",
+                            "$defs": {
+                              "Todo": {
+                                "type": "object",
+                                "properties": {
+                                  "text": { "type": "string" },
+                                  "done": { "type": "boolean" }
+                                },
+                                "required": ["text"]
+                              }
+                            },
+                            "x-pane-collections": {
+                              "todos": {
+                                "schema": { "$ref": "#/$defs/Todo" },
+                                "write":  ["page", "agent"],
+                                "delete": ["author"]
+                              }
+                            }
+                          }
+                      The relay validates the document and rejects anything
+                      malformed at create time. See 'pane skill show' (the
+                      "Records" section) for the full grammar.
   --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).
@@ -229,6 +277,29 @@ function resolveInputSchema(args) {
         fail(e instanceof Error ? e.message : String(e), "invalid_args");
     }
 }
+/**
+ * Resolve the optional --record-schema — file path or inline JSON. Must be an
+ * object (a JSON Schema 2020-12 document with an `x-pane-collections`
+ * extension). Absent → returns `undefined` so the caller omits `record_schema`
+ * from the request entirely (template has no 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 resolveRecordSchema(args) {
+    const raw = args.flags.get("record-schema");
+    if (raw === undefined)
+        return undefined;
+    try {
+        const v = resolveJson(raw, "--record-schema");
+        if (v === null || typeof v !== "object" || Array.isArray(v)) {
+            fail("--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");
@@ -249,6 +320,7 @@ async function runTemplateCreate(args) {
     const source = resolveSource(args, type);
     const eventSchema = resolveEventSchema(args);
     const inputSchema = resolveInputSchema(args);
+    const recordSchema = resolveRecordSchema(args);
     const tags = resolveTags(args);
     const slug = args.flags.get("slug");
     const description = args.flags.get("description");
@@ -269,6 +341,11 @@ async function runTemplateCreate(args) {
         candidate["tags"] = tags;
     if (inputSchema !== undefined)
         candidate["input_schema"] = inputSchema;
+    // record_schema is OMITTED entirely when --record-schema is absent — a
+    // template with no record collections (event-only). Setting it to
+    // `undefined` would still add the key.
+    if (recordSchema !== undefined)
+        candidate["record_schema"] = recordSchema;
     const iconEmoji = args.flags.get("icon-emoji");
     if (iconEmoji !== undefined)
         candidate["icon_emoji"] = iconEmoji;
@@ -302,6 +379,7 @@ async function runTemplateVersion(args) {
     const source = resolveSource(args, type);
     const eventSchema = resolveEventSchema(args);
     const inputSchema = resolveInputSchema(args);
+    const recordSchema = resolveRecordSchema(args);
     const candidate = {
         source,
         type,
@@ -312,6 +390,11 @@ async function runTemplateVersion(args) {
         candidate["event_schema"] = eventSchema;
     if (inputSchema !== undefined)
         candidate["input_schema"] = inputSchema;
+    // record_schema is OMITTED entirely when --record-schema is absent — same
+    // rationale as event_schema above. Including the key as undefined would
+    // serialise as null and read as "intentionally cleared" on the wire.
+    if (recordSchema !== undefined)
+        candidate["record_schema"] = recordSchema;
     const parsed = createArtifactVersionSchema.safeParse(candidate);
     if (!parsed.success) {
         const issue = parsed.error.issues[0];

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.14";
+export const VERSION = "0.0.16";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paneui/cli",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "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.14",
+    "@paneui/core": "^0.0.16",
     "qrcode-terminal": "^0.12.0"
   },
   "devDependencies": {