@cello-protocol/cli 0.0.44 → 0.0.45

package/dist/parity-commands.js

@@ -0,0 +1,317 @@
+/**
+ * DOD-CLI-PARITY-1 Phases 1-2 — every daemon capability that was MCP-only, reachable from `cello`.
+ *
+ * Bash is the universal agent adapter: with these commands any bash-capable agent (not just Claude
+ * Code or Hermes) operates a CELLO node — connect, send, receive, seal — with no MCP dependency.
+ *
+ * Each command is a THIN PASS-THROUGH: parse args → call the SAME daemon IPC handler the
+ * corresponding cello_* MCP tool calls → emit the response under the §3 contract (json-out.ts).
+ * No daemon changes, no second IPC client, no logic that the daemon owns (validation, tier bounds,
+ * agent_id resolution) is duplicated here — the CLI surfaces the daemon's verdict, verbatim.
+ *
+ * ── The per-invocation current-agent problem (why `use-agent` persists) ──────────────────────
+ * The daemon's "current agent" is PER-CONNECTION state. The MCP shim holds one long-lived socket,
+ * so `cello_use_agent` sticks for the whole session. The CLI is the opposite: a fresh process and a
+ * fresh connection per invocation, torn down microseconds later. A naive `cello use-agent alice`
+ * pass-through would therefore set state on a dying socket and report ok:true while changing NOTHING
+ * for the next command — a fabricated success of exactly the kind §3 forbids.
+ *
+ * So the selection is DURABLE: `use-agent` calls the real handler (which validates the agent and
+ * auto-starts it — AUTOSTART-1) and, only if the daemon says ok, persists the name. Every
+ * agent-scoped command then REPLAYS `cello_use_agent` on its new connection before dispatching.
+ * That is not a parallel path — it is the same replay the MCP proxy performs after a reconnect
+ * (ipc-proxy.ts invariant 1), reusing the existing handler.
+ *
+ * Agent resolution, in order: explicit `--agent` > the persisted selection > (omitted, so the
+ * daemon applies its own sole-online-agent fallback, and stays ambiguous → no_current_agent when
+ * two or more are online). If a replay FAILS, the command STOPS and surfaces that error — it never
+ * shrugs and lets the daemon's fallback quietly run the work as a different agent.
+ */
+import { join } from "node:path";
+import { readFile, writeFile, unlink } from "node:fs/promises";
+import { connectToDaemon, readLock } from "@cello-protocol/daemon";
+import { emitIpcResult, emitTransportError } from "./json-out.js";
+/** Where `cello use-agent` records the selection: a plain text file the operator can read/delete. */
+function currentAgentPath(celloDir) {
+    return join(celloDir, "current-agent");
+}
+/**
+ * The persisted agent selection, or undefined if none was ever made.
+ *
+ * ENOENT — never selected — is the ONLY swallowed error (review F4). A blanket catch here would let
+ * an unreadable file (EACCES, EISDIR, a corrupt mount) read as "no selection", after which the
+ * daemon's sole-online fallback would quietly run the command as whatever agent happens to be up:
+ * the operator's selection silently replaced by a different identity, exit 0. Anything that is not
+ * "the file isn't there" is a real failure and is thrown.
+ */
+export async function readCurrentAgent(celloDir) {
+    try {
+        const raw = (await readFile(currentAgentPath(celloDir), "utf8")).trim();
+        return raw.length > 0 ? raw : undefined;
+    }
+    catch (err) {
+        if (err?.code === "ENOENT")
+            return undefined; // never selected
+        throw err;
+    }
+}
+/**
+ * Forget the persisted selection. Called by `stop-agent` (review F1): the daemon clears an agent
+ * from every connection's current-agent state when it is stopped, so the CLI's durable mirror of
+ * that state must be cleared too. Leaving it behind was a genuine defect — see stopAgent().
+ */
+async function clearCurrentAgent(celloDir) {
+    try {
+        await unlink(currentAgentPath(celloDir));
+    }
+    catch (err) {
+        if (err?.code !== "ENOENT")
+            throw err;
+    }
+}
+async function writeCurrentAgent(celloDir, name) {
+    await writeFile(currentAgentPath(celloDir), name + "\n", "utf8");
+}
+/**
+ * Open a daemon connection, establish the current agent (if one is selected), run `fn`, and always
+ * close. Transport failures come back as structured JSON on stderr — so a bash agent branches on
+ * the same shape whether the daemon rejected the call or never received it.
+ */
+async function withDaemon(celloDir, opts, agentScoped, fn) {
+    const lock = await readLock(join(celloDir, "daemon.lock"));
+    if (!lock) {
+        return emitTransportError("daemon_not_running", "No daemon is running. Start it with 'cello login', then retry.", opts);
+    }
+    let client;
+    try {
+        client = await connectToDaemon(lock.socketPath);
+    }
+    catch (err) {
+        return emitTransportError("daemon_unreachable", `Could not connect to the daemon at ${lock.socketPath}: ${err instanceof Error ? err.message : String(err)}. It may be mid-shutdown — check 'cello status'.`, opts);
+    }
+    try {
+        await client.send("ipc.connect", { clientType: "cli" });
+        if (agentScoped) {
+            // Review F2 — an EMPTY --agent must never be treated as "no --agent". `--agent "$VAR"` with
+            // VAR unset yields "", which is not nullish: it would suppress the persisted selection, fail
+            // the truthiness check below, run NO replay, and let the daemon's sole-online fallback execute
+            // the command as whatever agent happened to be up — exit 0, wrong identity, silently. That is
+            // the exact misroute this module exists to prevent, and the bash idiom makes it likely.
+            if (opts.agent !== undefined && opts.agent.trim() === "") {
+                return emitTransportError("missing_agent_value", "--agent was given an empty value (an unset shell variable?). Name an agent explicitly, or omit --agent to use the selection from 'cello use-agent'.", opts);
+            }
+            const selected = opts.agent ?? (await readCurrentAgent(celloDir));
+            if (selected) {
+                // Review F1 — the replay must not RESURRECT a stopped agent. cello_use_agent auto-starts an
+                // offline agent (AUTOSTART-1), so replaying it blindly meant `cello stop-agent alice` could
+                // be silently undone by the very next read-only command (`cello inbox`), bringing alice back
+                // online and reachable with no signal. Stopping an agent is kill-switch-adjacent; a command
+                // that reads must never re-arm it. The MCP surface never does this — the daemon clears the
+                // agent from every connection on stop, and later calls get no_current_agent.
+                //
+                // So: only replay an agent that is ALREADY ONLINE. An offline selection fails loud, naming
+                // the remedy, rather than quietly starting it or quietly running as someone else.
+                if (!(await isAgentOnline(client, selected))) {
+                    return emitTransportError("selected_agent_offline", `Agent '${selected}' is not online, so this command was not run as it. Bring it online with 'cello start-agent ${selected}' (or select another with 'cello use-agent <name>'). It is NOT auto-started here: that would silently undo a deliberate 'cello stop-agent'.`, opts);
+                }
+                // The agent is online — claim it for this connection. A refusal (retired/unknown) stops the
+                // command: continuing would let the sole-online fallback run it as a DIFFERENT agent.
+                const used = (await client.send("cello_use_agent", { name: selected }));
+                if (used.ok !== true) {
+                    // Defensive: cello_use_agent is ok-bearing on every path today, but if it ever returned an
+                    // ok-less body, emitIpcResult would print IT as this command's successful result. Fail loud
+                    // on any shape that is not an explicit ok:false, rather than pass off the wrong body.
+                    if (used.ok === false)
+                        return emitIpcResult(used, opts);
+                    return emitTransportError("unexpected_replay_response", `Selecting agent '${selected}' returned an unrecognized response, so the command was not run. This is a daemon/CLI version mismatch — check 'cello status'.`, opts);
+                }
+            }
+            // No selection at all → send nothing, and let the daemon apply its own documented fallback
+            // (sole online agent; ambiguous → no_current_agent). Guessing here would misroute.
+        }
+        const result = await fn(client);
+        return emitIpcResult(result, opts);
+    }
+    catch (err) {
+        return emitTransportError("ipc_error", `The daemon call failed: ${err instanceof Error ? err.message : String(err)}`, opts);
+    }
+    finally {
+        client.close();
+    }
+}
+/**
+ * Is this agent currently ONLINE? Asked via cello_list_agents (a real handler, no new IPC path) so
+ * the replay can refuse to auto-start a stopped agent (review F1). Fails CLOSED: any unexpected
+ * shape reads as "not online", which fails the command loud rather than resurrecting an agent the
+ * operator deliberately stopped.
+ */
+async function isAgentOnline(client, name) {
+    const res = (await client.send("cello_list_agents"));
+    return (res.agents ?? []).some((a) => a.name === name && a.state === "online");
+}
+/** The common case: one IPC call, agent-scoped unless stated otherwise. */
+function ipcCommand(celloDir, method, params, opts, agentScoped = true) {
+    return withDaemon(celloDir, opts, agentScoped, async (client) => {
+        return (await client.send(method, params));
+    });
+}
+/** Drop undefined values so an omitted optional param is ABSENT, not an explicit `undefined`. */
+function defined(params) {
+    return Object.fromEntries(Object.entries(params).filter(([, v]) => v !== undefined));
+}
+/**
+ * The ONE place a CLI command's daemon IPC method is named (review T2).
+ *
+ * The registry's `ipcMethod` field is set FROM this map, and every function below dispatches FROM
+ * this map — so the field that DoD §9's parity test audits is, by construction, the literal that is
+ * actually sent. Previously the two were independent strings: the registry could say
+ * `cello_contact_set_moniker` while the code called `cello_contact_set_away`, and the audit — which
+ * only read the metadata — would happily pass. A comment-in-a-field is not a guarantee; this is.
+ */
+export const IPC_METHODS = {
+    agents: "cello_list_agents",
+    "start-agent": "cello_start_agent",
+    "stop-agent": "cello_stop_agent",
+    "use-agent": "cello_use_agent",
+    inbox: "cello_check_notifications",
+    transcript: "cello_get_transcript",
+    "sealed-receipt": "cello_get_sealed_receipt",
+    initiate: "cello_initiate_session",
+    send: "cello_send",
+    receive: "cello_receive",
+    "receive-session": "cello_receive_session",
+    close: "cello_close_session",
+    "await-session": "cello_await_session",
+    "contact-add": "cello_contact_add",
+    "contact-remove": "cello_contact_remove",
+    "contact-list": "cello_contact_list",
+    "contact-set-tier": "cello_contact_set_tier",
+    "contact-set-away": "cello_contact_set_away",
+    "contact-set-moniker": "cello_contact_set_moniker",
+};
+// ─── Group A: agent lifecycle ──────────────────────────────────────────────────────────────────
+/** `cello agents` → cello_list_agents. Daemon-wide, not agent-scoped. */
+export function listAgents(celloDir, opts) {
+    return ipcCommand(celloDir, IPC_METHODS.agents, {}, opts, false);
+}
+/** `cello start-agent <name>` → cello_start_agent. Brings an agent online WITHOUT claiming current. */
+export function startAgent(celloDir, name, opts) {
+    return ipcCommand(celloDir, IPC_METHODS["start-agent"], { name }, opts, false);
+}
+/**
+ * `cello stop-agent <name>` → cello_stop_agent.
+ *
+ * Also CLEARS the persisted selection when it names this agent (review F1). The daemon clears a
+ * stopped agent from every connection's current-agent state; the CLI's durable mirror of that state
+ * must follow, or the next command would try to act as an agent the operator just stopped.
+ */
+export async function stopAgent(celloDir, name, opts) {
+    const out = await ipcCommand(celloDir, IPC_METHODS["stop-agent"], { name }, opts, false);
+    if (out.exitCode === 0 && (await readCurrentAgent(celloDir)) === name) {
+        await clearCurrentAgent(celloDir);
+    }
+    return out;
+}
+/**
+ * `cello use-agent <name>` → cello_use_agent, and — only if the daemon accepts it — persists the
+ * selection so it survives this process. The handler auto-starts the agent if offline (AUTOSTART-1).
+ * A rejected selection is NEVER written: a later command must not silently act as an agent the
+ * daemon refused.
+ */
+export async function useAgent(celloDir, name, opts) {
+    const out = await ipcCommand(celloDir, IPC_METHODS["use-agent"], { name }, opts, false);
+    if (out.exitCode === 0)
+        await writeCurrentAgent(celloDir, name);
+    return out;
+}
+/** `cello inbox [--scope current|all]` → cello_check_notifications (the push-loss reconciler). */
+export function inbox(celloDir, opts) {
+    return ipcCommand(celloDir, IPC_METHODS.inbox, defined({ scope: opts.scope }), opts);
+}
+/** `cello transcript <session-id>` → cello_get_transcript (durable, survives a daemon restart). */
+export function transcript(celloDir, sessionId, opts) {
+    return ipcCommand(celloDir, IPC_METHODS.transcript, { session_id: sessionId }, opts);
+}
+/**
+ * `cello sealed-receipt <session-id>` → cello_get_sealed_receipt.
+ *
+ * NOT in the brief's mapping table, which listed cello_get_sealed_receipt as "already covered by
+ * `receipts`". It is not: `cello receipts <name>` calls cello_get_relay_receipts — a DIFFERENT
+ * handler (relay ordering receipts). The notarized bilateral SEAL receipt — the artifact the whole
+ * close ceremony exists to produce, and the one an arbitrator reads — had no CLI surface at all.
+ * Added under the standing rule: a real, non-stub handler with no CLI command gets one.
+ */
+export function sealedReceipt(celloDir, sessionId, opts) {
+    return ipcCommand(celloDir, IPC_METHODS["sealed-receipt"], { session_id: sessionId }, opts);
+}
+// Review F3: the WHOLE address book now speaks the §3 contract, not just the three new sub-verbs.
+// Previously add/remove/list/tier/away went through the legacy path (errors pretty-printed to
+// STDOUT, no --pretty) while the new set-moniker used the parity path (errors to stderr) — so a
+// bash script branching on stderr got DIFFERENT conventions between sub-verbs of the same command.
+// One command, one contract. (Behavior change, journaled: contact failures now print JSON on stderr
+// rather than stdout; the exit codes were already correct.)
+/** `cello contact add <pubkey>` → cello_contact_add. */
+export function contactAdd(celloDir, pubkey, opts) {
+    return ipcCommand(celloDir, IPC_METHODS["contact-add"], { pubkey }, opts);
+}
+/** `cello contact remove <pubkey>` → cello_contact_remove. */
+export function contactRemove(celloDir, pubkey, opts) {
+    return ipcCommand(celloDir, IPC_METHODS["contact-remove"], { pubkey }, opts);
+}
+/** `cello contact list` → cello_contact_list. */
+export function contactList(celloDir, opts) {
+    return ipcCommand(celloDir, IPC_METHODS["contact-list"], {}, opts);
+}
+/** `cello contact set-tier <pubkey> <tier>` → cello_contact_set_tier. */
+export function contactSetTier(celloDir, pubkey, tier, opts) {
+    return ipcCommand(celloDir, IPC_METHODS["contact-set-tier"], { pubkey, tier }, opts);
+}
+/** `cello contact set-away <pubkey> <message>` → cello_contact_set_away (empty message clears it). */
+export function contactSetAway(celloDir, pubkey, message, opts) {
+    return ipcCommand(celloDir, IPC_METHODS["contact-set-away"], { pubkey, message }, opts);
+}
+/** `cello contact set-moniker <pubkey> <moniker>` → cello_contact_set_moniker (per-CONTACT pet name). */
+export function contactSetMoniker(celloDir, pubkey, moniker, opts) {
+    return ipcCommand(celloDir, IPC_METHODS["contact-set-moniker"], { pubkey, moniker }, opts);
+}
+// ─── Group B: live conversation (mirrors the MCP params EXACTLY) ───────────────────────────────
+/** `cello initiate <target-pubkey>` → cello_initiate_session. Prints the session_id. */
+export function initiate(celloDir, targetPubkey, opts) {
+    return ipcCommand(celloDir, IPC_METHODS.initiate, { target_pubkey: targetPubkey }, opts);
+}
+/**
+ * `cello send <session-id> <message>` → cello_send.
+ *
+ * Honors read-before-write exactly as the MCP tool does: if the daemon returns session_not_current
+ * (with its cursor), that verdict is surfaced VERBATIM and the command exits non-zero. It is never
+ * auto-fixed by silently reading the transcript first — the operator/agent must catch up explicitly,
+ * because a send that "worked" after a hidden read is a send whose ordering guarantees are a fiction.
+ */
+export function send(celloDir, sessionId, content, opts) {
+    return ipcCommand(celloDir, "cello_send", defined({ session_id: sessionId, content, governance_decisions: opts.governanceDecisions }), opts);
+}
+/**
+ * `cello receive <session-id> [--since-seq N] [--timeout-ms N]` → cello_receive.
+ * Mirrors the MCP semantics exactly: with since_seq it is a stateless catch-up BATCH (no replay
+ * race, timeout ignored); without it, it BLOCKS for the next live message until timeout_ms.
+ */
+export function receive(celloDir, sessionId, opts) {
+    return ipcCommand(celloDir, "cello_receive", defined({ session_id: sessionId, timeout_ms: opts.timeoutMs, since_seq: opts.sinceSeq }), opts);
+}
+/** `cello receive-session <session-id> [--timeout-ms N]` → cello_receive_session. */
+export function receiveSession(celloDir, sessionId, opts) {
+    return ipcCommand(celloDir, "cello_receive_session", defined({ session_id: sessionId, timeout_ms: opts.timeoutMs }), opts);
+}
+/**
+ * `cello close <session-id> [--force]` → cello_close_session. Normally triggers the bilateral seal
+ * ceremony. --force is passed ONLY when asked for (mirroring the shim), since it forfeits the seal.
+ */
+export function closeSession(celloDir, sessionId, opts) {
+    const params = opts.force ? { session_id: sessionId, force: true } : { session_id: sessionId };
+    return ipcCommand(celloDir, IPC_METHODS.close, params, opts);
+}
+/** `cello await-session [--timeout-ms N]` → cello_await_session. Blocks for an inbound doorbell. */
+export function awaitSession(celloDir, opts) {
+    return ipcCommand(celloDir, IPC_METHODS["await-session"], defined({ timeout_ms: opts.timeoutMs }), opts);
+}
+//# sourceMappingURL=parity-commands.js.map

