mdkg 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -8,6 +8,28 @@ mdkg is pre-v1 public alpha software. Command, graph, cache, bundle, and DAL con
 
 ## Unreleased
 
+## 0.5.2 - 2026-07-15
+
+### Added
+
+- Added `mdkg git materialize --request <file|-> --json` with strict
+  `mdkg.git.materialize.request.v1` parsing, full-ref accepted-revision
+  verification, SHA-1/SHA-256 support, bounded auth capability checks, explicit
+  submodule/project-memory policies, and atomic contained publication.
+- Added bounded `mdkg.git.materialize.receipt.v1` success and failure evidence,
+  installed-tarball consumer coverage, generated CLI contract metadata, and a
+  dedicated docs.mdkg.dev advanced-alpha guide.
+
+### Security
+
+- Disabled Git prompts, repository hooks, push, and recursive submodules during
+  materialization; candidate project-memory validation does not index or execute
+  repository-controlled scripts, hooks, skills, or commands.
+- Redacted credentials, environment values, helper output, socket paths, raw Git
+  output, repository contents, and absolute local paths from materialization
+  receipts while preserving bounded identity, policy, destination, and cleanup
+  evidence.
+
 ## 0.5.1 - 2026-07-14
 
 ### Changed

package/CLI_COMMAND_MATRIX.md

@@ -1,7 +1,7 @@
 # CLI Command Matrix
 
-as_of: 2026-07-14
-package_version_in_source: 0.5.1
+as_of: 2026-07-15
+package_version_in_source: 0.5.2
 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
 
@@ -779,12 +779,14 @@ JSON receipts:
 
 When to use:
 - inspect the current Git-backed mdkg project and accepted revision evidence
+- materialize a strict caller-selected Git ref only after commit, tree, and policy verification
 - clone or fetch real Git remotes through the system Git CLI with external auth
 - close out mdkg state to static receipts before an agent checkpoint commit
 - prove push readiness before any approval-gated real remote push
 
 Usage:
 - `mdkg git inspect [--json]`
+- `mdkg git materialize --request <file|-> [--json]`
 - `mdkg git clone <repository-ref> --target <path> [--branch <name>] [--json]`
 - `mdkg git fetch [--remote <name>] [--branch <name>] [--json]`
 - `mdkg git closeout [--queue-policy drain|paused] [--output <path>] [--json]`
@@ -794,6 +796,7 @@ Usage:
 - `mdkg git push --remote <name> --branch <name> [--stage-all --message <text>] [--json]`
 
 Flags:
+- `--request <file|->`
 - `--target <path>`
 - `--branch <name>`
 - `--remote <name>`
@@ -808,6 +811,10 @@ Notes:
 - v1 uses the system Git CLI; authentication stays external through credential helpers, SSH, `gh`, CI/runtime env, or shell state
 - mdkg rejects repository refs and push remotes with embedded URL credentials; inspected remotes with userinfo are redacted before receipts are printed
 - `git inspect` is read-only and emits sanitized source descriptors plus accepted-revision hashes
+- `git materialize` accepts only `mdkg.git.materialize.request.v1` JSON, rejects unsafe input before Git, verifies a full ref and exact commit/tree, and atomically renames a same-parent temporary tree into a contained destination
+- materialization disables prompts, repository hooks, push, and recursive submodules; project-memory checks do not index or execute repository-controlled behavior
+- `deny|ignore` controls submodule acceptance and `required|optional|forbidden` controls project-memory presence
+- materialization receipts never retain credentials, environment values, helper output, socket paths, raw Git output, repository contents, or absolute local paths
 - `git clone` writes only to an empty or absent contained `--target`; use `mdkg graph clone|fork` for bundle/template graph transport
 - `git closeout` validates mdkg state and writes static JSON and Markdown receipts under `.mdkg/git/closeouts` by default
 - when the project DB participated, `git closeout` also seals `.mdkg/db/state/project.sqlite` and writes a deterministic dump
