@cello-protocol/cli 0.0.44 → 0.0.46

package/dist/registry.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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;
+}
+/**
+ * DOD-ONBOARD-HELP-1 §1 — the help is GROUPED, not alphabetical, and the groups render in this
+ * order. A new user reads it top-to-bottom as the order they will actually do things: get set up,
+ * bring an agent online, hold a conversation, then look at what it produced.
+ */
+export declare const GROUP_ORDER: readonly ["Setup", "Agents", "Messaging", "Sessions & receipts", "Contacts", "Other"];
+export type CommandGroup = (typeof GROUP_ORDER)[number];
+export interface CommandSpec {
+    name: string;
+    /**
+     * Which section of `cello --help` this command appears under. Registry metadata, so the table
+     * cannot drift from dispatch — adding a command FORCES choosing where a reader will find it.
+     * Within a group, commands render in DECLARATION order (logical, not alphabetical).
+     */
+    group: CommandGroup;
+    /** 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 §1: render the `Commands:` table GROUPED and in logical order.
+ *
+ * Flat-and-arbitrary was the reopen: `register` appeared before `create-agent`, so the table
+ * literally listed step 2 above step 1. Sections in GROUP_ORDER, commands in declaration order
+ * within each — the order a reader would actually do them. Name column is padded across the WHOLE
+ * table (not per group) so the summaries line up as one column down the page.
+ */
+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;;;;GAIG;AACH,eAAO,MAAM,WAAW,uFAOd,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,KAAK,EAAE,YAAY,CAAC;IACpB,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,EA8lB1C,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;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAS5C"}