package/dist/parity-commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parity-commands.js","sourceRoot":"","sources":["../src/parity-commands.ts"],"names":[],"mappings":"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"}

package/dist/registry.d.ts

@@ -0,0 +1,69 @@
+/**
+ * DOD-CLI-PARITY-1 §4 — the command REGISTRY: the single source of truth for the `cello` CLI.
+ *
+ * Each entry carries { name, summary, help, flags, run }. Everything derives from this one table:
+ *  - dispatch (src/bin/cello.ts) — no switch to keep in sync,
+ *  - the `cello --help` described `Commands:` table — rendered from each entry's `summary`
+ *    (this is DOD-ONBOARD-HELP-1's remaining gap; the old surface was a pipe-delimited blob),
+ *  - per-command `cello <cmd> --help` — the pre-existing help text, moved here VERBATIM,
+ *  - the recognized-flag set used to reject unknown flags before dispatch.
+ *
+ * Consequence, and the reason for the refactor: the help table, per-command help, and dispatch
+ * CANNOT DRIFT, and adding a command FORCES adding its one-line summary.
+ */
+import type { Logger } from "@cello-protocol/daemon";
+/** What a command needs from the process to run. Injected so dispatch is testable in-process. */
+export interface CommandContext {
+    celloDir: string;
+    daemonBin: string;
+    logger: Logger;
+    /** Progress lines printed BEFORE the result (e.g. logout's "Shutting down…"). */
+    onProgress?: (line: string) => void;
+}
+/** The (stdout, stderr, exitCode) triple a command produces. See json-out.ts for the §3 contract. */
+export interface CliOutput {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export interface FlagSpec {
+    name: string;
+    /** The flag takes the NEXT argv token as its value (so a dash-prefixed value isn't misread). */
+    consumesValue?: boolean;
+}
+export interface CommandSpec {
+    name: string;
+    /** One line. Rendered as this command's row in the `cello --help` Commands: table. */
+    summary: string;
+    /** Full per-command help, printed by `cello <cmd> --help`. */
+    help: string;
+    flags?: readonly FlagSpec[];
+    /**
+     * The daemon IPC handler this command calls — i.e. the SAME handler the corresponding `cello_*`
+     * MCP tool calls. Recorded here so the parity claim (DoD §9: "every cello_* MCP tool has a cello
+     * command calling the same IPC handler") is AUDITABLE from the registry itself rather than by
+     * reading each implementation. Absent for commands that are not a single IPC call (login, logout,
+     * install) or that route to sub-handlers (contact, settings, moniker, telegram).
+     */
+    ipcMethod?: string;
+    /**
+     * True for commands that honor the §3 bash-adapter contract (JSON to stdout, structured error
+     * VERBATIM to stderr, exit code branching on ok). Such commands automatically accept `--pretty`.
+     */
+    jsonOut?: boolean;
+    run(ctx: CommandContext, args: string[]): Promise<CliOutput>;
+}
+export declare const COMMANDS: readonly CommandSpec[];
+export declare function commandNames(): string[];
+export declare function findCommand(name: string): CommandSpec | undefined;
+/**
+ * The flags a command recognizes, derived from its registry entry. `--pretty` is granted
+ * automatically to every command honoring the §3 JSON contract, so it can never be forgotten.
+ */
+export declare function flagsFor(name: string): ReadonlyMap<string, FlagSpec>;
+/**
+ * DOD-ONBOARD-HELP-1: render the described `Commands:` table — each command on its own line with
+ * its one-line summary (git / `claude --help` style). Arguments stay in per-command `--help`.
+ */
+export declare function renderCommandsTable(): string;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAiDrD,iGAAiG;AACjG,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AAED,qGAAqG;AACrG,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,gGAAgG;IAChG,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC5B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CAC9D;AAgFD,eAAO,MAAM,QAAQ,EAAE,SAAS,WAAW,EA6f1C,CAAC;AAEF,wBAAgB,YAAY,IAAI,MAAM,EAAE,CAEvC;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEjE;AAgBD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAOpE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAI5C"}