mdkg 0.1.3 → 0.1.5

package/dist/commands/subgraph.js

@@ -0,0 +1,312 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSubgraphAddCommand = runSubgraphAddCommand;
+exports.runSubgraphListCommand = runSubgraphListCommand;
+exports.runSubgraphShowCommand = runSubgraphShowCommand;
+exports.runSubgraphRemoveCommand = runSubgraphRemoveCommand;
+exports.runSubgraphEnableCommand = runSubgraphEnableCommand;
+exports.runSubgraphDisableCommand = runSubgraphDisableCommand;
+exports.runSubgraphVerifyCommand = runSubgraphVerifyCommand;
+exports.runSubgraphRefreshCommand = runSubgraphRefreshCommand;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const config_1 = require("../core/config");
+const migrate_1 = require("../core/migrate");
+const workspace_path_1 = require("../core/workspace_path");
+const subgraphs_1 = require("../graph/subgraphs");
+const reindex_1 = require("../graph/reindex");
+const errors_1 = require("../util/errors");
+const atomic_1 = require("../util/atomic");
+const lock_1 = require("../util/lock");
+const ALIAS_RE = /^[a-z][a-z0-9_]*$/;
+function writeJson(value) {
+    console.log(JSON.stringify(value, null, 2));
+}
+function normalizeAlias(alias) {
+    if (alias === "all") {
+        throw new errors_1.UsageError("subgraph alias cannot be 'all'");
+    }
+    if (alias !== alias.toLowerCase() || !ALIAS_RE.test(alias)) {
+        throw new errors_1.UsageError("subgraph alias must be lowercase and use [a-z0-9_]");
+    }
+    return alias;
+}
+function normalizeVisibility(value) {
+    const normalized = (value ?? "private").toLowerCase();
+    if (normalized === "private" || normalized === "internal" || normalized === "public") {
+        return normalized;
+    }
+    throw new errors_1.UsageError("--visibility must be private, internal, or public");
+}
+function normalizeProfile(value) {
+    const normalized = (value ?? "private").toLowerCase();
+    if (normalized === "private" || normalized === "public") {
+        return normalized;
+    }
+    throw new errors_1.UsageError("--profile must be private or public");
+}
+function normalizeContained(value, label) {
+    try {
+        return (0, workspace_path_1.normalizeContainedWorkspacePath)(value, label);
+    }
+    catch (err) {
+        throw new errors_1.UsageError(err instanceof Error ? err.message : String(err));
+    }
+}
+function readRawConfig(root) {
+    const configPath = path_1.default.join(root, ".mdkg", "config.json");
+    if (!fs_1.default.existsSync(configPath)) {
+        throw new errors_1.NotFoundError(`config not found at ${configPath}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs_1.default.readFileSync(configPath, "utf8"));
+    }
+    catch (err) {
+        throw new errors_1.UsageError(`failed to read config: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const migrated = (0, migrate_1.migrateConfig)(parsed).config;
+    (0, config_1.validateConfigSchema)(migrated);
+    if (typeof migrated !== "object" || migrated === null || Array.isArray(migrated)) {
+        throw new errors_1.UsageError("config must be a JSON object");
+    }
+    return { configPath, raw: migrated };
+}
+function writeRawConfig(configPath, raw) {
+    (0, atomic_1.atomicWriteFile)(configPath, `${JSON.stringify(raw, null, 2)}\n`);
+}
+function getSubgraphs(raw) {
+    if (raw.bundle_imports !== undefined) {
+        throw new errors_1.UsageError("config uses legacy bundle_imports; run `mdkg upgrade --apply` before editing subgraphs");
+    }
+    const subgraphs = raw.subgraphs;
+    if (subgraphs === undefined) {
+        raw.subgraphs = {};
+        return raw.subgraphs;
+    }
+    if (typeof subgraphs !== "object" || subgraphs === null || Array.isArray(subgraphs)) {
+        throw new errors_1.UsageError("config.subgraphs must be an object");
+    }
+    return subgraphs;
+}
+function receiptForHealth(action, health) {
+    return {
+        action,
+        subgraph: health,
+    };
+}
+function healthByAlias(root, alias) {
+    const config = (0, config_1.loadConfig)(root);
+    const health = (0, subgraphs_1.buildSubgraphsIndex)(root, config).index.subgraphs.find((item) => item.alias === alias);
+    if (!health) {
+        throw new errors_1.NotFoundError(`subgraph not found: ${alias}`);
+    }
+    return health;
+}
+function withSubgraphLock(root, fn) {
+    const config = (0, config_1.loadConfig)(root);
+    return (0, lock_1.withMutationLock)(root, config.index.lock_timeout_ms, fn);
+}
+function runSubgraphAddCommandLocked(options) {
+    const alias = normalizeAlias(options.alias);
+    const bundlePath = normalizeContained(options.bundlePath, "subgraph bundle path");
+    const visibility = normalizeVisibility(options.visibility);
+    const expected_profile = normalizeProfile(options.profile);
+    if (visibility !== "private" && expected_profile !== "public") {
+        throw new errors_1.UsageError("--profile public is required when --visibility is public or internal");
+    }
+    const source_path = options.sourcePath
+        ? normalizeContained(options.sourcePath, "subgraph source path")
+        : undefined;
+    if (options.maxStaleSeconds !== undefined && (!Number.isInteger(options.maxStaleSeconds) || options.maxStaleSeconds <= 0)) {
+        throw new errors_1.UsageError("--max-stale-seconds must be a positive integer");
+    }
+    const { configPath, raw } = readRawConfig(options.root);
+    const subgraphs = getSubgraphs(raw);
+    if (subgraphs[alias]) {
+        throw new errors_1.UsageError(`subgraph already exists: ${alias}`);
+    }
+    const workspaces = raw.workspaces;
+    if (workspaces && workspaces[alias]) {
+        throw new errors_1.UsageError(`subgraph alias collides with workspace: ${alias}`);
+    }
+    subgraphs[alias] = {
+        enabled: true,
+        visibility,
+        permissions: ["read"],
+        max_stale_seconds: options.maxStaleSeconds ?? 3600,
+        ...(source_path ? { source_path } : {}),
+        ...(options.sourceRepo ? { source_repo: options.sourceRepo } : {}),
+        sources: [
+            {
+                path: bundlePath,
+                enabled: true,
+                expected_profile,
+            },
+        ],
+    };
+    raw.subgraphs = subgraphs;
+    const validated = (0, config_1.validateConfigSchema)(raw);
+    const health = (0, subgraphs_1.buildSubgraphsIndex)(options.root, validated).index.subgraphs.find((item) => item.alias === alias);
+    if (!health) {
+        throw new errors_1.NotFoundError(`subgraph not found after validation: ${alias}`);
+    }
+    if (health.error_count > 0) {
+        throw new errors_1.ValidationError(`subgraph ${alias} is invalid:\n${health.errors.join("\n")}`);
+    }
+    writeRawConfig(configPath, raw);
+    const receipt = receiptForHealth("added", health);
+    if (options.json) {
+        writeJson(receipt);
+        return;
+    }
+    console.log(`subgraph added: ${alias} (${bundlePath})`);
+    if (health.warning_count > 0) {
+        console.log(`warnings: ${health.warning_count}`);
+    }
+}
+function runSubgraphAddCommand(options) {
+    return withSubgraphLock(options.root, () => runSubgraphAddCommandLocked(options));
+}
+function runSubgraphListCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const subgraphs = (0, subgraphs_1.buildSubgraphsIndex)(options.root, config).index.subgraphs;
+    if (options.json) {
+        writeJson({ action: "list", count: subgraphs.length, subgraphs });
+        return;
+    }
+    if (subgraphs.length === 0) {
+        console.log("no subgraphs configured");
+        return;
+    }
+    for (const item of subgraphs) {
+        const status = item.enabled ? item.error_count > 0 ? "invalid" : item.stale ? "stale" : "ok" : "disabled";
+        const sourcePaths = item.sources.map((source) => source.path).join(",");
+        console.log(`${item.alias} | ${status} | ${item.visibility} | ${sourcePaths}`);
+    }
+}
+function runSubgraphShowCommand(options) {
+    const alias = normalizeAlias(options.alias);
+    const health = healthByAlias(options.root, alias);
+    if (options.json) {
+        writeJson(receiptForHealth("show", health));
+        return;
+    }
+    console.log(`${health.alias} | ${health.enabled ? "enabled" : "disabled"} | ${health.visibility}`);
+    console.log(`permissions: ${health.permissions.join(",")}`);
+    console.log(`max source count: ${health.sources.length}`);
+    for (const source of health.sources) {
+        const status = source.enabled ? source.error_count > 0 ? "invalid" : source.stale ? "stale" : "ok" : "disabled";
+        console.log(`source: ${source.path} | ${status} | ${source.expected_profile}`);
+    }
+}
+function runSubgraphRemoveCommandLocked(options) {
+    const alias = normalizeAlias(options.alias);
+    const { configPath, raw } = readRawConfig(options.root);
+    const subgraphs = getSubgraphs(raw);
+    const existing = subgraphs[alias];
+    if (!existing) {
+        throw new errors_1.NotFoundError(`subgraph not found: ${alias}`);
+    }
+    delete subgraphs[alias];
+    raw.subgraphs = subgraphs;
+    (0, config_1.validateConfigSchema)(raw);
+    writeRawConfig(configPath, raw);
+    const receipt = { action: "removed", subgraph: { alias } };
+    if (options.json) {
+        writeJson(receipt);
+        return;
+    }
+    console.log(`subgraph removed: ${alias}`);
+}
+function runSubgraphRemoveCommand(options) {
+    return withSubgraphLock(options.root, () => runSubgraphRemoveCommandLocked(options));
+}
+function setSubgraphEnabledLocked(options, enabled) {
+    const alias = normalizeAlias(options.alias);
+    const { configPath, raw } = readRawConfig(options.root);
+    const subgraphs = getSubgraphs(raw);
+    const existing = subgraphs[alias];
+    if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
+        throw new errors_1.NotFoundError(`subgraph not found: ${alias}`);
+    }
+    subgraphs[alias] = { ...existing, enabled };
+    raw.subgraphs = subgraphs;
+    (0, config_1.validateConfigSchema)(raw);
+    writeRawConfig(configPath, raw);
+    const health = healthByAlias(options.root, alias);
+    const receipt = receiptForHealth(enabled ? "enabled" : "disabled", health);
+    if (options.json) {
+        writeJson(receipt);
+        return;
+    }
+    console.log(`subgraph ${enabled ? "enabled" : "disabled"}: ${alias}`);
+}
+function runSubgraphEnableCommand(options) {
+    withSubgraphLock(options.root, () => setSubgraphEnabledLocked(options, true));
+}
+function runSubgraphDisableCommand(options) {
+    withSubgraphLock(options.root, () => setSubgraphEnabledLocked(options, false));
+}
+function selectHealth(items, alias, all) {
+    const includeAll = all || !alias;
+    const selected = items.filter((item) => includeAll ? true : item.alias === alias);
+    if (!includeAll && selected.length === 0) {
+        throw new errors_1.NotFoundError(`subgraph not found: ${alias}`);
+    }
+    return selected;
+}
+function runSubgraphVerifyCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const subgraphs = selectHealth((0, subgraphs_1.buildSubgraphsIndex)(options.root, config).index.subgraphs, options.alias, options.all);
+    const ok = subgraphs.every((item) => item.error_count === 0 && !item.stale);
+    const receipt = { action: "verified", ok, count: subgraphs.length, subgraphs };
+    if (options.json) {
+        writeJson(receipt);
+    }
+    else if (ok) {
+        console.log(`subgraphs verified: ${subgraphs.length}`);
+    }
+    else {
+        console.log(`subgraph verify failed: ${subgraphs.length}`);
+        for (const item of subgraphs) {
+            for (const warning of item.warnings) {
+                console.log(`warning: ${item.alias}: ${warning}`);
+            }
+            for (const error of item.errors) {
+                console.log(`error: ${item.alias}: ${error}`);
+            }
+        }
+    }
+    if (!ok) {
+        throw new errors_1.ValidationError("subgraph verify failed");
+    }
+}
+function runSubgraphRefreshCommand(options) {
+    withSubgraphLock(options.root, () => {
+        const config = (0, config_1.loadConfig)(options.root);
+        const result = (0, reindex_1.writeDerivedIndexes)(options.root, config);
+        const subgraphs = selectHealth((0, subgraphs_1.buildSubgraphsIndex)(options.root, config).index.subgraphs, options.alias, options.all);
+        const ok = subgraphs.every((item) => item.error_count === 0);
+        const receipt = {
+            action: "refreshed",
+            ok,
+            count: subgraphs.length,
+            paths: result.paths,
+            subgraphs,
+        };
+        if (options.json) {
+            writeJson(receipt);
+        }
+        else {
+            console.log(`subgraphs refreshed: ${subgraphs.length}`);
+            console.log(`index: ${path_1.default.relative(options.root, result.paths.subgraphs)}`);
+        }
+        if (!ok) {
+            throw new errors_1.ValidationError("subgraph refresh failed");
+        }
+    });
+}

