mdkg 0.3.5 → 0.3.7

package/dist/cli.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runCli = runCli;
+exports.runCliAsync = runCliAsync;
 exports.main = main;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -14,11 +15,13 @@ const list_1 = require("./commands/list");
 const search_1 = require("./commands/search");
 const show_1 = require("./commands/show");
 const pack_1 = require("./commands/pack");
+const handoff_1 = require("./commands/handoff");
 const next_1 = require("./commands/next");
 const validate_1 = require("./commands/validate");
 const format_1 = require("./commands/format");
 const doctor_1 = require("./commands/doctor");
 const status_1 = require("./commands/status");
+const mcp_1 = require("./commands/mcp");
 const fix_1 = require("./commands/fix");
 const db_1 = require("./commands/db");
 const capability_1 = require("./commands/capability");
@@ -65,12 +68,13 @@ function printUsage(log) {
     log("  list        List nodes with filters");
     log("  search      Search nodes by query");
     log("  pack        Generate a context pack");
+    log("  handoff     Create sanitized agent handoff prompts from graph context");
     log("  skill       Create, list, show, search, and validate skills");
     log("  capability  List, search, show, and resolve cached capability surfaces");
     log("  spec        List, show, and validate optional SPEC.md capability records");
     log("  archive     Add, list, show, verify, and compress archive sidecars");
     log("  bundle      Create, list, show, and verify full graph snapshot bundles");
-    log("  graph       Clone and fork whole mdkg graphs");
+    log("  graph       Clone, fork, import, and inspect mdkg graph references");
     log("  subgraph    Register, audit, plan, sync, materialize, and verify read-only child graph snapshots");
     log("  work        Create and update work contracts, orders, receipts, and artifacts");
     log("  goal        Inspect and advance recursive goal nodes");
@@ -78,6 +82,7 @@ function printUsage(log) {
     log("  next        Suggest the next work item");
     log("  validate    Validate frontmatter + graph");
     log("  status      Show read-only operator health summary");
+    log("  mcp         Serve local read-only MCP tools over stdio");
     log("  fix         Plan read-only repairs with receipt-shaped JSON");
     log("\nAdvanced / maintenance commands:");
     log("  db          Project database and index-cache commands");
@@ -233,8 +238,10 @@ function printDbHelp(log, subcommand) {
             log("  mdkg db queue stats [queue] [--json]");
             log("  mdkg db queue list <queue> [--status ready|leased|acked|dead_letter|all] [--limit <n>] [--json]");
             log("  mdkg db queue show <queue> <message-id> [--json]");
+            log("  mdkg db queue contract [--json]");
             log("\nSemantics:");
             log("  - queues are durable local delivery state, not canonical event history");
+            log("  - contract is read-only adapter metadata and does not require an initialized project DB");
             log("  - paused queues reject enqueue and claim");
             log("  - ack, fail, dead-letter, and release-expired are allowed while paused so leased work can settle");
             log("  - no raw SQL or hosted queue dependency is exposed");
@@ -255,6 +262,7 @@ function printDbHelp(log, subcommand) {
             log("  mdkg db queue ack|fail|dead-letter <queue> <message-id> --lease-owner <owner> [--json]");
             log("  mdkg db queue pause|resume <queue> [--json]");
             log("  mdkg db queue stats|list|show ... [--json]");
+            log("  mdkg db queue contract [--json]");
             log("  mdkg db snapshot seal [--queue-policy drain|paused] [--json]");
             log("  mdkg db snapshot verify [--json]");
             log("  mdkg db snapshot status [--json]");
@@ -323,12 +331,14 @@ function printPackHelp(log) {
     log("      --list-profiles          List built-in pack profiles and exit");
     log("\nAdvanced shaping / debug flags:");
     log("  --depth --edges --strip-code --max-code-lines --max-chars --max-lines --max-tokens");
+    log("  --edges accepts parent, epic, relates, blocked_by, blocks, prev, next, context_refs, evidence_refs");
     log("  --truncation-report --stats-out");
     log("\nExamples:");
     log("  mdkg pack --list-profiles");
     log("  mdkg pack task-1");
     log("  mdkg pack task-1 --profile concise --dry-run --stats");
     log("  mdkg pack task-1 --visibility public --dry-run");
+    log("  mdkg pack task-1 --edges context_refs,evidence_refs --format json");
     log("  mdkg pack task-1 --skills auto --skills-depth full");
     log("  mdkg pack epic-2 --format json --profile headers");
     printGlobalOptions(log);
@@ -344,6 +354,19 @@ function printPackProfiles(log) {
         }
     }
 }
+function printHandoffHelp(log) {
+    log("Usage:");
+    log("  mdkg handoff create <id-or-qid> [--ws <alias>] [--depth <n>] [--out <path>] [--json]");
+    log("\nPurpose:");
+    log("  - create a sanitized, copy-ready agent handoff from mdkg graph context");
+    log("  - summarize goal/work state, included pack nodes, latest checkpoint, boundaries, required checks, and next actions");
+    log("  - include raw secret, prompt, token, or payload marker warnings without copying raw node bodies into the handoff");
+    log("  - use pack traversal with context_refs and evidence_refs for background and proof nodes");
+    log("\nBoundaries:");
+    log("  - handoff create does not execute work, mutate graph nodes, or generate detailed node content");
+    log("  - --out must stay inside the repo root");
+    printGlobalOptions(log);
+}
 function printSkillHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "new":
@@ -581,16 +604,26 @@ function printGraphHelp(log, subcommand) {
             log("  - imports authored .mdkg/work template nodes into the current graph");
             log("  - defaults to dry-run unless --apply is supplied");
             log("  - rewrites canonical numeric IDs and structured graph links deterministically");
-            log("  - --select-goal requires --start-goal and writes selected-goal state only after apply validation");
+            log("  - --select-goal requires --start-goal; on apply it activates the imported start goal, pauses competing active root goals, validates, then writes selected-goal state");
+            break;
+        case "refs":
+            log("Usage:");
+            log("  mdkg graph refs <id-or-qid> [--ws <alias>] [--json]");
+            log("\nNotes:");
+            log("  - read-only summary of inbound and outbound graph references");
+            log("  - reports scope_refs, context_refs, evidence_refs, blockers, related refs, and structural links");
+            log("  - subgraph qids are inspectable but remain read-only");
             break;
         default:
             log("Usage:");
             log("  mdkg graph clone <source-bundle-or-mdkg-dir> --target <path> [--json]");
             log("  mdkg graph fork <source-bundle-or-mdkg-dir> --target <path> [--start-goal <goal-id>] [--json]");
             log("  mdkg graph import-template <source-bundle-or-mdkg-dir> [--start-goal <goal-id>] [--select-goal] [--id-prefix <prefix>] [--dry-run] [--apply] [--json]");
+            log("  mdkg graph refs <id-or-qid> [--ws <alias>] [--json]");
             log("\nNotes:");
             log("  - graph clone/fork create authored graph state in separate target directories and preserve IDs");
             log("  - graph import-template imports template work nodes into the current graph with rewritten IDs");
+            log("  - graph refs is read-only and explains local plus subgraph graph relationships");
             log("  - subgraphs remain read-only bundle projections for orchestration context");
     }
     printGlobalOptions(log);
@@ -712,6 +745,14 @@ function printWorkHelp(log, subcommand) {
             log("Usage:");
             log("  mdkg work artifact add <order-or-receipt-id-or-qid> <file> [--id <archive.id>] [--kind source|artifact] [--json]");
             break;
+        case "validate":
+            log("Usage:");
+            log("  mdkg work validate [<id-or-qid>] [--type spec|work|work_order|receipt|feedback|dispute|proposal] [--json]");
+            log("\nNotes:");
+            log("  Read-only focused validation for agent workflow mirrors.");
+            log("  Reports typed diagnostics for SPEC.md, WORK.md, WORK_ORDER.md, RECEIPT.md, FEEDBACK.md, DISPUTE.md, and PROPOSAL.md files.");
+            log("  Obvious raw secret, prompt, token, or payload markers are warnings so humans and agents can review boundaries.");
+            break;
         default:
             log("Usage:");
             log("  mdkg work contract new ...");
@@ -719,8 +760,10 @@ function printWorkHelp(log, subcommand) {
             log("  mdkg work order new|status|update ...");
             log("  mdkg work receipt new|verify|update ...");
             log("  mdkg work artifact add ...");
+            log("  mdkg work validate [<id-or-qid>] [--type <workflow-type>] [--json]");
             log("\nNotes:");
             log("  - work commands mutate semantic mirror files only");
+            log("  - work validate is read-only and reports typed workflow diagnostics");
             log("  - production order, receipt, feedback, dispute, payment, ledger, marketplace inventory, fulfillment, and execution state remains canonical outside mdkg");
             log("  - do not store raw secrets, credentials, live payment state, ledger mutations, or canonical marketplace state in work mirrors");
             log("  - artifact:// refs identify external/runtime-managed artifacts; archive:// refs identify committed mdkg archive sidecars");
@@ -751,7 +794,7 @@ function printTaskHelp(log, subcommand) {
         case "done":
             log("Usage:");
             log('  mdkg task done <id-or-qid> [--ws <alias>] [--add-artifacts <a,...>] [--add-links <l,...>]');
-            log('                 [--add-refs <id,...>] [--checkpoint "<title>"] [--run-id <id>] [--note "<text>"] [--json]');
+            log('                 [--add-refs <id,...>] [--checkpoint "<title>"] [--checkpoint-kind implementation|test-proof|goal-closeout|audit|handoff] [--run-id <id>] [--note "<text>"] [--json]');
             log("\nWhen to use:");
             log("  Mark a task-like node done, optionally create a checkpoint, and emit a completion event when enabled.");
             log("  Use `--checkpoint` for milestone compression, not every routine task completion.");
@@ -761,7 +804,7 @@ function printTaskHelp(log, subcommand) {
             log("Usage:");
             log('  mdkg task start <id-or-qid> [--ws <alias>] [--run-id <id>] [--note "<text>"] [--json]');
             log("  mdkg task update <id-or-qid> [options] [--json]");
-            log('  mdkg task done <id-or-qid> [--checkpoint "<title>"] [options] [--json]');
+            log('  mdkg task done <id-or-qid> [--checkpoint "<title>"] [--checkpoint-kind implementation|test-proof|goal-closeout|audit|handoff] [options] [--json]');
             log("\nNotes:");
             log("  `mdkg task ...` only supports feat, task, bug, test, and spike nodes.");
             log("  Spikes use this lifecycle; there is no separate `mdkg spike ...` command family.");
@@ -775,7 +818,7 @@ function printGoalHelp(log, subcommand) {
             log("Usage:");
             log("  mdkg goal show <goal-id-or-qid> [--ws <alias>] [--json]");
             log("\nWhen to use:");
-            log("  Inspect a goal condition, current goal state, active node, required skills, and required checks.");
+            log("  Inspect a goal condition, current goal state, active node, last active node, required skills, and required checks.");
             printGlobalOptions(log);
             return;
         case "next":
@@ -844,6 +887,9 @@ function printGoalHelp(log, subcommand) {
             log(`  mdkg goal ${subcommand} <goal-id-or-qid> [--ws <alias>] [--json]`);
             log("\nWhen to use:");
             log("  Update durable goal state after agent or human review.");
+            if (subcommand === "done") {
+                log("  Done goals preserve the final active_node as last_active_node and stop routing actionable work.");
+            }
             printGlobalOptions(log);
             return;
         default:
@@ -860,6 +906,7 @@ function printGoalHelp(log, subcommand) {
             log("\nNotes:");
             log("  - goals orchestrate recursive progress; features, tasks, bugs, tests, and spikes are iterable work units");
             log("  - `mdkg goal next` is read-only; use `mdkg goal claim` to update active_node");
+            log("  - `mdkg goal done` moves active_node to last_active_node so completed goals keep history without staying actionable");
             log("  - `mdkg goal activate` enforces one active local root goal and pauses competing active goals");
             log("  - goal evaluation is report-only and never executes required_checks");
             log("  - subgraph goal qids are read-only; update the source workspace instead");
@@ -898,13 +945,18 @@ function printNextHelp(log) {
 }
 function printCheckpointHelp(log) {
     log("Usage:");
-    log("  mdkg checkpoint new <title> [--ws <alias>] [--json]");
+    log("  mdkg checkpoint new <title> [--kind implementation|test-proof|goal-closeout|audit|handoff] [--ws <alias>] [--json]");
+    log("  Checkpoint bodies include command evidence, pass/fail status, warnings, changed surfaces, boundaries, and follow-up refs.");
     log('        [--relates <id,id,...>] [--scope <id,id,...>] [--run-id <id>] [--note "<text>"]');
     printGlobalOptions(log);
 }
 function printValidateHelp(log) {
     log("Usage:");
-    log("  mdkg validate [--out <path>] [--quiet] [--json]");
+    log("  mdkg validate [--out <path>] [--quiet] [--changed-only] [--json]");
+    log("\nNotes:");
+    log("  Validates frontmatter schemas, graph references, visibility, skills, and events.");
+    log("  --changed-only filters warning presentation to changed .mdkg files while full graph errors still run.");
+    log("  JSON output includes warning_diagnostics with warning ids, categories, severity, paths, refs, and remediation text.");
     printGlobalOptions(log);
 }
 function printStatusHelp(log) {
@@ -923,6 +975,29 @@ function printStatusHelp(log) {
     log("  --json                Emit machine-readable JSON output");
     printGlobalOptions(log);
 }
+function printMcpHelp(log, subcommand) {
+    switch ((subcommand ?? "").toLowerCase()) {
+        case "serve":
+            log("Usage:");
+            log("  mdkg mcp serve --stdio");
+            log("\nBoundary:");
+            log("  - starts one local Model Context Protocol server bound to the selected --root");
+            log("  - stdio is the only transport in this release; no HTTP listener is opened");
+            log("  - exposes read-only tools for status, workspace list, search, show, pack, goal current/next, and validate");
+            log("  - exposes no task, goal, graph, queue, event, archive, format, SQL, shell, filesystem, or environment mutation tools");
+            log("  - stdout is reserved for newline-delimited JSON-RPC MCP messages");
+            printGlobalOptions(log);
+            return;
+        default:
+            log("Usage:");
+            log("  mdkg mcp serve --stdio");
+            log("\nBoundary:");
+            log("  - local read-only MCP server for mdkg graph inspection");
+            log("  - use --root <path> to select the mdkg graph explicitly");
+            log("  - phase one is stdio-only and does not expose mutation tools");
+            printGlobalOptions(log);
+    }
+}
 function printFixHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "plan":
@@ -985,6 +1060,10 @@ function printFixHelp(log, subcommand) {
 function printFormatHelp(log) {
     log("Usage:");
     log("  mdkg format");
+    log("  mdkg format --headings [--dry-run|--apply] [--json]");
+    log("\nNotes:");
+    log("  Default format normalizes frontmatter in place.");
+    log("  --headings adds missing recommended body headings; it defaults to dry-run and requires --apply to write files.");
     printGlobalOptions(log);
 }
 function printDoctorHelp(log) {
@@ -1046,6 +1125,9 @@ function printCommandHelp(log, command, subcommand) {
         case "pack":
             printPackHelp(log);
             return;
+        case "handoff":
+            printHandoffHelp(log);
+            return;
         case "skill":
             printSkillHelp(log, subcommand);
             return;
@@ -1091,6 +1173,9 @@ function printCommandHelp(log, command, subcommand) {
         case "status":
             printStatusHelp(log);
             return;
+        case "mcp":
+            printMcpHelp(log, subcommand);
+            return;
         case "fix":
             printFixHelp(log, subcommand);
             return;
@@ -1407,6 +1492,12 @@ function runDbSubcommand(parsed, root) {
                     }
                     (0, db_1.runDbQueueCreateCommand)(common);
                     return 0;
+                case "contract":
+                    if (parsed.positionals.length > 3) {
+                        throw new errors_1.UsageError("mdkg db queue contract accepts no positional arguments");
+                    }
+                    (0, db_1.runDbQueueContractCommand)(common);
+                    return 0;
                 case "pause":
                     if (!queueName || parsed.positionals.length > 4) {
                         throw new errors_1.UsageError("mdkg db queue pause requires <queue>");
@@ -1474,7 +1565,7 @@ function runDbSubcommand(parsed, root) {
                     (0, db_1.runDbQueueShowCommand)(common);
                     return 0;
                 default:
-                    throw new errors_1.UsageError("mdkg db queue requires create/pause/resume/enqueue/claim/ack/fail/dead-letter/release-expired/stats/list/show");
+                    throw new errors_1.UsageError("mdkg db queue requires create/contract/pause/resume/enqueue/claim/ack/fail/dead-letter/release-expired/stats/list/show");
             }
         }
         case "snapshot": {
@@ -1770,8 +1861,17 @@ function runGraphSubcommand(parsed, root) {
             (0, graph_1.runGraphImportTemplateCommand)({ root, source, startGoal, idPrefix, dryRun, apply, selectGoal, json });
             return 0;
         }
+        case "refs": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("graph refs requires <id-or-qid>");
+            }
+            const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
+            (0, graph_1.runGraphRefsCommand)({ root, id, ws, json });
+            return 0;
+        }
         default:
-            throw new errors_1.UsageError("graph requires clone/fork/import-template");
+            throw new errors_1.UsageError("graph requires clone/fork/import-template/refs");
     }
 }
 function runSubgraphSubcommand(parsed, root) {
@@ -1927,6 +2027,15 @@ function runWorkSubcommand(parsed, root) {
         (0, work_1.runWorkTriggerCommand)({ root, ws, targetRef, id, title, requester, enqueue, json });
         return 0;
     }
+    if (domain === "validate") {
+        const id = parsed.positionals[2];
+        if (parsed.positionals.length > 3) {
+            throw new errors_1.UsageError("work validate accepts at most one workflow reference");
+        }
+        const type = requireFlagValue("--type", parsed.flags["--type"]);
+        (0, work_1.runWorkValidateCommand)({ root, ws, id, type, json });
+        return 0;
+    }
     if (domain === "contract" && action === "new") {
         const title = parsed.positionals.slice(3).join(" ");
         const id = requireFlagValue("--id", parsed.flags["--id"]);
@@ -2086,7 +2195,7 @@ function runWorkSubcommand(parsed, root) {
         (0, work_1.runWorkArtifactAddCommand)({ root, ws, targetId, file, id, kind, json });
         return 0;
     }
-    throw new errors_1.UsageError("work requires contract new, order new/update, receipt new/update, or artifact add");
+    throw new errors_1.UsageError("work requires contract new, trigger, order new/update/status, receipt new/update/verify, artifact add, or validate");
 }
 function runSkillSubcommand(parsed, root) {
     const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
@@ -2371,6 +2480,7 @@ function runTaskSubcommand(parsed, root) {
             const addLinks = requireFlagValue("--add-links", parsed.flags["--add-links"]);
             const addRefs = requireFlagValue("--add-refs", parsed.flags["--add-refs"]);
             const checkpoint = requireFlagValue("--checkpoint", parsed.flags["--checkpoint"]);
+            const checkpointKind = requireFlagValue("--checkpoint-kind", parsed.flags["--checkpoint-kind"]);
             const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
             const note = requireFlagValue("--note", parsed.flags["--note"]);
             const json = parseBooleanFlag("--json", parsed.flags["--json"]);
@@ -2382,6 +2492,7 @@ function runTaskSubcommand(parsed, root) {
                 addLinks,
                 addRefs,
                 checkpoint,
+                checkpointKind,
                 runId,
                 note,
                 json,
@@ -2720,6 +2831,32 @@ function runCommand(parsed, root, runtime) {
             });
             return 0;
         }
+        case "handoff": {
+            const sub = (parsed.positionals[1] ?? "").toLowerCase();
+            if (!sub) {
+                throw new errors_1.UsageError("handoff requires a subcommand");
+            }
+            if (sub !== "create") {
+                throw new errors_1.UsageError(`unknown handoff subcommand: ${sub}`);
+            }
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("mdkg handoff create requires <id-or-qid>");
+            }
+            const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
+            const out = requireFlagValue("--out", parsed.flags["--out"]);
+            const depth = parseNumberFlag("--depth", parsed.flags["--depth"]);
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            (0, handoff_1.runHandoffCreateCommand)({
+                root,
+                id,
+                ws,
+                out,
+                depth,
+                json,
+            });
+            return 0;
+        }
         case "next": {
             if (parsed.positionals.length > 2) {
                 throw new errors_1.UsageError("next accepts at most one id");
@@ -2749,6 +2886,7 @@ function runCommand(parsed, root, runtime) {
             const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
             const relates = requireFlagValue("--relates", parsed.flags["--relates"]);
             const scope = requireFlagValue("--scope", parsed.flags["--scope"]);
+            const kind = requireFlagValue("--kind", parsed.flags["--kind"]);
             const status = requireFlagValue("--status", parsed.flags["--status"]);
             const priority = parseNumberFlag("--priority", parsed.flags["--priority"]);
             const template = requireFlagValue("--template", parsed.flags["--template"]);
@@ -2761,6 +2899,7 @@ function runCommand(parsed, root, runtime) {
                 ws,
                 relates,
                 scope,
+                kind,
                 status,
                 priority,
                 template,
@@ -2776,8 +2915,9 @@ function runCommand(parsed, root, runtime) {
             }
             const out = requireFlagValue("--out", parsed.flags["--out"]);
             const quiet = parseBooleanFlag("--quiet", parsed.flags["--quiet"]);
+            const changedOnly = parseBooleanFlag("--changed-only", parsed.flags["--changed-only"]);
             const json = parseBooleanFlag("--json", parsed.flags["--json"]);
-            (0, validate_1.runValidateCommand)({ root, out, quiet, json });
+            (0, validate_1.runValidateCommand)({ root, out, quiet, json, changedOnly });
             return 0;
         }
         case "status": {
@@ -2788,6 +2928,8 @@ function runCommand(parsed, root, runtime) {
             (0, status_1.runStatusCommand)({ root, json });
             return 0;
         }
+        case "mcp":
+            throw new errors_1.UsageError("mcp serve requires the async CLI entrypoint");
         case "fix": {
             const sub = (parsed.positionals[1] ?? "").toLowerCase();
             if (!sub) {
@@ -2819,7 +2961,17 @@ function runCommand(parsed, root, runtime) {
             if (parsed.positionals.length > 1) {
                 throw new errors_1.UsageError("format does not accept positional arguments");
             }
-            (0, format_1.runFormatCommand)({ root });
+            const headings = parseBooleanFlag("--headings", parsed.flags["--headings"]);
+            const dryRun = parseBooleanFlag("--dry-run", parsed.flags["--dry-run"]);
+            const apply = parseBooleanFlag("--apply", parsed.flags["--apply"]);
+            const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+            if (!headings && (dryRun || apply || json)) {
+                throw new errors_1.UsageError("format --dry-run, --apply, and --json require --headings");
+            }
+            if (dryRun && apply) {
+                throw new errors_1.UsageError("format --headings cannot use --dry-run and --apply together");
+            }
+            (0, format_1.runFormatCommand)({ root, headings, dryRun, apply, json });
             return 0;
         case "doctor": {
             if (parsed.positionals.length > 1) {
@@ -2838,6 +2990,18 @@ function runCommand(parsed, root, runtime) {
             return 1;
     }
 }
+async function runMcpSubcommand(parsed, root) {
+    const sub = (parsed.positionals[1] ?? "").toLowerCase();
+    if (sub !== "serve") {
+        throw new errors_1.UsageError("mcp requires serve --stdio");
+    }
+    if (parsed.positionals.length > 2) {
+        throw new errors_1.UsageError("mcp serve does not accept positional arguments");
+    }
+    const stdio = parseBooleanFlag("--stdio", parsed.flags["--stdio"]);
+    await (0, mcp_1.runMcpServeCommand)({ root, stdio });
+    return 0;
+}
 function runCli(argv, runtime = {}) {
     const io = resolveRuntime(runtime);
     const parsed = (0, argparse_1.parseArgs)(argv);
@@ -2875,8 +3039,53 @@ function runCli(argv, runtime = {}) {
         return handleCommandError(err, command, io);
     }
 }
+async function runCliAsync(argv, runtime = {}) {
+    const io = resolveRuntime(runtime);
+    const parsed = (0, argparse_1.parseArgs)(argv);
+    if (parsed.error) {
+        io.error(parsed.error);
+        printUsage(io.log);
+        return 1;
+    }
+    if (parsed.help) {
+        printCommandHelp(io.log, parsed.positionals[0], parsed.positionals[1]);
+        return 0;
+    }
+    if (parsed.version) {
+        io.log(readPackageVersion());
+        return 0;
+    }
+    const command = (parsed.positionals[0] ?? "").toLowerCase();
+    if (!command) {
+        printUsage(io.log);
+        return 0;
+    }
+    if (command === "help") {
+        printCommandHelp(io.log, parsed.positionals[1], parsed.positionals[2]);
+        return 0;
+    }
+    const root = parsed.root ? path_1.default.resolve(parsed.root) : io.cwd();
+    if (shouldRequireConfig(command, parsed.flags) && !hasConfig(root)) {
+        printRootError(io.error, root);
+        return 1;
+    }
+    try {
+        if (command === "mcp") {
+            return await runMcpSubcommand(parsed, root);
+        }
+        return runCommand(parsed, root, io);
+    }
+    catch (err) {
+        return handleCommandError(err, command, io);
+    }
+}
 function main(argv = process.argv.slice(2)) {
-    process.exit(runCli(argv, { cwd: () => process.cwd() }));
+    runCliAsync(argv, { cwd: () => process.cwd() })
+        .then((code) => process.exit(code))
+        .catch((err) => {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(4);
+    });
 }
 if (require.main === module) {
     main();