mdkg 0.1.1 → 0.1.3

package/dist/commands/doctor.js

@@ -8,32 +8,42 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const config_1 = require("../core/config");
 const index_cache_1 = require("../graph/index_cache");
+const capabilities_index_cache_1 = require("../graph/capabilities_index_cache");
+const bundle_imports_1 = require("../graph/bundle_imports");
 const node_1 = require("../graph/node");
 const template_schema_1 = require("../graph/template_schema");
+const visibility_1 = require("../graph/visibility");
+const sqlite_index_1 = require("../graph/sqlite_index");
 const errors_1 = require("../util/errors");
-const REQUIRED_NODE_MAJOR = 18;
-function parseNodeMajor(version) {
-    const major = Number.parseInt(version.split(".")[0] ?? "", 10);
-    if (!Number.isInteger(major)) {
+const REQUIRED_NODE_MAJOR = 24;
+const REQUIRED_NODE_MINOR = 15;
+const ARCHIVE_RAW_ALLOWED_DIRS = new Set(["source"]);
+function parseNodeVersion(version) {
+    const [majorRaw, minorRaw, patchRaw] = version.split(".");
+    const major = Number.parseInt(majorRaw ?? "", 10);
+    const minor = Number.parseInt(minorRaw ?? "", 10);
+    const patch = Number.parseInt(patchRaw ?? "", 10);
+    if (!Number.isInteger(major) || !Number.isInteger(minor) || !Number.isInteger(patch)) {
         return null;
     }
-    return major;
+    return { major, minor, patch };
 }
 function runNodeVersionCheck() {
     const nodeVersion = process.versions.node;
-    const major = parseNodeMajor(nodeVersion);
-    if (major === null) {
+    const parsed = parseNodeVersion(nodeVersion);
+    if (parsed === null) {
         return {
             name: "node-version",
             ok: false,
             detail: `unable to parse Node.js version: ${nodeVersion}`,
         };
     }
-    if (major < REQUIRED_NODE_MAJOR) {
+    if (parsed.major < REQUIRED_NODE_MAJOR ||
+        (parsed.major === REQUIRED_NODE_MAJOR && parsed.minor < REQUIRED_NODE_MINOR)) {
         return {
             name: "node-version",
             ok: false,
-            detail: `Node.js ${nodeVersion} is unsupported (requires >=${REQUIRED_NODE_MAJOR})`,
+            detail: `Node.js ${nodeVersion} is unsupported (requires >=${REQUIRED_NODE_MAJOR}.${REQUIRED_NODE_MINOR}.0)`,
         };
     }
     return {
@@ -42,6 +52,213 @@ function runNodeVersionCheck() {
         detail: `Node.js ${nodeVersion} (ok)`,
     };
 }
+function runSqliteCheck(root, config) {
+    if (!(0, sqlite_index_1.isSqliteBackend)(config)) {
+        return {
+            name: "sqlite-cache",
+            ok: true,
+            detail: "SQLite backend disabled; JSON cache backend active",
+        };
+    }
+    const health = (0, sqlite_index_1.sqliteHealth)(root, config);
+    if (health.errors.length > 0) {
+        return {
+            name: "sqlite-cache",
+            ok: false,
+            detail: health.errors.join("; "),
+        };
+    }
+    if (health.warnings.length > 0) {
+        return {
+            name: "sqlite-cache",
+            ok: true,
+            level: "warn",
+            detail: health.warnings.join("; "),
+        };
+    }
+    return {
+        name: "sqlite-cache",
+        ok: true,
+        detail: `.mdkg SQLite cache ok (${health.size} bytes)`,
+    };
+}
+function walkFiles(root) {
+    if (!fs_1.default.existsSync(root)) {
+        return [];
+    }
+    const entries = fs_1.default.readdirSync(root, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path_1.default.join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...walkFiles(fullPath));
+        }
+        else if (entry.isFile()) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+function runArchiveStorageCheck(root) {
+    const archiveRoot = path_1.default.join(root, ".mdkg", "archive");
+    const files = walkFiles(archiveRoot);
+    const strayRaw = files
+        .filter((filePath) => {
+        const relative = path_1.default.relative(archiveRoot, filePath).split(path_1.default.sep);
+        const ext = path_1.default.extname(filePath).toLowerCase();
+        if (ext === ".md" || ext === ".zip") {
+            return false;
+        }
+        return !relative.some((segment) => ARCHIVE_RAW_ALLOWED_DIRS.has(segment));
+    })
+        .map((filePath) => path_1.default.relative(root, filePath).split(path_1.default.sep).join("/"))
+        .sort();
+    if (strayRaw.length === 0) {
+        return {
+            name: "archive-storage",
+            ok: true,
+            detail: ".mdkg/archive has no stray raw files outside managed source directories",
+        };
+    }
+    return {
+        name: "archive-storage",
+        ok: true,
+        level: "warn",
+        detail: `stray uncompressed archive file(s) found without managed sidecars: ${strayRaw.join(", ")}; run \`mdkg archive add <file>\` or move raw files under a managed archive source directory`,
+    };
+}
+function runArchiveLargeCacheCheck(root, warningBytes) {
+    if (warningBytes === 0) {
+        return {
+            name: "archive-large-cache",
+            ok: true,
+            detail: "archive large-cache warning disabled",
+        };
+    }
+    const archiveRoot = path_1.default.join(root, ".mdkg", "archive");
+    const largeCaches = walkFiles(archiveRoot)
+        .filter((filePath) => filePath.endsWith(".zip"))
+        .map((filePath) => ({
+        path: path_1.default.relative(root, filePath).split(path_1.default.sep).join("/"),
+        size: fs_1.default.statSync(filePath).size,
+    }))
+        .filter((entry) => entry.size > warningBytes)
+        .sort((a, b) => a.path.localeCompare(b.path));
+    if (largeCaches.length === 0) {
+        return {
+            name: "archive-large-cache",
+            ok: true,
+            detail: `no archive ZIP cache exceeds ${warningBytes} bytes`,
+        };
+    }
+    return {
+        name: "archive-large-cache",
+        ok: true,
+        level: "warn",
+        detail: `archive ZIP cache(s) exceed ${warningBytes} bytes: ${largeCaches
+            .map((entry) => `${entry.path} (${entry.size} bytes)`)
+            .join(", ")}; keep large caches private or move bulky originals to repo policy-managed storage`,
+    };
+}
+function runBundleStorageCheck(root, outputDir) {
+    const bundleRoot = path_1.default.resolve(root, outputDir);
+    if (!fs_1.default.existsSync(bundleRoot)) {
+        return {
+            name: "bundle-storage",
+            ok: true,
+            detail: `no bundle directory found; run \`mdkg bundle create --profile private\` when a snapshot should be tracked`,
+        };
+    }
+    const bundles = walkFiles(bundleRoot)
+        .filter((filePath) => filePath.endsWith(".mdkg.zip"))
+        .map((filePath) => path_1.default.relative(root, filePath).split(path_1.default.sep).join("/"))
+        .sort();
+    if (bundles.length === 0) {
+        return {
+            name: "bundle-storage",
+            ok: true,
+            detail: `bundle directory has no .mdkg.zip files; run \`mdkg bundle create --profile private\` when a snapshot should be tracked`,
+        };
+    }
+    return {
+        name: "bundle-storage",
+        ok: true,
+        detail: `${bundles.length} bundle(s) found; run \`mdkg bundle verify <path>\` to check freshness before handoff`,
+    };
+}
+function runBundleImportChecks(root, config) {
+    const projection = (0, bundle_imports_1.buildBundleImportsIndex)(root, config);
+    if (projection.index.imports.length === 0) {
+        return [
+            {
+                name: "bundle-imports",
+                ok: true,
+                detail: "no bundle imports configured",
+            },
+        ];
+    }
+    return projection.index.imports.map((item) => {
+        if (!item.enabled) {
+            return {
+                name: `bundle-import:${item.alias}`,
+                ok: true,
+                level: "warn",
+                detail: `disabled import at ${item.path}`,
+            };
+        }
+        if (item.error_count > 0) {
+            return {
+                name: `bundle-import:${item.alias}`,
+                ok: false,
+                detail: item.errors.join("; "),
+            };
+        }
+        if (item.stale || item.warning_count > 0) {
+            return {
+                name: `bundle-import:${item.alias}`,
+                ok: true,
+                level: "warn",
+                detail: `import is stale or has warnings; run \`mdkg bundle import verify ${item.alias}\` (${item.warnings.join("; ")})`,
+            };
+        }
+        return {
+            name: `bundle-import:${item.alias}`,
+            ok: true,
+            detail: `import loaded from ${item.path}`,
+        };
+    });
+}
+function runVisibilityPolicyCheck(root, config, options) {
+    try {
+        const { index } = (0, index_cache_1.loadIndex)({
+            root,
+            config,
+            useCache: !options.noCache,
+            allowReindex: !options.noReindex,
+        });
+        const messages = (0, visibility_1.visibilityViolationMessages)((0, visibility_1.collectVisibilityViolations)(index, config));
+        if (messages.length === 0) {
+            return {
+                name: "visibility-policy",
+                ok: true,
+                detail: "public/internal records do not reference less-visible mdkg records",
+            };
+        }
+        return {
+            name: "visibility-policy",
+            ok: false,
+            detail: `${messages.length} violation(s): ${messages.join("; ")}`,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            name: "visibility-policy",
+            ok: false,
+            detail: message,
+        };
+    }
+}
 function runDoctorCommand(options) {
     const results = [];
     results.push(runNodeVersionCheck());
@@ -78,6 +295,12 @@ function runDoctorCommand(options) {
         });
     }
     if (config) {
+        results.push(runArchiveStorageCheck(options.root));
+        results.push(runArchiveLargeCacheCheck(options.root, config.archive.large_cache_warning_bytes));
+        results.push(runBundleStorageCheck(options.root, config.bundles.output_dir));
+        results.push(runSqliteCheck(options.root, config));
+        results.push(...runBundleImportChecks(options.root, config));
+        results.push(runVisibilityPolicyCheck(options.root, config, options));
         try {
             const templateSchemaInfo = (0, template_schema_1.loadTemplateSchemasWithInfo)(options.root, config, node_1.ALLOWED_TYPES);
             results.push({
@@ -139,6 +362,43 @@ function runDoctorCommand(options) {
                 detail: message,
             });
         }
+        try {
+            const { rebuilt, stale } = (0, capabilities_index_cache_1.loadCapabilitiesIndex)({
+                root: options.root,
+                config,
+                useCache: !options.noCache,
+                allowReindex: !options.noReindex,
+            });
+            if (rebuilt) {
+                results.push({
+                    name: "capabilities-index",
+                    ok: true,
+                    detail: "capabilities cache rebuilt and loaded",
+                });
+            }
+            else if (stale) {
+                results.push({
+                    name: "capabilities-index",
+                    ok: true,
+                    detail: "capabilities cache is stale (run mdkg index to refresh)",
+                });
+            }
+            else {
+                results.push({
+                    name: "capabilities-index",
+                    ok: true,
+                    detail: "capabilities cache loaded",
+                });
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            results.push({
+                name: "capabilities-index",
+                ok: false,
+                detail: message,
+            });
+        }
     }
     const failures = results.filter((result) => !result.ok);
     if (options.json) {

package/dist/commands/format.js

@@ -10,16 +10,34 @@ const config_1 = require("../core/config");
 const frontmatter_1 = require("../graph/frontmatter");
 const template_schema_1 = require("../graph/template_schema");
 const node_1 = require("../graph/node");
+const agent_file_types_1 = require("../graph/agent_file_types");
+const archive_file_1 = require("../graph/archive_file");
 const workspace_files_1 = require("../graph/workspace_files");
 const errors_1 = require("../util/errors");
 const date_1 = require("../util/date");
 const id_1 = require("../util/id");
+const refs_1 = require("../util/refs");
 const DEC_ID_RE = /^dec-[0-9]+$/;
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const ID_LIST_KEYS = new Set(["refs", "scope"]);
 const ID_REF_LIST_KEYS = new Set(["relates", "blocked_by", "blocks"]);
 const ID_REF_SCALAR_KEYS = new Set(["epic", "parent", "prev", "next"]);
-const PRESERVE_CASE_LIST_KEYS = new Set(["links", "artifacts"]);
+const PRESERVE_CASE_LIST_KEYS = new Set([
+    "links",
+    "artifacts",
+    "work_contracts",
+    "input_refs",
+    "constraint_refs",
+    "proof_refs",
+    "attestation_refs",
+]);
+const EXTERNAL_REF_LIST_KEYS = new Set([
+    "input_refs",
+    "constraint_refs",
+    "proof_refs",
+    "attestation_refs",
+]);
+const HASH_REF_LIST_KEYS = new Set(["input_hashes", "output_hashes"]);
 function isValidId(value) {
     return (0, id_1.isCanonicalId)(value);
 }
@@ -48,7 +66,7 @@ function sortList(values) {
         return 0;
     });
 }
-function normalizeList(values, key, errors, filePath) {
+function normalizeList(values, key, errors, filePath, allowPortableRefs = false) {
     const trimmed = values.map((value) => normalizeScalar(value));
     const shouldLowercase = !PRESERVE_CASE_LIST_KEYS.has(key);
     const normalized = shouldLowercase ? trimmed.map((value) => value.toLowerCase()) : trimmed;
@@ -57,12 +75,18 @@ function normalizeList(values, key, errors, filePath) {
             errors.push(`${filePath}: ${key} entries must be non-empty`);
             continue;
         }
-        if (ID_LIST_KEYS.has(key) && !isValidId(entry)) {
+        if (ID_LIST_KEYS.has(key) && !(allowPortableRefs ? (0, id_1.isPortableId)(entry) : isValidId(entry))) {
             errors.push(`${filePath}: ${key} entries must match <prefix>-<number> or reserved id`);
         }
-        if (ID_REF_LIST_KEYS.has(key) && !(0, id_1.isCanonicalIdRef)(entry)) {
+        if (ID_REF_LIST_KEYS.has(key) && !(allowPortableRefs ? (0, id_1.isPortableIdRef)(entry) : (0, id_1.isCanonicalIdRef)(entry))) {
             errors.push(`${filePath}: ${key} entries must be valid id references`);
         }
+        if (EXTERNAL_REF_LIST_KEYS.has(key) && !(0, refs_1.validatePortableOrUriRef)(entry)) {
+            errors.push(`${filePath}: ${key} entries must be portable ids or URI refs`);
+        }
+        if (HASH_REF_LIST_KEYS.has(key) && !(0, refs_1.isSha256Ref)(entry)) {
+            errors.push(`${filePath}: ${key} entries must be sha256:<64 lowercase hex chars>`);
+        }
     }
     return sortList(normalized);
 }
@@ -73,14 +97,15 @@ function normalizeIdRef(value, key, errors, filePath) {
     }
     return normalized;
 }
-function normalizeFrontmatterValue(key, value, schema, errors, filePath) {
+function normalizeFrontmatterValue(key, value, schema, errors, filePath, type) {
     const expected = schema.keyKinds[key];
     if (expected === "list") {
         if (!Array.isArray(value)) {
             errors.push(`${filePath}: ${key} must be a list`);
             return [];
         }
-        return normalizeList(value, key, errors, filePath);
+        const allowPortableRefs = (0, agent_file_types_1.isAgentFileType)(type) || (0, archive_file_1.isArchiveType)(type);
+        return normalizeList(value, key, errors, filePath, allowPortableRefs);
     }
     if (expected === "boolean") {
         if (typeof value !== "boolean") {
@@ -111,7 +136,7 @@ function normalizeFrontmatter(frontmatter, schema, type, workStatusEnum, priorit
             }
             continue;
         }
-        const normalizedValue = normalizeFrontmatterValue(key, value, schema, errors, filePath);
+        const normalizedValue = normalizeFrontmatterValue(key, value, schema, errors, filePath, type);
         if (normalizedValue !== undefined) {
             normalized[key] = normalizedValue;
         }
@@ -122,8 +147,12 @@ function normalizeFrontmatter(frontmatter, schema, type, workStatusEnum, priorit
     }
     else {
         const normalizedId = idValue.toLowerCase();
-        if (!isValidId(normalizedId)) {
-            errors.push(`${filePath}: id must match <prefix>-<number> or reserved id`);
+        const allowPortableId = (0, agent_file_types_1.isAgentFileType)(type) || (0, archive_file_1.isArchiveType)(type);
+        if (!(allowPortableId ? (0, id_1.isPortableId)(normalizedId) : isValidId(normalizedId))) {
+            const requirement = allowPortableId
+                ? "<prefix>-<number>, reserved id, or allowed portable id"
+                : "<prefix>-<number> or reserved id";
+            errors.push(`${filePath}: id must match ${requirement}`);
         }
         normalized.id = normalizedId;
     }

package/dist/commands/index.js

@@ -6,18 +6,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runIndexCommand = runIndexCommand;
 const path_1 = __importDefault(require("path"));
 const config_1 = require("../core/config");
-const indexer_1 = require("../graph/indexer");
-const index_cache_1 = require("../graph/index_cache");
-const skills_index_cache_1 = require("../graph/skills_index_cache");
-const skills_indexer_1 = require("../graph/skills_indexer");
+const reindex_1 = require("../graph/reindex");
+const lock_1 = require("../util/lock");
 function runIndexCommand(options) {
     const config = (0, config_1.loadConfig)(options.root);
-    const nodeIndex = (0, indexer_1.buildIndex)(options.root, config, { tolerant: options.tolerant });
-    const skillsIndex = (0, skills_indexer_1.buildSkillsIndex)(options.root, config);
-    const nodesOutputPath = path_1.default.resolve(options.root, config.index.global_index_path);
-    const skillsOutputPath = (0, skills_indexer_1.resolveSkillsIndexPath)(options.root);
-    (0, index_cache_1.writeIndex)(nodesOutputPath, nodeIndex);
-    (0, skills_index_cache_1.writeSkillsIndex)(skillsOutputPath, skillsIndex);
-    console.log(`index written: ${path_1.default.relative(options.root, nodesOutputPath)}`);
-    console.log(`skills index written: ${path_1.default.relative(options.root, skillsOutputPath)}`);
+    (0, lock_1.withMutationLock)(options.root, config.index.lock_timeout_ms, () => {
+        const result = (0, reindex_1.writeDerivedIndexes)(options.root, config, undefined, { tolerant: options.tolerant });
+        console.log(`index written: ${path_1.default.relative(options.root, result.paths.nodes)}`);
+        console.log(`skills index written: ${path_1.default.relative(options.root, result.paths.skills)}`);
+        console.log(`capabilities index written: ${path_1.default.relative(options.root, result.paths.capabilities)}`);
+        console.log(`bundle imports index written: ${path_1.default.relative(options.root, result.paths.imports)}`);
+        if (result.paths.sqlite) {
+            console.log(`sqlite index written: ${path_1.default.relative(options.root, result.paths.sqlite)}`);
+        }
+    });
 }