mdkg 0.1.6 → 0.1.7

package/dist/commands/db.js

@@ -0,0 +1,560 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDbIndexRebuildCommand = runDbIndexRebuildCommand;
+exports.runDbInitCommand = runDbInitCommand;
+exports.runDbMigrateCommand = runDbMigrateCommand;
+exports.runDbVerifyCommand = runDbVerifyCommand;
+exports.runDbStatsCommand = runDbStatsCommand;
+exports.runDbSnapshotSealCommand = runDbSnapshotSealCommand;
+exports.runDbSnapshotVerifyCommand = runDbSnapshotVerifyCommand;
+exports.runDbSnapshotStatusCommand = runDbSnapshotStatusCommand;
+exports.runDbSnapshotDumpCommand = runDbSnapshotDumpCommand;
+exports.runDbSnapshotDiffCommand = runDbSnapshotDiffCommand;
+exports.runDbIndexStatusCommand = runDbIndexStatusCommand;
+exports.runDbIndexVerifyCommand = runDbIndexVerifyCommand;
+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 paths_1 = require("../core/paths");
+const project_db_1 = require("../core/project_db");
+const project_db_migrations_1 = require("../core/project_db_migrations");
+const project_db_snapshot_1 = require("../core/project_db_snapshot");
+const version_1 = require("../core/version");
+const index_1 = require("./index");
+const capabilities_indexer_1 = require("../graph/capabilities_indexer");
+const capabilities_indexer_2 = require("../graph/capabilities_indexer");
+const capabilities_index_cache_1 = require("../graph/capabilities_index_cache");
+const indexer_1 = require("../graph/indexer");
+const staleness_1 = require("../graph/staleness");
+const skills_indexer_1 = require("../graph/skills_indexer");
+const skills_index_cache_1 = require("../graph/skills_index_cache");
+const subgraphs_1 = require("../graph/subgraphs");
+const sqlite_index_1 = require("../graph/sqlite_index");
+const atomic_1 = require("../util/atomic");
+const lock_1 = require("../util/lock");
+const errors_1 = require("../util/errors");
+function rel(root, filePath) {
+    return path_1.default.relative(root, filePath).split(path_1.default.sep).join("/");
+}
+function fileSize(filePath) {
+    if (!fs_1.default.existsSync(filePath)) {
+        return undefined;
+    }
+    return fs_1.default.statSync(filePath).size;
+}
+function readRawConfig(root) {
+    const filePath = (0, paths_1.configPath)(root);
+    if (!fs_1.default.existsSync(filePath)) {
+        throw new errors_1.NotFoundError(`config not found at ${filePath}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs_1.default.readFileSync(filePath, "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: filePath, raw: migrated };
+}
+function writeRawConfig(filePath, raw) {
+    (0, atomic_1.atomicWriteFile)(filePath, `${JSON.stringify(raw, null, 2)}\n`);
+}
+function ensureDirectory(root, dirPath, created, unchanged) {
+    const relative = rel(root, dirPath);
+    if (fs_1.default.existsSync(dirPath)) {
+        if (!fs_1.default.statSync(dirPath).isDirectory()) {
+            throw new errors_1.ValidationError(`${relative} exists and is not a directory`);
+        }
+        unchanged.push(relative);
+        return;
+    }
+    fs_1.default.mkdirSync(dirPath, { recursive: true });
+    created.push(relative);
+}
+function writeJsonIfChanged(root, filePath, payload, created, unchanged, updated) {
+    const relative = rel(root, filePath);
+    if (fs_1.default.existsSync(filePath) && fs_1.default.statSync(filePath).isDirectory()) {
+        throw new errors_1.ValidationError(`${relative} exists and is not a file`);
+    }
+    const content = `${JSON.stringify(payload, null, 2)}\n`;
+    if (fs_1.default.existsSync(filePath)) {
+        const current = fs_1.default.readFileSync(filePath, "utf8");
+        if (current === content) {
+            unchanged.push(relative);
+            return;
+        }
+        (0, atomic_1.atomicWriteFile)(filePath, content);
+        updated.push(relative);
+        return;
+    }
+    (0, atomic_1.atomicWriteFile)(filePath, content);
+    created.push(relative);
+}
+function readJsonCache(filePath) {
+    try {
+        JSON.parse(fs_1.default.readFileSync(filePath, "utf8"));
+        return undefined;
+    }
+    catch (err) {
+        return err instanceof Error ? err.message : String(err);
+    }
+}
+function jsonCacheCheck(options) {
+    const exists = fs_1.default.existsSync(options.filePath);
+    const errors = [];
+    const warnings = [];
+    if (!exists) {
+        errors.push("cache file missing");
+    }
+    else {
+        const readError = readJsonCache(options.filePath);
+        if (readError) {
+            errors.push(`cache is unreadable: ${readError}`);
+        }
+    }
+    if (exists && options.stale) {
+        warnings.push("cache is stale");
+    }
+    const ok = errors.length === 0 && warnings.length === 0;
+    return {
+        name: options.name,
+        ok,
+        level: errors.length > 0 ? "fail" : warnings.length > 0 ? "warn" : "ok",
+        path: rel(options.root, options.filePath),
+        exists,
+        stale: exists ? options.stale : true,
+        size: fileSize(options.filePath),
+        detail: !exists
+            ? "cache file missing"
+            : options.stale
+                ? "cache is stale"
+                : "cache is present and fresh",
+        errors,
+        warnings,
+    };
+}
+function buildCurrentSqliteFingerprint(root, tolerant) {
+    const config = (0, config_1.loadConfig)(root);
+    const nodeIndex = (0, indexer_1.buildIndex)(root, config, { tolerant });
+    const skillsIndex = (0, skills_indexer_1.buildSkillsIndex)(root, config);
+    const capabilitiesIndex = (0, capabilities_indexer_2.buildCapabilitiesIndex)(root, config, nodeIndex);
+    const subgraphsIndex = (0, subgraphs_1.buildSubgraphsIndex)(root, config).index;
+    return (0, sqlite_index_1.sqliteSourceFingerprint)({
+        root,
+        nodeIndex,
+        skillsIndex,
+        capabilitiesIndex,
+        subgraphsIndex,
+    });
+}
+function sqliteCacheCheck(root, tolerant) {
+    const config = (0, config_1.loadConfig)(root);
+    if (!(0, sqlite_index_1.isSqliteBackend)(config)) {
+        return {
+            name: "sqlite",
+            ok: true,
+            level: "ok",
+            path: rel(root, (0, sqlite_index_1.resolveSqlitePath)(root, config)),
+            exists: false,
+            stale: false,
+            size: undefined,
+            detail: "SQLite backend disabled; JSON cache backend active",
+            errors: [],
+            warnings: [],
+        };
+    }
+    const health = (0, sqlite_index_1.sqliteHealth)(root, config);
+    const fatalWarnings = health.warnings.filter((warning) => /missing|stale/i.test(warning));
+    const errors = [...health.errors, ...fatalWarnings];
+    const warnings = health.warnings.filter((warning) => !fatalWarnings.includes(warning));
+    if (health.exists && errors.length === 0) {
+        try {
+            const meta = (0, sqlite_index_1.readSqliteIndexMeta)(root, config);
+            const expectedFingerprint = buildCurrentSqliteFingerprint(root, tolerant);
+            const actualFingerprint = meta.source_fingerprint;
+            if (!actualFingerprint) {
+                errors.push("SQLite cache missing source fingerprint; run mdkg index");
+            }
+            else if (actualFingerprint !== expectedFingerprint) {
+                errors.push("SQLite source fingerprint mismatch; run mdkg index");
+            }
+        }
+        catch (err) {
+            errors.push(`failed to verify SQLite source fingerprint: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    const ok = health.exists && errors.length === 0;
+    return {
+        name: "sqlite",
+        ok,
+        level: errors.length > 0 ? "fail" : warnings.length > 0 ? "warn" : "ok",
+        path: rel(root, health.path),
+        exists: health.exists,
+        stale: fatalWarnings.some((warning) => /stale/i.test(warning)),
+        size: health.size,
+        detail: errors.length > 0
+            ? errors.join("; ")
+            : warnings.length > 0
+                ? warnings.join("; ")
+                : "SQLite cache is present and fresh",
+        errors,
+        warnings,
+    };
+}
+function collectDbIndexChecks(root, tolerant) {
+    const config = (0, config_1.loadConfig)(root);
+    return [
+        jsonCacheCheck({
+            root,
+            name: "global",
+            filePath: path_1.default.resolve(root, config.index.global_index_path),
+            stale: (0, staleness_1.isIndexStale)(root, config),
+        }),
+        jsonCacheCheck({
+            root,
+            name: "skills",
+            filePath: (0, skills_indexer_1.resolveSkillsIndexPath)(root),
+            stale: (0, skills_index_cache_1.isSkillsIndexStale)(root, config),
+        }),
+        jsonCacheCheck({
+            root,
+            name: "capabilities",
+            filePath: (0, capabilities_indexer_1.resolveCapabilitiesIndexPath)(root, config),
+            stale: (0, capabilities_index_cache_1.isCapabilitiesIndexStale)(root, config),
+        }),
+        jsonCacheCheck({
+            root,
+            name: "subgraphs",
+            filePath: (0, subgraphs_1.resolveSubgraphsIndexPath)(root),
+            stale: (0, subgraphs_1.isSubgraphsIndexStale)(root, config),
+        }),
+        sqliteCacheCheck(root, tolerant),
+    ];
+}
+function dbIndexPayload(action, root, checks) {
+    const failures = checks.filter((check) => !check.ok);
+    return {
+        action,
+        ok: failures.length === 0,
+        backend: (0, config_1.loadConfig)(root).index.backend,
+        root,
+        checks,
+        failure_count: failures.length,
+        warnings: checks.flatMap((check) => check.warnings.map((warning) => `${check.name}: ${warning}`)),
+        errors: checks.flatMap((check) => check.errors.map((error) => `${check.name}: ${error}`)),
+    };
+}
+function printChecks(payload) {
+    for (const check of payload.checks) {
+        const location = check.path ? ` (${check.path})` : "";
+        console.log(`${check.level}: ${check.name}${location} - ${check.detail}`);
+    }
+}
+function runDbIndexRebuildCommand(options) {
+    const result = (0, index_1.rebuildDerivedIndexCaches)({ root: options.root, tolerant: options.tolerant });
+    if (options.json) {
+        const config = (0, config_1.loadConfig)(options.root);
+        const paths = {
+            global: rel(options.root, result.paths.nodes),
+            skills: rel(options.root, result.paths.skills),
+            capabilities: rel(options.root, result.paths.capabilities),
+            subgraphs: rel(options.root, result.paths.subgraphs),
+        };
+        if (result.paths.sqlite) {
+            paths.sqlite = rel(options.root, result.paths.sqlite);
+        }
+        console.log(JSON.stringify({
+            action: "db-index-rebuild",
+            ok: true,
+            backend: config.index.backend,
+            paths,
+            node_count: Object.keys(result.nodeIndex.nodes).length,
+        }, null, 2));
+        return;
+    }
+    console.log("db index rebuilt");
+    console.log(`index written: ${rel(options.root, result.paths.nodes)}`);
+    console.log(`skills index written: ${rel(options.root, result.paths.skills)}`);
+    console.log(`capabilities index written: ${rel(options.root, result.paths.capabilities)}`);
+    console.log(`subgraphs index written: ${rel(options.root, result.paths.subgraphs)}`);
+    if (result.paths.sqlite) {
+        console.log(`sqlite index written: ${rel(options.root, result.paths.sqlite)}`);
+    }
+}
+function runDbInitCommandLocked(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const layout = (0, project_db_1.resolveConfiguredProjectDbLayout)(options.root, config.db);
+    const created = [];
+    const unchanged = [];
+    const updated = [];
+    for (const dirPath of [
+        layout.db,
+        layout.schema,
+        layout.migrations,
+        layout.runtimeDir,
+        layout.stateDir,
+        layout.receipts,
+    ]) {
+        ensureDirectory(options.root, dirPath, created, unchanged);
+    }
+    const manifest = {
+        tool: "mdkg",
+        kind: "project_db",
+        mdkg_version: (0, version_1.readPackageVersion)(),
+        schema_version: config.db.schema_version,
+        enabled: true,
+        layout: {
+            root_path: config.db.root_path,
+            schema_path: config.db.schema_path,
+            migrations_path: config.db.migrations_path,
+            runtime_path: config.db.runtime_path,
+            state_path: config.db.state_path,
+            receipts_path: config.db.receipts_path,
+        },
+        migration_table: config.db.migration_table,
+        runtime_database_created: false,
+    };
+    writeJsonIfChanged(options.root, layout.manifest, manifest, created, unchanged, updated);
+    const rawConfig = readRawConfig(options.root);
+    const nextConfig = { ...rawConfig.raw };
+    const nextDb = { ...config.db, enabled: true };
+    const currentDb = JSON.stringify(nextConfig.db ?? null);
+    const normalizedDb = JSON.stringify(nextDb);
+    const enabledBefore = config.db.enabled;
+    let config_updated = false;
+    if (currentDb !== normalizedDb) {
+        nextConfig.db = nextDb;
+        (0, config_1.validateConfigSchema)(nextConfig);
+        writeRawConfig(rawConfig.configPath, nextConfig);
+        updated.push(".mdkg/config.json");
+        config_updated = true;
+    }
+    else {
+        unchanged.push(".mdkg/config.json");
+    }
+    const receipt = {
+        action: "db-init",
+        ok: true,
+        enabled_before: enabledBefore,
+        enabled_after: true,
+        config_updated,
+        runtime_database_created: false,
+        paths: {
+            root: rel(options.root, layout.db),
+            schema: rel(options.root, layout.schema),
+            migrations: rel(options.root, layout.migrations),
+            runtime_dir: rel(options.root, layout.runtimeDir),
+            runtime_path: config.db.runtime_path,
+            state_dir: rel(options.root, layout.stateDir),
+            state_path: config.db.state_path,
+            receipts: rel(options.root, layout.receipts),
+            manifest: rel(options.root, layout.manifest),
+        },
+        created: created.sort(),
+        updated: updated.sort(),
+        unchanged: unchanged.sort(),
+    };
+    if (options.json) {
+        console.log(JSON.stringify(receipt, null, 2));
+        return;
+    }
+    console.log("project db initialized");
+    for (const item of receipt.created) {
+        console.log(`created: ${item}`);
+    }
+    for (const item of receipt.updated) {
+        console.log(`updated: ${item}`);
+    }
+    if (receipt.created.length === 0 && receipt.updated.length === 0) {
+        console.log("project db already initialized");
+    }
+    console.log("runtime database created: false");
+}
+function runDbInitCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    return (0, lock_1.withMutationLock)(options.root, config.index.lock_timeout_ms, () => runDbInitCommandLocked(options));
+}
+function runDbMigrateCommandLocked(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const receipt = (0, project_db_migrations_1.runProjectDbMigrations)(options.root, config);
+    if (options.json) {
+        console.log(JSON.stringify(receipt, null, 2));
+        return;
+    }
+    console.log("project db migrated");
+    console.log(`database: ${receipt.database}`);
+    console.log(`migration table: ${receipt.migration_table}`);
+    console.log(`applied: ${receipt.applied_count}`);
+    console.log(`already applied: ${receipt.skipped_count}`);
+    for (const migration of receipt.migrations) {
+        console.log(`${migration.status}: ${migration.ordinal} ${migration.key}`);
+    }
+}
+function runDbMigrateCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    return (0, lock_1.withMutationLock)(options.root, config.index.lock_timeout_ms, () => runDbMigrateCommandLocked(options));
+}
+function printProjectDbChecks(payload) {
+    for (const check of payload.checks) {
+        const location = check.path ? ` (${check.path})` : "";
+        console.log(`${check.level}: ${check.name}${location} - ${check.detail}`);
+    }
+}
+function runDbVerifyCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const payload = (0, project_db_migrations_1.verifyProjectDb)(options.root, config);
+    if (options.json) {
+        console.log(JSON.stringify(payload, null, 2));
+    }
+    else {
+        printProjectDbChecks(payload);
+    }
+    if (!payload.ok) {
+        throw new errors_1.ValidationError(`db verify failed with ${payload.failure_count} issue(s)`);
+    }
+    if (!options.json) {
+        console.log("db verify ok");
+    }
+}
+function runDbStatsCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const payload = (0, project_db_migrations_1.projectDbStats)(options.root, config);
+    if (options.json) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    console.log("project db stats");
+    console.log(`database: ${payload.database}`);
+    console.log(`db size: ${payload.db_size}`);
+    console.log(`migrations: ${payload.migration_count}`);
+    console.log(`latest migration: ${payload.latest_migration?.key ?? "(none)"}`);
+    console.log(`receipt files: ${payload.receipt_files.count}`);
+    console.log("tables:");
+    for (const table of payload.tables) {
+        console.log(`  ${table.name}: ${table.row_count}`);
+    }
+    if (payload.transient_files.length > 0) {
+        console.log("transient files:");
+        for (const item of payload.transient_files) {
+            console.log(`  ${item.path}: ${item.size}`);
+        }
+    }
+}
+function printSnapshotChecks(payload) {
+    for (const check of payload.checks) {
+        const location = check.path ? ` (${path_1.default.isAbsolute(check.path) ? rel(process.cwd(), check.path) : check.path})` : "";
+        console.log(`${check.level}: ${check.name}${location} - ${check.detail}`);
+    }
+}
+function runDbSnapshotSealCommandLocked(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const payload = (0, project_db_snapshot_1.sealProjectDbSnapshot)(options.root, config);
+    if (options.json) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    console.log("db snapshot sealed");
+    console.log(`snapshot: ${payload.snapshot}`);
+    console.log(`manifest: ${payload.manifest}`);
+    console.log(`sha256: ${payload.new_snapshot_sha256}`);
+    console.log(`byte size: ${payload.byte_size}`);
+    if (payload.warnings.length > 0) {
+        console.log("warnings:");
+        for (const warning of payload.warnings) {
+            console.log(`  ${warning}`);
+        }
+    }
+}
+function runDbSnapshotSealCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    return (0, lock_1.withMutationLock)(options.root, config.index.lock_timeout_ms, () => runDbSnapshotSealCommandLocked(options));
+}
+function runDbSnapshotVerifyCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const payload = (0, project_db_snapshot_1.verifyProjectDbSnapshot)(options.root, config);
+    if (options.json) {
+        console.log(JSON.stringify(payload, null, 2));
+    }
+    else {
+        printSnapshotChecks(payload);
+    }
+    if (!payload.ok) {
+        throw new errors_1.ValidationError(`db snapshot verify failed with ${payload.failure_count} issue(s)`);
+    }
+    if (!options.json) {
+        console.log("db snapshot verify ok");
+    }
+}
+function runDbSnapshotStatusCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const payload = (0, project_db_snapshot_1.projectDbSnapshotStatus)(options.root, config);
+    if (options.json) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    printSnapshotChecks(payload);
+    console.log(`db snapshot status: ${payload.status}`);
+}
+function runDbSnapshotDumpCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const payload = (0, project_db_snapshot_1.dumpProjectDbSnapshot)(options.root, config, options.snapshot, options.output);
+    const { dump, ...receipt } = payload;
+    if (options.json) {
+        console.log(JSON.stringify(receipt, null, 2));
+        return;
+    }
+    if (options.output) {
+        console.log("db snapshot dump written");
+        console.log(`output: ${receipt.output}`);
+        console.log(`sha256: ${receipt.sha256}`);
+        return;
+    }
+    process.stdout.write(dump);
+}
+function runDbSnapshotDiffCommand(options) {
+    const payload = (0, project_db_snapshot_1.diffProjectDbSnapshots)(options.root, options.left, options.right);
+    if (options.json) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    console.log(`db snapshot diff: ${payload.changed_count} change(s)`);
+    for (const line of payload.removed) {
+        console.log(`- ${line}`);
+    }
+    for (const line of payload.added) {
+        console.log(`+ ${line}`);
+    }
+}
+function runDbIndexStatusCommand(options) {
+    const payload = dbIndexPayload("db-index-status", options.root, collectDbIndexChecks(options.root, options.tolerant ?? false));
+    if (options.json) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    printChecks(payload);
+    console.log(payload.ok ? "db index status ok" : "db index status has issues");
+}
+function runDbIndexVerifyCommand(options) {
+    const payload = dbIndexPayload("db-index-verify", options.root, collectDbIndexChecks(options.root, options.tolerant ?? false));
+    if (options.json) {
+        console.log(JSON.stringify(payload, null, 2));
+    }
+    else {
+        printChecks(payload);
+    }
+    if (!payload.ok) {
+        throw new errors_1.ValidationError(`db index verify failed with ${payload.failure_count} issue(s)`);
+    }
+    if (!options.json) {
+        console.log("db index verify ok");
+    }
+}

