@cleocode/cleo 2026.4.9 → 2026.4.11

package/dist/cli/commands/adr.js

@@ -0,0 +1,79 @@
+/**
+ * CLI adr command group — ADR validation, listing, sync, and search.
+ *
+ * Thin CLI wrapper delegating to dispatch layer (admin domain).
+ * Core logic lives in src/core/adrs/.
+ *
+ * Commands:
+ *   ct adr validate              — validate frontmatter on all .cleo/adrs/*.md
+ *   ct adr list [--status]       — list ADRs with optional status filter
+ *   ct adr show <id>             — show single ADR by ID (e.g., ADR-017)
+ *   ct adr sync                  — sync .cleo/adrs/ into architecture_decisions DB
+ *   ct adr find <query>          — fuzzy search ADRs by title, summary, keywords, topics
+ *
+ * Dispatch equivalents:
+ *   mutate({domain:'admin', operation:'adr.validate'})
+ *   query({domain:'admin',  operation:'adr.list',  params:{status?}})
+ *   query({domain:'admin',  operation:'adr.show',  params:{adrId}})
+ *   mutate({domain:'admin', operation:'adr.sync'})
+ *   query({domain:'admin',  operation:'adr.find',  params:{query, topics?, keywords?, status?}})
+ *
+ * @see ADR-017 §5.1 for canonical frontmatter spec
+ * @see ADR-017 §5.4 for cognitive search spec
+ * @see schemas/adr-frontmatter.schema.json for validation schema
+ */
+import { dispatchFromCli } from '../../dispatch/adapters/cli.js';
+export function registerAdrCommand(program) {
+    const adr = program
+        .command('adr')
+        .description('Manage and validate Architecture Decision Records in .cleo/adrs/');
+    // ct adr validate
+    adr
+        .command('validate')
+        .description('Validate frontmatter on all .cleo/adrs/*.md files against ADR-017 schema')
+        .action(async () => {
+        await dispatchFromCli('mutate', 'admin', 'adr.sync', { validate: true }, { command: 'adr validate', operation: 'admin.adr.sync' });
+    });
+    // ct adr list
+    adr
+        .command('list')
+        .description('List ADRs from .cleo/adrs/')
+        .option('--status <status>', 'Filter by status: proposed | accepted | superseded | deprecated')
+        .option('--since <date>', 'Filter to ADRs created on or after YYYY-MM-DD')
+        .action(async (opts) => {
+        await dispatchFromCli('query', 'admin', 'adr.find', {
+            status: opts['status'],
+            since: opts['since'],
+        }, { command: 'adr list', operation: 'admin.adr.find' });
+    });
+    // ct adr show <id>
+    adr
+        .command('show <adrId>')
+        .description('Show full details for a single ADR (e.g., ct adr show ADR-017)')
+        .action(async (adrId) => {
+        await dispatchFromCli('query', 'admin', 'adr.show', { adrId }, { command: 'adr show', operation: 'admin.adr.show' });
+    });
+    // ct adr sync
+    adr
+        .command('sync')
+        .description('Sync .cleo/adrs/ markdown files into the architecture_decisions DB table')
+        .action(async () => {
+        await dispatchFromCli('mutate', 'admin', 'adr.sync', {}, { command: 'adr sync', operation: 'admin.adr.sync' });
+    });
+    // ct adr find <query>
+    adr
+        .command('find <query>')
+        .description('Fuzzy search ADRs by title, summary, keywords, and topics')
+        .option('--topics <topics>', 'Filter by topics (comma-separated domain tags)')
+        .option('--keywords <keywords>', 'Filter by keywords (comma-separated tags)')
+        .option('--status <status>', 'Filter by status: proposed | accepted | superseded | deprecated')
+        .action(async (query, opts) => {
+        await dispatchFromCli('query', 'admin', 'adr.find', {
+            query,
+            topics: opts['topics'],
+            keywords: opts['keywords'],
+            status: opts['status'],
+        }, { command: 'adr find', operation: 'admin.adr.find' });
+    });
+}
+//# sourceMappingURL=adr.js.map

