mdkg 0.3.4 → 0.3.6

package/dist/commands/validate.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectValidateReceipt = collectValidateReceipt;
 exports.runValidateCommand = runValidateCommand;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -244,7 +245,7 @@ function validateEventsJsonl(root, config, errors) {
         }
     }
 }
-function runValidateCommand(options) {
+function collectValidateReceipt(options) {
     const config = (0, config_1.loadConfig)(options.root);
     const templateSchemaInfo = (0, template_schema_1.loadTemplateSchemasWithInfo)(options.root, config, node_1.ALLOWED_TYPES);
     const templateSchemas = templateSchemaInfo.schemas;
@@ -392,31 +393,35 @@ function runValidateCommand(options) {
         errors: uniqueErrors,
         ...(outPath ? { report_path: outPath } : {}),
     };
+    return receipt;
+}
+function runValidateCommand(options) {
+    const receipt = collectValidateReceipt(options);
     if (options.json) {
         console.log(JSON.stringify(receipt, null, 2));
-        if (uniqueErrors.length > 0) {
-            throw new errors_1.ValidationError(`validation failed with ${uniqueErrors.length} error(s)`);
+        if (receipt.error_count > 0) {
+            throw new errors_1.ValidationError(`validation failed with ${receipt.error_count} error(s)`);
         }
         return;
     }
     if (!options.quiet) {
-        for (const warning of uniqueWarnings) {
+        for (const warning of receipt.warnings) {
             console.error(`warning: ${warning}`);
         }
     }
-    if (uniqueErrors.length > 0) {
-        if (outPath) {
-            console.error(`validation failed: ${uniqueErrors.length} error(s). details written to ${outPath}`);
+    if (receipt.error_count > 0) {
+        if (receipt.report_path) {
+            console.error(`validation failed: ${receipt.error_count} error(s). details written to ${receipt.report_path}`);
         }
         else {
-            for (const error of uniqueErrors) {
+            for (const error of receipt.errors) {
                 console.error(error);
             }
         }
-        throw new errors_1.ValidationError(`validation failed with ${uniqueErrors.length} error(s)`);
+        throw new errors_1.ValidationError(`validation failed with ${receipt.error_count} error(s)`);
     }
-    if (outPath) {
-        console.log(`validation report written: ${outPath}`);
+    if (receipt.report_path) {
+        console.log(`validation report written: ${receipt.report_path}`);
     }
     console.log("validation ok");
 }

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -22,11 +22,14 @@ Primary commands:
 - `mdkg spec`
 - `mdkg archive`
 - `mdkg bundle`
+- `mdkg graph`
+- `mdkg subgraph`
 - `mdkg work`
 - `mdkg goal`
 - `mdkg task`
 - `mdkg validate`
 - `mdkg status [--json]`
+- `mdkg mcp serve --stdio`
 - `mdkg fix plan [--family index|refs|ids|all] [--target <id-or-qid>] [--base-ref <ref>] [--json]`
 - `mdkg fix apply [--family ids] [--target <id-or-qid>] [--base-ref <ref>] [--json]`
 - `mdkg fix ids [--target <id-or-qid>] [--base-ref <ref>] [--apply] [--json]`
@@ -42,6 +45,15 @@ Operator health:
 - graph-reference and index/cache findings remain review-only guidance
 - `fix plan --json` returns a receipt-shaped plan with selected families, risk counts, paths, reason codes, and per-change `apply_supported` metadata
 
+Local MCP server:
+- `mdkg mcp serve --stdio`
+- starts one local Model Context Protocol server bound to the selected `--root`
+- stdio is the only transport in this release; no HTTP listener is opened
+- exposes read-only tools for status, workspace/subgraph list, search, show, in-memory pack, goal current/next, and validate
+- exposes no task, goal activation, graph import, queue, event, archive, format, SQL, shell, arbitrary file-read, filesystem mutation, environment, or secret-access tools
+- use `--root <path>` when launching from outside the repo
+- stdout is reserved for newline-delimited JSON-RPC MCP messages
+
 Index backend:
 - fresh mdkg workspaces default to `index.backend: sqlite`
 - `.mdkg/index/mdkg.sqlite` is rebuildable and commit-eligible when intentionally tracked
@@ -204,6 +216,22 @@ Graph snapshot bundles:
 - public bundles include only public workspace content and public archive sidecars
 - public bundle creation fails when public records reference private graph, archive, or subgraph records
 
+Graph clone, fork, and template import:
+- `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]`
+- `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
+
 Subgraph orchestration:
 - `mdkg subgraph add <alias> <bundle-path> [--visibility private|internal|public] [--profile private|public] [--source-path <path>] [--json]`
 - `mdkg subgraph list [--json]`

package/dist/init/README.md

@@ -29,13 +29,14 @@ mdkg capability search "..."
 mdkg spec list --json
 mdkg archive list
 mdkg bundle create --profile private
+mdkg graph clone .mdkg/bundles/private/all.mdkg.zip --target demos/demo-1 --json
 mdkg subgraph list --json
 mdkg status --json
 mdkg fix plan --json
 mdkg validate
 ```
 
-This repo is already initialized. Use `mdkg upgrade` to preview safe scaffold updates, `mdkg index` to create or refresh generated graph/skill/capability/subgraph and SQLite caches after init, `mdkg new` to create work, `mdkg new goal "..."` plus `mdkg goal activate/current/next/claim/evaluate` for recursive long-running objectives, `mdkg search`/`mdkg show` to inspect graph state, `mdkg capability ...` to inspect cached skill/spec/work/core/design capabilities, `mdkg spec ...` for focused optional SPEC records, `mdkg capability resolve ...` to rank local and subgraph capabilities, `mdkg archive ...` to register source/artifact sidecars, `mdkg work ...` to create work contract/order/receipt semantic mirrors and deterministic trigger/verification records, `mdkg bundle ...` to create full graph snapshot bundles, `mdkg subgraph ...` to register read-only child graph planning views, `mdkg pack <id>` to build deterministic context, and `mdkg validate` before closeout.
+This repo is already initialized. Use `mdkg upgrade` to preview safe scaffold updates, `mdkg index` to create or refresh generated graph/skill/capability/subgraph and SQLite caches after init, `mdkg new` to create work, `mdkg new goal "..."` plus `mdkg goal activate/current/next/claim/evaluate` for recursive long-running objectives, `mdkg search`/`mdkg show` to inspect graph state, `mdkg capability ...` to inspect cached skill/spec/work/core/design capabilities, `mdkg spec ...` for focused optional SPEC records, `mdkg capability resolve ...` to rank local and subgraph capabilities, `mdkg archive ...` to register source/artifact sidecars, `mdkg work ...` to create work contract/order/receipt semantic mirrors and deterministic trigger/verification records, `mdkg bundle ...` to create full graph snapshot bundles, `mdkg graph ...` to clone/fork/import authored graph templates, `mdkg subgraph ...` to register read-only child graph planning views, `mdkg pack <id>` to build deterministic context, and `mdkg validate` before closeout.
 
 Use `mdkg status --json` for a read-only operator summary of Git, graph,
 selected-goal, project DB, and generated-cache health before mutating work. Use
@@ -158,6 +159,22 @@ mdkg bundle verify .mdkg/bundles/private/all.mdkg.zip
 
 Use this as a pre-commit recommendation only when the repo tracks archive caches or `.mdkg/bundles/`. Private bundles are local graph transport artifacts and may be tracked in private repos when configured. Public bundles require selected workspaces with `visibility: public` and fail closed when public records reference private graph, archive, or subgraph records.
 
+Clone or fork an authored graph into a separate repo/workspace while preserving IDs:
+
+```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 with deterministic ID and link rewrites:
+
+```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 because the target is a separate graph namespace. `graph import-template` rewrites canonical numeric IDs for same-repo imports and requires `--id-prefix` for colliding semantic IDs. 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 child bundle snapshots as read-only subgraphs with:
 
 ```bash
@@ -176,6 +193,14 @@ Use `mdkg subgraph materialize child_repo --target .mdkg/subgraphs --gitignore -
 
 Subgraph nodes use the subgraph alias as their qid prefix and can be inspected or packed, but mutations must happen in the owning child repo.
 
+Launch a local read-only MCP server when an MCP-capable agent should inspect this graph without receiving mutation tools:
+
+```bash
+mdkg mcp serve --stdio --root /path/to/repo
+```
+
+The MCP server 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.
+
 ## Archive and Work Mirrors
 
 Archive source/artifact files with:

package/dist/init/init-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "tool": "mdkg",
-  "mdkg_version": "0.3.4",
+  "mdkg_version": "0.3.6",
   "files": [
     {
       "path": ".mdkg/config.json",
@@ -61,7 +61,7 @@
     {
       "path": ".mdkg/README.md",
       "category": "mdkg_doc",
-      "sha256": "5962993e8dffd53ccbceaaedd0b8f2a868421a3a1cc16d7002b661b39b7ebf79"
+      "sha256": "cecb50528b70c0c4e32f8a052a668b5d87d6ac542818229efa848a6b1ac42d62"
     },
     {
       "path": ".mdkg/skills/build-pack-and-execute-task/SKILL.md",
@@ -261,7 +261,7 @@
     {
       "path": "CLI_COMMAND_MATRIX.md",
       "category": "startup_doc",
-      "sha256": "7322e6a2c47261f87dacd15ba0d93eba0d1e32eec0900a1e9f447ad13aaae860"
+      "sha256": "5321d82b594c1c0aa5574dcffbf21e5a1d3df89566b0f9acfc854fcaac3e13a7"
     },
     {
       "path": "llms.txt",

package/dist/util/argparse.js

@@ -95,6 +95,8 @@ const VALUE_FLAGS = new Set([
     "--target",
     "--snapshot",
     "--family",
+    "--start-goal",
+    "--id-prefix",
 ]);
 const BOOLEAN_FLAGS = new Set([
     "--tolerant",
@@ -132,6 +134,8 @@ const BOOLEAN_FLAGS = new Set([
     "--allow-dirty",
     "--clean",
     "--gitignore",
+    "--select-goal",
+    "--stdio",
 ]);
 const FLAG_ALIASES = {
     "--o": "--out",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdkg",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Markdown Knowledge Graph",
   "license": "MIT",
   "bin": {
@@ -33,6 +33,8 @@
     "smoke:spike": "npm run build && node scripts/smoke-spike.js",
     "smoke:goal-lifecycle": "npm run build && node scripts/smoke-goal-lifecycle.js",
     "smoke:bundle": "npm run build && node scripts/smoke-bundle.js",
+    "smoke:graph-clone": "npm run build && node scripts/smoke-graph-clone.js",
+    "smoke:mcp": "npm run build && node scripts/smoke-mcp.js",
     "smoke:bundle-import": "npm run smoke:subgraph",
     "smoke:visibility": "npm run build && node scripts/smoke-visibility.js",
     "smoke:sqlite": "npm run build && node scripts/smoke-sqlite.js",
@@ -42,7 +44,7 @@
     "cli:check": "npm run build && node scripts/cli_help_snapshot.js --check",
     "cli:contract": "npm run build && node scripts/generate-command-contract.js --check",
     "prepack": "npm run build && node scripts/assert-publish-ready.js",
-    "prepublishOnly": "npm run test && npm run cli:check && npm run cli:contract && node dist/cli.js validate && npm run smoke:consumer && npm run smoke:matrix && npm run smoke:upgrade && npm run smoke:init && npm run smoke:capabilities && npm run smoke:db && npm run smoke:db-queue && npm run smoke:db-queue-cli && npm run smoke:db-events && npm run smoke:db-materializer && npm run smoke:db-snapshot && npm run smoke:archive-work && npm run smoke:work-invocation && npm run smoke:cli-ux-polish && npm run smoke:operator-health && npm run smoke:fix-plan && npm run smoke:branch-conflicts && npm run smoke:id-repair && npm run smoke:command-docs && npm run smoke:spike && npm run smoke:goal-lifecycle && npm run smoke:bundle && npm run smoke:subgraph && npm run smoke:visibility && npm run smoke:sqlite && npm run smoke:parallel && npm run smoke:goal && node scripts/assert-publish-ready.js",
+    "prepublishOnly": "npm run test && npm run cli:check && npm run cli:contract && node dist/cli.js validate && npm run smoke:consumer && npm run smoke:matrix && npm run smoke:upgrade && npm run smoke:init && npm run smoke:capabilities && npm run smoke:db && npm run smoke:db-queue && npm run smoke:db-queue-cli && npm run smoke:db-events && npm run smoke:db-materializer && npm run smoke:db-snapshot && npm run smoke:archive-work && npm run smoke:work-invocation && npm run smoke:cli-ux-polish && npm run smoke:operator-health && npm run smoke:fix-plan && npm run smoke:branch-conflicts && npm run smoke:id-repair && npm run smoke:command-docs && npm run smoke:spike && npm run smoke:goal-lifecycle && npm run smoke:bundle && npm run smoke:graph-clone && npm run smoke:mcp && npm run smoke:subgraph && npm run smoke:visibility && npm run smoke:sqlite && npm run smoke:parallel && npm run smoke:goal && node scripts/assert-publish-ready.js",
     "postinstall": "node scripts/postinstall.js",
     "smoke:subgraph": "npm run build && node scripts/smoke-subgraph.js"
   },