@@ -817,6 +824,7 @@ Notes:
 
 JSON receipts:
 - `inspect`: `{ action: "git.inspect", ok, root, inside_work_tree, branch, head_sha, tree_hash, remotes, status, source_descriptor, accepted_revision, warnings }`
+- `materialize`: `{ schema: "mdkg.git.materialize.receipt.v1", action: "git.materialize", ok, reason_code, request_hash, repository, source_ref, access_ref, correlation_ref, evidence_refs, target_ref, expected_revision, observed_revision, policies, destination, cleanup, warnings }`
 - `clone`: `{ action: "git.clone", ok, repository_ref, target, branch, source_descriptor, accepted_revision, inspect, warnings }`
 - `fetch`: `{ action: "git.fetch", ok, remote, branch, fetch_output, inspect, warnings }`
 - `closeout`: `{ action: "git.closeout", ok, root, output_dir, generated_at, git, validation, db_participated, db_snapshot_status, db_snapshot_seal, db_snapshot_dump, static_receipts, warnings }`

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.5.1`
+Current package version in source: `0.5.2`
 
 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.
 
@@ -242,11 +242,13 @@ Subgraph nodes are projected under the subgraph alias, for example `child_repo:t
 
 Use `mdkg graph refs <id-or-qid> --json` to inspect inbound and outbound scope, context, evidence, blocker, related, and structural links for local or read-only subgraph qids without mutating either graph.
 
