@ouro.bot/cli 0.1.0-alpha.302 → 0.1.0-alpha.303

package/changelog.json

@@ -1,6 +1,12 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.303",
+      "changes": [
+        "feat(cli): overhaul CLI help and error handling. `ouro --help` now shows commands grouped into 9 categories (Lifecycle, Agents, Chat, Tasks, Habits, Friends, Auth, Internal, System) instead of a flat wall of text. `ouro help <command>` and `ouro <command> --help` show per-command help with description, usage syntax, subcommands, and an example. Unknown commands get Levenshtein-based typo suggestions when distance <= 2 (e.g., `ouro stauts` -> `Did you mean 'status'?`). `ouro up` now prints progress messages: 'Checking for updates...' -> 'Installing <version>...' or 'Up to date.' -> 'Starting daemon...'. New command metadata registry in `src/heart/daemon/cli-help.ts` covers 32 commands. 50+ new tests at 100% coverage on all new code."
+      ]
+    },
     {
       "version": "0.1.0-alpha.302",
       "changes": [

package/dist/heart/daemon/cli-exec.js

@@ -66,6 +66,7 @@ const auth_flow_1 = require("../auth/auth-flow");
 const ouro_version_manager_1 = require("../versioning/ouro-version-manager");
 const cli_parse_1 = require("./cli-parse");
 const cli_parse_2 = require("./cli-parse");
+const cli_help_1 = require("./cli-help");
 const cli_render_1 = require("./cli-render");
 const cli_defaults_1 = require("./cli-defaults");
 const doctor_1 = require("./doctor");
@@ -647,7 +648,7 @@ function resolveClonePath(options, checkExists, deps) {
 // ── Main CLI execution ──
 async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDeps)()) {
     if (args.length === 1 && (args[0] === "--help" || args[0] === "-h")) {
-        const text = (0, cli_parse_2.usage)();
+        const text = (0, cli_help_1.getGroupedHelp)();
         deps.writeStdout(text);
         return text;
     }
@@ -725,6 +726,13 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
         message: "ouro CLI command invoked",
         meta: { kind: command.kind },
     });
