mdkg 0.0.8 → 0.1.0

package/dist/commands/upgrade.js

@@ -0,0 +1,286 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runUpgradeCommand = runUpgradeCommand;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const migrate_1 = require("../core/migrate");
+const config_1 = require("../core/config");
+const paths_1 = require("../core/paths");
+const version_1 = require("../core/version");
+const errors_1 = require("../util/errors");
+const init_manifest_1 = require("./init_manifest");
+const skill_support_1 = require("./skill_support");
+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"]);
+function seededInitEvent(nowIso) {
+    const event = {
+        ts: nowIso,
+        run_id: `upgrade-${nowIso.replace(/[^0-9]/g, "").slice(0, 14)}`,
+        workspace: "root",
+        agent: "mdkg",
+        kind: "RUN_STARTED",
+        status: "ok",
+        refs: ["edd-4"],
+        artifacts: [],
+        notes: "upgrade ensured agent event log",
+        redacted: true,
+    };
+    return `${JSON.stringify(event)}\n`;
+}
+function requireSeedAssets(seedRoot) {
+    for (const required of ["config.json", "README.md", "core", "templates"]) {
+        if (!fs_1.default.existsSync(path_1.default.join(seedRoot, required))) {
+            throw new errors_1.NotFoundError(`upgrade assets missing ${required} at ${seedRoot} (try reinstalling mdkg)`);
+        }
+    }
+}
+function isAgentWorkspace(root) {
+    return [
+        path_1.default.join(root, ".mdkg", "skills"),
+        path_1.default.join(root, ".agents", "skills"),
+        path_1.default.join(root, ".claude", "skills"),
+        path_1.default.join(root, ".mdkg", "work", "events", "events.jsonl"),
+    ].some((candidate) => fs_1.default.existsSync(candidate));
+}
+function copyFile(src, dest) {
+    fs_1.default.mkdirSync(path_1.default.dirname(dest), { recursive: true });
+    fs_1.default.copyFileSync(src, dest);
+}
+function writeFile(filePath, content) {
+    fs_1.default.mkdirSync(path_1.default.dirname(filePath), { recursive: true });
+    fs_1.default.writeFileSync(filePath, content, "utf8");
+}
+function createSummary() {
+    return {
+        created: 0,
+        updated: 0,
+        migrated: 0,
+        synced: 0,
+        skipped: 0,
+        conflicted: 0,
+        unchanged: 0,
+    };
+}
+function record(summary, changes, change) {
+    changes.push(change);
+    switch (change.action) {
+        case "create":
+            summary.created += 1;
+            break;
+        case "update":
+            summary.updated += 1;
+            break;
+        case "migrate":
+            summary.migrated += 1;
+            break;
+        case "sync":
+            summary.synced += 1;
+            break;
+        case "conflict":
+            summary.skipped += 1;
+            summary.conflicted += 1;
+            break;
+    }
+}
+function buildKnownHashes(manifests) {
+    const hashes = new Map();
+    for (const manifest of manifests) {
+        if (!manifest) {
+            continue;
+        }
+        for (const file of manifest.files) {
+            if (!hashes.has(file.path)) {
+                hashes.set(file.path, new Set());
+            }
+            hashes.get(file.path)?.add(file.sha256);
+        }
+    }
+    return hashes;
+}
+function shouldIncludeFile(file, agentWorkspace) {
+    if (file.category === "default_skill") {
+        return agentWorkspace;
+    }
+    return file.category !== "config";
+}
+function planSeedFile(options) {
+    const destPath = path_1.default.join(options.root, options.file.path);
+    const srcPath = (0, init_manifest_1.seedSourcePath)(options.seedRoot, options.file);
+    const currentHash = fs_1.default.existsSync(destPath) && fs_1.default.statSync(destPath).isFile() ? (0, init_manifest_1.sha256File)(destPath) : undefined;
+    const nextHash = options.file.sha256;
+    if (!currentHash) {
+        record(options.summary, options.changes, {
+            path: options.file.path,
+            category: options.file.category,
+            action: "create",
+            reason: "missing managed init asset",
+        });
+        if (!options.dryRun) {
+            copyFile(srcPath, destPath);
+        }
+        options.managedCurrentFiles.push(options.file);
+        return true;
+    }
+    if (currentHash === nextHash) {
+        options.summary.unchanged += 1;
+        options.managedCurrentFiles.push(options.file);
+        return false;
+    }
+    if (CREATE_ONLY_PRESERVED.has(options.file.path)) {
+        options.summary.unchanged += 1;
+        return false;
+    }
+    if (PROTECTED_CORE_DOCS.has(options.file.path)) {
+        record(options.summary, options.changes, {
+            path: options.file.path,
+            category: options.file.category,
+            action: "conflict",
+            reason: "protected core document exists; local content preserved",
+        });
+        return false;
+    }
+    const known = options.knownHashes.get(options.file.path);
+    if (known?.has(currentHash)) {
+        record(options.summary, options.changes, {
+            path: options.file.path,
+            category: options.file.category,
+            action: "update",
+            reason: "matches a managed seed hash",
+        });
+        if (!options.dryRun) {
+            copyFile(srcPath, destPath);
+        }
+        options.managedCurrentFiles.push(options.file);
+        return true;
+    }
+    record(options.summary, options.changes, {
+        path: options.file.path,
+        category: options.file.category,
+        action: "conflict",
+        reason: "local changes detected; content preserved",
+    });
+    return false;
+}
+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) {
+        summary.unchanged += 1;
+        return;
+    }
+    record(summary, changes, {
+        path: ".mdkg/config.json",
+        category: "config",
+        action: "migrate",
+        reason: `config schema_version ${migrated.from} -> ${migrated.to}`,
+    });
+    if (!dryRun) {
+        writeFile(cfgPath, `${JSON.stringify(migrated.config, null, 2)}\n`);
+    }
+}
+function ensureAgentRuntimeFiles(root, dryRun, summary, changes) {
+    const eventsPath = path_1.default.join(root, ".mdkg", "work", "events", "events.jsonl");
+    if (!fs_1.default.existsSync(eventsPath)) {
+        record(summary, changes, {
+            path: ".mdkg/work/events/events.jsonl",
+            category: "event_log",
+            action: "create",
+            reason: "agent workspace is missing event log",
+        });
+        if (!dryRun) {
+            writeFile(eventsPath, seededInitEvent(new Date().toISOString()));
+        }
+    }
+    else {
+        summary.unchanged += 1;
+    }
+}
+function emitHumanReceipt(receipt) {
+    const mode = receipt.dry_run ? "dry-run" : "apply";
+    console.log(`mdkg upgrade ${mode}: ${receipt.summary.created} create, ${receipt.summary.updated} update, ${receipt.summary.migrated} migrate, ${receipt.summary.synced} sync, ${receipt.summary.conflicted} conflict`);
+    if (receipt.changes.length === 0) {
+        console.log("no upgrade changes pending");
+    }
+    else {
+        for (const change of receipt.changes) {
+            console.log(`  ${change.action}: ${change.path} (${change.reason})`);
+        }
+    }
+    if (receipt.dry_run && receipt.changes.some((change) => change.action !== "conflict")) {
+        console.log("next: mdkg upgrade --apply");
+    }
+}
+function runUpgradeCommand(options) {
+    const root = path_1.default.resolve(options.root);
+    const seedRoot = options.seedRoot ? path_1.default.resolve(options.seedRoot) : DEFAULT_SEED_SUBDIR;
+    const dryRun = !options.apply;
+    const version = (0, version_1.readPackageVersion)();
+    requireSeedAssets(seedRoot);
+    const currentManifest = (0, init_manifest_1.createInitManifest)(seedRoot, version);
+    const existingManifest = (0, init_manifest_1.readInitManifest)(path_1.default.join(root, ".mdkg", init_manifest_1.INIT_MANIFEST_FILE));
+    const legacyManifests = (0, init_manifest_1.loadLegacyInitManifests)(seedRoot);
+    const knownHashes = buildKnownHashes([existingManifest, ...legacyManifests]);
+    const summary = createSummary();
+    const changes = [];
+    const agentWorkspace = isAgentWorkspace(root);
+    const managedCurrentFiles = [];
+    migrateConfigIfNeeded(root, dryRun, summary, changes);
+    for (const file of currentManifest.files) {
+        if (!shouldIncludeFile(file, agentWorkspace)) {
+            continue;
+        }
+        planSeedFile({
+            root,
+            seedRoot,
+            file,
+            knownHashes,
+            dryRun,
+            summary,
+            changes,
+            managedCurrentFiles,
+        });
+    }
+    if (agentWorkspace) {
+        ensureAgentRuntimeFiles(root, dryRun, summary, changes);
+    }
+    if (!dryRun) {
+        const appliedManifest = {
+            ...currentManifest,
+            files: managedCurrentFiles.sort((a, b) => a.path.localeCompare(b.path)),
+        };
+        (0, init_manifest_1.writeInitManifest)(path_1.default.join(root, ".mdkg", init_manifest_1.INIT_MANIFEST_FILE), appliedManifest);
+        if (agentWorkspace) {
+            const config = (0, config_1.validateConfigSchema)((0, migrate_1.migrateConfig)(JSON.parse(fs_1.default.readFileSync((0, paths_1.configPath)(root), "utf8"))).config);
+            (0, skill_support_1.refreshSkillsRegistry)(root, config);
+            (0, skill_mirror_1.scaffoldMirrorRoots)(root);
+            const result = (0, skill_mirror_1.syncSkillMirrors)({ root, config, createRoots: true });
+            record(summary, changes, {
+                path: ".agents/skills,.claude/skills",
+                category: "skill_mirror",
+                action: "sync",
+                reason: `${result.synced} mirrored skill(s), ${result.pruned} stale mirror(s) pruned`,
+            });
+        }
+    }
+    const receipt = {
+        action: "upgrade",
+        dry_run: dryRun,
+        version,
+        summary,
+        changes,
+    };
+    if (options.json) {
+        console.log(`${JSON.stringify(receipt, null, 2)}`);
+    }
+    else {
+        emitHumanReceipt(receipt);
+    }
+    return receipt;
+}

