mdkg 0.3.4 → 0.3.6

package/CHANGELOG.md

@@ -8,9 +8,76 @@ mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL con
 
 ## Unreleased
 
-### Planned
+## 0.3.6 - 2026-06-17
 
-- No changes yet.
+### Added
+
+- Added `mdkg mcp serve --stdio` as a local read-only MCP server for status,
+  workspace/subgraph discovery, search, show, bounded in-memory packs, goal
+  current/next, and validation.
+- Added packed `smoke:mcp` coverage that installs mdkg from a tarball in a
+  temp prefix, launches the stdio server, exercises root and subgraph reads,
+  and proves mutation-shaped tool calls fail closed.
+
+### Fixed
+
+- Prepared `0.3.6` graph import hardening after the `0.3.5` publish:
+  `mdkg graph import-template --select-goal --apply` now activates the
+  rewritten imported start goal, pauses competing active root goals, validates,
+  and only then writes selected-goal state.
+
+### Changed
+
+- Extended graph import dry-run/apply receipts with activation and paused-goal
+  details, and made active template imports fail before writing when
+  `--select-goal` is omitted and multiple active root goals would result.
+
+### Security
+
+- The MCP server is stdio-only and exposes no task, goal activation, graph
+  import, queue, event, archive, format, SQL, shell, arbitrary file-read,
+  filesystem mutation, environment, or secret-access tools.
+
+## 0.3.5 - 2026-06-17
+
+### Added
+
+- Added `mdkg graph clone <source> --target <path>` to create a complete
+  authored mdkg graph in a separate contained target directory while preserving
+  source IDs.
+- Added `mdkg graph fork <source> --target <path> --start-goal <goal-id>` to
+  preserve IDs in a separate target graph and optionally select the demo or
+  bootstrap start goal in that target.
+- Added `mdkg graph import-template <source> --dry-run|--apply` for same-repo
+  template graph imports with deterministic canonical ID rewrites, structured
+  reference rewrites, safe body ID/qid rewrites, and optional selected-goal
+  setup.
+- Added packed `smoke:graph-clone` coverage that installs mdkg from a tarball
+  in a temp prefix and validates clone, fork, import-template dry-run/apply,
+  source non-mutation, help text, search, pack, and validation behavior.
+
+### Changed
+
+- Updated README, seeded init README, command matrix, help snapshots,
+  prepublish gates, and publish-readiness assertions to document the
+  distinction between authored graph creation through `mdkg graph ...` and
+  read-only orchestration context through `mdkg subgraph ...`.
+- Added `smoke:graph-clone` to `prepublishOnly` before the existing subgraph
+  smoke so graph template import behavior is proven before release.
+- Consolidated website-template-mdkg dogfood planning under the 0.3.5 graph
+  clone/import goal without mutating downstream repositories or starting
+  website implementation.
+
+### Security
+
+- Clone/fork targets must be empty or absent, root-contained, and not nested
+  inside live directory sources.
+- Same-repo template imports default to dry-run, require `--apply` to write,
+  run under the mdkg mutation lock, rebuild generated indexes, and validate the
+  resulting graph before selecting a start goal.
+- Semantic ID collisions during template import require an explicit
+  `--id-prefix`; numeric canonical IDs are rewritten to the next unused ID so
+  links remain deterministic.
 
 ## 0.3.4 - 2026-06-17
 

package/CLI_COMMAND_MATRIX.md

@@ -1,7 +1,7 @@
 # CLI Command Matrix
 
-as_of: 2026-06-06
-package_version_in_source: 0.3.4
+as_of: 2026-06-17
+package_version_in_source: 0.3.6
 source: live help from `src/cli.ts`, runtime command handlers, and `dec-15`..`dec-18`
 status: canonical single-source command and flag reference for mdkg
 
@@ -28,6 +28,7 @@ Primary commands:
 - `spec`
 - `archive`
 - `bundle`
+- `graph`
 - `subgraph`
 - `work`
 - `goal`