-Use low-level Git lifecycle receipts when an agent run needs to close out local
-mdkg state and prove push readiness before an explicit remote update:
+Use low-level Git lifecycle receipts when an agent run needs to accept an exact
+source revision, close out local mdkg state, or prove push readiness before an
+explicit remote update:
 
 ```bash
 mdkg git inspect --json
+mdkg git materialize --request materialize-request.json --json
 mdkg git clone git@github.com:org/repo.git --target worktrees/repo --branch main --json
 mdkg git fetch --remote origin --branch main --json
 mdkg git closeout --json
@@ -257,7 +259,12 @@ mdkg git push --remote origin --branch main --stage-all --message "agent checkpo
 `mdkg git` uses the system Git CLI. Authentication stays external through SSH,
 credential helpers, `gh`, CI/runtime environment, or shell state; mdkg rejects
 embedded URL credentials and records only sanitized refs, hashes, policy names,
-and receipts. `closeout` validates mdkg state before writing static JSON and
+and receipts. `materialize` accepts only strict
+`mdkg.git.materialize.request.v1` JSON, verifies the full target ref and
+accepted revision, and publishes a contained destination only after all checks
+pass; see the [verified Git materialization
+guide](https://docs.mdkg.dev/advanced-alpha/git-materialization/). `closeout`
+validates mdkg state before writing static JSON and
 Markdown receipts, and when the project DB participated it also seals the
 SQLite state and writes a deterministic dump. Treat real `mdkg git push` as an
 approval-gated operation in agent runtimes.

package/dist/cli.js

@@ -30,6 +30,7 @@ const archive_1 = require("./commands/archive");
 const bundle_1 = require("./commands/bundle");
 const graph_1 = require("./commands/graph");
 const git_1 = require("./commands/git");
+const git_materialize_1 = require("./commands/git_materialize");
 const subgraph_1 = require("./commands/subgraph");
 const checkpoint_1 = require("./commands/checkpoint");
 const init_1 = require("./commands/init");
@@ -79,7 +80,7 @@ function printUsage(log) {
     log("  archive     Add, list, show, verify, and compress archive sidecars");
     log("  bundle      Create, list, show, and verify full graph snapshot bundles");
     log("  graph       Clone, fork, import, and inspect mdkg graph references");
-    log("  git         Clone, fetch, inspect, close out, and push Git-backed mdkg projects");
+    log("  git         Materialize, clone, fetch, inspect, close out, and push Git-backed projects");
     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("  loop        List, show, fork, plan, and inspect first-class loop nodes");
@@ -709,6 +710,14 @@ function printGitHelp(log, subcommand) {
             log("  - --target must be empty or absent and stay inside the current repo");
             log("  - repository refs must not embed credentials");
             break;
+        case "materialize":
+            log("Usage:");
+            log("  mdkg git materialize --request <file|-> [--json]");
+            log("\nNotes:");
+            log("  - accepts only schema mdkg.git.materialize.request.v1 JSON");
+            log("  - verifies the full target ref, expected commit, optional tree, and policy checks before publishing");
+            log("  - uses external auth and an atomic contained destination; receipts never include credentials or raw Git output");
+            break;
         case "fetch":
             log("Usage:");
             log("  mdkg git fetch [--remote <name>] [--branch <name>] [--json]");
@@ -743,6 +752,7 @@ function printGitHelp(log, subcommand) {
         default:
             log("Usage:");
             log("  mdkg git inspect [--json]");
+            log("  mdkg git materialize --request <file|-> [--json]");
             log("  mdkg git clone <repository-ref> --target <path> [--branch <name>] [--json]");
             log("  mdkg git fetch [--remote <name>] [--branch <name>] [--json]");
             log("  mdkg git closeout [--queue-policy drain|paused] [--output <path>] [--json]");
@@ -2031,6 +2041,8 @@ function runGitSubcommand(parsed, root) {
             (0, git_1.runGitInspectCommand)({ root, json });
             return 0;
         }
+        case "materialize":
+            throw new errors_1.UsageError("git materialize requires the asynchronous CLI entrypoint");
         case "clone": {
             const repository = parsed.positionals[2];
             if (!repository || parsed.positionals.length > 3) {
@@ -2084,7 +2096,44 @@ function runGitSubcommand(parsed, root) {
             return 0;
         }
         default:
-            throw new errors_1.UsageError("git requires inspect/clone/fetch/closeout/push-ready/push");
+            throw new errors_1.UsageError("git requires inspect/materialize/clone/fetch/closeout/push-ready/push");
+    }
+}
+function printGitMaterializeReceipt(receipt, json, runtime) {
+    if (json) {
+        runtime.log(JSON.stringify(receipt, null, 2));
+        return;
+    }
+    if (receipt.ok) {
+        runtime.log("git materialize accepted");
+        runtime.log(`destination: ${receipt.destination.path ?? "(none)"}`);
+        runtime.log(`commit: ${receipt.observed_revision.commit ?? "(none)"}`);
+        runtime.log(`tree: ${receipt.observed_revision.tree ?? "(none)"}`);
+        return;
+    }
+    runtime.error(`git materialize failed: ${receipt.reason_code}`);
+    runtime.error(`destination: ${receipt.destination.state}`);
+    runtime.error(`cleanup: ${receipt.cleanup.state}`);
+}
+async function runGitMaterializeSubcommand(parsed, root, runtime) {
+    if (parsed.positionals.length > 2) {
+        throw new errors_1.UsageError("git materialize does not accept positional arguments");
+    }
+    const request = requireFlagValue("--request", parsed.flags["--request"]);
+    if (!request)
+        throw new errors_1.UsageError("git materialize requires --request <file|->");
+    const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+    try {
+        const receipt = await (0, git_materialize_1.collectGitMaterializeReceipt)({ root, request });
+        printGitMaterializeReceipt(receipt, json, runtime);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof git_materialize_1.GitMaterializeError) {
+            printGitMaterializeReceipt(error.receipt, json, runtime);
+            return 2;
+        }
+        throw error;
     }
 }
 function runSubgraphSubcommand(parsed, root) {
@@ -3412,6 +3461,9 @@ async function runCliAsync(argv, runtime = {}) {
         if (command === "mcp") {
             return await runMcpSubcommand(parsed, root);
         }
+        if (command === "git" && (parsed.positionals[1] ?? "").toLowerCase() === "materialize") {
+            return await runGitMaterializeSubcommand(parsed, root, io);
+        }
         return runCommand(parsed, root, io);
     }
     catch (err) {