package/dist/commands/doctor.js

@@ -14,6 +14,7 @@ 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 project_db_1 = require("../core/project_db");
 const errors_1 = require("../util/errors");
 const REQUIRED_NODE_MAJOR = 24;
 const REQUIRED_NODE_MINOR = 15;
@@ -186,6 +187,22 @@ function runBundleStorageCheck(root, outputDir) {
         detail: `${bundles.length} bundle(s) found; run \`mdkg bundle verify <path>\` to check freshness before handoff`,
     };
 }
+function runProjectDbRuntimePolicyCheck(root) {
+    const files = (0, project_db_1.listProjectDbRuntimePolicyFiles)(root);
+    if (files.length === 0) {
+        return {
+            name: "project-db-runtime",
+            ok: true,
+            detail: "no active project DB runtime or transient files found",
+        };
+    }
+    return {
+        name: "project-db-runtime",
+        ok: true,
+        level: "warn",
+        detail: `active project DB runtime/transient file(s) are local-only and should not be committed: ${files.join(", ")}`,
+    };
+}
 function runSubgraphChecks(root, config) {
     const projection = (0, subgraphs_1.buildSubgraphsIndex)(root, config);
     if (projection.index.subgraphs.length === 0) {
@@ -298,6 +315,7 @@ function runDoctorCommand(options) {
         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(runProjectDbRuntimePolicyCheck(options.root));
         results.push(runSqliteCheck(options.root, config));
         results.push(...runSubgraphChecks(options.root, config));
         results.push(runVisibilityPolicyCheck(options.root, config, options));

package/dist/commands/format.js

@@ -69,16 +69,21 @@ function sortList(values) {
 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;
+    const normalized = shouldLowercase
+        ? trimmed.map((value) => ((0, refs_1.isUriRef)(value) ? value : value.toLowerCase()))
+        : trimmed.map((value) => (EXTERNAL_REF_LIST_KEYS.has(key) && !(0, refs_1.isUriRef)(value) ? value.toLowerCase() : value));
     for (const entry of normalized) {
         if (!entry) {
             errors.push(`${filePath}: ${key} entries must be non-empty`);
             continue;
         }
-        if (ID_LIST_KEYS.has(key) && !(allowPortableRefs ? (0, id_1.isPortableId)(entry) : isValidId(entry))) {
+        if (ID_LIST_KEYS.has(key) && key === "refs" && !(0, refs_1.validatePortableOrUriRef)(entry)) {
+            errors.push(`${filePath}: ${key} entries must be portable ids, qids, or URI refs`);
+        }
+        else if (ID_LIST_KEYS.has(key) && key !== "refs" && !(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) && !(allowPortableRefs ? (0, id_1.isPortableIdRef)(entry) : (0, id_1.isCanonicalIdRef)(entry))) {
+        if (ID_REF_LIST_KEYS.has(key) && !(0, id_1.isPortableIdRef)(entry)) {
             errors.push(`${filePath}: ${key} entries must be valid id references`);
         }
         if (EXTERNAL_REF_LIST_KEYS.has(key) && !(0, refs_1.validatePortableOrUriRef)(entry)) {
@@ -92,7 +97,7 @@ function normalizeList(values, key, errors, filePath, allowPortableRefs = false)
 }
 function normalizeIdRef(value, key, errors, filePath) {
     const normalized = normalizeScalar(value).toLowerCase();
-    if (!(0, id_1.isCanonicalIdRef)(normalized)) {
+    if (!(0, id_1.isPortableIdRef)(normalized)) {
         errors.push(`${filePath}: ${key} must be a valid id reference`);
     }
     return normalized;
@@ -104,7 +109,7 @@ function normalizeFrontmatterValue(key, value, schema, errors, filePath, type) {
             errors.push(`${filePath}: ${key} must be a list`);
             return [];
         }
-        const allowPortableRefs = (0, agent_file_types_1.isAgentFileType)(type) || (0, archive_file_1.isArchiveType)(type);
+        const allowPortableRefs = (0, agent_file_types_1.isAgentFileType)(type) || (0, archive_file_1.isArchiveType)(type) || ID_REF_LIST_KEYS.has(key) || key === "refs";
         return normalizeList(value, key, errors, filePath, allowPortableRefs);
     }
     if (expected === "boolean") {

package/dist/commands/index.js

@@ -3,21 +3,26 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.rebuildDerivedIndexCaches = rebuildDerivedIndexCaches;
+exports.printIndexRebuildReceipt = printIndexRebuildReceipt;
 exports.runIndexCommand = runIndexCommand;
 const path_1 = __importDefault(require("path"));
 const config_1 = require("../core/config");
 const reindex_1 = require("../graph/reindex");
 const lock_1 = require("../util/lock");
-function runIndexCommand(options) {
+function rebuildDerivedIndexCaches(options) {
     const config = (0, config_1.loadConfig)(options.root);
-    (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(`subgraphs index written: ${path_1.default.relative(options.root, result.paths.subgraphs)}`);
-        if (result.paths.sqlite) {
-            console.log(`sqlite index written: ${path_1.default.relative(options.root, result.paths.sqlite)}`);
-        }
-    });
+    return (0, lock_1.withMutationLock)(options.root, config.index.lock_timeout_ms, () => (0, reindex_1.writeDerivedIndexes)(options.root, config, undefined, { tolerant: options.tolerant }));
+}
+function printIndexRebuildReceipt(root, result) {
+    console.log(`index written: ${path_1.default.relative(root, result.paths.nodes)}`);
+    console.log(`skills index written: ${path_1.default.relative(root, result.paths.skills)}`);
+    console.log(`capabilities index written: ${path_1.default.relative(root, result.paths.capabilities)}`);
+    console.log(`subgraphs index written: ${path_1.default.relative(root, result.paths.subgraphs)}`);
+    if (result.paths.sqlite) {
+        console.log(`sqlite index written: ${path_1.default.relative(root, result.paths.sqlite)}`);
+    }
+}
+function runIndexCommand(options) {
+    printIndexRebuildReceipt(options.root, rebuildDerivedIndexCaches(options));
 }