mdkg 0.4.1 → 0.5.0

package/dist/cli.js

@@ -29,12 +29,15 @@ 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 git_1 = require("./commands/git");
 const subgraph_1 = require("./commands/subgraph");
 const checkpoint_1 = require("./commands/checkpoint");
 const init_1 = require("./commands/init");
 const new_1 = require("./commands/new");
 const guide_1 = require("./commands/guide");
 const upgrade_1 = require("./commands/upgrade");
+const loop_1 = require("./commands/loop");
+const loop_descriptors_1 = require("./commands/loop_descriptors");
 const goal_1 = require("./commands/goal");
 const event_1 = require("./commands/event");
 const skill_1 = require("./commands/skill");
@@ -76,8 +79,10 @@ 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("  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");
     log("  goal        Inspect and advance recursive goal nodes");
     log("  task        Start, update, and complete task-like nodes");
     log("  next        Suggest the next work item");
@@ -144,7 +149,7 @@ function printNewHelp(log) {
     log("Usage:");
     log('  mdkg new <type> "<title>" [options] [--json]');
     log("\nTypes:");
-    log("  rule prd edd dec prop goal epic feat task bug spike checkpoint test");
+    log("  rule prd edd dec prop loop goal epic feat task bug spike checkpoint test");
     log("\nAgent workflow file types:");
     log("  manifest work work_order receipt feedback dispute proposal");
     log("  spec is a legacy alias for manifest and emits MANIFEST.md during the compatibility bridge.");
@@ -177,6 +182,34 @@ function printNewHelp(log) {
     log("  spikes do not run web search, create follow-up nodes, generate SKILL.md, or expose `mdkg spike ...`.");
     printGlobalOptions(log);
 }
+function printLoopHelp(log, subcommand) {
+    printLoopDescriptorHelp(log, (0, loop_descriptors_1.loopDescriptorForSubcommand)(subcommand));
+}
+function printLoopDescriptorHelp(log, descriptor) {
+    log("Usage:");
+    for (const usage of descriptor.usage) {
+        log(`  ${usage}`);
+    }
+    if (descriptor.key === "loop fork") {
+        log("\nMaterialization modes:");
+        log("  default_children planning_only manual");
+    }
+    const commandFlags = descriptor.flags.filter((flag) => flag.name !== "--root");
+    if (commandFlags.length > 0) {
+        log("\nOptions:");
+        for (const flag of commandFlags) {
+            const syntax = flag.value ? `${flag.name} ${flag.value}` : flag.name;
+            log(`  ${syntax.padEnd(28)} ${flag.description}`);
+        }
+    }
+    if (descriptor.notes.length > 0) {
+        log("\nNotes:");
+        for (const note of descriptor.notes) {
+            log(`  ${note}`);
+        }
+    }
+    printGlobalOptions(log);
+}
 function printGuideHelp(log) {
     log("Usage:");
     log("  mdkg guide");
@@ -316,9 +349,10 @@ function printListHelp(log) {
 function printSearchHelp(log) {
     log("Usage:");
     log('  mdkg search "<query>" [--type <type>] [--status <status>] [--ws <alias>]');
-    log("               [--tags <tag,tag,...>] [--tags-mode any|all] [--json|--xml|--toon|--md]");
+    log("               [--tags <tag,tag,...>] [--tags-mode any|all] [--limit <n>] [--json|--xml|--toon|--md]");
     log("\nWhen to use:");
     log("  Search mdkg nodes by metadata. Use `mdkg skill search` for skills.");
+    log("  Structured output defaults to a bounded page and reports count, returned_count, limit, and truncated.");
     printGlobalOptions(log);
 }
 function printPackHelp(log) {
@@ -653,6 +687,70 @@ function printGraphHelp(log, subcommand) {
     }
     printGlobalOptions(log);
 }
+function printGitHelp(log, subcommand) {
+    switch ((subcommand ?? "").toLowerCase()) {
+        case "inspect":
+            log("Usage:");
+            log("  mdkg git inspect [--json]");
+            log("\nNotes:");
+            log("  - read-only Git worktree, remote, branch, status, descriptor, and accepted-revision receipt");
+            log("  - remote URLs are redacted when userinfo is present");
+            break;
+        case "clone":
+            log("Usage:");
+            log("  mdkg git clone <repository-ref> --target <path> [--branch <name>] [--json]");
+            log("\nNotes:");
+            log("  - uses the system Git CLI and external Git auth");
+            log("  - --target must be empty or absent and stay inside the current repo");
+            log("  - repository refs must not embed credentials");
+            break;
+        case "fetch":
+            log("Usage:");
+            log("  mdkg git fetch [--remote <name>] [--branch <name>] [--json]");
+            log("\nNotes:");
+            log("  - defaults to remote origin");
+            log("  - auth stays external through Git credential helpers, SSH, gh, CI env, or shell state");
+            break;
+        case "closeout":
+            log("Usage:");
+            log("  mdkg git closeout [--queue-policy drain|paused] [--output <path>] [--json]");
+            log("\nNotes:");
+            log("  - validates mdkg state before writing closeout receipts");
+            log("  - when the project DB participated, seals SQLite state and writes a deterministic dump");
+            log("  - writes static JSON and Markdown receipts under .mdkg/git/closeouts by default");
+            break;
+        case "push-ready":
+            log("Usage:");
+            log("  mdkg git push-ready --remote <name> --branch <name> [--json]");
+            log("\nNotes:");
+            log("  - read-only high-bar preflight for explicit Git remote/branch push");
+            log("  - requires clean worktree, valid mdkg graph, external auth boundary, and valid DB snapshot when DB state participated");
+            break;
+        case "push":
+            log("Usage:");
+            log("  mdkg git push --remote <name> --branch <name> [--json]");
+            log("  mdkg git push --remote <name> --branch <name> --stage-all --message <text> [--queue-policy drain|paused] [--json]");
+            log("\nNotes:");
+            log("  - real Git push via system Git; requires explicit remote and branch");
+            log("  - --stage-all writes closeout evidence, stages all changes, commits with --message, then runs push-ready before pushing");
+            log("  - no raw credentials, tokens, SSH keys, prompts, payloads, or provider auth are stored in receipts");
+            break;
+        default:
+            log("Usage:");
+            log("  mdkg git inspect [--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]");
+            log("  mdkg git push-ready --remote <name> --branch <name> [--json]");
+            log("  mdkg git push --remote <name> --branch <name> [--stage-all --message <text>] [--json]");
+            log("\nBoundaries:");
+            log("  - mdkg git is a low-level Git lifecycle surface, not project-memory semantic search");
+            log("  - system Git is the v1 execution backend");
+            log("  - authentication stays external; mdkg records only refs, hashes, policy names, and receipts");
+            log("  - real push operations require explicit remote and branch and should be approval-gated by the caller");
+    }
+    printGlobalOptions(log);
+}
 function printSubgraphHelp(log, subcommand) {
     switch ((subcommand ?? "").toLowerCase()) {
         case "add":
@@ -1179,12 +1277,18 @@ function printCommandHelp(log, command, subcommand) {
         case "graph":
             printGraphHelp(log, subcommand);
             return;
+        case "git":
+            printGitHelp(log, subcommand);
+            return;
         case "subgraph":
             printSubgraphHelp(log, subcommand);
             return;
         case "work":
             printWorkHelp(log, subcommand);
             return;
+        case "loop":
+            printLoopHelp(log, subcommand);
+            return;
         case "task":
             printTaskHelp(log, subcommand);
             return;
@@ -1911,6 +2015,73 @@ function runGraphSubcommand(parsed, root) {
             throw new errors_1.UsageError("graph requires clone/fork/import-template/refs");
     }
 }
+function runGitSubcommand(parsed, root) {
+    const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
+    const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+    switch (subcommand) {
+        case "inspect": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("git inspect does not accept positional arguments");
+            }
+            (0, git_1.runGitInspectCommand)({ root, json });
+            return 0;
+        }
+        case "clone": {
+            const repository = parsed.positionals[2];
+            if (!repository || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("git clone requires <repository-ref>");
+            }
+            const target = requireFlagValue("--target", parsed.flags["--target"]);
+            if (!target) {
+                throw new errors_1.UsageError("git clone requires --target <path>");
+            }
+            const branch = requireFlagValue("--branch", parsed.flags["--branch"]);
+            (0, git_1.runGitCloneCommand)({ root, repository, target, branch, json });
+            return 0;
+        }
+        case "fetch": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("git fetch does not accept positional arguments");
+            }
+            const remote = requireFlagValue("--remote", parsed.flags["--remote"]);
+            const branch = requireFlagValue("--branch", parsed.flags["--branch"]);
+            (0, git_1.runGitFetchCommand)({ root, remote, branch, json });
+            return 0;
+        }
+        case "closeout": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("git closeout does not accept positional arguments");
+            }
+            const queuePolicy = parseQueuePolicyFlag(parsed.flags["--queue-policy"]);
+            const output = requireFlagValue("--output", parsed.flags["--out"]);
+            (0, git_1.runGitCloseoutCommand)({ root, queuePolicy, output, json });
+            return 0;
+        }
+        case "push-ready": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("git push-ready does not accept positional arguments");
+            }
+            const remote = requireFlagValue("--remote", parsed.flags["--remote"]);
+            const branch = requireFlagValue("--branch", parsed.flags["--branch"]);
+            (0, git_1.runGitPushReadyCommand)({ root, remote, branch, json });
+            return 0;
+        }
+        case "push": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("git push does not accept positional arguments");
+            }
+            const remote = requireFlagValue("--remote", parsed.flags["--remote"]);
+            const branch = requireFlagValue("--branch", parsed.flags["--branch"]);
+            const message = requireFlagValue("--message", parsed.flags["--message"]);
+            const stageAll = parseBooleanFlag("--stage-all", parsed.flags["--stage-all"]);
+            const queuePolicy = parseQueuePolicyFlag(parsed.flags["--queue-policy"]);
+            (0, git_1.runGitPushCommand)({ root, remote, branch, message, stageAll, queuePolicy, json });
+            return 0;
+        }
+        default:
+            throw new errors_1.UsageError("git requires inspect/clone/fetch/closeout/push-ready/push");
+    }
+}
 function runSubgraphSubcommand(parsed, root) {
     const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
     const json = parseBooleanFlag("--json", parsed.flags["--json"]);
@@ -2372,6 +2543,89 @@ function runSkillSubcommand(parsed, root) {
             throw new errors_1.UsageError("skill requires new/list/show/search/validate/sync");
     }
 }
