mdkg 0.3.4 → 0.3.5

package/dist/commands/graph.js

@@ -0,0 +1,582 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runGraphCloneCommand = runGraphCloneCommand;
+exports.runGraphForkCommand = runGraphForkCommand;
+exports.runGraphImportTemplateCommand = runGraphImportTemplateCommand;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const bundle_1 = require("./bundle");
+const index_1 = require("./index");
+const validate_1 = require("./validate");
+const config_1 = require("../core/config");
+const workspace_path_1 = require("../core/workspace_path");
+const indexer_1 = require("../graph/indexer");
+const frontmatter_1 = require("../graph/frontmatter");
+const errors_1 = require("../util/errors");
+const qid_1 = require("../util/qid");
+const atomic_1 = require("../util/atomic");
+const zip_1 = require("../util/zip");
+const lock_1 = require("../util/lock");
+function writeJson(value) {
+    console.log(JSON.stringify(value, null, 2));
+}
+function toPosixPath(value) {
+    return value.split(path_1.default.sep).join("/");
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function rel(root, target) {
+    return toPosixPath(path_1.default.relative(root, target)) || ".";
+}
+function isInside(parent, child) {
+    const relative = path_1.default.relative(parent, child);
+    return relative === "" || (!relative.startsWith("..") && !path_1.default.isAbsolute(relative));
+}
+function resolveSourcePath(root, source) {
+    if (source.includes("\0")) {
+        throw new errors_1.UsageError("source cannot contain NUL bytes");
+    }
+    return path_1.default.isAbsolute(source) ? source : path_1.default.resolve(root, source);
+}
+function safeZipEntryPath(entryName) {
+    const normalized = entryName.replace(/\\/g, "/");
+    const parts = normalized.split("/");
+    if (path_1.default.isAbsolute(normalized) ||
+        parts.some((part) => part === "..") ||
+        parts.some((part) => part.length === 0)) {
+        throw new errors_1.ValidationError(`unsafe graph source entry path: ${entryName}`);
+    }
+    return normalized;
+}
+function resolveSourceDirectory(sourcePath) {
+    if (!fs_1.default.existsSync(sourcePath) || !fs_1.default.statSync(sourcePath).isDirectory()) {
+        return undefined;
+    }
+    const directConfig = path_1.default.join(sourcePath, ".mdkg", "config.json");
+    if (fs_1.default.existsSync(directConfig)) {
+        return sourcePath;
+    }
+    if (path_1.default.basename(sourcePath) === ".mdkg" && fs_1.default.existsSync(path_1.default.join(sourcePath, "config.json"))) {
+        return path_1.default.dirname(sourcePath);
+    }
+    throw new errors_1.UsageError("directory source must contain .mdkg/config.json or be an .mdkg directory");
+}
+function loadGraphSource(root, source) {
+    const sourcePath = resolveSourcePath(root, source);
+    const sourceRoot = resolveSourceDirectory(sourcePath);
+    if (sourceRoot) {
+        const bundle = (0, bundle_1.buildBundle)({ root: sourceRoot, profile: "private" });
+        return {
+            kind: "directory",
+            sourcePath,
+            sourceRoot,
+            entries: new Map((0, zip_1.readZipEntries)(bundle.zip).map((entry) => [entry.name, entry.data])),
+            manifest: bundle.manifest,
+            zipSha256: bundle.zipSha256,
+        };
+    }
+    if (!fs_1.default.existsSync(sourcePath)) {
+        throw new errors_1.NotFoundError(`graph source not found: ${source}`);
+    }
+    if (!fs_1.default.statSync(sourcePath).isFile()) {
+        throw new errors_1.UsageError("source must be a bundle file or directory containing .mdkg");
+    }
+    const parsed = (0, bundle_1.parseBundle)(sourcePath);
+    return {
+        kind: "bundle",
+        sourcePath,
+        entries: parsed.entries,
+        manifest: parsed.manifest,
+        zipSha256: (0, bundle_1.sha256Buffer)(fs_1.default.readFileSync(sourcePath)),
+    };
+}
+function resolveTargetRoot(root, target) {
+    let contained;
+    try {
+        contained = (0, workspace_path_1.normalizeContainedWorkspacePath)(target, "--target");
+    }
+    catch (err) {
+        throw new errors_1.UsageError(err instanceof Error ? err.message : String(err));
+    }
+    const targetRoot = path_1.default.resolve(root, contained);
+    if (!isInside(root, targetRoot)) {
+        throw new errors_1.UsageError("--target must stay inside the current mdkg root");
+    }
+    if (fs_1.default.existsSync(targetRoot)) {
+        const entries = fs_1.default.readdirSync(targetRoot);
+        if (entries.length > 0) {
+            throw new errors_1.UsageError(`target must be empty or absent: ${rel(root, targetRoot)}`);
+        }
+    }
+    return targetRoot;
+}
+function assertSourceNotMutatedByTarget(source, targetRoot) {
+    if (source.kind !== "directory" || !source.sourceRoot) {
+        return;
+    }
+    const sourceRoot = path_1.default.resolve(source.sourceRoot);
+    if (isInside(sourceRoot, targetRoot)) {
+        throw new errors_1.UsageError("target must not be inside the live directory source");
+    }
+}
+function writeGraphFiles(targetRoot, source) {
+    const filesWritten = [];
+    const skippedPaths = [];
+    for (const file of source.manifest.files) {
+        const safeName = safeZipEntryPath(file.path);
+        if (file.kind === "generated_index") {
+            skippedPaths.push(safeName);
+            continue;
+        }
+        const data = source.entries.get(file.path);
+        if (!data) {
+            throw new errors_1.ValidationError(`graph source missing bundled file: ${file.path}`);
+        }
+        const output = path_1.default.join(targetRoot, safeName);
+        fs_1.default.mkdirSync(path_1.default.dirname(output), { recursive: true });
+        fs_1.default.writeFileSync(output, data);
+        filesWritten.push(safeName);
+    }
+    return { filesWritten: filesWritten.sort(), skippedPaths: skippedPaths.sort() };
+}
+function indexPathsReceipt(root, result) {
+    return {
+        nodes: rel(root, result.paths.nodes),
+        skills: rel(root, result.paths.skills),
+        capabilities: rel(root, result.paths.capabilities),
+        subgraphs: rel(root, result.paths.subgraphs),
+        sqlite: result.paths.sqlite ? rel(root, result.paths.sqlite) : null,
+    };
+}
+function resolveStartGoal(targetRoot, requested) {
+    const config = (0, config_1.loadConfig)(targetRoot);
+    const index = (0, indexer_1.buildIndex)(targetRoot, config);
+    const resolved = (0, qid_1.resolveQid)(index, requested, undefined);
+    if (resolved.status !== "ok") {
+        throw new errors_1.NotFoundError((0, qid_1.formatResolveError)("goal", requested, resolved, undefined));
+    }
+    const node = index.nodes[resolved.qid];
+    if (!node || node.type !== "goal") {
+        throw new errors_1.UsageError(`start goal must resolve to a goal: ${requested}`);
+    }
+    return node;
+}
+function writeSelectedGoal(targetRoot, qid, id, ws) {
+    const statePath = path_1.default.join(targetRoot, ".mdkg", "state", "selected-goal.json");
+    const state = {
+        qid,
+        id,
+        ws,
+        selected_at: new Date().toISOString(),
+    };
+    (0, atomic_1.atomicWriteFile)(statePath, `${JSON.stringify(state, null, 2)}\n`);
+    return rel(targetRoot, statePath);
+}
+function isWorkMarkdownPath(value) {
+    const normalized = value.replace(/\\/g, "/");
+    return normalized.startsWith(".mdkg/work/") && normalized.endsWith(".md");
+}
+function numericIdPrefix(value) {
+    const match = /^([a-z]+)-([0-9]+)$/.exec(value);
+    return match?.[1];
+}
+function normalizeIdPrefix(value) {
+    const normalized = value.trim().toLowerCase();
+    if (!/^[a-z][a-z0-9_-]*$/.test(normalized)) {
+        throw new errors_1.UsageError("--id-prefix must start with a letter and use lowercase letters, numbers, underscore, or dash");
+    }
+    return normalized;
+}
+function nextNumericId(fromId, usedIds) {
+    const prefix = numericIdPrefix(fromId);
+    if (!prefix) {
+        throw new errors_1.UsageError(`cannot rewrite non-numeric template id without --id-prefix: ${fromId}`);
+    }
+    let next = 1;
+    while (usedIds.has(`${prefix}-${next}`)) {
+        next += 1;
+    }
+    return `${prefix}-${next}`;
+}
+function prefixedId(prefix, fromId, usedIds) {
+    let candidate = `${prefix}-${fromId}`.replace(/[^a-z0-9._-]+/g, "-");
+    let suffix = 2;
+    while (usedIds.has(candidate)) {
+        candidate = `${prefix}-${fromId}-${suffix}`.replace(/[^a-z0-9._-]+/g, "-");
+        suffix += 1;
+    }
+    return candidate;
+}
+function rewriteStringValue(value, idMap, pathLabel, field, rewrites) {
+    let output = value;
+    for (const [fromId, toId] of Array.from(idMap.entries()).sort((a, b) => b[0].length - a[0].length)) {
+        const replacements = [
+            [new RegExp(`\\broot:${escapeRegExp(fromId)}\\b`, "g"), `root:${toId}`, `root:${fromId}`],
+            [
+                new RegExp(`(^|[^a-zA-Z0-9._:-])${escapeRegExp(fromId)}(?=$|[^a-zA-Z0-9._:-])`, "g"),
+                `$1${toId}`,
+                fromId,
+            ],
+        ];
+        for (const [pattern, replacement, loggedFrom] of replacements) {
+            let count = 0;
+            output = output.replace(pattern, (...args) => {
+                count += 1;
+                return typeof replacement === "string" ? replacement.replace("$1", String(args[1] ?? "")) : replacement;
+            });
+            if (count > 0) {
+                rewrites.push({
+                    path: pathLabel,
+                    field,
+                    from: loggedFrom,
+                    to: loggedFrom.startsWith("root:") ? `root:${toId}` : toId,
+                    count,
+                });
+            }
+        }
+    }
+    return output;
+}
+function rewriteFrontmatterValue(value, idMap, pathLabel, field, rewrites) {
+    if (Array.isArray(value)) {
+        return value.map((item) => rewriteStringValue(item, idMap, pathLabel, field, rewrites));
+    }
+    if (typeof value === "string") {
+        return rewriteStringValue(value, idMap, pathLabel, field, rewrites);
+    }
+    return value;
+}
+function targetPathForImport(sourcePath, fromId, toId, usedPaths) {
+    const basename = path_1.default.posix.basename(sourcePath);
+    const suffix = basename.startsWith(fromId) ? basename.slice(fromId.length) : ".md";
+    let candidate = `.mdkg/work/${toId}${suffix}`;
+    let count = 2;
+    while (usedPaths.has(candidate)) {
+        candidate = `.mdkg/work/${toId}-${count}.md`;
+        count += 1;
+    }
+    usedPaths.add(candidate);
+    return candidate;
+}
+function renderNode(frontmatter, body) {
+    return ["---", ...(0, frontmatter_1.formatFrontmatter)(frontmatter, frontmatter_1.DEFAULT_FRONTMATTER_KEY_ORDER), "---", body].join("\n");
+}
+function localIdsAndPaths(root) {
+    const config = (0, config_1.loadConfig)(root);
+    const index = (0, indexer_1.buildIndex)(root, config);
+    return {
+        ids: new Set(Object.values(index.nodes).filter((node) => !node.source?.imported).map((node) => node.id)),
+        paths: new Set(Object.values(index.nodes).filter((node) => !node.source?.imported).map((node) => node.path)),
+    };
+}
+function planImportTemplate(options) {
+    if (options.dryRun && options.apply) {
+        throw new errors_1.UsageError("choose either --dry-run or --apply, not both");
+    }
+    if (options.selectGoal && !options.startGoal) {
+        throw new errors_1.UsageError("--select-goal requires --start-goal <goal-id>");
+    }
+    const source = loadGraphSource(options.root, options.source);
+    const idPrefix = options.idPrefix ? normalizeIdPrefix(options.idPrefix) : undefined;
+    const { ids: usedIds, paths: usedPaths } = localIdsAndPaths(options.root);
+    const workFiles = source.manifest.files
+        .map((file) => safeZipEntryPath(file.path))
+        .filter(isWorkMarkdownPath)
+        .sort();
+    const skippedPaths = source.manifest.files
+        .map((file) => safeZipEntryPath(file.path))
+        .filter((filePath) => !isWorkMarkdownPath(filePath))
+        .sort();
+    const imported = workFiles.map((sourcePath) => {
+        const data = source.entries.get(sourcePath);
+        if (!data) {
+            throw new errors_1.ValidationError(`graph source missing bundled file: ${sourcePath}`);
+        }
+        const parsed = (0, frontmatter_1.parseFrontmatter)(data.toString("utf8"), sourcePath);
+        const id = typeof parsed.frontmatter.id === "string" ? parsed.frontmatter.id : undefined;
+        const type = typeof parsed.frontmatter.type === "string" ? parsed.frontmatter.type : undefined;
+        if (!id || !type) {
+            throw new errors_1.ValidationError(`${sourcePath}: imported node requires string id and type`);
+        }
+        return { sourcePath, parsed, id, type };
+    });
+    const idMap = new Map();
+    for (const node of imported) {
+        const mustRewrite = usedIds.has(node.id) || Boolean(numericIdPrefix(node.id));
+        if (mustRewrite && !numericIdPrefix(node.id) && !idPrefix) {
+            throw new errors_1.UsageError(`cannot rewrite non-numeric template id without --id-prefix: ${node.id}`);
+        }
+        const toId = mustRewrite
+            ? numericIdPrefix(node.id)
+                ? nextNumericId(node.id, usedIds)
+                : prefixedId(idPrefix, node.id, usedIds)
+            : node.id;
+        usedIds.add(toId);
+        idMap.set(node.id, toId);
+    }
+    const rewrittenRefs = [];
+    const plans = imported.map((node) => {
+        const toId = idMap.get(node.id) ?? node.id;
+        const frontmatter = { ...node.parsed.frontmatter, id: toId };
+        for (const [field, value] of Object.entries(frontmatter)) {
+            if (field === "id") {
+                continue;
+            }
+            frontmatter[field] = rewriteFrontmatterValue(value, idMap, node.sourcePath, field, rewrittenRefs);
+        }
+        const body = rewriteStringValue(node.parsed.body, idMap, node.sourcePath, "body", rewrittenRefs);
+        const targetPath = targetPathForImport(node.sourcePath, node.id, toId, usedPaths);
+        const targetAbs = path_1.default.resolve(options.root, targetPath);
+        if (fs_1.default.existsSync(targetAbs)) {
+            throw new errors_1.UsageError(`import target already exists after rewrite: ${targetPath}`);
+        }
+        return {
+            source_path: node.sourcePath,
+            target_path: targetPath,
+            from_id: node.id,
+            to_id: toId,
+            type: node.type,
+            title: typeof frontmatter.title === "string" ? frontmatter.title : undefined,
+            content: renderNode(frontmatter, body),
+        };
+    });
+    const startGoalToId = options.startGoal ? (idMap.get(options.startGoal) ?? options.startGoal) : undefined;
+    if (options.startGoal && !plans.some((plan) => plan.to_id === startGoalToId && plan.type === "goal")) {
+        throw new errors_1.NotFoundError(`start goal not found in imported template graph: ${options.startGoal}`);
+    }
+    const mode = options.apply ? "import_template_applied" : "import_template_dry_run";
+    return {
+        action: "graph.import_template",
+        ok: true,
+        mode,
+        source: {
+            kind: source.kind,
+            path: rel(options.root, source.sourcePath),
+            ...(source.sourceRoot ? { source_root: rel(options.root, source.sourceRoot) } : {}),
+            profile: source.manifest.profile,
+            selected_workspaces: source.manifest.selected_workspaces,
+        },
+        source_hash: {
+            source_tree_hash: source.manifest.source_tree_hash,
+            bundle_hash: source.manifest.bundle_hash,
+            zip_sha256: source.zipSha256,
+        },
+        preserved_ids: false,
+        rewritten_ids: plans.map((plan) => ({
+            from_id: plan.from_id,
+            to_id: plan.to_id,
+            from_path: plan.source_path,
+            to_path: plan.target_path,
+            reason: plan.from_id === plan.to_id ? "preserved_non_colliding_id" : "same_repo_import_rewrite",
+        })),
+        rewritten_refs: rewrittenRefs.sort((a, b) => `${a.path}:${a.field}:${a.from}`.localeCompare(`${b.path}:${b.field}:${b.from}`)),
+        planned_paths: plans.map((plan) => plan.target_path).sort(),
+        files_written: [],
+        skipped_paths: skippedPaths,
+        ...(options.startGoal && startGoalToId
+            ? { start_goal: { requested: options.startGoal, from_qid: `root:${options.startGoal}`, to_qid: `root:${startGoalToId}` } }
+            : {}),
+        ...(options.selectGoal && startGoalToId
+            ? { selected_goal: { qid: `root:${startGoalToId}`, path: ".mdkg/state/selected-goal.json", planned: !options.apply } }
+            : {}),
+        warnings: [],
+    };
+}
+function applyImportTemplate(options, receipt) {
+    const config = (0, config_1.loadConfig)(options.root);
+    return (0, lock_1.withMutationLock)(options.root, config.index.lock_timeout_ms, () => {
+        for (const plan of receipt.rewritten_ids) {
+            const source = receipt.planned_paths.find((targetPath) => targetPath === plan.to_path);
+            if (!source) {
+                throw new errors_1.UsageError(`import plan missing target path for ${plan.from_id}`);
+            }
+        }
+        const source = loadGraphSource(options.root, options.source);
+        const idPrefix = options.idPrefix ? normalizeIdPrefix(options.idPrefix) : undefined;
+        const applyPlan = planImportTemplate({ ...options, apply: true, dryRun: false, idPrefix });
+        const files = applyPlan.planned_paths;
+        const workFiles = source.manifest.files
+            .map((file) => safeZipEntryPath(file.path))
+            .filter(isWorkMarkdownPath)
+            .sort();
+        const contentByTarget = new Map();
+        const { ids: usedIds, paths: usedPaths } = localIdsAndPaths(options.root);
+        const imported = workFiles.map((sourcePath) => {
+            const data = source.entries.get(sourcePath);
+            if (!data) {
+                throw new errors_1.ValidationError(`graph source missing bundled file: ${sourcePath}`);
+            }
+            const parsed = (0, frontmatter_1.parseFrontmatter)(data.toString("utf8"), sourcePath);
+            const id = String(parsed.frontmatter.id);
+            return { sourcePath, parsed, id };
+        });
+        const idMap = new Map();
+        for (const node of imported) {
+            const mustRewrite = usedIds.has(node.id) || Boolean(numericIdPrefix(node.id));
+            if (mustRewrite && !numericIdPrefix(node.id) && !idPrefix) {
+                throw new errors_1.UsageError(`cannot rewrite non-numeric template id without --id-prefix: ${node.id}`);
+            }
+            const toId = mustRewrite
+                ? numericIdPrefix(node.id)
+                    ? nextNumericId(node.id, usedIds)
+                    : prefixedId(idPrefix, node.id, usedIds)
+                : node.id;
+            usedIds.add(toId);
+            idMap.set(node.id, toId);
+        }
+        const ignoredRewrites = [];
+        for (const node of imported) {
+            const toId = idMap.get(node.id) ?? node.id;
+            const frontmatter = { ...node.parsed.frontmatter, id: toId };
+            for (const [field, value] of Object.entries(frontmatter)) {
+                if (field === "id") {
+                    continue;
+                }
+                frontmatter[field] = rewriteFrontmatterValue(value, idMap, node.sourcePath, field, ignoredRewrites);
+            }
+            const body = rewriteStringValue(node.parsed.body, idMap, node.sourcePath, "body", ignoredRewrites);
+            const targetPath = targetPathForImport(node.sourcePath, node.id, toId, usedPaths);
+            contentByTarget.set(targetPath, renderNode(frontmatter, body));
+        }
+        for (const targetPath of files) {
+            const content = contentByTarget.get(targetPath);
+            if (!content) {
+                throw new errors_1.UsageError(`import plan content missing for ${targetPath}`);
+            }
+            const targetAbs = path_1.default.resolve(options.root, targetPath);
+            fs_1.default.mkdirSync(path_1.default.dirname(targetAbs), { recursive: true });
+            (0, atomic_1.atomicWriteFile)(targetAbs, content);
+        }
+        const indexReceipt = (0, index_1.rebuildDerivedIndexCaches)({ root: options.root });
+        if (options.selectGoal && options.startGoal) {
+            const selected = applyPlan.selected_goal?.qid;
+            if (!selected) {
+                throw new errors_1.UsageError("--select-goal could not resolve imported start goal");
+            }
+            const [, id] = selected.split(":");
+            if (!id) {
+                throw new errors_1.UsageError(`invalid selected goal qid: ${selected}`);
+            }
+            writeSelectedGoal(options.root, selected, id, "root");
+            applyPlan.selected_goal = { qid: selected, path: ".mdkg/state/selected-goal.json", planned: false };
+        }
+        const validation = (0, validate_1.collectValidateReceipt)({ root: options.root, quiet: true });
+        if (validation.error_count > 0) {
+            throw new errors_1.ValidationError(`imported graph validation failed with ${validation.error_count} error(s)`);
+        }
+        return {
+            ...applyPlan,
+            files_written: files,
+            index: {
+                rebuilt: true,
+                paths: indexPathsReceipt(options.root, indexReceipt),
+            },
+            validation,
+        };
+    });
+}
+function runGraphTransport(options, mode) {
+    const source = loadGraphSource(options.root, options.source);
+    const targetRoot = resolveTargetRoot(options.root, options.target);
+    assertSourceNotMutatedByTarget(source, targetRoot);
+    const warnings = [];
+    fs_1.default.mkdirSync(targetRoot, { recursive: true });
+    const { filesWritten, skippedPaths } = writeGraphFiles(targetRoot, source);
+    const indexReceipt = (0, index_1.rebuildDerivedIndexCaches)({ root: targetRoot });
+    let validation = (0, validate_1.collectValidateReceipt)({ root: targetRoot, quiet: true });
+    if (validation.error_count > 0) {
+        throw new errors_1.ValidationError(`cloned graph validation failed with ${validation.error_count} error(s)`);
+    }
+    let startGoal;
+    let selectedGoal;
+    if (mode === "fork" && options.startGoal) {
+        const node = resolveStartGoal(targetRoot, options.startGoal);
+        const statePath = writeSelectedGoal(targetRoot, node.qid, node.id, node.ws);
+        startGoal = {
+            requested: options.startGoal,
+            qid: node.qid,
+            path: node.path,
+        };
+        selectedGoal = {
+            qid: node.qid,
+            path: statePath,
+        };
+        validation = (0, validate_1.collectValidateReceipt)({ root: targetRoot, quiet: true });
+        if (validation.error_count > 0) {
+            throw new errors_1.ValidationError(`forked graph validation failed with ${validation.error_count} error(s)`);
+        }
+    }
+    else if (mode === "clone" && options.startGoal) {
+        warnings.push("--start-goal is ignored by graph clone; use graph fork for start-goal selection");
+    }
+    return {
+        action: mode === "clone" ? "graph.clone" : "graph.fork",
+        ok: true,
+        mode,
+        source: {
+            kind: source.kind,
+            path: rel(options.root, source.sourcePath),
+            ...(source.sourceRoot ? { source_root: rel(options.root, source.sourceRoot) } : {}),
+            profile: source.manifest.profile,
+            selected_workspaces: source.manifest.selected_workspaces,
+        },
+        target: rel(options.root, targetRoot),
+        source_hash: {
+            source_tree_hash: source.manifest.source_tree_hash,
+            bundle_hash: source.manifest.bundle_hash,
+            zip_sha256: source.zipSha256,
+        },
+        preserved_ids: true,
+        files_written: filesWritten,
+        skipped_paths: skippedPaths,
+        ...(startGoal ? { start_goal: startGoal } : {}),
+        ...(selectedGoal ? { selected_goal: selectedGoal } : {}),
+        index: {
+            rebuilt: true,
+            paths: indexPathsReceipt(targetRoot, indexReceipt),
+        },
+        validation,
+        warnings,
+    };
+}
+function printReceipt(receipt, json) {
+    if (json) {
+        writeJson(receipt);
+        return;
+    }
+    console.log(`${receipt.action}: ${receipt.target}`);
+    console.log(`source: ${receipt.source.path}`);
+    console.log(`files: ${receipt.files_written.length}`);
+    console.log(`preserved_ids: ${receipt.preserved_ids}`);
+    if (receipt.start_goal) {
+        console.log(`start_goal: ${receipt.start_goal.qid}`);
+    }
+    if (receipt.warnings.length > 0) {
+        console.log(`warnings: ${receipt.warnings.length}`);
+    }
+}
+function runGraphCloneCommand(options) {
+    printReceipt(runGraphTransport(options, "clone"), options.json);
+}
+function runGraphForkCommand(options) {
+    printReceipt(runGraphTransport(options, "fork"), options.json);
+}
+function runGraphImportTemplateCommand(options) {
+    const plan = planImportTemplate(options);
+    const receipt = options.apply ? applyImportTemplate(options, plan) : plan;
+    if (options.json) {
+        writeJson(receipt);
+        return;
+    }
+    console.log(`${receipt.action}: ${receipt.mode}`);
+    console.log(`source: ${receipt.source.path}`);
+    console.log(`planned_paths: ${receipt.planned_paths.length}`);
+    console.log(`rewritten_ids: ${receipt.rewritten_ids.filter((item) => item.from_id !== item.to_id).length}`);
+    if (receipt.selected_goal) {
+        console.log(`selected_goal: ${receipt.selected_goal.qid}${receipt.selected_goal.planned ? " (planned)" : ""}`);
+    }
+}

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,6 +22,8 @@ Primary commands:
 - `mdkg spec`
 - `mdkg archive`
 - `mdkg bundle`
+- `mdkg graph`
+- `mdkg subgraph`
 - `mdkg work`
 - `mdkg goal`
 - `mdkg task`
@@ -204,6 +206,21 @@ 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` and writes selected-goal state only after apply validation
+- 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]`