@ouro.bot/cli 0.1.0-alpha.384 → 0.1.0-alpha.386

package/changelog.json

@@ -1,6 +1,22 @@
 {
   "_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.386",
+      "changes": [
+        "`ouro vault recover --help` and `ouro help vault recover` now show the recovery-specific flags instead of generic vault help.",
+        "Nested command help now preserves subcommand words before flags, so help output can be specific to commands like `vault recover`.",
+        "`@ouro.bot/cli` and the `ouro.bot` wrapper are version-synced for the vault recovery help release."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.385",
+      "changes": [
+        "`ouro up` provider-check repair hints for locked agent vaults now mention both normal unlock and lost-secret `ouro vault recover --agent <agent> --from <json>` recovery.",
+        "Provider health checks now share the locked-vault unlock-or-recover wording so compact degraded summaries do not send operators back to a secret they never saved.",
+        "`@ouro.bot/cli` and the `ouro.bot` wrapper are version-synced for the locked-vault repair-hint release."
+      ]
+    },
     {
       "version": "0.1.0-alpha.384",
       "changes": [

package/dist/heart/daemon/agent-config-check.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.vaultUnlockOrRecoverFix = vaultUnlockOrRecoverFix;
 exports.checkAgentConfig = checkAgentConfig;
 exports.checkAgentConfigWithProviderHealth = checkAgentConfigWithProviderHealth;
 const fs = __importStar(require("fs"));
@@ -238,7 +239,7 @@ function invalidPoolResult(agentName, lane, provider, model, pool) {
         return {
             ok: false,
             error: `${lane} provider ${provider} model ${model} cannot read provider credentials because ${agentName}'s credential vault is locked on this machine.`,
-            fix: `Run 'ouro vault unlock --agent ${agentName}', then run 'ouro up' again.`,
+            fix: vaultUnlockOrRecoverFix(agentName),
         };
     }
     if (pool.reason === "invalid") {
@@ -251,13 +252,20 @@ function invalidPoolResult(agentName, lane, provider, model, pool) {
     return {
         ok: false,
         error: `${lane} provider ${provider} model ${model} cannot read provider credentials from ${agentName}'s vault at ${pool.poolPath}: ${pool.error}`,
-        fix: `Run 'ouro vault unlock --agent ${agentName}', then run 'ouro up' again. If the credential is missing or stale after unlock, run 'ouro auth --agent ${agentName} --provider ${provider}'.`,
+        fix: vaultUnlockOrRecoverFix(agentName, `Then run 'ouro up' again. If the credential is missing or stale after unlock or recovery, run 'ouro auth --agent ${agentName} --provider ${provider}'.`),
     };
 }
 function isVaultLockedError(error) {
     const normalized = error.toLowerCase();
     return /(?:ouro )?credential vault is locked|vault(?: is)? locked/.test(normalized);
 }
+function vaultUnlockOrRecoverFix(agentName, nextStep = "Then run 'ouro up' again.") {
+    return [
+        `Run 'ouro vault unlock --agent ${agentName}' if you have the saved vault unlock secret.`,
+        `If nobody saved it, run 'ouro vault recover --agent ${agentName} --from <json>' with a local credential export.`,
+        nextStep,
+    ].join(" ");
+}
 function failedPingResult(agentName, lane, provider, model, result) {
     return {
         ok: false,

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

@@ -229,6 +229,38 @@ exports.COMMAND_REGISTRY = {
         subcommands: ["replay"],
     },
 };
+const SUBCOMMAND_HELP = {
+    "vault create": {
+        description: "Create an agent credential vault and store local unlock material",
+        usage: "ouro vault create --agent <name> --email <email> [--server <url>] [--store <store>] [--generate-unlock-secret]",
+        example: "ouro vault create --agent ouroboros --email ouroboros@ouro.bot --generate-unlock-secret",
+    },
+    "vault recover": {
+        description: "Create a replacement agent vault and import local JSON credential exports",
+        usage: "ouro vault recover --agent <name> --from <json> [--from <json>] [--email <email>] [--server <url>] [--store <store>] [--generate-unlock-secret]",
+        example: "ouro vault recover --agent ouroboros --from ./credentials.json --generate-unlock-secret",
+    },
+    "vault unlock": {
+        description: "Unlock an existing agent credential vault on this machine",
+        usage: "ouro vault unlock --agent <name> [--store <store>]",
+        example: "ouro vault unlock --agent ouroboros",
+    },
+    "vault status": {
+        description: "Show whether this machine can unlock an agent credential vault",
+        usage: "ouro vault status --agent <name> [--store <store>]",
+        example: "ouro vault status --agent ouroboros",
+    },
+    "vault config set": {
+        description: "Write runtime configuration into the agent credential vault",
+        usage: "ouro vault config set --agent <name> --key <path> [--value <value>]",
+        example: "ouro vault config set --agent ouroboros --key senses/outlook/clientId",
+    },
+    "vault config status": {
+        description: "List runtime configuration keys stored in the agent credential vault",
+        usage: "ouro vault config status --agent <name>",
+        example: "ouro vault config status --agent ouroboros",
+    },
+};
 // ── Levenshtein distance ──
 function levenshteinDistance(a, b) {
     if (a.length === 0)
@@ -296,7 +328,7 @@ function getGroupedHelp() {
 }
 // ── Per-command help ──
 function getCommandHelp(name) {
-    const entry = exports.COMMAND_REGISTRY[name];
+    const entry = SUBCOMMAND_HELP[name] ?? exports.COMMAND_REGISTRY[name];
     if (!entry)
         return null;
     const lines = [

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

@@ -42,6 +42,17 @@ function facingToProviderLane(facing) {
 function isProviderLane(value) {
     return value === "outward" || value === "inner";
 }
+function helpCommandName(args) {
+    const positional = [];
+    for (const arg of args) {
+        if (arg === "--help" || arg === "-h")
+            break;
+        if (arg.startsWith("-"))
+            break;
+        positional.push(arg);
+    }
+    return positional.length > 0 ? positional.join(" ") : undefined;
+}
 function extractLaneFlag(args) {
     const idx = args.indexOf("--lane");
     if (idx === -1 || idx + 1 >= args.length)
@@ -932,11 +943,13 @@ function parseOuroCommand(args) {
         return { kind: "daemon.up" };
     // ── help command ──
     if (head === "help") {
-        return second ? { kind: "help", command: second } : { kind: "help" };
+        const command = helpCommandName(args.slice(1));
+        return command ? { kind: "help", command } : { kind: "help" };
     }
     // ── per-command --help ──
-    if (args.includes("--help")) {
-        return { kind: "help", command: head };
+    if (args.includes("--help") || args.includes("-h")) {
+        const command = helpCommandName(args);
+        return command ? { kind: "help", command } : { kind: "help" };
     }
     if (head === "--agent" && second) {
         return parseOuroCommand(args.slice(2));

package/package.json

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