@paneui/cli 0.0.9 → 0.0.10

package/dist/store.js

@@ -1,11 +1,35 @@
 // Persisted CLI config: ${XDG_CONFIG_HOME or ~/.config}/pane/config.json.
 //
-// Holds the relay URL and the agent API key obtained via `pane agent register`, so
-// later commands need no env vars. The file holds a secret — it is written
-// 0600. Tiny and synchronous; no deps.
+// Holds one or more named profiles. Each profile is one agent identity on
+// one relay — (url, api_key). Switching profiles is the multi-environment
+// story: dev / staging / prod, or personal / work agents on the same relay,
+// without re-running `pane agent register` between them.
+//
+// On-disk shape:
+//
+//   {
+//     "current_profile": "prod",
+//     "profiles": {
+//       "prod": { "url": "https://…", "api_key": "pane_…" },
+//       "dev":  { "url": "http://localhost:3000", "api_key": "pane_…" }
+//     }
+//   }
+//
+// Tiny and synchronous; no deps. Holds secrets — files written mode 0600.
 import { readFileSync, writeFileSync, mkdirSync, chmodSync, rmSync, } from "node:fs";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
+/**
+ * Default profile name when the user runs `pane agent register` without
+ * `--profile` on a fresh install. Stable, predictable, and short enough to
+ * type in `pane --profile default …` if needed.
+ */
+export const DEFAULT_PROFILE_NAME = "default";
+/** Profile-name validation (a-z, A-Z, 0-9, _ and -, 1..32 chars). */
+const PROFILE_NAME_RX = /^[A-Za-z0-9_-]{1,32}$/;
+export function isValidProfileName(name) {
+    return PROFILE_NAME_RX.test(name);
+}
 /** Absolute path to the config file (honours XDG_CONFIG_HOME). */
 export function storePath() {
     const base = process.env.XDG_CONFIG_HOME && process.env.XDG_CONFIG_HOME.trim() !== ""
@@ -13,52 +37,169 @@ export function storePath() {
         : join(homedir(), ".config");
     return join(base, "pane", "config.json");
 }
-/** Read the persisted config. Returns {} if the file is missing or unparseable. */
+/**
+ * Read the persisted config. Returns an empty store if the file is missing,
+ * unparseable, or doesn't carry a `profiles` object.
+ */
 export function readStore() {
     let text;
     try {
         text = readFileSync(storePath(), "utf8");
     }
     catch {
-        return {};
+        return { profiles: {} };
     }
+    let parsed;
     try {
-        const parsed = JSON.parse(text);
-        if (parsed === null ||
-            typeof parsed !== "object" ||
-            Array.isArray(parsed)) {
-            return {};
-        }
-        const out = {};
-        if (typeof parsed.url === "string")
-            out.url = parsed.url;
-        if (typeof parsed.apiKey === "string")
-            out.apiKey = parsed.apiKey;
-        return out;
+        parsed = JSON.parse(text);
     }
     catch {
-        return {};
+        return { profiles: {} };
     }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { profiles: {} };
+    }
+    const obj = parsed;
+    if (!obj["profiles"] || typeof obj["profiles"] !== "object") {
+        return { profiles: {} };
+    }
+    const rawProfiles = obj["profiles"];
+    const profiles = {};
+    for (const [name, raw] of Object.entries(rawProfiles)) {
+        if (raw === null || typeof raw !== "object")
+            continue;
+        const p = raw;
+        const profile = {};
+        if (typeof p["url"] === "string")
+            profile.url = p["url"];
+        if (typeof p["api_key"] === "string")
+            profile.apiKey = p["api_key"];
+        profiles[name] = profile;
+    }
+    const currentProfile = typeof obj["current_profile"] === "string"
+        ? obj["current_profile"]
+        : undefined;
+    // If the named current profile was deleted out-of-band, drop it back to
+    // undefined so the resolver can fall through to env / default URL.
+    return {
+        currentProfile: currentProfile && profiles[currentProfile] !== undefined
+            ? currentProfile
+            : undefined,
+        profiles,
+    };
+}
+/** Serialise a Store to the on-disk JSON shape (snake_case fields). */
+function serialize(store) {
+    const profilesOut = {};
+    for (const [name, p] of Object.entries(store.profiles)) {
+        const o = {};
+        if (p.url !== undefined)
+            o["url"] = p.url;
+        if (p.apiKey !== undefined)
+            o["api_key"] = p.apiKey;
+        profilesOut[name] = o;
+    }
+    const body = { profiles: profilesOut };
+    if (store.currentProfile !== undefined) {
+        body["current_profile"] = store.currentProfile;
+    }
+    return JSON.stringify(body, null, 2) + "\n";
 }
 /**
- * Merge `patch` into the existing config and write it back as pretty JSON.
- * Creates the parent directory if needed; the file is written with mode 0600.
+ * Atomically write the whole Store to disk. The file is created with mode
+ * 0600 and the parent directory is created as needed.
  */