+    if (command.kind === "help") {
+        const text = command.command
+            ? ((0, cli_help_1.getCommandHelp)(command.command) ?? `Unknown command: ${command.command}\n\n${(0, cli_help_1.getGroupedHelp)()}`)
+            : (0, cli_help_1.getGroupedHelp)();
+        deps.writeStdout(text);
+        return text;
+    }
     if (command.kind === "bluebubbles.replay") {
         const { replayBlueBubblesMessage, formatBlueBubblesReplayText } = await Promise.resolve().then(() => __importStar(require("../../senses/bluebubbles/replay")));
         const replay = await replayBlueBubblesMessage({
@@ -773,10 +781,12 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
         const linkedVersionBeforeUp = deps.getCurrentCliVersion?.() ?? null;
         // ── versioned CLI update check ──
         if (deps.checkForCliUpdate) {
+            deps.writeStdout("checking for updates...");
             let pendingReExec = false;
             try {
                 const updateResult = await deps.checkForCliUpdate();
                 if (updateResult.available && updateResult.latestVersion) {
+                    deps.writeStdout(`installing ${updateResult.latestVersion}...`);
                     /* v8 ignore next -- fallback: getCurrentCliVersion always injected in tests @preserve */
                     const currentVersion = linkedVersionBeforeUp ?? "unknown";
                     await deps.installCliVersion(updateResult.latestVersion);
@@ -804,6 +814,9 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
             if (pendingReExec) {
                 deps.reExecFromNewVersion(args);
             }
+            else {
+                deps.writeStdout("up to date.");
+            }
         }
         await performSystemSetup(deps);
         // Track whether we've already printed the "ouro updated to" message
@@ -873,6 +886,7 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
             const count = agents.length;
             deps.writeStdout(`updated ${count} agent${count === 1 ? "" : "s"} to runtime ${to}${fromStr}`);
         }
+        deps.writeStdout("starting daemon...");
         const daemonResult = await ensureDaemonRunning(deps);
         deps.writeStdout(daemonResult.message);
         // Persist boot startup AFTER daemon is running — bootstrap is safe now

package/dist/heart/daemon/cli-help.js

@@ -0,0 +1,306 @@
+"use strict";
+/**
+ * CLI help system — command registry, grouped help output, and per-command help.
+ *
+ * Pure data + formatting: no side effects, no daemon communication.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMAND_REGISTRY = void 0;
+exports.levenshteinDistance = levenshteinDistance;
+exports.suggestCommand = suggestCommand;
+exports.getGroupedHelp = getGroupedHelp;
+exports.getCommandHelp = getCommandHelp;
+// ── Registry ──
+exports.COMMAND_REGISTRY = {
+    up: {
+        category: "Lifecycle",
+        description: "Start the ouro daemon (default command)",
+        usage: "ouro [up]",
+        example: "ouro up",
+    },
+    stop: {
+        category: "Lifecycle",
+        description: "Stop the running daemon",
+        usage: "ouro stop",
+        example: "ouro stop",
+    },
+    down: {
+        category: "Lifecycle",
+        description: "Stop the running daemon (alias for stop)",
+        usage: "ouro down",
+        example: "ouro down",
+    },
+    status: {
+        category: "Lifecycle",
+        description: "Show daemon status",
+        usage: "ouro status",
+        example: "ouro status",
+    },
+    logs: {
+        category: "Lifecycle",
+        description: "View or prune daemon logs",
+        usage: "ouro logs [prune]",
+        example: "ouro logs",
+        subcommands: ["prune"],
+    },
+    dev: {
+        category: "Lifecycle",
+        description: "Start daemon in development mode from a local repo",
+        usage: "ouro dev [--repo-path <path>] [--clone [--clone-path <path>]]",
+        example: "ouro dev --repo-path ~/code/ouroboros",
+    },
+    hatch: {
+        category: "Lifecycle",
+        description: "Create a new agent",
+        usage: "ouro hatch [--agent <name>] [--human <name>] [--provider <provider>]",
+        example: "ouro hatch --agent Sprout --human Ari --provider anthropic",
+    },
+    rollback: {
+        category: "Lifecycle",
+        description: "Roll back to a previous CLI version",
+        usage: "ouro rollback [<version>]",
+        example: "ouro rollback 0.1.0-alpha.250",
+    },
+    versions: {
+        category: "Lifecycle",
+        description: "List installed CLI versions",
+        usage: "ouro versions",
+        example: "ouro versions",
+    },
+    doctor: {
+        category: "Lifecycle",
+        description: "Run diagnostic checks on the ouro installation",
+        usage: "ouro doctor",
+        example: "ouro doctor",
+    },
+    outlook: {
+        category: "Agents",
+        description: "Show the agent's current outlook",
+        usage: "ouro outlook [--json]",
+        example: "ouro outlook --json",
+    },
+    whoami: {
+        category: "Agents",
+        description: "Show current agent identity info",
+        usage: "ouro whoami [--agent <name>]",
+        example: "ouro whoami",
+    },
+    config: {
+        category: "Agents",
+        description: "View or change agent configuration",
+        usage: "ouro config <subcommand> --agent <name>",
+        example: "ouro config models --agent ouroboros",
+        subcommands: ["model", "models"],
+    },
+    changelog: {
+        category: "Agents",
+        description: "View the agent changelog",
+        usage: "ouro changelog [--from <version>] [--agent <name>]",
+        example: "ouro changelog --from 0.1.0-alpha.250",
+    },
+    chat: {
+        category: "Chat",
+        description: "Open an interactive chat session with an agent",
+        usage: "ouro chat <agent>",
+        example: "ouro chat ouroboros",
+    },
+    msg: {
+        category: "Chat",
+        description: "Send a single message to an agent",
+        usage: "ouro msg --to <agent> [--session <id>] [--task <ref>] <message>",
+        example: "ouro msg --to ouroboros hello there",
+    },
+    task: {
+        category: "Tasks",
+        description: "Manage agent tasks",
+        usage: "ouro task <subcommand> [--agent <name>]",
+        example: "ouro task board",
+        subcommands: ["board", "create", "update", "show", "actionable", "deps", "sessions", "fix"],
+    },
+    poke: {
+        category: "Tasks",
+        description: "Poke an agent about a task or habit",
+        usage: "ouro poke <agent> --task <task-id> | --habit <name>",
+        example: "ouro poke ouroboros --task abc123",
+    },
+    reminder: {
+        category: "Tasks",
+        description: "Create reminders for an agent",
+        usage: "ouro reminder create <title> --body <body> [--at <iso>] [--cadence <interval>]",
+        example: "ouro reminder create standup --body 'daily standup' --cadence '1d'",
+        subcommands: ["create"],
+    },
+    habit: {
+        category: "Habits",
+        description: "Manage agent habits",
+        usage: "ouro habit <subcommand> [--agent <name>]",
+        example: "ouro habit list",
+        subcommands: ["list", "create", "poke"],
+    },
+    friend: {
+        category: "Friends",
+        description: "Manage agent friends and identity links",
+        usage: "ouro friend <subcommand> [--agent <name>]",
+        example: "ouro friend list",
+        subcommands: ["list", "show", "create", "update", "link", "unlink"],
+    },
+    link: {
+        category: "Friends",
+        description: "Link an external identity to an agent friend",
+        usage: "ouro link <agent> --friend <id> --provider <provider> --external-id <eid>",
+        example: "ouro link ouroboros --friend f1 --provider aad --external-id user@example.com",
+    },
+    auth: {
+        category: "Auth",
+        description: "Set up, verify, or switch agent credentials",
+        usage: "ouro auth [verify|switch] --agent <name> [--provider <provider>]",
+        example: "ouro auth --agent ouroboros",
+        subcommands: ["verify", "switch"],
+    },
+    thoughts: {
+        category: "Internal",
+        description: "View agent inner dialog thoughts",
+        usage: "ouro thoughts [--last <n>] [--json] [--follow] [--agent <name>]",
+        example: "ouro thoughts --last 5 --follow",
+    },
+    inner: {
+        category: "Internal",
+        description: "Show inner dialog status",
+        usage: "ouro inner [--agent <name>]",
+        example: "ouro inner",
+    },
+    attention: {
+        category: "Internal",
+        description: "View agent attention items",
+        usage: "ouro attention [show <id>|history] [--agent <name>]",
+        example: "ouro attention history",
+        subcommands: ["show", "history"],
+    },
+    session: {
+        category: "Internal",
+        description: "Manage agent sessions",
+        usage: "ouro session list [--agent <name>]",
+        example: "ouro session list",
+        subcommands: ["list"],
+    },
+    mcp: {
+        category: "System",
+        description: "Interact with MCP servers",
+        usage: "ouro mcp <subcommand>",
+        example: "ouro mcp list",
+        subcommands: ["list", "call"],
+    },
+    "mcp-serve": {
+        category: "System",
+        description: "Start an MCP server for dev tool integration",
+        usage: "ouro mcp-serve --agent <name> [--friend <id>]",
+        example: "ouro mcp-serve --agent ouroboros",
+    },
+    setup: {
+        category: "System",
+        description: "Register MCP server and hooks for a dev tool",
+        usage: "ouro setup --tool <claude-code|codex> --agent <name>",
+        example: "ouro setup --tool claude-code --agent ouroboros",
+    },
+    hook: {
+        category: "System",
+        description: "Fire a dev tool lifecycle hook",
+        usage: "ouro hook <event> --agent <name>",
+        example: "ouro hook session-start --agent ouroboros",
+    },
+    bluebubbles: {
+        category: "System",
+        description: "BlueBubbles integration commands",
+        usage: "ouro bluebubbles replay --agent <name> --message-guid <guid> [--event-type <type>] [--json]",
+        example: "ouro bluebubbles replay --agent ouroboros --message-guid abc123",
+        subcommands: ["replay"],
+    },
+};
+// ── Levenshtein distance ──
+function levenshteinDistance(a, b) {
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const matrix = [];
+    for (let i = 0; i <= a.length; i++) {
+        matrix[i] = [i];
+    }
+    for (let j = 0; j <= b.length; j++) {
+        matrix[0][j] = j;
+    }
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            matrix[i][j] = Math.min(matrix[i - 1][j] + 1, // deletion
+            matrix[i][j - 1] + 1, // insertion
+            matrix[i - 1][j - 1] + cost);
+        }
+    }
+    return matrix[a.length][b.length];
+}
+// ── Command suggestion ──
+function suggestCommand(input) {
+    if (!input)
+        return null;
+    let bestMatch = null;
+    let bestDistance = Infinity;
+    for (const name of Object.keys(exports.COMMAND_REGISTRY)) {
+        const distance = levenshteinDistance(input, name);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            bestMatch = name;
+        }
+    }
+    return bestDistance <= 2 ? bestMatch : null;
+}
+// ── Category display order ──
+const CATEGORY_ORDER = [
+    "Lifecycle",
+    "Agents",
+    "Chat",
+    "Tasks",
+    "Habits",
+    "Friends",
+    "Auth",
+    "Internal",
+    "System",
+];
+// ── Grouped help output ──
+function getGroupedHelp() {
+    const lines = ["Usage: ouro <command> [options]", ""];
+    for (const category of CATEGORY_ORDER) {
+        lines.push(`  ${category}:`);
+        for (const [name, entry] of Object.entries(exports.COMMAND_REGISTRY)) {
+            if (entry.category === category) {
+                lines.push(`    ${name.padEnd(16)} ${entry.description}`);
+            }
+        }
+        lines.push("");
+    }
+    lines.push("Run 'ouro help <command>' for details on a specific command.");
+    return lines.join("\n");
+}
+// ── Per-command help ──
+function getCommandHelp(name) {
+    const entry = exports.COMMAND_REGISTRY[name];
+    if (!entry)
+        return null;
+    const lines = [
+        `${name} - ${entry.description}`,
+        "",
+        `Usage: ${entry.usage}`,
+    ];
+    if (entry.subcommands && entry.subcommands.length > 0) {
+        lines.push("");
+        lines.push("Subcommands:");
+        for (const sub of entry.subcommands) {
+            lines.push(`  ${sub}`);
+        }
+    }
+    if (entry.example) {
+        lines.push("");
+        lines.push(`Example: ${entry.example}`);
+    }
+    return lines.join("\n");
+}

package/dist/heart/daemon/cli-parse.js

@@ -13,6 +13,7 @@ exports.usage = usage;
 exports.parseMcpServeCommand = parseMcpServeCommand;
 exports.parseOuroCommand = parseOuroCommand;
 const types_1 = require("../../mind/friends/types");
+const cli_help_1 = require("./cli-help");
 // ── Shared helpers ──
 function extractAgentFlag(args) {
     const idx = args.indexOf("--agent");
@@ -686,6 +687,14 @@ function parseOuroCommand(args) {
     const [head, second] = args;
     if (!head)
         return { kind: "daemon.up" };
+    // ── help command ──
+    if (head === "help") {
+        return second ? { kind: "help", command: second } : { kind: "help" };
+    }
+    // ── per-command --help ──
+    if (args.includes("--help")) {
+        return { kind: "help", command: head };
+    }
     if (head === "--agent" && second) {
         return parseOuroCommand(args.slice(2));
     }
@@ -807,5 +816,7 @@ function parseOuroCommand(args) {
         return { kind: "doctor" };
     if (head === "bluebubbles")
         return parseBlueBubblesCommand(args.slice(1));
-    throw new Error(`Unknown command '${args.join(" ")}'.\n${usage()}`);
+    const suggestion = (0, cli_help_1.suggestCommand)(head);
+    const hint = suggestion ? ` Did you mean '${suggestion}'?` : "";
+    throw new Error(`Unknown command '${args.join(" ")}'.${hint}\n${usage()}`);
 }

package/dist/nerves/coverage/file-completeness.js

@@ -59,9 +59,10 @@ const DISPATCH_EXEMPT_PATTERNS = [
     "repertoire/tools-config",
     "repertoire/tools-base",
     // CLI sub-modules: cli-exec.ts is the router with emitNervesEvent calls;
-    // cli-parse and cli-render are pure functions with no side effects.
+    // cli-parse, cli-render, and cli-help are pure functions/data with no side effects.
     "daemon/cli-parse",
     "daemon/cli-render",
+    "daemon/cli-help",
     // Shared utility modules: pure helpers consumed by modules that own observability.
     "arc/json-store",
     "repertoire/api-client",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.302",
+  "version": "0.1.0-alpha.303",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",