@@ -35,6 +36,7 @@ Primary commands:
 - `next`
 - `validate`
 - `status`
+- `mcp`
 - `fix`
 
 Advanced / maintenance commands:
@@ -55,6 +57,7 @@ Capability cache discovery is read-only and accessed through `mdkg capability ..
 Optional reusable SPEC capability records are accessed through `mdkg spec ...`.
 Archive sidecars are accessed through `mdkg archive ...`.
 Full graph snapshot bundles are accessed through `mdkg bundle ...`.
+Whole-graph clone, fork, and same-repo template import workflows are accessed through `mdkg graph ...`.
 Read-only child graph orchestration is accessed through `mdkg subgraph ...`.
 Work contract/order/receipt semantic mirrors are accessed through `mdkg work ...`.
 Recursive long-running objective contracts are accessed through `mdkg goal ...`.
@@ -62,6 +65,7 @@ Fresh init workspaces default to the SQLite access cache backend; existing migra
 Project application database foundation commands are accessed through `mdkg db ...`; `mdkg index` remains the compatibility shortcut for graph index rebuilds.
 Operator health summaries are accessed through read-only `mdkg status ...`; deeper diagnostics remain under `mdkg doctor ...`.
 Repair planning is accessed through read-only `mdkg fix plan ...`; duplicate-ID graph repairs can be applied through `mdkg fix apply --family ids ...` or the convenience `mdkg fix ids --apply ...`. Index/cache and graph-reference findings remain plan/manual-review only.
+Local MCP integration is accessed through `mdkg mcp serve --stdio`; it exposes read-only graph/status/workspace/search/show/pack/goal/validate tools only.
 
 ## Global usage
 
@@ -615,6 +619,45 @@ JSON receipts:
 - `show`: `{ action: "show", bundle, manifest }`
 - `list`: `{ action: "list", count, items }`
 
+### `mdkg graph`
+
+When to use:
+- clone or fork a complete mdkg graph into a separate target directory while preserving IDs
+- import a template graph into the current repo with deterministic ID/link rewrites
+- prepare selected-goal demo handoffs from reusable graph templates
+
+Usage:
+- `mdkg graph clone <source-bundle-or-mdkg-dir> --target <path> [--json]`
+- `mdkg graph fork <source-bundle-or-mdkg-dir> --target <path> [--start-goal <goal-id>] [--json]`
+- `mdkg graph import-template <source-bundle-or-mdkg-dir> [--start-goal <goal-id>] [--select-goal] [--id-prefix <prefix>] [--dry-run] [--apply] [--json]`
+
+Flags:
+- `--target <path>`
+- `--start-goal <goal-id>`
+- `--select-goal`
+- `--id-prefix <prefix>`
+- `--dry-run`
+- `--apply`
+- `--json`
+
+Notes:
+- `graph clone` and `graph fork` preserve IDs because the target is a separate graph namespace
+- clone/fork targets must be empty or absent and stay under the current mdkg root
+- live directory sources are never mutated; clone/fork refuses targets nested inside a live source directory
+- `graph fork --start-goal <goal-id>` writes selected-goal state in the target graph after validation
+- `graph import-template` imports authored `.mdkg/work/*.md` template nodes into the current repo and skips config, generated indexes, archive payloads, bundles, and materialized subgraph views
+- `graph import-template` defaults to dry-run unless `--apply` is supplied
+- same-repo template import rewrites canonical numeric IDs to the next unused ID by type prefix and rewrites structured refs plus safe body-local id/qid mentions
+- colliding semantic template IDs require `--id-prefix`
+- `--select-goal` requires `--start-goal`; on apply it activates the imported start goal, pauses competing active root goals, validates, then writes selected-goal state
+- importing active template goals without `--select-goal` fails before writing when it would create multiple active root goals
+- subgraphs remain read-only bundle projections for orchestration context; use `graph clone|fork|import-template` when authored graph state should be created
+
+JSON receipts:
+- `clone`: `{ action: "graph.clone", ok, mode, source, target, source_hash, preserved_ids, files_written, skipped_paths, index, validation, warnings }`
+- `fork`: `{ action: "graph.fork", ok, mode, source, target, source_hash, preserved_ids, files_written, skipped_paths, start_goal?, selected_goal?, index, validation, warnings }`
+- `import-template`: `{ action: "graph.import_template", ok, mode, source, source_hash, preserved_ids: false, rewritten_ids, rewritten_refs, planned_paths, files_written, skipped_paths, start_goal?, selected_goal?, activated_goal?, paused_goals, index?, validation?, warnings }`
+
 ### `mdkg subgraph`
 
 When to use:
@@ -1046,6 +1089,34 @@ JSON receipt shape:
 - `generated` reports index, skills, capabilities, and subgraph cache existence/staleness
 - `summary` includes machine-readable warning and error counts plus messages
 
+### `mdkg mcp`
+
+Usage:
+- `mdkg mcp serve --stdio`
+
+When to use:
+- expose one local mdkg root to an MCP-capable agent or orchestrator
+- let an external agent inspect mdkg status, workspace/subgraph aliases, search/show results, in-memory packs, goal current/next, and validation without shelling out to individual CLI commands
+
+Flags:
+- `--stdio`
+- `--root`, `-r <path>`
+
+Boundaries:
+- stdio is the only transport in this release; mdkg opens no HTTP listener
+- bind the server to one graph root with `--root <path>` when launching from outside the repo
+- tool calls are read-only and return MCP `structuredContent` plus text content
+- exposed tools: `mdkg_status`, `mdkg_workspace_list`, `mdkg_search`, `mdkg_show`, `mdkg_pack`, `mdkg_goal_current`, `mdkg_goal_next`, and `mdkg_validate`
+- `mdkg_pack` builds an in-memory bounded pack and does not write `.mdkg/pack`
+- no task, goal activation, graph import, queue, event, archive, format, SQL, shell, arbitrary file-read, filesystem mutation, environment, or secret-access tool is exposed
+- mutation allowlists and broader CLI parity are future design work, not part of this command surface
+- stdout is reserved for newline-delimited JSON-RPC MCP messages; diagnostics must stay off stdout
+
+JSON-RPC receipt shapes:
+- initialize: `{ protocolVersion, capabilities: { tools }, serverInfo, instructions }`
+- `tools/list`: `{ tools: [{ name, title, description, inputSchema, annotations }] }`
+- `tools/call`: MCP tool result with `{ content, structuredContent, isError }`
+
 ### `mdkg fix`
 
 When to use:

package/README.md

@@ -14,7 +14,7 @@ mdkg stays deliberately boring:
 - first-class rebuildable SQLite cache through built-in `node:sqlite`
 - no daemon, hosted index, or vector DB
 
-Current package version in source: `0.3.4`
+Current package version in source: `0.3.6`
 
 mdkg is still pre-v1 public alpha software. The public package is usable, but graph, cache, bundle, and DAL contracts may continue to change quickly while the project converges on a stable v1 surface.
 
@@ -150,6 +150,29 @@ mdkg bundle list --json
 
 Bundles are explicit graph transport artifacts, separate from task context packs. Before a commit in repos that track archives or bundles, refresh compressed archive caches first, then create the private bundle so the committed graph state is self-consistent. Private bundles are the default and may be committed in private repos when configured. Public bundles require at least one selected workspace with `visibility: public` and include only public workspace content and public archive sidecars; bundle creation fails if public content points at private graph, archive, or subgraph records.
 
+Clone or fork a reusable graph template into a separate target when the target
+should preserve IDs as its own graph namespace:
+
+```bash
+mdkg graph clone .mdkg/bundles/private/all.mdkg.zip --target demos/demo-1 --json
+mdkg graph fork templates/website-template-mdkg --target demos/live-build --start-goal goal-1 --json
+```
+
+Import a template graph into the current repo only through the rewritten-ID
+path. Review the dry-run receipt first, then apply explicitly:
+
+```bash
+mdkg graph import-template templates/website-template-mdkg --start-goal goal-1 --select-goal --dry-run --json
+mdkg graph import-template templates/website-template-mdkg --start-goal goal-1 --select-goal --apply --json
+```
+
+`graph clone` and `graph fork` preserve IDs; `graph import-template` rewrites
+canonical numeric IDs and internal links to avoid same-repo collisions. With
+`--select-goal --apply`, import-template activates the rewritten imported start
+goal, pauses competing active root goals, validates the graph, and then writes
+selected-goal state. Subgraphs remain read-only planning views; use
+`mdkg graph ...` when authored graph state should be created.
+
 Register a child repo bundle as a read-only subgraph planning view:
 
 ```bash
@@ -185,6 +208,20 @@ Materialized trees are generated local state, ignored by graph indexing/search/v
 
 Subgraph nodes are projected under the subgraph alias, for example `child_repo:task-1`. They are available to `list`, `search`, `show`, `pack`, capability discovery, and `capability resolve`, but remain read-only; mutate the child repo and sync its root-owned bundle snapshot to change subgraph content. Root-authored relationship and reference fields can point at configured subgraph qids such as `child_repo:work.example`; local ownership fields such as `epic`, `parent`, `prev`, and `next` stay local-only. Stale subgraphs warn during planning reads and fail `mdkg subgraph verify`. Public or internal subgraphs must be backed by public bundle profiles; private subgraphs stay private planning context.
 
+Launch a local read-only MCP server when an MCP-capable agent should inspect a
+specific mdkg graph without receiving mutation tools:
+
+```bash
+mdkg mcp serve --stdio --root /path/to/repo
+```
+
+The MCP surface is stdio-only in this release. It exposes read-only tools for
+status, workspace/subgraph listing, search, show, in-memory pack generation,
+goal current/next, and validation. It does not expose task updates, goal
+activation, graph import, queue, event, archive, format, SQL, shell, arbitrary
+file reads, filesystem mutation, environment variables, or secret access.
+Future mutation allowlists remain design work.
+
 Validate before handoff or commit:
 
 ```bash
@@ -309,6 +346,7 @@ These are the commands new users and agents should learn first:
 - `mdkg task`
 - `mdkg validate`
 - `mdkg status`
+- `mdkg mcp`
 - `mdkg fix`
 
 Advanced / maintenance commands still exist, but they are not the first-run story:

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"));
@@ -19,12 +20,14 @@ 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");
 const spec_1 = require("./commands/spec");
 const archive_1 = require("./commands/archive");
 const bundle_1 = require("./commands/bundle");
+const graph_1 = require("./commands/graph");
 const subgraph_1 = require("./commands/subgraph");
 const checkpoint_1 = require("./commands/checkpoint");
 const init_1 = require("./commands/init");
@@ -69,6 +72,7 @@ function printUsage(log) {
     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("  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");
@@ -76,6 +80,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");
@@ -554,6 +559,45 @@ function printBundleHelp(log, subcommand) {
     }
     printGlobalOptions(log);
 }
+function printGraphHelp(log, subcommand) {
+    switch ((subcommand ?? "").toLowerCase()) {
+        case "clone":
+            log("Usage:");
+            log("  mdkg graph clone <source-bundle-or-mdkg-dir> --target <path> [--json]");
+            log("\nNotes:");
+            log("  - clones a complete graph into an empty contained target directory");
+            log("  - preserves IDs because the target is a separate graph namespace");
+            log("  - source bundle or source directory is never mutated");
+            break;
+        case "fork":
+            log("Usage:");
+            log("  mdkg graph fork <source-bundle-or-mdkg-dir> --target <path> [--start-goal <goal-id>] [--json]");
+            log("\nNotes:");
+            log("  - forks a complete graph into an empty contained target directory");
+            log("  - preserves IDs and can select a start goal in the target graph");
+            log("  - source bundle or source directory is never mutated");
+            break;
+        case "import-template":
+            log("Usage:");
+            log("  mdkg graph import-template <source-bundle-or-mdkg-dir> [--start-goal <goal-id>] [--select-goal] [--id-prefix <prefix>] [--dry-run] [--apply] [--json]");
+            log("\nNotes:");
+            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; on apply it activates the imported start goal, pauses competing active root goals, validates, then writes selected-goal state");
+            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("\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("  - subgraphs remain read-only bundle projections for orchestration context");
+    }
+    printGlobalOptions(log);
+}
 function printSubgraphHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "add":
@@ -882,6 +926,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":
@@ -1020,6 +1087,9 @@ function printCommandHelp(log, command, subcommand) {
         case "bundle":
             printBundleHelp(log, subcommand);
             return;
+        case "graph":
+            printGraphHelp(log, subcommand);
+            return;
         case "subgraph":
             printSubgraphHelp(log, subcommand);
             return;
@@ -1047,6 +1117,9 @@ function printCommandHelp(log, command, subcommand) {
         case "status":
             printStatusHelp(log);
             return;
+        case "mcp":
+            printMcpHelp(log, subcommand);
+            return;
         case "fix":
             printFixHelp(log, subcommand);
             return;
@@ -1687,6 +1760,49 @@ function runBundleSubcommand(parsed, root) {
             throw new errors_1.UsageError("bundle requires create/list/show/verify");
     }
 }
+function runGraphSubcommand(parsed, root) {
+    const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
+    const source = parsed.positionals[2];
+    const target = requireFlagValue("--target", parsed.flags["--target"]);
+    const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+    switch (subcommand) {
+        case "clone": {
+            if (!source || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("graph clone requires <source-bundle-or-mdkg-dir>");
+            }
+            if (!target) {
+                throw new errors_1.UsageError("graph clone requires --target <path>");
+            }
+            (0, graph_1.runGraphCloneCommand)({ root, source, target, json });
+            return 0;
+        }
+        case "fork": {
+            if (!source || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("graph fork requires <source-bundle-or-mdkg-dir>");
+            }
+            if (!target) {
+                throw new errors_1.UsageError("graph fork requires --target <path>");
+            }
+            const startGoal = requireFlagValue("--start-goal", parsed.flags["--start-goal"]);
+            (0, graph_1.runGraphForkCommand)({ root, source, target, startGoal, json });
+            return 0;
+        }
+        case "import-template": {
+            if (!source || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("graph import-template requires <source-bundle-or-mdkg-dir>");
+            }
+            const startGoal = requireFlagValue("--start-goal", parsed.flags["--start-goal"]);
+            const idPrefix = requireFlagValue("--id-prefix", parsed.flags["--id-prefix"]);
+            const dryRun = parseBooleanFlag("--dry-run", parsed.flags["--dry-run"]);
+            const apply = parseBooleanFlag("--apply", parsed.flags["--apply"]);
+            const selectGoal = parseBooleanFlag("--select-goal", parsed.flags["--select-goal"]);
+            (0, graph_1.runGraphImportTemplateCommand)({ root, source, startGoal, idPrefix, dryRun, apply, selectGoal, json });
+            return 0;
+        }
+        default:
+            throw new errors_1.UsageError("graph requires clone/fork/import-template");
+    }
+}
 function runSubgraphSubcommand(parsed, root) {
     const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
     const json = parseBooleanFlag("--json", parsed.flags["--json"]);
@@ -2479,6 +2595,8 @@ function runCommand(parsed, root, runtime) {
             return runArchiveSubcommand(parsed, root);
         case "bundle":
             return runBundleSubcommand(parsed, root);
+        case "graph":
+            return runGraphSubcommand(parsed, root);
         case "subgraph":
             return runSubgraphSubcommand(parsed, root);
         case "work":
@@ -2699,6 +2817,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) {
@@ -2749,6 +2869,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);
@@ -2786,8 +2918,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();