mdkg 0.0.2 → 0.0.4

package/dist/commands/checkpoint.js

@@ -11,8 +11,8 @@ const index_cache_1 = require("../graph/index_cache");
 const loader_1 = require("../templates/loader");
 const date_1 = require("../util/date");
 const errors_1 = require("../util/errors");
-const ID_RE = /^[a-z]+-[0-9]+$/;
-const ID_REF_RE = /^([a-z][a-z0-9_]*:)?[a-z]+-[0-9]+$/;
+const id_1 = require("../util/id");
+const event_support_1 = require("./event_support");
 function parseCsvList(raw) {
     if (!raw) {
         return [];
@@ -24,14 +24,14 @@ function parseCsvList(raw) {
 }
 function normalizeId(value, key) {
     const normalized = value.toLowerCase();
-    if (!ID_RE.test(normalized) && normalized !== "rule-guide") {
-        throw new errors_1.UsageError(`${key} entries must match <prefix>-<number>: ${value}`);
+    if (!(0, id_1.isCanonicalId)(normalized)) {
+        throw new errors_1.UsageError(`${key} entries must match <prefix>-<number> or reserved id: ${value}`);
     }
     return normalized;
 }
 function normalizeIdRef(value, key) {
     const normalized = value.toLowerCase();
-    if (!ID_REF_RE.test(normalized)) {
+    if (!(0, id_1.isCanonicalIdRef)(normalized)) {
         throw new errors_1.UsageError(`${key} entries must match <id> or <ws>:<id>: ${value}`);
     }
     return normalized;
@@ -115,7 +115,8 @@ function runCheckpointNewCommand(options) {
         }
     }
     const scope = parseCsvList(options.scope).map((value) => normalizeId(value, "--scope"));
-    const today = (0, date_1.formatDate)(new Date());
+    const now = options.now ?? new Date();
+    const today = (0, date_1.formatDate)(now);
     const template = (0, loader_1.loadTemplate)(options.root, config, "checkpoint", options.template);
     const content = (0, loader_1.renderTemplate)(template, {
         id,
@@ -129,5 +130,15 @@ function runCheckpointNewCommand(options) {
     });
     fs_1.default.mkdirSync(workDir, { recursive: true });
     fs_1.default.writeFileSync(filePath, content, "utf8");
+    (0, event_support_1.appendAutomaticEvent)({
+        root: options.root,
+        ws,
+        kind: "CHECKPOINT_CREATED",
+        status: "ok",
+        refs: [id],
+        notes: options.note ?? `checkpoint created via mdkg checkpoint new`,
+        runId: options.runId,
+        now,
+    });
     console.log(`checkpoint created: ${ws}:${id} (${path_1.default.relative(options.root, filePath)})`);
 }

package/dist/commands/doctor.js

@@ -0,0 +1,156 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDoctorCommand = runDoctorCommand;
+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 node_1 = require("../graph/node");
+const template_schema_1 = require("../graph/template_schema");
+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)) {
+        return null;
+    }
+    return major;
+}
+function runNodeVersionCheck() {
+    const nodeVersion = process.versions.node;
+    const major = parseNodeMajor(nodeVersion);
+    if (major === null) {
+        return {
+            name: "node-version",
+            ok: false,
+            detail: `unable to parse Node.js version: ${nodeVersion}`,
+        };
+    }
+    if (major < REQUIRED_NODE_MAJOR) {
+        return {
+            name: "node-version",
+            ok: false,
+            detail: `Node.js ${nodeVersion} is unsupported (requires >=${REQUIRED_NODE_MAJOR})`,
+        };
+    }
+    return {
+        name: "node-version",
+        ok: true,
+        detail: `Node.js ${nodeVersion} (ok)`,
+    };
+}
+function runDoctorCommand(options) {
+    const results = [];
+    results.push(runNodeVersionCheck());
+    const configPath = path_1.default.resolve(options.root, ".mdkg", "config.json");
+    if (!fs_1.default.existsSync(configPath)) {
+        results.push({
+            name: "config",
+            ok: false,
+            detail: `missing config at ${configPath}`,
+        });
+    }
+    else {
+        results.push({
+            name: "config",
+            ok: true,
+            detail: `found ${configPath}`,
+        });
+    }
+    let config;
+    try {
+        config = (0, config_1.loadConfig)(options.root);
+        results.push({
+            name: "config-schema",
+            ok: true,
+            detail: "config schema valid",
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        results.push({
+            name: "config-schema",
+            ok: false,
+            detail: message,
+        });
+    }
+    if (config) {
+        try {
+            (0, template_schema_1.loadTemplateSchemas)(options.root, config, node_1.ALLOWED_TYPES);
+            results.push({
+                name: "templates",
+                ok: true,
+                detail: "template schema set loaded",
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            results.push({
+                name: "templates",
+                ok: false,
+                detail: message,
+            });
+        }
+        try {
+            const { rebuilt, stale } = (0, index_cache_1.loadIndex)({
+                root: options.root,
+                config,
+                useCache: !options.noCache,
+                allowReindex: !options.noReindex,
+            });
+            if (rebuilt) {
+                results.push({
+                    name: "index",
+                    ok: true,
+                    detail: "index cache rebuilt and loaded",
+                });
+            }
+            else if (stale) {
+                results.push({
+                    name: "index",
+                    ok: true,
+                    detail: "index cache is stale (run mdkg index to refresh)",
+                });
+            }
+            else {
+                results.push({
+                    name: "index",
+                    ok: true,
+                    detail: "index cache loaded",
+                });
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            results.push({
+                name: "index",
+                ok: false,
+                detail: message,
+            });
+        }
+    }
+    const failures = results.filter((result) => !result.ok);
+    if (options.json) {
+        const payload = {
+            ok: failures.length === 0,
+            checks: results,
+            failure_count: failures.length,
+        };
+        console.log(JSON.stringify(payload, null, 2));
+    }
+    else {
+        for (const result of results) {
+            const prefix = result.ok ? "ok" : "fail";
+            console.log(`${prefix}: ${result.name} - ${result.detail}`);
+        }
+    }
+    if (failures.length > 0) {
+        throw new errors_1.ValidationError(`doctor failed with ${failures.length} issue(s)`);
+    }
+    if (!options.json) {
+        console.log("doctor ok");
+    }
+}

package/dist/commands/event.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runEventEnableCommand = runEventEnableCommand;
+exports.runEventAppendCommand = runEventAppendCommand;
+const event_support_1 = require("./event_support");
+const errors_1 = require("../util/errors");
+function runEventEnableCommand(options) {
+    const result = (0, event_support_1.ensureEventsEnabled)(options);
+    const createdLabel = result.created ? "created" : "already present";
+    const ignoreLabel = result.gitignoreUpdated ? "updated .gitignore" : "left .gitignore unchanged";
+    console.log(`event logging enabled: ${result.ws} (${createdLabel}; ${ignoreLabel})`);
+}
+function normalizeEventStatus(value) {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "ok" ||
+        normalized === "error" ||
+        normalized === "retry" ||
+        normalized === "skipped") {
+        return normalized;
+    }
+    throw new errors_1.UsageError("--status must be one of ok, error, retry, skipped");
+}
+function runEventAppendCommand(options) {
+    const kind = options.kind.trim();
+    if (!kind) {
+        throw new errors_1.UsageError("--kind is required");
+    }
+    const refs = (0, event_support_1.normalizeEventRefList)(options.refs);
+    if (refs.length === 0) {
+        throw new errors_1.UsageError("--refs requires at least one id or qid");
+    }
+    const record = (0, event_support_1.appendEvent)({
+        root: options.root,
+        ws: options.ws,
+        kind,
+        status: normalizeEventStatus(options.status),
+        refs,
+        artifacts: (0, event_support_1.normalizeEventStringList)(options.artifacts),
+        notes: options.notes,
+        runId: options.runId,
+        agent: options.agent,
+        skill: options.skill,
+        tool: options.tool,
+    });
+    console.log(`event appended: ${record.workspace}:${record.kind} (${record.run_id})`);
+}

package/dist/commands/event_support.js

@@ -0,0 +1,146 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeWorkspaceForEvents = normalizeWorkspaceForEvents;
+exports.resolveEventsPath = resolveEventsPath;
+exports.createLocalRunId = createLocalRunId;
+exports.isEventLoggingEnabled = isEventLoggingEnabled;
+exports.ensureEventsEnabled = ensureEventsEnabled;
+exports.normalizeEventRefList = normalizeEventRefList;
+exports.normalizeEventStringList = normalizeEventStringList;
+exports.appendEvent = appendEvent;
+exports.appendAutomaticEvent = appendAutomaticEvent;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const config_1 = require("../core/config");
+const errors_1 = require("../util/errors");
+function appendIgnoreEntries(filePath, entries) {
+    const normalizedEntries = entries.map((entry) => entry.trim()).filter(Boolean);
+    if (normalizedEntries.length === 0) {
+        return false;
+    }
+    let existing = "";
+    if (fs_1.default.existsSync(filePath)) {
+        existing = fs_1.default.readFileSync(filePath, "utf8");
+    }
+    const existingLines = new Set(existing
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean));
+    const additions = normalizedEntries.filter((entry) => !existingLines.has(entry));
+    if (additions.length === 0) {
+        return false;
+    }
+    const next = existing.length === 0 ? `${additions.join("\n")}\n` : `${existing.replace(/\s*$/, "\n")}${additions.join("\n")}\n`;
+    fs_1.default.writeFileSync(filePath, next, "utf8");
+    return true;
+}
+function normalizeWorkspaceForEvents(config, raw) {
+    const normalized = (raw ?? "root").toLowerCase();
+    if (normalized === "all") {
+        throw new errors_1.UsageError("--ws all is not valid here");
+    }
+    if (!config.workspaces[normalized]) {
+        throw new errors_1.NotFoundError(`workspace not found: ${normalized}`);
+    }
+    return normalized;
+}
+function resolveEventsPath(root, config, ws = "root") {
+    const entry = config.workspaces[ws];
+    if (!entry) {
+        throw new errors_1.NotFoundError(`workspace not found: ${ws}`);
+    }
+    return path_1.default.resolve(root, entry.path, entry.mdkg_dir, "work", "events", "events.jsonl");
+}
+function formatRunIdTimestamp(now) {
+    const iso = now.toISOString().replace(/[-:]/g, "").replace(/\./g, "").replace("Z", "Z");
+    return iso;
+}
+function createLocalRunId(kind, now = new Date()) {
+    const normalizedKind = kind.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+    return `run_mdkg_cli_${normalizedKind}_${formatRunIdTimestamp(now)}`;
+}
+function isEventLoggingEnabled(root, config, ws) {
+    const normalizedWs = normalizeWorkspaceForEvents(config, ws);
+    return fs_1.default.existsSync(resolveEventsPath(root, config, normalizedWs));
+}
+function ensureEventsEnabled(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const ws = normalizeWorkspaceForEvents(config, options.ws);
+    const eventsPath = resolveEventsPath(options.root, config, ws);
+    const updateGitignore = options.updateGitignore !== false;
+    let created = false;
+    if (!fs_1.default.existsSync(eventsPath)) {
+        fs_1.default.mkdirSync(path_1.default.dirname(eventsPath), { recursive: true });
+        fs_1.default.writeFileSync(eventsPath, "", "utf8");
+        created = true;
+    }
+    let gitignoreUpdated = false;
+    if (updateGitignore) {
+        gitignoreUpdated = appendIgnoreEntries(path_1.default.join(options.root, ".gitignore"), [
+            ".mdkg/work/events/*.jsonl",
+        ]);
+    }
+    return { ws, eventsPath, created, gitignoreUpdated };
+}
+function normalizeIdOrIdRef(value) {
+    return value.trim().toLowerCase();
+}
+function normalizeEventRefList(raw) {
+    if (!raw) {
+        return [];
+    }
+    return raw
+        .split(",")
+        .map((value) => normalizeIdOrIdRef(value))
+        .filter(Boolean);
+}
+function normalizeEventStringList(raw) {
+    if (!raw) {
+        return [];
+    }
+    return raw
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean);
+}
+function buildEventRecord(config, options) {
+    const now = options.now ?? new Date();
+    const ws = normalizeWorkspaceForEvents(config, options.ws);
+    return {
+        ts: now.toISOString(),
+        run_id: options.runId?.trim() || createLocalRunId(options.kind, now),
+        workspace: ws,
+        agent: options.agent?.trim() || "mdkg-cli",
+        kind: options.kind,
+        status: options.status,
+        refs: options.refs.map(normalizeIdOrIdRef).filter(Boolean),
+        artifacts: (options.artifacts ?? []).map((value) => value.trim()).filter(Boolean),
+        notes: options.notes?.trim() ?? "",
+        ...(options.skill ? { skill: options.skill.trim().toLowerCase() } : {}),
+        ...(options.tool ? { tool: options.tool.trim() } : {}),
+    };
+}
+function appendEvent(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const record = buildEventRecord(config, options);
+    if (record.refs.length === 0) {
+        throw new errors_1.UsageError("--refs requires at least one id or qid");
+    }
+    const eventsPath = resolveEventsPath(options.root, config, record.workspace);
+    if (!fs_1.default.existsSync(eventsPath)) {
+        throw new errors_1.NotFoundError(`event logging is not enabled for workspace ${record.workspace}; run \`mdkg event enable --ws ${record.workspace}\``);
+    }
+    fs_1.default.appendFileSync(eventsPath, `${JSON.stringify(record)}\n`, "utf8");
+    return record;
+}
+function appendAutomaticEvent(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const ws = normalizeWorkspaceForEvents(config, options.ws);
+    if (!isEventLoggingEnabled(options.root, config, ws)) {
+        return undefined;
+    }
+    return appendEvent({ ...options, ws });
+}

package/dist/commands/format.js

@@ -13,8 +13,7 @@ const node_1 = require("../graph/node");
 const workspace_files_1 = require("../graph/workspace_files");
 const errors_1 = require("../util/errors");
 const date_1 = require("../util/date");
-const ID_RE = /^[a-z]+-[0-9]+$/;
-const ID_REF_RE = /^([a-z][a-z0-9_]*:)?[a-z]+-[0-9]+$/;
+const id_1 = require("../util/id");
 const DEC_ID_RE = /^dec-[0-9]+$/;
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const ID_LIST_KEYS = new Set(["refs", "scope"]);
@@ -22,7 +21,7 @@ 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"]);
 function isValidId(value) {
-    return ID_RE.test(value) || value === "rule-guide";
+    return (0, id_1.isCanonicalId)(value);
 }
 function isCoreListFile(filePath) {
     return path_1.default.basename(filePath) === "core.md" && path_1.default.basename(path_1.default.dirname(filePath)) === "core";
@@ -59,9 +58,9 @@ function normalizeList(values, key, errors, filePath) {
             continue;
         }
         if (ID_LIST_KEYS.has(key) && !isValidId(entry)) {
-            errors.push(`${filePath}: ${key} entries must match <prefix>-<number>`);
+            errors.push(`${filePath}: ${key} entries must match <prefix>-<number> or reserved id`);
         }
-        if (ID_REF_LIST_KEYS.has(key) && !ID_REF_RE.test(entry)) {
+        if (ID_REF_LIST_KEYS.has(key) && !(0, id_1.isCanonicalIdRef)(entry)) {
             errors.push(`${filePath}: ${key} entries must be valid id references`);
         }
     }
@@ -69,7 +68,7 @@ function normalizeList(values, key, errors, filePath) {
 }
 function normalizeIdRef(value, key, errors, filePath) {
     const normalized = normalizeScalar(value).toLowerCase();
-    if (!ID_REF_RE.test(normalized)) {
+    if (!(0, id_1.isCanonicalIdRef)(normalized)) {
         errors.push(`${filePath}: ${key} must be a valid id reference`);
     }
     return normalized;
@@ -124,7 +123,7 @@ function normalizeFrontmatter(frontmatter, schema, type, workStatusEnum, priorit
     else {
         const normalizedId = idValue.toLowerCase();
         if (!isValidId(normalizedId)) {
-            errors.push(`${filePath}: id must match <prefix>-<number>`);
+            errors.push(`${filePath}: id must match <prefix>-<number> or reserved id`);
         }
         normalized.id = normalizedId;
     }

package/dist/commands/index.js

@@ -8,10 +8,16 @@ 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");
 function runIndexCommand(options) {
     const config = (0, config_1.loadConfig)(options.root);
-    const index = (0, indexer_1.buildIndex)(options.root, config, { tolerant: options.tolerant });
-    const outputPath = path_1.default.resolve(options.root, config.index.global_index_path);
-    (0, index_cache_1.writeIndex)(outputPath, index);
-    console.log(`index written: ${path_1.default.relative(options.root, outputPath)}`);
+    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)}`);
 }