package/dist/commands/validate.js

@@ -65,6 +65,13 @@ const RECOMMENDED_HEADINGS = {
         "Rollout plan",
     ],
     dec: ["Context", "Decision", "Alternatives considered", "Consequences", "Links / references"],
+    spec: ["Purpose", "Runtime", "Work Contracts", "Capabilities"],
+    work: ["Capability", "Inputs", "Outputs", "Receipt"],
+    work_order: ["Request", "Inputs", "Constraints"],
+    receipt: ["Outcome", "Artifacts", "Notes"],
+    feedback: ["Feedback", "Evidence"],
+    dispute: ["Dispute", "Evidence", "Resolution"],
+    proposal: ["Summary", "Evidence", "Proposed Change", "Review"],
 };
 function normalizeHeading(value) {
     return value.trim().toLowerCase();
@@ -119,6 +126,7 @@ function buildIndexNode(root, ws, filePath, node) {
         refs: node.refs,
         aliases: node.aliases,
         skills: node.skills,
+        attributes: node.attributes,
         path: path_1.default.relative(root, filePath),
         edges: normalizeEdges(node.edges, ws),
     };
@@ -256,11 +264,10 @@ function runValidateCommand(options) {
         nodes,
         reverse_edges: {},
     };
-    const graphErrors = (0, validate_graph_1.collectGraphErrors)(index, { allowMissing: false });
-    errors.push(...graphErrors);
+    let knownSkills = new Set();
     try {
         const skillsIndex = (0, skills_indexer_1.buildSkillsIndex)(options.root, config);
-        const knownSkills = new Set(Object.keys(skillsIndex.skills));
+        knownSkills = new Set(Object.keys(skillsIndex.skills));
         for (const node of Object.values(nodes)) {
             for (const slug of node.skills) {
                 if (!knownSkills.has(slug)) {
@@ -273,6 +280,11 @@ function runValidateCommand(options) {
         const message = err instanceof Error ? err.message : "unknown skill validation error";
         errors.push(message);
     }
+    const graphErrors = (0, validate_graph_1.collectGraphErrors)(index, {
+        allowMissing: false,
+        knownSkillSlugs: knownSkills,
+    });
+    errors.push(...graphErrors);
     const skillsRoot = (0, skills_indexer_1.resolveSkillsRoot)(options.root, config);
     for (const dirPath of listDirectories(skillsRoot)) {
         const canonicalPath = path_1.default.join(dirPath, "SKILL.md");
@@ -305,6 +317,22 @@ function runValidateCommand(options) {
         fs_1.default.mkdirSync(path_1.default.dirname(outPath), { recursive: true });
         fs_1.default.writeFileSync(outPath, reportLines.join("\n"), "utf8");
     }
+    const receipt = {
+        action: "validated",
+        ok: uniqueErrors.length === 0,
+        warning_count: uniqueWarnings.length,
+        error_count: uniqueErrors.length,
+        warnings: uniqueWarnings,
+        errors: uniqueErrors,
+        ...(outPath ? { report_path: outPath } : {}),
+    };
+    if (options.json) {
+        console.log(JSON.stringify(receipt, null, 2));
+        if (uniqueErrors.length > 0) {
+            throw new errors_1.ValidationError(`validation failed with ${uniqueErrors.length} error(s)`);
+        }
+        return;
+    }
     if (!options.quiet) {
         for (const warning of uniqueWarnings) {
             console.error(`warning: ${warning}`);

package/dist/commands/workspace.js

@@ -6,11 +6,34 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runWorkspaceListCommand = runWorkspaceListCommand;
 exports.runWorkspaceAddCommand = runWorkspaceAddCommand;
 exports.runWorkspaceRemoveCommand = runWorkspaceRemoveCommand;
+exports.runWorkspaceEnableCommand = runWorkspaceEnableCommand;
+exports.runWorkspaceDisableCommand = runWorkspaceDisableCommand;
 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 errors_1 = require("../util/errors");
 const ALIAS_RE = /^[a-z][a-z0-9_]*$/;
+function workspaceReceipt(alias, workspace) {
+    return {
+        alias,
+        path: workspace.path,
+        enabled: workspace.enabled,
+        mdkg_dir: workspace.mdkg_dir,
+    };
+}
+function printWorkspaceMutationReceipt(action, workspace, json) {
+    if (json) {
+        console.log(JSON.stringify({ action, workspace }, null, 2));
+        return;
+    }
+    if (action === "added") {
+        console.log(`workspace added: ${workspace.alias} (${workspace.path})`);
+        return;
+    }
+    console.log(`workspace ${action}: ${workspace.alias}`);
+}
 function readRawConfig(root) {
     const configPath = path_1.default.join(root, ".mdkg", "config.json");
     if (!fs_1.default.existsSync(configPath)) {
@@ -27,24 +50,51 @@ function readRawConfig(root) {
     if (typeof raw !== "object" || raw === null) {
         throw new errors_1.UsageError("config must be a JSON object");
     }
-    return { path: configPath, raw: raw };
+    const migrated = (0, migrate_1.migrateConfig)(raw).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 { path: configPath, raw: migrated };
 }
 function writeRawConfig(configPath, raw) {
     fs_1.default.writeFileSync(configPath, JSON.stringify(raw, null, 2), "utf8");
 }
 function normalizeAlias(alias) {
-    const normalized = alias.toLowerCase();
-    if (normalized === "all") {
+    if (alias.toLowerCase() === "all") {
         throw new errors_1.UsageError("workspace alias cannot be 'all'");
     }
-    if (!ALIAS_RE.test(normalized)) {
+    if (alias !== alias.toLowerCase() || !ALIAS_RE.test(alias)) {
         throw new errors_1.UsageError("workspace alias must be lowercase and use [a-z0-9_]");
     }
-    return normalized;
+    return alias;
+}
+function normalizeCommandWorkspacePath(value, label) {
+    try {
+        return (0, workspace_path_1.normalizeContainedWorkspacePath)(value, label);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new errors_1.UsageError(message);
+    }
 }
 function runWorkspaceListCommand(options) {
     const config = (0, config_1.loadConfig)(options.root);
     const aliases = Object.keys(config.workspaces).sort();
+    if (options.json) {
+        console.log(JSON.stringify({
+            workspaces: aliases.map((alias) => {
+                const ws = config.workspaces[alias];
+                return {
+                    alias,
+                    path: ws.path,
+                    enabled: ws.enabled,
+                    mdkg_dir: ws.mdkg_dir,
+                };
+            }),
+        }, null, 2));
+        return;
+    }
     if (aliases.length === 0) {
         console.log("no workspaces registered");
         return;
@@ -57,11 +107,11 @@ function runWorkspaceListCommand(options) {
 }
 function runWorkspaceAddCommand(options) {
     const alias = normalizeAlias(options.alias);
-    const workspacePath = options.workspacePath.trim();
-    if (!workspacePath) {
-        throw new errors_1.UsageError("workspace path cannot be empty");
+    const workspacePath = normalizeCommandWorkspacePath(options.workspacePath, "workspace path");
+    const mdkgDir = normalizeCommandWorkspacePath(options.mdkgDir ?? ".mdkg", "workspace mdkg dir");
+    if ((0, workspace_path_1.isRootWorkspacePath)(workspacePath)) {
+        throw new errors_1.UsageError('workspace path must not be "." for non-root workspaces');
     }
-    const mdkgDir = options.mdkgDir?.trim() || ".mdkg";
     const { path: configPath, raw } = readRawConfig(options.root);
     const workspacesRaw = raw.workspaces;
     if (typeof workspacesRaw !== "object" || workspacesRaw === null) {
@@ -71,14 +121,27 @@ function runWorkspaceAddCommand(options) {
     if (workspaces[alias]) {
         throw new errors_1.UsageError(`workspace already exists: ${alias}`);
     }
-    workspaces[alias] = { path: workspacePath, enabled: true, mdkg_dir: mdkgDir };
+    const docRootKey = (0, workspace_path_1.workspaceDocumentRootKey)(workspacePath, mdkgDir);
+    for (const [existingAlias, entry] of Object.entries(workspaces)) {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            continue;
+        }
+        const existing = entry;
+        if (typeof existing.path === "string" &&
+            typeof existing.mdkg_dir === "string" &&
+            (0, workspace_path_1.workspaceDocumentRootKey)(existing.path, existing.mdkg_dir) === docRootKey) {
+            throw new errors_1.UsageError(`workspace document root already registered by ${existingAlias}`);
+        }
+    }
+    const workspace = { path: workspacePath, enabled: true, mdkg_dir: mdkgDir };
+    workspaces[alias] = workspace;
     raw.workspaces = workspaces;
     writeRawConfig(configPath, raw);
     const wsRoot = path_1.default.resolve(options.root, workspacePath, mdkgDir);
     fs_1.default.mkdirSync(path_1.default.join(wsRoot, "core"), { recursive: true });
     fs_1.default.mkdirSync(path_1.default.join(wsRoot, "design"), { recursive: true });
     fs_1.default.mkdirSync(path_1.default.join(wsRoot, "work"), { recursive: true });
-    console.log(`workspace added: ${alias} (${workspacePath})`);
+    printWorkspaceMutationReceipt("added", workspaceReceipt(alias, workspace), options.json);
 }
 function runWorkspaceRemoveCommand(options) {
     const alias = normalizeAlias(options.alias);
@@ -91,11 +154,40 @@ function runWorkspaceRemoveCommand(options) {
         throw new errors_1.UsageError("config.workspaces must be an object");
     }
     const workspaces = workspacesRaw;
-    if (!workspaces[alias]) {
+    const workspace = workspaces[alias];
+    if (!workspace || typeof workspace !== "object" || Array.isArray(workspace)) {
         throw new errors_1.NotFoundError(`workspace not found: ${alias}`);
     }
+    const removed = workspaceReceipt(alias, workspace);
     delete workspaces[alias];
     raw.workspaces = workspaces;
     writeRawConfig(configPath, raw);
-    console.log(`workspace removed: ${alias}`);
+    printWorkspaceMutationReceipt("removed", removed, options.json);
+}
+function setWorkspaceEnabled(options, enabled) {
+    const alias = normalizeAlias(options.alias);
+    if (alias === "root" && !enabled) {
+        throw new errors_1.UsageError("cannot disable root workspace");
+    }
+    const { path: configPath, raw } = readRawConfig(options.root);
+    const workspacesRaw = raw.workspaces;
+    if (typeof workspacesRaw !== "object" || workspacesRaw === null) {
+        throw new errors_1.UsageError("config.workspaces must be an object");
+    }
+    const workspaces = workspacesRaw;
+    const workspace = workspaces[alias];
+    if (!workspace || typeof workspace !== "object" || Array.isArray(workspace)) {
+        throw new errors_1.NotFoundError(`workspace not found: ${alias}`);
+    }
+    const updated = { ...workspace, enabled };
+    workspaces[alias] = updated;
+    raw.workspaces = workspaces;
+    writeRawConfig(configPath, raw);
+    printWorkspaceMutationReceipt(enabled ? "enabled" : "disabled", workspaceReceipt(alias, updated), options.json);
+}
+function runWorkspaceEnableCommand(options) {
+    setWorkspaceEnabled(options, true);
+}
+function runWorkspaceDisableCommand(options) {
+    setWorkspaceEnabled(options, false);
 }