package/dist/cli/commands/adr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adr.js","sourceRoot":"","sources":["../../../src/cli/commands/adr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAGjE,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,MAAM,GAAG,GAAG,OAAO;SAChB,OAAO,CAAC,KAAK,CAAC;SACd,WAAW,CAAC,kEAAkE,CAAC,CAAC;IAEnF,kBAAkB;IAClB,GAAG;SACA,OAAO,CAAC,UAAU,CAAC;SACnB,WAAW,CAAC,0EAA0E,CAAC;SACvF,MAAM,CAAC,KAAK,IAAI,EAAE;QACjB,MAAM,eAAe,CACnB,QAAQ,EACR,OAAO,EACP,UAAU,EACV,EAAE,QAAQ,EAAE,IAAI,EAAE,EAClB,EAAE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,gBAAgB,EAAE,CACzD,CAAC;IACJ,CAAC,CAAC,CAAC;IAEL,cAAc;IACd,GAAG;SACA,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,4BAA4B,CAAC;SACzC,MAAM,CAAC,mBAAmB,EAAE,iEAAiE,CAAC;SAC9F,MAAM,CAAC,gBAAgB,EAAE,+CAA+C,CAAC;SACzE,MAAM,CAAC,KAAK,EAAE,IAA6B,EAAE,EAAE;QAC9C,MAAM,eAAe,CACnB,OAAO,EACP,OAAO,EACP,UAAU,EACV;YACE,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAuB;YAC5C,KAAK,EAAE,IAAI,CAAC,OAAO,CAAuB;SAC3C,EACD,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,gBAAgB,EAAE,CACrD,CAAC;IACJ,CAAC,CAAC,CAAC;IAEL,mBAAmB;IACnB,GAAG;SACA,OAAO,CAAC,cAAc,CAAC;SACvB,WAAW,CAAC,gEAAgE,CAAC;SAC7E,MAAM,CAAC,KAAK,EAAE,KAAa,EAAE,EAAE;QAC9B,MAAM,eAAe,CACnB,OAAO,EACP,OAAO,EACP,UAAU,EACV,EAAE,KAAK,EAAE,EACT,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,gBAAgB,EAAE,CACrD,CAAC;IACJ,CAAC,CAAC,CAAC;IAEL,cAAc;IACd,GAAG;SACA,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,0EAA0E,CAAC;SACvF,MAAM,CAAC,KAAK,IAAI,EAAE;QACjB,MAAM,eAAe,CACnB,QAAQ,EACR,OAAO,EACP,UAAU,EACV,EAAE,EACF,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,gBAAgB,EAAE,CACrD,CAAC;IACJ,CAAC,CAAC,CAAC;IAEL,sBAAsB;IACtB,GAAG;SACA,OAAO,CAAC,cAAc,CAAC;SACvB,WAAW,CAAC,2DAA2D,CAAC;SACxE,MAAM,CAAC,mBAAmB,EAAE,gDAAgD,CAAC;SAC7E,MAAM,CAAC,uBAAuB,EAAE,2CAA2C,CAAC;SAC5E,MAAM,CAAC,mBAAmB,EAAE,iEAAiE,CAAC;SAC9F,MAAM,CAAC,KAAK,EAAE,KAAa,EAAE,IAA6B,EAAE,EAAE;QAC7D,MAAM,eAAe,CACnB,OAAO,EACP,OAAO,EACP,UAAU,EACV;YACE,KAAK;YACL,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAuB;YAC5C,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAuB;YAChD,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAuB;SAC7C,EACD,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,gBAAgB,EAAE,CACrD,CAAC;IACJ,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/cli/commands/agent-profile-status.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Pure helper for computing the human-readable `profile` status string
+ * surfaced by `cleo agent start`.
+ *
+ * Extracted from `agent.ts` so it can be unit-tested without spinning up
+ * the full daemon, the SignalDock registry, or the Pi runtime. The
+ * helper has zero side effects and accepts only plain inputs — that is
+ * the entire point of pulling it out.
+ *
+ * **Daemon vs. Pi session.** The status this helper produces describes
+ * what `cleo agent start` did with the on-disk `.cant` profile file. It
+ * is purely informational. The daemon NEVER interprets the profile —
+ * profile-driven workflow execution lives inside the Pi extension at
+ * `packages/cleo/templates/cleoos-hub/pi-extensions/cant-bridge.ts`,
+ * not inside the daemon process. See ADR-035 §D5 (Option Y addendum)
+ * for the rationale.
+ *
+ * @see ../commands/agent.ts
+ * @see .cleo/adrs/ADR-035-pi-v2-v3-harness.md §D5 + Addendum
+ *
+ * @packageDocumentation
+ */
+/**
+ * Outcome of validating a `.cant` profile via `@cleocode/cant`'s
+ * `validate()` function (when available in the current build).
+ *
+ * @public
+ */
+export interface ProfileValidation {
+    /** `true` when the parser produced zero diagnostics. */
+    readonly valid: boolean;
+    /** Diagnostic messages surfaced by the parser, in order. */
+    readonly errors: readonly string[];
+}
+/**
+ * Possible status values surfaced by `cleo agent start` for the
+ * profile-loading step.
+ *
+ * - `'none'` — no `.cant` file at the resolved path; the daemon starts
+ *   without a profile loaded.
+ * - `'loaded (unvalidated)'` — file existed and was read into memory,
+ *   but the optional `@cleocode/cant` validator was not available in
+ *   this build, so we cannot say whether it parses cleanly.
+ * - `'validated'` — file existed, the validator ran, and the parser
+ *   produced zero diagnostics.
+ * - `` `invalid (${N} errors)` `` — file existed, the validator ran,
+ *   and the parser surfaced N diagnostics. The N is the diagnostic
+ *   count, not a severity score.
+ *
+ * The status is purely informational. None of these branches change
+ * the daemon's behaviour — the daemon polls SignalDock either way.
+ * Profile-driven behaviour runs inside Pi sessions via the
+ * `cant-bridge.ts` Pi extension.
+ *
+ * @public
+ */
+export type ProfileStatus = 'none' | 'loaded (unvalidated)' | 'validated' | `invalid (${number} errors)`;
+/**
+ * Compute the human-readable profile status string for the
+ * `cleo agent start` command output.
+ *
+ * @remarks
+ * This is a pure function with three branches:
+ *
+ * 1. `profile === null` → `'none'` — no file existed at the resolved path.
+ * 2. `validation === null` → `'loaded (unvalidated)'` — file was read
+ *    but the optional validator was not available.
+ * 3. `validation.valid === true` → `'validated'`
+ * 4. `validation.valid === false` → `` `invalid (${N} errors)` ``
+ *    where N is `validation.errors.length`.
+ *
+ * The function NEVER consults `createRuntime`, the registry, or any
+ * other side-effecting subsystem. It exists exactly so the
+ * profile-status branch can be exercised in unit tests without booting
+ * the daemon.
+ *
+ * @param profile - The contents of the `.cant` file, or `null` when no
+ *   file was present at the resolved path.
+ * @param validation - The result of running `@cleocode/cant`'s
+ *   `validate()` against `profile`, or `null` when the validator was
+ *   not available in the current build.
+ * @returns A status string suitable for the `profile` field of the
+ *   `cleo agent start` LAFS envelope.
+ *
+ * @example
+ * ```typescript
+ * computeProfileStatus(null, null);                        // 'none'
+ * computeProfileStatus('agent foo:', null);                // 'loaded (unvalidated)'
+ * computeProfileStatus('agent foo:', { valid: true, errors: [] });
+ * // 'validated'
+ * computeProfileStatus('agent foo:', { valid: false, errors: ['e1', 'e2'] });
+ * // 'invalid (2 errors)'
+ * ```
+ *
+ * @public
+ */
+export declare function computeProfileStatus(profile: string | null, validation: ProfileValidation | null): ProfileStatus;
+//# sourceMappingURL=agent-profile-status.d.ts.map

