mdkg 0.0.9 → 0.1.1

package/dist/commands/upgrade.js

@@ -0,0 +1,401 @@
+"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 child_process_1 = require("child_process");
+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;
+        case "skip":
+            summary.skipped += 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 isIgnoredBySimpleGitignore(root, relativePath) {
+    const ignorePath = path_1.default.join(root, ".gitignore");
+    if (!fs_1.default.existsSync(ignorePath)) {
+        return false;
+    }
+    const normalized = relativePath.replace(/\\/g, "/");
+    const lines = fs_1.default.readFileSync(ignorePath, "utf8").split(/\r?\n/);
+    let ignored = false;
+    for (const rawLine of lines) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#")) {
+            continue;
+        }
+        const negated = line.startsWith("!");
+        const pattern = negated ? line.slice(1) : line;
+        const normalizedPattern = pattern.replace(/\\/g, "/").replace(/^\/+/, "");
+        const matches = normalizedPattern === normalized ||
+            (normalizedPattern.endsWith("/") && normalized.startsWith(normalizedPattern)) ||
+            (normalizedPattern.endsWith("/*") && normalized.startsWith(normalizedPattern.slice(0, -1)));
+        if (matches) {
+            ignored = !negated;
+        }
+    }
+    return ignored;
+}
+function isGitIgnored(root, relativePath) {
+    const result = (0, child_process_1.spawnSync)("git", ["check-ignore", "--quiet", "--", relativePath], {
+        cwd: root,
+        stdio: "ignore",
+    });
+    if (result.status === 0) {
+        return true;
+    }
+    if (result.status === 1) {
+        return false;
+    }
+    return isIgnoredBySimpleGitignore(root, relativePath);
+}
+function ensureAgentRuntimeFiles(root, dryRun, summary, changes) {
+    const eventsPath = path_1.default.join(root, ".mdkg", "work", "events", "events.jsonl");
+    const relEventsPath = ".mdkg/work/events/events.jsonl";
+    if (!fs_1.default.existsSync(eventsPath)) {
+        if (isGitIgnored(root, relEventsPath)) {
+            record(summary, changes, {
+                path: relEventsPath,
+                category: "event_log",
+                action: "skip",
+                reason: "event log path is ignored; run `mdkg event enable` if local event provenance should be restored",
+            });
+            return;
+        }
+        record(summary, changes, {
+            path: relEventsPath,
+            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 isWritableChange(change) {
+    return change.action === "create" || change.action === "update" || change.action === "migrate" || change.action === "sync";
+}
+function buildApplySideEffects(options) {
+    const hasDirectWrites = options.changes.some(isWritableChange);
+    if (!hasDirectWrites && options.existingManifest) {
+        return [];
+    }
+    const effects = [
+        {
+            path: ".mdkg/init-manifest.json",
+            category: "init_manifest",
+            action: options.existingManifest ? "update" : "create",
+            reason: "records managed init asset fingerprints after apply",
+        },
+    ];
+    if (options.agentWorkspace) {
+        effects.push({
+            path: ".mdkg/skills/registry.md",
+            category: "skill_registry",
+            action: "update",
+            reason: "refreshes canonical skill registry after apply",
+        }, {
+            path: ".agents/skills,.claude/skills",
+            category: "skill_mirror",
+            action: "sync",
+            reason: "syncs managed skill mirrors after apply",
+        });
+    }
+    return effects;
+}
+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`);
+    console.log(`safe to apply: ${receipt.safe_to_apply ? "yes" : "no"}`);
+    if (receipt.will_write_paths.length > 0) {
+        console.log(`will write: ${receipt.will_write_paths.join(", ")}`);
+    }
+    if (receipt.preserved_customizations.length > 0) {
+        console.log(`preserved customizations: ${receipt.preserved_customizations.length}`);
+    }
+    if (receipt.blocking_conflicts.length > 0) {
+        console.log(`blocking conflicts: ${receipt.blocking_conflicts.length}`);
+    }
+    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.apply_side_effects.length > 0) {
+        for (const effect of receipt.apply_side_effects) {
+            console.log(`  apply-side-effect: ${effect.path} (${effect.reason})`);
+        }
+    }
+    if (receipt.dry_run && receipt.will_write_paths.length > 0) {
+        if (receipt.safe_to_apply) {
+            console.log("next: mdkg upgrade --apply (writes only safe managed paths; preserves customized files)");
+        }
+        else {
+            console.log("next: resolve blocking conflicts before running 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);
+    }
+    const applySideEffects = buildApplySideEffects({
+        existingManifest,
+        agentWorkspace,
+        changes,
+    });
+    for (const effect of applySideEffects) {
+        record(summary, changes, effect);
+    }
+    if (!dryRun) {
+        const appliedManifest = {
+            ...currentManifest,
+            files: managedCurrentFiles.sort((a, b) => a.path.localeCompare(b.path)),
+        };
+        if (applySideEffects.length > 0) {
+            (0, init_manifest_1.writeInitManifest)(path_1.default.join(root, ".mdkg", init_manifest_1.INIT_MANIFEST_FILE), appliedManifest);
+        }
+        if (agentWorkspace && applySideEffects.length > 0) {
+            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);
+            (0, skill_mirror_1.syncSkillMirrors)({ root, config, createRoots: true });
+        }
+    }
+    const preservedCustomizations = changes.filter((change) => change.action === "conflict");
+    const blockingConflicts = [];
+    const willWritePaths = changes.filter(isWritableChange).map((change) => change.path);
+    const receipt = {
+        action: "upgrade",
+        dry_run: dryRun,
+        version,
+        safe_to_apply: blockingConflicts.length === 0,
+        summary,
+        will_write_paths: Array.from(new Set(willWritePaths)),
+        preserved_customizations: preservedCustomizations,
+        blocking_conflicts: blockingConflicts,
+        apply_side_effects: applySideEffects,
+        changes,
+    };
+    if (options.json) {
+        console.log(`${JSON.stringify(receipt, null, 2)}`);
+    }
+    else {
+        emitHumanReceipt(receipt);
+    }
+    return receipt;
+}

package/dist/commands/validate.js

@@ -200,10 +200,14 @@ function validateEventsJsonl(root, config, errors) {
 }
 function runValidateCommand(options) {
     const config = (0, config_1.loadConfig)(options.root);
-    const templateSchemas = (0, template_schema_1.loadTemplateSchemas)(options.root, config, node_1.ALLOWED_TYPES);
+    const templateSchemaInfo = (0, template_schema_1.loadTemplateSchemasWithInfo)(options.root, config, node_1.ALLOWED_TYPES);
+    const templateSchemas = templateSchemaInfo.schemas;
     const filesByAlias = (0, workspace_files_1.listWorkspaceDocFilesByAlias)(options.root, config);
     const errors = [];
     const warnings = [];
+    if (templateSchemaInfo.fallbackTypes.length > 0) {
+        warnings.push(`using bundled template schema fallback for missing local type(s): ${templateSchemaInfo.fallbackTypes.join(", ")}; run \`mdkg upgrade --apply\` to vendor built-in templates`);
+    }
     const nodes = {};
     const idsByWorkspace = {};
     for (const [alias, files] of Object.entries(filesByAlias)) {

package/dist/core/version.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readPackageVersion = readPackageVersion;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function readPackageVersion(startDir = __dirname) {
+    let current = path_1.default.resolve(startDir);
+    for (let i = 0; i < 5; i += 1) {
+        const packagePath = path_1.default.join(current, "package.json");
+        if (fs_1.default.existsSync(packagePath)) {
+            try {
+                const raw = JSON.parse(fs_1.default.readFileSync(packagePath, "utf8"));
+                if (raw.name === "mdkg" && typeof raw.version === "string" && raw.version.trim().length > 0) {
+                    return raw.version;
+                }
+            }
+            catch {
+                return "unknown";
+            }
+        }
+        const parent = path_1.default.dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return "unknown";
+}

package/dist/graph/template_schema.js

@@ -4,9 +4,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadTemplateSchemas = loadTemplateSchemas;
+exports.loadTemplateSchemasWithInfo = loadTemplateSchemasWithInfo;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const frontmatter_1 = require("./frontmatter");
+const builtin_1 = require("../templates/builtin");
 function listMarkdownFiles(dir) {
     if (!fs_1.default.existsSync(dir)) {
         return [];
@@ -45,9 +47,12 @@ function addKeyToSchema(schema, key, kind, filePath) {
     }
 }
 function loadTemplateSchemas(root, config, requiredTypes) {
+    return loadTemplateSchemasWithInfo(root, config, requiredTypes).schemas;
+}
+function loadTemplateSchemasWithInfo(root, config, requiredTypes) {
     const templateRoot = path_1.default.resolve(root, config.templates.root_path, config.templates.default_set);
     const files = listMarkdownFiles(templateRoot);
-    if (files.length === 0) {
+    if (files.length === 0 && !requiredTypes) {
         throw new Error(`no templates found at ${templateRoot}`);
     }
     const schemas = {};
@@ -75,12 +80,35 @@ function loadTemplateSchemas(root, config, requiredTypes) {
             addKeyToSchema(schema, key, kind, filePath);
         }
     }
+    const fallbackTypes = [];
     if (requiredTypes) {
         const required = Array.from(requiredTypes, (value) => value.toLowerCase());
-        const missing = required.filter((value) => !schemas[value]);
-        if (missing.length > 0) {
-            throw new Error(`template schema missing for type(s): ${missing.join(", ")}`);
+        for (const missingType of required.filter((value) => !schemas[value])) {
+            const bundledPath = (0, builtin_1.requireBundledTemplatePath)(missingType);
+            const content = fs_1.default.readFileSync(bundledPath, "utf8");
+            const { frontmatter } = (0, frontmatter_1.parseFrontmatter)(content, bundledPath);
+            const typeValue = frontmatter.type;
+            if (typeValue !== missingType) {
+                throw new Error(`bundled template fallback type mismatch for ${missingType}: ${bundledPath}`);
+            }
+            const schema = {
+                type: missingType,
+                allowedKeys: new Set(),
+                keyKinds: {},
+                listKeys: new Set(),
+            };
+            schemas[missingType] = schema;
+            for (const [key, value] of Object.entries(frontmatter)) {
+                const kind = getValueKind(value);
+                addKeyToSchema(schema, key, kind, bundledPath);
+            }
+            fallbackTypes.push(missingType);
         }
     }
-    return schemas;
+    return {
+        schemas,
+        templateRoot,
+        bundledTemplateRoot: (0, builtin_1.resolveBundledTemplateRoot)(),
+        fallbackTypes,
+    };
 }

package/dist/init/AGENT_START.md

@@ -23,6 +23,7 @@ Agent operating prompt:
 - Use `mdkg search "..."` and `mdkg next` to discover current work.
 - Use `mdkg skill list`, `mdkg skill search`, and `mdkg skill show <slug>` for skill discovery.
 - Use `mdkg task start/update/done` for structured task, bug, and test lifecycle fields.
+- Use `mdkg upgrade` to preview scaffold updates; only run `mdkg upgrade --apply` after reviewing the receipt.
 - Keep nuanced summaries, body text, and manual parent closeout edits in markdown.
 - Use `mdkg event enable` only if `events.jsonl` is missing and provenance should be restored.
 - Use `CLI_COMMAND_MATRIX.md` for the canonical command and flag surface.

package/dist/init/CLI_COMMAND_MATRIX.md

@@ -8,6 +8,7 @@ Verify live help with:
 
 Primary commands:
 - `mdkg init`
+- `mdkg upgrade [--dry-run] [--apply] [--json]`
 - `mdkg new`
 - `mdkg show`
 - `mdkg list`
@@ -64,6 +65,13 @@ Agent bootstrap:
 - `mdkg init --llm --agent`
 - published bootstrap config is root-only by default
 
+Upgrade:
+- `mdkg upgrade` previews safe scaffold updates and writes nothing by default
+- `mdkg upgrade --apply` updates only managed or unchanged init assets
+- JSON receipts include `safe_to_apply`, `will_write_paths`, `preserved_customizations`, `blocking_conflicts`, and `apply_side_effects`
+- customized docs, templates, skills, and core files are preserved and reported
+- ignored event logs are skipped with guidance to run `mdkg event enable`
+
 Skill discovery:
 - `mdkg skill list --tags stage:plan --json`
 - `mdkg skill search "<query>" --json`

package/dist/init/README.md

@@ -15,6 +15,7 @@ This repository is initialized for mdkg.
 
 ```bash
 mdkg init --llm --agent
+mdkg upgrade
 mdkg search "..."
 mdkg show <id>
 mdkg pack <id>
@@ -50,3 +51,9 @@ Recommended:
 ```bash
 mdkg init --update-gitignore --update-npmignore
 ```
+
+## Upgrade
+
+`mdkg upgrade` previews safe scaffold updates for existing workspaces and writes nothing by default.
+
+Use `mdkg upgrade --apply` only after reviewing `safe_to_apply`, `will_write_paths`, and `apply_side_effects` in the receipt. Local customizations are preserved and reported instead of overwritten. Missing built-in templates can be loaded from the installed package as a read-only fallback until you vendor them with upgrade.

package/dist/init/core/rule-6-templates-and-schemas.md

@@ -187,4 +187,6 @@ Body headings are strongly recommended for agent usability but should not be har
 - Node -> skill references in `skills: [...]` are validated against `.mdkg/skills/<slug>/SKILL.md`.
 - `.mdkg/work/events/events.jsonl` is optional; when present, records are schema-validated by `mdkg validate`.
 - If a template is missing:
-  - `mdkg new` must fail with a helpful error (exit code 3).
+  - built-in mdkg node types may use the installed package's bundled default template as a read-only schema fallback.
+  - commands should warn when bundled fallback is used and recommend `mdkg upgrade --apply` to vendor missing templates.
+  - missing non-built-in templates or missing packaged fallback assets must fail with a helpful error.