@paneui/cli 0.0.5 → 0.0.7

package/dist/commands/surface.js

@@ -0,0 +1,118 @@
+// `pane surface` — the central noun of pane: open, observe, send to, and
+// close a surface.
+//
+// A surface is one *use* of an template: an open URL the human(s) interact
+// with, plus an event log the agent reads and appends to. Every other noun
+// (template, attachment, key, taste, feedback) exists in service of surfaces.
+//
+// This file is a thin dispatcher — each verb's actual logic lives in its own
+// file (create.ts, state.ts, send.ts, watch.ts, delete.ts). The verb runners
+// expect the surface id at positionals[0]; we slice off our own verb before
+// delegating so they don't need to know they're being called via `surface`.
+import { runCreate } from "./create.js";
+import { runState } from "./state.js";
+import { runSend } from "./send.js";
+import { runWatch } from "./watch.js";
+import { runDelete } from "./delete.js";
+import { runList, listHelp } from "./list.js";
+import { runParticipant, participantHelp } from "./participant.js";
+import { fail } from "../output.js";
+export const sessionHelp = `pane surface — open, observe, send to, and close surfaces
+
+A surface is one use of an template: an open URL the human(s) interact with,
+plus an event log the agent reads and appends to.
+
+Usage:
+  pane surface <verb> [options]
+
+Verbs:
+  create            Create a surface (POST /v1/surfaces). Prints surface_id,
+                    urls, tokens, expires_at.
+  list              Enumerate YOUR agent's surfaces. The recovery primitive
+                    for "I dropped the create response" — surfaces are
+                    listable, but participant tokens are stored hashed and
+                    CANNOT be recovered. Use 'participant new' to mint a
+                    fresh URL.
+  show <id>         Non-blocking snapshot: surface metadata + event log.
+                    Supports --wait <secs> for relay-side long-polling.
+  send <id>         Emit an agent event into a surface.
+  watch <id>        Stream a surface's events as JSON-lines on stdout
+                    (long-lived; the building block for pipe-readers).
+  delete <id>       Close/delete a surface (DELETE /v1/surfaces/:id).
+  participant         List / mint / revoke participant URLs on an existing
+    <list|new|revoke> surface. 'list' returns the participant ids you need
+                      for 'revoke'; 'new' replaces the destructive 'delete
+                      + recreate' workaround for a lost URL; 'revoke'
+                      invalidates one URL without touching the surface.
+
+Run \`pane surface <verb> --help\` for verb-specific options.`;
+/**
+ * Build a new ParsedArgs with the leading positional (the verb) stripped.
+ * The downstream verb runners (runState / runSend / runWatch / runDelete)
+ * read the surface id at positionals[0], so we hand them an args object that
+ * looks exactly like the pre-restructure invocation.
+ */
+function shiftPositionals(args) {
+    // Propagate danglingValueFlags too — otherwise the leaf runner's
+    // assertKnownFlags can't tell that the user wrote `--title` without a
+    // value, and falls through to a less-useful downstream error.
+    const out = {
+        positionals: args.positionals.slice(1),
+        flags: args.flags,
+        bools: args.bools,
+    };
+    if (args.danglingValueFlags !== undefined) {
+        out.danglingValueFlags = args.danglingValueFlags;
+    }
+    return out;
+}
+export async function runSession(args) {
+    const verb = args.positionals[0];
+    // `pane surface participant --help` (verb-level help on the participant
+    // sub-noun, with no further sub-verb). The general --help pre-empt in
+    // index.ts only fires when no positional follows the noun; here a
+    // positional ("participant") is present, so the sub-noun must own its own
+    // --help routing.
+    if (verb === "participant" &&
+        args.bools.has("help") &&
+        args.positionals.length === 1) {
+        process.stdout.write(participantHelp + "\n");
+        return;
+    }
+    // `pane surface list --help` — same pattern.
+    if (verb === "list" &&
+        args.bools.has("help") &&
+        args.positionals.length === 1) {
+        process.stdout.write(listHelp + "\n");
+        return;
+    }
+    const inner = shiftPositionals(args);
+    switch (verb) {
+        case "create":
+            await runCreate(inner);
+            break;
+        case "list":
+            await runList(inner);
+            break;
+        case "show":
+            await runState(inner);
+            break;
+        case "send":
+            await runSend(inner);
+            break;
+        case "watch":
+            await runWatch(inner);
+            break;
+        case "delete":
+            await runDelete(inner);
+            break;
+        case "participant":
+            await runParticipant(inner);
+            break;
+        case undefined:
+            fail("missing verb — usage: pane surface <create|list|show|send|watch|delete|participant> (run 'pane surface --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown surface verb '${verb}' — expected create|list|show|send|watch|delete|participant (run 'pane surface --help')`, "invalid_args");
+    }
+}

package/dist/commands/taste.js

@@ -1,46 +1,51 @@
 // `pane taste` — read / write / clear the calling agent's freeform "taste
-// notes" markdown blob.
+// notes" markdown attachment.
 //
 // Taste notes are presentation preferences the agent has learned from human
 // feedback ("denser layout", "no rounded corners", "use a dark header") — the
-// kind of guidance that should outlive a single session. The intended loop:
+// kind of guidance that should outlive a single surface. The intended loop:
 //
-//   1. Before generating a pane artifact, run `pane taste get` and feed the
+//   1. Before generating a pane template, run `pane taste get` and feed the
 //      `taste` field into the prompt so prior preferences shape the output.
 //   2. When the human gives new presentation feedback, run `pane taste get`,
 //      merge the feedback into the existing notes IN THE PROMPT, then call
-//      `pane taste set` with the WHOLE new blob (the relay does whole-blob
+//      `pane taste set` with the WHOLE new attachment (the relay does whole-attachment
 //      replace, not append — that's deliberate, so the notes can't grow
 //      unbounded into noise).
 //
 // Keep taste notes about *presentation/UI taste only* — colours, density,
-// component preferences. Project context, todos, and per-session state belong
-// somewhere else. Today the blob is keyed by the agent's API key (per-agent);
+// component preferences. Project context, todos, and per-surface state belong
+// somewhere else. Today the attachment is keyed by the agent's API key (per-agent);
 // when pane gains first-class humans, this may move to per-human.
 import { readFileSync } from "node:fs";
+import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { printJson, fail, failFromError } from "../output.js";
+const NO_FLAGS = [];
+const NO_BOOLS = [];
+const SET_FLAGS = ["file"];
+const CLEAR_BOOLS = ["yes"];
 export const tasteHelp = `pane taste — read / write / clear YOUR agent's UI taste notes
 
-Taste notes are a small markdown blob storing presentation preferences your
+Taste notes are a small markdown attachment storing presentation preferences your
 agent has picked up from human feedback ("denser table", "no rounded corners",
-"use a dark header"). Read them before generating a pane artifact so prior
+"use a dark header"). Read them before generating a pane template so prior
 feedback shapes the output; rewrite them whenever the human gives new
 presentation feedback. Keep entries about UI/presentation taste only — not
-project context, todos, or session state.
+project context, todos, or surface state.
 
 Usage:
   pane taste <subcommand> [options]
 
 Subcommands:
-  get        Print the current notes blob:
+  get        Print the current notes attachment:
              { taste: string|null, updated_at: string|null, bytes: number }.
              taste is null and bytes is 0 when notes have never been written.
 
-  set        Whole-blob replace. Source the markdown via --file <path>,
+  set        Whole-attachment replace. Source the markdown via --file <path>,
              --file - (read stdin), or by piping into 'pane taste set' with
              no flag. The relay rejects empty/whitespace-only payloads and
-             caps the blob at MAX_TASTE_BYTES (utf8). To clear the notes,
+             caps the attachment at MAX_TASTE_BYTES (utf8). To clear the notes,
              use 'pane taste clear', not 'set' with an empty body.
 
   clear      Delete the notes. Requires --yes (it is destructive). Prints
@@ -74,6 +79,7 @@ async function readStdin() {
     return Buffer.concat(chunks).toString("utf8");
 }
 async function runTasteGet(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane taste get");
     const client = makeClient(args);
     try {
         const info = await client.getTaste();
@@ -84,8 +90,9 @@ async function runTasteGet(args) {
     }
 }
 async function runTasteSet(args) {
+    assertKnownFlags(args, SET_FLAGS, NO_BOOLS, "pane taste set");
     const filePath = args.flags.get("file");
-    // Source the blob deterministically — no isTTY-flag fusing, because
+    // Source the attachment deterministically — no isTTY-flag fusing, because
     // `!process.stdin.isTTY` is true under every non-interactive caller
     // (pipes, redirects, closed fd, CI, agent harnesses) and would wrongly
     // reject `--file` for the entire target audience. See issue #148.
@@ -112,7 +119,7 @@ async function runTasteSet(args) {
         fail("'pane taste set' needs input — pass --file <path>, pipe markdown on stdin, or use --file -", "invalid_args");
     }
     if (taste.trim().length === 0) {
-        fail("'pane taste set' refuses an empty or whitespace-only blob — use 'pane taste clear --yes' to delete the notes", "invalid_args");
+        fail("'pane taste set' refuses an empty or whitespace-only attachment — use 'pane taste clear --yes' to delete the notes", "invalid_args");
     }
     const client = makeClient(args);
     try {
@@ -124,6 +131,7 @@ async function runTasteSet(args) {
     }
 }
 async function runTasteClear(args) {
+    assertKnownFlags(args, NO_FLAGS, CLEAR_BOOLS, "pane taste clear");
     if (!args.bools.has("yes")) {
         fail("'pane taste clear' deletes YOUR agent's taste notes — it is destructive. Pass --yes to confirm.", "confirmation_required");
     }

package/dist/commands/{artifact.js → template.js}

@@ -1,80 +1,101 @@
-// `pane artifact` — manage reusable, versioned artifacts.
+// `pane template` — manage reusable, versioned templates.
 //
-// Flat command namespace: `artifact` is one top-level command that branches on
+// Flat command namespace: `template` is one top-level command that branches on
 // a positional subcommand (create / version / update / search / list / show /
 // delete).
-// An artifact is a reusable UI template (HTML + event schema + optional input
-// schema); a session is one *use* of one version of it. Authoring an artifact
-// once and instancing it via `pane create --artifact-id` removes the per-use
-// cost of regenerating the same HTML.
+// An template is a reusable UI template (HTML + event schema + optional input
+// schema); a surface is one *use* of one version of it. Authoring an template
+// once and instancing it via `pane surface create --template-id` removes the
+// per-use cost of regenerating the same HTML.
 import { createArtifactSchema, createArtifactVersionSchema, patchArtifactMetadataSchema, } from "@paneui/core";
+import { assertKnownFlags } from "../argv.js";
 import { makeClient } from "../config.js";
 import { resolveJson, resolveText } from "../input.js";
 import { printJson, fail, failFromError } from "../output.js";
-export const artifactHelp = `pane artifact — manage reusable, versioned artifacts
+const CREATE_FLAGS = [
+    "name",
+    "slug",
+    "description",
+    "tags",
+    "template",
+    "template-type",
+    "event-schema",
+    "input-schema",
+];
+const VERSION_FLAGS = [
+    "template",
+    "template-type",
+    "event-schema",
+    "input-schema",
+];
+const UPDATE_FLAGS = ["name", "slug", "description", "tags"];
+const NO_FLAGS = [];
+const NO_BOOLS = [];
+const DELETE_BOOLS = ["yes"];
+export const artifactHelp = `pane template — manage reusable, versioned templates
 
-An artifact is a reusable UI template: HTML + an event schema + an optional
-input schema. A session is one use of one version of it. Author an artifact
-once, then instance it many times with 'pane create --artifact-id <id|slug>'
-instead of regenerating the HTML on every session.
+An template is a reusable UI template: HTML + an event schema + an optional
+input schema. A surface is one use of one version of it. Author an template
+once, then instance it many times with 'pane surface create --template-id <id|slug>'
+instead of regenerating the HTML on every surface.
 
 Usage:
-  pane artifact <subcommand> [options]
+  pane template <subcommand> [options]
 
 Subcommands:
-  create     Create a named, reusable artifact (its v1).
-  version    Append a new version to an existing artifact.
-  update     Update an artifact's head metadata (name/slug/description/tags).
-  search     Search the agent's named artifacts (lean — no HTML).
-  list       List the agent's named artifacts (search with no query).
-  show       Show a full artifact: head metadata + its version list.
-  delete     Permanently delete an artifact and ALL its versions. Requires
-             --yes. Refused with 409 conflict if any session (open or
-             closed) still references the artifact — delete those first.
+  create     Create a named, reusable template (its v1).
+  version    Append a new version to an existing template.
+  update     Update an template's head metadata (name/slug/description/tags).
+  search     Search the agent's named templates (lean — no HTML).
+  list       List the agent's named templates (search with no query).
+  show       Show a full template: head metadata + its version list.
+  delete     Permanently delete an template and ALL its versions. Requires
+             --yes. Refused with 409 conflict if any surface (open or
+             closed) still references the template — delete those first.
 
-  pane artifact create --name <n> --artifact <path|inline>
+  pane template create --name <n> --template <path|inline>
                        [--event-schema <path|json>] [--slug <s>]
                        [--description <d>] [--tags <t1,t2>]
-                       [--input-schema <path|json>] [--artifact-type <t>]
-      Creates a named artifact. Prints { artifact_id, slug, version }.
+                       [--input-schema <path|json>] [--template-type <t>]
+      Creates a named template. Prints { template_id, slug, version }.
 
-  pane artifact version <id|slug> --artifact <path|inline>
+  pane template version <id|slug> --template <path|inline>
                         [--event-schema <path|json>]
-                        [--input-schema <path|json>] [--artifact-type <t>]
-      Appends a new immutable version. Prints { artifact_id, version }.
+                        [--input-schema <path|json>] [--template-type <t>]
+      Appends a new immutable version. Prints { template_id, version }.
 
-  pane artifact update <id|slug> [--name <n>] [--slug <s>]
+  pane template update <id|slug> [--name <n>] [--slug <s>]
                        [--description <d>] [--tags <t1,t2>]
       Updates head metadata only (never the content). Prints the lean summary.
 
-  pane artifact search [query]
+  pane template search [query]
       Text search over name + description + tags, ranked by last_used_at.
       Prints an array of { id, slug, name, description, tags,
       latest_version, last_used_at }.
 
-  pane artifact list
-      Alias of 'search' with no query — lists all the agent's artifacts.
+  pane template list
+      Alias of 'search' with no query — lists all the agent's templates.
 
-  pane artifact show <id|slug>
-      Prints the full artifact: head metadata + every version's content.
+  pane template show <id|slug>
+      Prints the full template: head metadata + every version's content.
 
-  pane artifact delete <id|slug> --yes
-      Permanently deletes the artifact and all its versions. Refused
-      (409 conflict) if any session in any state still references one
-      of the artifact's versions — run 'pane delete <session-id>' on
+  pane template delete <id|slug> --yes
+      Permanently deletes the template and all its versions. Refused
+      (409 conflict) if any surface in any state still references one
+      of the template's versions — run 'pane surface delete <surface-id>' on
       each first, or wait for the relay's TTL sweeper to reclaim them.
-      Prints { artifact, deleted: true } on success.
+      Prints { template, deleted: true } on success.
 
 Options:
-  --name <n>          Artifact display name (required for 'create').
+  --name <n>          Template display name (required for 'create').
   --slug <s>          Stable, agent-chosen handle (unique per agent). The
-                      durable way to reference the artifact later.
-  --description <d>   Prose: what the artifact is and does. Read by an agent
+                      durable way to reference the template later.
+  --description <d>   Prose: what the template is and does. Read by an agent
                       deciding whether to reuse it.
   --tags <t1,t2,...>  Comma-separated keywords for search.
-  --artifact <v>      HTML artifact body — a file path, or inline HTML.
+  --template <v>      HTML template body — a file path, or inline HTML.
   --event-schema <v>  Event schema — a .json file path, or inline JSON.
-                      Optional: omit for a view-only artifact (a
+                      Optional: omit for a view-only template (a
                       report/dashboard the human only views — no page/agent
                       events).
 
@@ -96,27 +117,27 @@ Options:
                       emittedBy is any non-empty subset of ["page", "agent"].
                       payload is a JSON Schema; the relay validates every
                       emit against it. See docs/SPEC.md for the full grammar.
-  --input-schema <v>  JSON Schema for this artifact's per-session input_data —
+  --input-schema <v>  JSON Schema for this template's per-surface input_data —
                       a file path, or inline JSON. Optional.
-  --artifact-type <t> "html-inline" (default) or "html-ref".
+  --template-type <t> "html-inline" (default) or "html-ref".
   --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 is machine-readable JSON.`;
-/** Resolve --artifact-type, defaulting to html-inline. */
+/** Resolve --template-type, defaulting to html-inline. */
 function resolveArtifactType(args) {
-    const t = (args.flags.get("artifact-type") ?? "html-inline");
+    const t = (args.flags.get("template-type") ?? "html-inline");
     if (t !== "html-inline" && t !== "html-ref") {
-        fail("--artifact-type must be 'html-inline' or 'html-ref'", "invalid_args");
+        fail("--template-type must be 'html-inline' or 'html-ref'", "invalid_args");
     }
     return t;
 }
-/** Resolve the artifact HTML body (file or inline; verbatim URL for html-ref). */
+/** Resolve the template HTML body (file or inline; verbatim URL for html-ref). */
 function resolveSource(args, type) {
-    const artifactVal = args.flags.get("artifact");
+    const artifactVal = args.flags.get("template");
     if (!artifactVal)
-        fail("missing --artifact", "invalid_args");
+        fail("missing --template", "invalid_args");
     try {
         return type === "html-ref" ? artifactVal : resolveText(artifactVal);
     }
@@ -127,7 +148,7 @@ function resolveSource(args, type) {
 /**
  * Resolve --event-schema — file path or inline JSON. --event-schema is
  * optional: when absent this returns `undefined`, which makes a view-only
- * artifact (no event vocabulary — the human only views it). The caller must
+ * template (no event vocabulary — the human only views it). The caller must
  * omit `event_schema` from the request entirely when this returns `undefined`.
  */
 function resolveEventSchema(args) {
@@ -169,6 +190,7 @@ function resolveTags(args) {
     return tags.length > 0 ? tags : undefined;
 }
 async function runArtifactCreate(args) {
+    assertKnownFlags(args, CREATE_FLAGS, NO_BOOLS, "pane template create");
     const name = args.flags.get("name");
     if (!name)
         fail("missing --name", "invalid_args");
@@ -185,7 +207,7 @@ async function runArtifactCreate(args) {
         type,
     };
     // event_schema is OMITTED entirely when --event-schema is absent — a view-only
-    // artifact. Setting it to `undefined` would still add the key.
+    // template. Setting it to `undefined` would still add the key.
     if (eventSchema !== undefined)
         candidate["event_schema"] = eventSchema;
     if (slug !== undefined)
@@ -200,14 +222,14 @@ async function runArtifactCreate(args) {
     if (!parsed.success) {
         const issue = parsed.error.issues[0];
         const where = issue && issue.path.length > 0 ? issue.path.join(".") : "request";
-        fail(`invalid artifact: ${where}: ${issue ? issue.message : "validation failed"}`, "invalid_args", parsed.error.flatten());
+        fail(`invalid template: ${where}: ${issue ? issue.message : "validation failed"}`, "invalid_args", parsed.error.flatten());
     }
     const req = parsed.data;
     const client = makeClient(args);
     try {
         const res = await client.createArtifact(req);
         printJson({
-            artifact_id: res.artifact_id,
+            template_id: res.template_id,
             slug: slug ?? null,
             version: res.version,
         });
@@ -217,9 +239,10 @@ async function runArtifactCreate(args) {
     }
 }
 async function runArtifactVersion(args) {
+    assertKnownFlags(args, VERSION_FLAGS, NO_BOOLS, "pane template version");
     const idOrSlug = args.positionals[1];
     if (!idOrSlug) {
-        fail("missing artifact <id|slug> — usage: pane artifact version <id|slug>", "invalid_args");
+        fail("missing template <id|slug> — usage: pane template version <id|slug>", "invalid_args");
     }
     const type = resolveArtifactType(args);
     const source = resolveSource(args, type);
@@ -245,16 +268,17 @@ async function runArtifactVersion(args) {
     const client = makeClient(args);
     try {
         const res = await client.createArtifactVersion(idOrSlug, req);
-        printJson({ artifact_id: res.artifact_id, version: res.version });
+        printJson({ template_id: res.template_id, version: res.version });
     }
     catch (e) {
         failFromError(e);
     }
 }
 async function runArtifactUpdate(args) {
+    assertKnownFlags(args, UPDATE_FLAGS, NO_BOOLS, "pane template update");
     const idOrSlug = args.positionals[1];
     if (!idOrSlug) {
-        fail("missing artifact <id|slug> — usage: pane artifact update <id|slug>", "invalid_args");
+        fail("missing template <id|slug> — usage: pane template update <id|slug>", "invalid_args");
     }
     const candidate = {};
     const name = args.flags.get("name");
@@ -289,6 +313,7 @@ async function runArtifactUpdate(args) {
     }
 }
 async function runArtifactSearch(args, query) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, query === undefined ? "pane template list" : "pane template search");
     const client = makeClient(args);
     try {
         const res = await client.searchArtifacts(query);
@@ -299,9 +324,10 @@ async function runArtifactSearch(args, query) {
     }
 }
 async function runArtifactShow(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "pane template show");
     const idOrSlug = args.positionals[1];
     if (!idOrSlug) {
-        fail("missing artifact <id|slug> — usage: pane artifact show <id|slug>", "invalid_args");
+        fail("missing template <id|slug> — usage: pane template show <id|slug>", "invalid_args");
     }
     const client = makeClient(args);
     try {
@@ -312,23 +338,24 @@ async function runArtifactShow(args) {
         failFromError(e);
     }
 }
-// `pane artifact delete <id|slug> --yes` — remove an artifact (and, server-
+// `pane template delete <id|slug> --yes` — remove an template (and, server-
 // side, all its versions). The relay refuses with 409 conflict if any
-// session still references it; the CLI surfaces that as the relay-supplied
+// surface still references it; the CLI surfaces that as the relay-supplied
 // envelope. `--yes` is required because there's no Undo button on a delete
-// and the same `pane artifact create` slug isn't reservable once gone.
+// and the same `pane template create` slug isn't reservable once gone.
 async function runArtifactDelete(args) {
+    assertKnownFlags(args, NO_FLAGS, DELETE_BOOLS, "pane template delete");
     const idOrSlug = args.positionals[1];
     if (!idOrSlug) {
-        fail("missing artifact <id|slug> — usage: pane artifact delete <id|slug> --yes", "invalid_args");
+        fail("missing template <id|slug> — usage: pane template delete <id|slug> --yes", "invalid_args");
     }
     if (!args.bools.has("yes")) {
-        fail("'pane artifact delete' permanently removes the artifact and all its versions — it is destructive. Pass --yes to confirm.", "invalid_args");
+        fail("'pane template delete' permanently removes the template and all its versions — it is destructive. Pass --yes to confirm.", "invalid_args");
     }
     const client = makeClient(args);
     try {
         await client.deleteArtifact(idOrSlug);
-        printJson({ artifact: idOrSlug, deleted: true });
+        printJson({ template: idOrSlug, deleted: true });
     }
     catch (e) {
         failFromError(e);
@@ -359,9 +386,9 @@ export async function runArtifact(args) {
             await runArtifactDelete(args);
             break;
         case undefined:
-            fail("missing subcommand — usage: pane artifact <create|version|update|search|list|show|delete> (run 'pane artifact --help')", "invalid_args");
+            fail("missing subcommand — usage: pane template <create|version|update|search|list|show|delete> (run 'pane template --help')", "invalid_args");
             break;
         default:
-            fail(`unknown artifact subcommand '${sub}' — expected create|version|update|search|list|show|delete (run 'pane artifact --help')`, "invalid_args");
+            fail(`unknown template subcommand '${sub}' — expected create|version|update|search|list|show|delete (run 'pane template --help')`, "invalid_args");
     }
 }