+function runLoopSubcommand(parsed, root) {
+    const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
+    const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
+    const json = parseBooleanFlag("--json", parsed.flags["--json"]);
+    const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
+    const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
+    switch (subcommand) {
+        case "list": {
+            if (parsed.positionals.length > 2) {
+                throw new errors_1.UsageError("loop list does not accept positional arguments");
+            }
+            (0, loop_1.runLoopListCommand)({ root, ws, json, noCache, noReindex });
+            return 0;
+        }
+        case "show": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("loop show requires <loop-or-template>");
+            }
+            const metaOnly = parseBooleanFlag("--meta", parsed.flags["--meta"]);
+            (0, loop_1.runLoopShowCommand)({ root, id, ws, metaOnly, json, noCache, noReindex });
+            return 0;
+        }
+        case "fork": {
+            const template = parsed.positionals[2];
+            if (!template || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("loop fork requires <template>");
+            }
+            const scope = requireFlagValue("--scope", parsed.flags["--scope"]);
+            if (!scope) {
+                throw new errors_1.UsageError("loop fork requires --scope");
+            }
+            const title = requireFlagValue("--title", parsed.flags["--title"]);
+            const materializationMode = requireFlagValue("--materialization", parsed.flags["--materialization"]);
+            const planningOnly = parseBooleanFlag("--planning-only", parsed.flags["--planning-only"]);
+            const noChildren = parseBooleanFlag("--no-children", parsed.flags["--no-children"]);
+            const dryRun = parseBooleanFlag("--dry-run", parsed.flags["--dry-run"]);
+            const runId = requireFlagValue("--run-id", parsed.flags["--run-id"]);
+            (0, loop_1.runLoopForkCommand)({
+                root,
+                template,
+                scope,
+                title,
+                ws,
+                materializationMode: materializationMode,
+                planningOnly,
+                noChildren,
+                dryRun,
+                runId,
+                json,
+                noCache,
+                noReindex,
+            });
+            return 0;
+        }
+        case "plan": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("loop plan requires <loop>");
+            }
+            (0, loop_1.runLoopPlanCommand)({ root, id, ws, json, noCache, noReindex });
+            return 0;
+        }
+        case "next": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("loop next requires <loop>");
+            }
+            (0, loop_1.runLoopNextCommand)({ root, id, ws, json, noCache, noReindex });
+            return 0;
+        }
+        case "runs": {
+            const id = parsed.positionals[2];
+            if (!id || parsed.positionals.length > 3) {
+                throw new errors_1.UsageError("loop runs requires <loop>");
+            }
+            (0, loop_1.runLoopRunsCommand)({ root, id, ws, json, noCache, noReindex });
+            return 0;
+        }
+        default:
+            throw new errors_1.UsageError("loop requires list/show/fork/plan/next/runs");
+    }
+}
 function runGoalSubcommand(parsed, root) {
     const subcommand = (parsed.positionals[1] ?? "").toLowerCase();
     const ws = requireFlagValue("--ws", parsed.flags["--ws"]);
@@ -2747,10 +3001,14 @@ function runCommand(parsed, root, runtime) {
             return runBundleSubcommand(parsed, root);
         case "graph":
             return runGraphSubcommand(parsed, root);
+        case "git":
+            return runGitSubcommand(parsed, root);
         case "subgraph":
             return runSubgraphSubcommand(parsed, root);
         case "work":
             return runWorkSubcommand(parsed, root);
+        case "loop":
+            return runLoopSubcommand(parsed, root);
         case "goal":
             return runGoalSubcommand(parsed, root);
         case "task":
@@ -2819,6 +3077,7 @@ function runCommand(parsed, root, runtime) {
             const status = requireFlagValue("--status", parsed.flags["--status"]);
             const tags = parseCsvFlag("--tags", parsed.flags["--tags"]);
             const tagsMode = parseTagsModeFlag(parsed.flags["--tags-mode"]);
+            const limit = parseNumberFlag("--limit", parsed.flags["--limit"]);
             const format = parseQueryOutputFormat(parsed);
             const noCache = parseBooleanFlag("--no-cache", parsed.flags["--no-cache"]);
             const noReindex = parseBooleanFlag("--no-reindex", parsed.flags["--no-reindex"]);
@@ -2830,6 +3089,7 @@ function runCommand(parsed, root, runtime) {
                 status,
                 tags,
                 tagsMode,
+                limit,
                 format,
                 noCache,
                 noReindex,