package/dist/cli/commands/agent-profile-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-profile-status.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/agent-profile-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,sBAAsB,GACtB,WAAW,GACX,YAAY,MAAM,UAAU,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,UAAU,EAAE,iBAAiB,GAAG,IAAI,GACnC,aAAa,CAKf"}

package/dist/cli/commands/agent-profile-status.js

@@ -0,0 +1,71 @@
+/**
+ * Pure helper for computing the human-readable `profile` status string
+ * surfaced by `cleo agent start`.
+ *
+ * Extracted from `agent.ts` so it can be unit-tested without spinning up
+ * the full daemon, the SignalDock registry, or the Pi runtime. The
+ * helper has zero side effects and accepts only plain inputs — that is
+ * the entire point of pulling it out.
+ *
+ * **Daemon vs. Pi session.** The status this helper produces describes
+ * what `cleo agent start` did with the on-disk `.cant` profile file. It
+ * is purely informational. The daemon NEVER interprets the profile —
+ * profile-driven workflow execution lives inside the Pi extension at
+ * `packages/cleo/templates/cleoos-hub/pi-extensions/cant-bridge.ts`,
+ * not inside the daemon process. See ADR-035 §D5 (Option Y addendum)
+ * for the rationale.
+ *
+ * @see ../commands/agent.ts
+ * @see .cleo/adrs/ADR-035-pi-v2-v3-harness.md §D5 + Addendum
+ *
+ * @packageDocumentation
+ */
+/**
+ * Compute the human-readable profile status string for the
+ * `cleo agent start` command output.
+ *
+ * @remarks
+ * This is a pure function with three branches:
+ *
+ * 1. `profile === null` → `'none'` — no file existed at the resolved path.
+ * 2. `validation === null` → `'loaded (unvalidated)'` — file was read
+ *    but the optional validator was not available.
+ * 3. `validation.valid === true` → `'validated'`
+ * 4. `validation.valid === false` → `` `invalid (${N} errors)` ``
+ *    where N is `validation.errors.length`.
+ *
+ * The function NEVER consults `createRuntime`, the registry, or any
+ * other side-effecting subsystem. It exists exactly so the
+ * profile-status branch can be exercised in unit tests without booting
+ * the daemon.
+ *
+ * @param profile - The contents of the `.cant` file, or `null` when no
+ *   file was present at the resolved path.
+ * @param validation - The result of running `@cleocode/cant`'s
+ *   `validate()` against `profile`, or `null` when the validator was
+ *   not available in the current build.
+ * @returns A status string suitable for the `profile` field of the
+ *   `cleo agent start` LAFS envelope.
+ *
+ * @example
+ * ```typescript
+ * computeProfileStatus(null, null);                        // 'none'
+ * computeProfileStatus('agent foo:', null);                // 'loaded (unvalidated)'
+ * computeProfileStatus('agent foo:', { valid: true, errors: [] });
+ * // 'validated'
+ * computeProfileStatus('agent foo:', { valid: false, errors: ['e1', 'e2'] });
+ * // 'invalid (2 errors)'
+ * ```
+ *
+ * @public
+ */
+export function computeProfileStatus(profile, validation) {
+    if (profile === null)
+        return 'none';
+    if (validation === null)
+        return 'loaded (unvalidated)';
+    if (validation.valid)
+        return 'validated';
+    return `invalid (${validation.errors.length} errors)`;
+}
+//# sourceMappingURL=agent-profile-status.js.map