package/dist/commands/task.js

@@ -110,7 +110,7 @@ function loadMutableTaskNode(root, idOrQid, wsHint) {
         throw new errors_1.NotFoundError(`task not found: ${idOrQid}`);
     }
     if (node.source?.imported) {
-        throw new errors_1.UsageError(`cannot mutate read-only imported node ${node.qid}; update the source workspace for bundle import ${node.source.import_alias}`);
+        throw new errors_1.UsageError(`cannot mutate read-only subgraph node ${node.qid}; update the source workspace for subgraph ${node.source.subgraph_alias}`);
     }
     if (!MUTABLE_TASK_TYPES.has(node.type)) {
         throw new errors_1.UsageError(`mdkg task only supports task, bug, and test nodes; use markdown editing for ${node.type}:${node.id}`);

package/dist/commands/upgrade.js

@@ -18,7 +18,7 @@ const skill_mirror_1 = require("./skill_mirror");
 const DEFAULT_SEED_SUBDIR = path_1.default.resolve(__dirname, "..", "init");
 const PROTECTED_CORE_DOCS = new Set([".mdkg/core/SOUL.md", ".mdkg/core/HUMAN.md"]);
 const CREATE_ONLY_PRESERVED = new Set([".mdkg/core/core.md"]);
-const ARCHIVE_RAW_IGNORE_ENTRIES = [".mdkg/archive/**/source/"];
+const LOCAL_STATE_IGNORE_ENTRIES = [".mdkg/state/", ".mdkg/archive/**/source/"];
 function seededInitEvent(nowIso) {
     const event = {
         ts: nowIso,
@@ -171,12 +171,57 @@ function planSeedFile(options) {
     });
     return false;
 }
+function migrateLegacyBundleImportsConfig(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        return { config: input, changed: false };
+    }
+    const raw = { ...input };
+    if (raw.bundle_imports === undefined) {
+        if (raw.subgraphs === undefined) {
+            raw.subgraphs = {};
+            return { config: raw, changed: true };
+        }
+        return { config: raw, changed: false };
+    }
+    if (raw.subgraphs !== undefined) {
+        return { config: raw, changed: false };
+    }
+    const subgraphs = {};
+    const legacy = raw.bundle_imports;
+    if (legacy && typeof legacy === "object" && !Array.isArray(legacy)) {
+        for (const [alias, value] of Object.entries(legacy)) {
+            if (!value || typeof value !== "object" || Array.isArray(value)) {
+                continue;
+            }
+            const entry = value;
+            subgraphs[alias] = {
+                enabled: entry.enabled ?? true,
+                visibility: entry.visibility ?? "private",
+                permissions: ["read"],
+                max_stale_seconds: entry.max_stale_seconds ?? 3600,
+                ...(entry.source_path ? { source_path: entry.source_path } : {}),
+                ...(entry.source_repo ? { source_repo: entry.source_repo } : {}),
+                sources: [
+                    {
+                        path: entry.path,
+                        enabled: true,
+                        expected_profile: entry.expected_profile ?? "private",
+                    },
+                ],
+            };
+        }
+    }
+    raw.subgraphs = subgraphs;
+    delete raw.bundle_imports;
+    return { config: raw, changed: true };
+}
 function migrateConfigIfNeeded(root, dryRun, summary, changes) {
     const cfgPath = (0, paths_1.configPath)(root);
     const raw = JSON.parse(fs_1.default.readFileSync(cfgPath, "utf8"));
     const migrated = (0, migrate_1.migrateConfig)(raw);
-    (0, config_1.validateConfigSchema)(migrated.config);
-    if (migrated.from === migrated.to) {
+    const nextConfig = migrateLegacyBundleImportsConfig(migrated.config);
+    (0, config_1.validateConfigSchema)(nextConfig.config);
+    if (migrated.from === migrated.to && !nextConfig.changed) {
         summary.unchanged += 1;
         return;
     }
@@ -184,10 +229,12 @@ function migrateConfigIfNeeded(root, dryRun, summary, changes) {
         path: ".mdkg/config.json",
         category: "config",
         action: "migrate",
-        reason: `config schema_version ${migrated.from} -> ${migrated.to}`,
+        reason: nextConfig.changed
+            ? `config subgraphs migration${migrated.from === migrated.to ? "" : ` and schema_version ${migrated.from} -> ${migrated.to}`}`
+            : `config schema_version ${migrated.from} -> ${migrated.to}`,
     });
     if (!dryRun) {
-        writeFile(cfgPath, `${JSON.stringify(migrated.config, null, 2)}\n`);
+        writeFile(cfgPath, `${JSON.stringify(nextConfig.config, null, 2)}\n`);
     }
 }
 function isIgnoredBySimpleGitignore(root, relativePath) {
@@ -260,7 +307,7 @@ function ensureArchiveIgnorePolicy(root, dryRun, summary, changes) {
     const raw = fs_1.default.existsSync(ignorePath) ? fs_1.default.readFileSync(ignorePath, "utf8") : "";
     const lines = raw.split(/\r?\n/);
     const existing = new Set(lines.map((line) => line.trim()).filter(Boolean));
-    const additions = ARCHIVE_RAW_IGNORE_ENTRIES.filter((entry) => !existing.has(entry));
+    const additions = LOCAL_STATE_IGNORE_ENTRIES.filter((entry) => !existing.has(entry));
     if (additions.length === 0) {
         summary.unchanged += 1;
         return;
@@ -269,7 +316,7 @@ function ensureArchiveIgnorePolicy(root, dryRun, summary, changes) {
         path: ".gitignore",
         category: "ignore_policy",
         action: fs_1.default.existsSync(ignorePath) ? "update" : "create",
-        reason: "ignore raw local archive source copies while keeping sidecars and zip caches commit-eligible",
+        reason: "ignore local mdkg state and raw archive source copies while keeping authored graph records commit-eligible",
     });
     if (!dryRun) {
         const suffix = raw.length === 0 || raw.endsWith("\n") ? "" : "\n";

package/dist/commands/validate.js

@@ -12,7 +12,7 @@ const node_1 = require("../graph/node");
 const skills_indexer_1 = require("../graph/skills_indexer");
 const workspace_files_1 = require("../graph/workspace_files");
 const validate_graph_1 = require("../graph/validate_graph");
-const bundle_imports_1 = require("../graph/bundle_imports");
+const subgraphs_1 = require("../graph/subgraphs");
 const visibility_1 = require("../graph/visibility");
 const sqlite_index_1 = require("../graph/sqlite_index");
 const errors_1 = require("../util/errors");
@@ -142,6 +142,38 @@ function buildWorkspaceMap(config) {
     }
     return workspaces;
 }
+function addReverseEdge(reverse, edgeKey, target, source) {
+    if (!target) {
+        return;
+    }
+    reverse[edgeKey] = reverse[edgeKey] ?? {};
+    reverse[edgeKey][target] = reverse[edgeKey][target] ?? [];
+    reverse[edgeKey][target].push(source);
+}
+function buildReverseEdges(nodes) {
+    const reverse = {};
+    for (const [qid, node] of Object.entries(nodes)) {
+        addReverseEdge(reverse, "epic", node.edges.epic, qid);
+        addReverseEdge(reverse, "parent", node.edges.parent, qid);
+        addReverseEdge(reverse, "prev", node.edges.prev, qid);
+        addReverseEdge(reverse, "next", node.edges.next, qid);
+        for (const target of node.edges.relates) {
+            addReverseEdge(reverse, "relates", target, qid);
+        }
+        for (const target of node.edges.blocked_by) {
+            addReverseEdge(reverse, "blocked_by", target, qid);
+        }
+        for (const target of node.edges.blocks) {
+            addReverseEdge(reverse, "blocks", target, qid);
+        }
+    }
+    for (const targets of Object.values(reverse)) {
+        for (const sources of Object.values(targets)) {
+            sources.sort();
+        }
+    }
+    return reverse;
+}
 function listDirectories(dirPath) {
     if (!fs_1.default.existsSync(dirPath)) {
         return [];
@@ -274,18 +306,18 @@ function runValidateCommand(options) {
         },
         workspaces: buildWorkspaceMap(config),
         nodes,
-        reverse_edges: {},
+        reverse_edges: buildReverseEdges(nodes),
     };
-    const importProjection = (0, bundle_imports_1.buildBundleImportsIndex)(options.root, config);
-    for (const item of importProjection.index.imports) {
+    const subgraphProjection = (0, subgraphs_1.buildSubgraphsIndex)(options.root, config);
+    for (const item of subgraphProjection.index.subgraphs) {
         for (const warning of item.warnings) {
-            warnings.push(`bundle import ${item.alias}: ${warning}`);
+            warnings.push(`subgraph ${item.alias}: ${warning}`);
         }
         for (const error of item.errors) {
-            errors.push(`bundle import ${item.alias}: ${error}`);
+            errors.push(`subgraph ${item.alias}: ${error}`);
         }
     }
-    const validationIndex = (0, bundle_imports_1.mergeBundleImportsIntoIndex)(index, importProjection);
+    const validationIndex = (0, subgraphs_1.mergeSubgraphsIntoIndex)(index, subgraphProjection);
     let knownSkills = new Set();
     try {
         const skillsIndex = (0, skills_indexer_1.buildSkillsIndex)(options.root, config);

package/dist/commands/work.js

@@ -190,7 +190,7 @@ function resolveWorkNode(index, idOrQid, ws, allowedTypes, label) {
         throw new errors_1.NotFoundError(`${label} not found: ${idOrQid}`);
     }
     if (node.source?.imported) {
-        throw new errors_1.UsageError(`cannot mutate read-only imported node ${node.qid}; update the source workspace for bundle import ${node.source.import_alias}`);
+        throw new errors_1.UsageError(`cannot mutate read-only subgraph node ${node.qid}; update the source workspace for subgraph ${node.source.subgraph_alias}`);
     }
     return node;
 }