-export function writeStore(patch) {
+export function writeStoreFull(store) {
     const path = storePath();
-    const merged = { ...readStore(), ...patch };
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify(merged, null, 2) + "\n", { mode: 0o600 });
-    // Ensure mode even if the file pre-existed with looser permissions.
+    writeFileSync(path, serialize(store), { mode: 0o600 });
+    // Ensure mode even when the file pre-existed with looser permissions.
     chmodSync(path, 0o600);
     return path;
 }
 /**
- * Delete the persisted config file (URL + API key). Idempotent — no error if
- * the file never existed. Returns the path it targeted. Used by `pane agent logout`.
+ * Upsert a single profile and write back. If `setCurrent` is true, the
+ * profile becomes the active one. If the store had no current profile yet
+ * (empty store), the newly-written profile becomes current regardless —
+ * there's no other choice that makes sense.
+ */
+export function upsertProfile(name, patch, setCurrent = false) {
+    if (!isValidProfileName(name)) {
+        throw new Error(`invalid profile name '${name}' — must match ${PROFILE_NAME_RX} (letters, digits, underscore, dash; 1..32 chars)`);
+    }
+    const store = readStore();
+    const merged = { ...(store.profiles[name] ?? {}), ...patch };
+    store.profiles[name] = merged;
+    if (setCurrent || store.currentProfile === undefined) {
+        store.currentProfile = name;
+    }
+    return writeStoreFull(store);
+}
+/**
+ * Set the active profile by name. Throws if `name` is not in the store.
+ * Use `upsertProfile` if you also want to create it.
+ */
+export function setCurrentProfile(name) {
+    const store = readStore();
+    if (store.profiles[name] === undefined) {
+        throw new Error(`profile '${name}' does not exist — run 'pane config list' to see available profiles`);
+    }
+    store.currentProfile = name;
+    return writeStoreFull(store);
+}
+/**
+ * Remove a profile. If it was current, drop `current_profile` (the resolver
+ * falls through to env / default URL). If the resulting store is empty,
+ * delete the file entirely so a `readStore` looks identical to "fresh".
+ * Returns `{ path, was_current }`. Throws if the profile doesn't exist.
+ */
+export function removeProfile(name) {
+    const store = readStore();
+    if (store.profiles[name] === undefined) {
+        throw new Error(`profile '${name}' does not exist`);
+    }
+    const wasCurrent = store.currentProfile === name;
+    delete store.profiles[name];
+    if (wasCurrent) {
+        store.currentProfile = undefined;
+    }
+    if (Object.keys(store.profiles).length === 0) {
+        // Empty store → delete the file so a subsequent register starts fresh.
+        return { path: clearStore(), was_current: wasCurrent };
+    }
+    return { path: writeStoreFull(store), was_current: wasCurrent };
+}
+/**
+ * Delete the persisted config file entirely. Idempotent — no error if the
+ * file never existed. Returns the path it targeted. Used by
+ * `pane agent logout --all` and `removeProfile` when it drains the last
+ * profile.
  */
 export function clearStore() {
     const path = storePath();
     rmSync(path, { force: true });
     return path;
 }
+/**
+ * Resolve which profile to load from the store, given the optional selector
+ * (`--profile` flag or `PANE_PROFILE` env). Returns `null` if no profile
+ * matches — i.e. the caller should fall through to env / default-URL
+ * resolution. Throws if `selector` was explicit (truthy) and not found, so
+ * a typo in `--profile dev` doesn't silently fall back to the wrong relay.
+ */
+export function resolveProfile(store, selector) {
+    if (selector !== undefined && selector !== "") {
+        const p = store.profiles[selector];
+        if (p === undefined) {
+            const known = Object.keys(store.profiles).sort().join(", ") || "(none)";
+            throw new Error(`profile '${selector}' does not exist (known: ${known}) — run 'pane config list'`);
+        }
+        return { name: selector, profile: p };
+    }
+    if (store.currentProfile !== undefined) {
+        const p = store.profiles[store.currentProfile];
+        if (p !== undefined)
+            return { name: store.currentProfile, profile: p };
+    }
+    return null;
+}

package/dist/upgrade.js

@@ -40,7 +40,7 @@ export function detectInstallMethod(entryPath) {
     }
     // npx caches the package under ~/Library/Caches/_npx (macOS) or
     // ~/.npm/_npx (Linux) and runs it from a node_modules inside that dir.
-    // Surface this distinctly from a real vendored install: with an npx
+    // Pane this distinctly from a real vendored install: with an npx
     // execution there is no project package.json owning the version and no
     // global to upgrade — the user runs `npx @paneui/cli@<version>` each
     // time, so the right answer is "ask the human / re-run with a newer

package/dist/version.js

@@ -1,11 +1,11 @@
 // Single source of truth for the CLI version string.
 //
 // - `pane --version` prints this verbatim.
-// - Every PaneClient construction passes it as `cliVersion`, which surfaces
+// - Every PaneClient construction passes it as `cliVersion`, which panes
 //   as the `x-pane-cli-version` header on every relay request — drives the
 //   relay's version-skew check (HTTP 426 `cli_upgrade_required`).
 //
 // 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.9";
+export const VERSION = "0.0.10";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@paneui/cli",
-  "version": "0.0.9",
-  "description": "Command-line client for the Pane relay: create surfaces, inspect state, send and watch events.",
+  "version": "0.0.10",
+  "description": "Command-line client for the Pane relay: create panes, inspect state, send and watch events.",
   "license": "MIT",
   "type": "module",
   "keywords": [
@@ -41,10 +41,12 @@
     "test:unit": "vitest run"
   },
   "dependencies": {
-    "@paneui/core": "^0.0.9"
+    "@paneui/core": "^0.0.10",
+    "qrcode-terminal": "^0.12.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",
+    "@types/qrcode-terminal": "^0.12.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.6"
   }

package/dist/commands/surface.js

@@ -1,118 +0,0 @@
-// `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");
-    }
-}