package/dist/cli/commands/agent-profile-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-profile-status.js","sourceRoot":"","sources":["../../../src/cli/commands/agent-profile-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA2CH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAsB,EACtB,UAAoC;IAEpC,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IACpC,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,sBAAsB,CAAC;IACvD,IAAI,UAAU,CAAC,KAAK;QAAE,OAAO,WAAW,CAAC;IACzC,OAAO,YAAY,UAAU,CAAC,MAAM,CAAC,MAAM,UAAU,CAAC;AACxD,CAAC"}

package/dist/cli/commands/agent.d.ts

@@ -0,0 +1,38 @@
+/**
+ * CLI agent command group — agent credential management (unified registry).
+ *
+ * Provides:
+ *   cleo agent register   — register a new agent credential
+ *   cleo agent list       — list all registered agent credentials
+ *   cleo agent get <id>   — get a specific agent credential
+ *   cleo agent remove <id> — remove an agent credential
+ *   cleo agent rotate-key <id> — rotate an agent's API key
+ *   cleo agent poll       — one-shot message check
+ *   cleo agent send       — send a message to an agent or conversation
+ *   cleo agent start      — start the daemon poller for an agent
+ *
+ * **Daemon vs. Pi session — important distinction.** The daemon spawned
+ * by `cleo agent start` ONLY polls SignalDock for inbound messages and
+ * keeps the cloud status indicator green. It does NOT execute CANT
+ * workflow profiles inside the daemon process. CANT workflow execution
+ * (sessions, parallel arms, conditionals, approval gates, discretion
+ * evaluation, etc.) lives entirely inside the
+ * `cant-bridge.ts` Pi extension at
+ * `packages/cleo/templates/cleoos-hub/pi-extensions/cant-bridge.ts`,
+ * which interprets `.cant` files via shell-out to the `cleo cant`
+ * command family. Operators who want profile-driven behaviour should
+ * start a Pi session and use `/cant:load <file>` followed by
+ * `/cant:run <file> <workflowName>`. The daemon and the Pi session are
+ * distinct runtimes with distinct purposes, by design (see ADR-035 §D5
+ * "Option Y" addendum).
+ *
+ * @see docs/specs/SIGNALDOCK-UNIFIED-AGENT-REGISTRY.md Section 3.4
+ * @see .cleo/adrs/ADR-035-pi-v2-v3-harness.md §D5 + Addendum
+ * @task T178
+ */
+import type { ShimCommand as Command } from '../commander-shim.js';
+/**
+ * Register the `cleo agent` command group.
+ */
+export declare function registerAgentCommand(program: Command): void;
+//# sourceMappingURL=agent.d.ts.map

package/dist/cli/commands/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AASH,OAAO,KAAK,EAAE,WAAW,IAAI,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAInE;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAi2C3D"}