mdkg 0.0.1 → 0.0.2

package/dist/commands/checkpoint.js

@@ -0,0 +1,133 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCheckpointNewCommand = runCheckpointNewCommand;
+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 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]+$/;
+function parseCsvList(raw) {
+    if (!raw) {
+        return [];
+    }
+    return raw
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean);
+}
+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}`);
+    }
+    return normalized;
+}
+function normalizeIdRef(value, key) {
+    const normalized = value.toLowerCase();
+    if (!ID_REF_RE.test(normalized)) {
+        throw new errors_1.UsageError(`${key} entries must match <id> or <ws>:<id>: ${value}`);
+    }
+    return normalized;
+}
+function nextCheckpointId(index, ws) {
+    let max = 0;
+    for (const node of Object.values(index.nodes)) {
+        if (node.ws !== ws) {
+            continue;
+        }
+        const match = /^chk-(\d+)$/.exec(node.id);
+        if (!match) {
+            continue;
+        }
+        const parsed = Number.parseInt(match[1] ?? "", 10);
+        if (Number.isInteger(parsed) && parsed > max) {
+            max = parsed;
+        }
+    }
+    return `chk-${max + 1}`;
+}
+function slugifyTitle(title) {
+    const slug = title
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/-+/g, "-");
+    if (!slug) {
+        return "checkpoint";
+    }
+    const maxLen = 80;
+    return slug.length > maxLen ? slug.slice(0, maxLen).replace(/-+$/g, "") : slug;
+}
+function normalizeWorkspace(value) {
+    if (!value) {
+        return "root";
+    }
+    const normalized = value.toLowerCase();
+    if (normalized === "all") {
+        throw new errors_1.UsageError("--ws all is not valid for checkpoint creation");
+    }
+    return normalized;
+}
+function runCheckpointNewCommand(options) {
+    const title = options.title.trim();
+    if (!title) {
+        throw new errors_1.UsageError("checkpoint title cannot be empty");
+    }
+    const config = (0, config_1.loadConfig)(options.root);
+    const ws = normalizeWorkspace(options.ws);
+    if (!config.workspaces[ws]) {
+        throw new errors_1.NotFoundError(`workspace not found: ${ws}`);
+    }
+    const status = (options.status ?? "backlog").toLowerCase();
+    const allowedStatuses = new Set(config.work.status_enum.map((value) => value.toLowerCase()));
+    if (!allowedStatuses.has(status)) {
+        throw new errors_1.UsageError(`--status must be one of ${Array.from(allowedStatuses).join(", ")}`);
+    }
+    const priorityMin = config.work.priority_min;
+    const priorityMax = config.work.priority_max;
+    const priority = options.priority ?? priorityMax;
+    if (!Number.isInteger(priority) || priority < priorityMin || priority > priorityMax) {
+        throw new errors_1.UsageError(`--priority must be between ${priorityMin} and ${priorityMax}`);
+    }
+    const { index } = (0, index_cache_1.loadIndex)({ root: options.root, config });
+    const id = nextCheckpointId(index, ws);
+    const slug = slugifyTitle(title);
+    const fileName = `${id}-${slug}.md`;
+    const wsEntry = config.workspaces[ws];
+    const workDir = path_1.default.resolve(options.root, wsEntry.path, wsEntry.mdkg_dir, "work");
+    const filePath = path_1.default.join(workDir, fileName);
+    if (fs_1.default.existsSync(filePath)) {
+        throw new errors_1.UsageError(`checkpoint file already exists: ${path_1.default.relative(options.root, filePath)}`);
+    }
+    const relates = parseCsvList(options.relates).map((value) => normalizeIdRef(value, "--relates"));
+    for (const target of relates) {
+        const qid = target.includes(":") ? target : `${ws}:${target}`;
+        if (!index.nodes[qid]) {
+            throw new errors_1.NotFoundError(`related node not found: ${target}`);
+        }
+    }
+    const scope = parseCsvList(options.scope).map((value) => normalizeId(value, "--scope"));
+    const today = (0, date_1.formatDate)(new Date());
+    const template = (0, loader_1.loadTemplate)(options.root, config, "checkpoint", options.template);
+    const content = (0, loader_1.renderTemplate)(template, {
+        id,
+        title,
+        status,
+        priority,
+        created: today,
+        updated: today,
+        relates,
+        scope,
+    });
+    fs_1.default.mkdirSync(workDir, { recursive: true });
+    fs_1.default.writeFileSync(filePath, content, "utf8");
+    console.log(`checkpoint created: ${ws}:${id} (${path_1.default.relative(options.root, filePath)})`);
+}

package/dist/commands/format.js

@@ -0,0 +1,297 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFormatCommand = runFormatCommand;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const config_1 = require("../core/config");
+const frontmatter_1 = require("../graph/frontmatter");
+const template_schema_1 = require("../graph/template_schema");
+const node_1 = require("../graph/node");
+const 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 DEC_ID_RE = /^dec-[0-9]+$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const ID_LIST_KEYS = new Set(["refs", "scope"]);
+const ID_REF_LIST_KEYS = new Set(["relates", "blocked_by", "blocks"]);
+const ID_REF_SCALAR_KEYS = new Set(["epic", "parent", "prev", "next"]);
+const PRESERVE_CASE_LIST_KEYS = new Set(["links", "artifacts"]);
+function isValidId(value) {
+    return ID_RE.test(value) || value === "rule-guide";
+}
+function isCoreListFile(filePath) {
+    return path_1.default.basename(filePath) === "core.md" && path_1.default.basename(path_1.default.dirname(filePath)) === "core";
+}
+function normalizeScalar(value) {
+    return value.trim();
+}
+function sortList(values) {
+    return values.slice().sort((a, b) => {
+        const aLower = a.toLowerCase();
+        const bLower = b.toLowerCase();
+        if (aLower < bLower) {
+            return -1;
+        }
+        if (aLower > bLower) {
+            return 1;
+        }
+        if (a < b) {
+            return -1;
+        }
+        if (a > b) {
+            return 1;
+        }
+        return 0;
+    });
+}
+function normalizeList(values, key, errors, filePath) {
+    const trimmed = values.map((value) => normalizeScalar(value));
+    const shouldLowercase = !PRESERVE_CASE_LIST_KEYS.has(key);
+    const normalized = shouldLowercase ? trimmed.map((value) => value.toLowerCase()) : trimmed;
+    for (const entry of normalized) {
+        if (!entry) {
+            errors.push(`${filePath}: ${key} entries must be non-empty`);
+            continue;
+        }
+        if (ID_LIST_KEYS.has(key) && !isValidId(entry)) {
+            errors.push(`${filePath}: ${key} entries must match <prefix>-<number>`);
+        }
+        if (ID_REF_LIST_KEYS.has(key) && !ID_REF_RE.test(entry)) {
+            errors.push(`${filePath}: ${key} entries must be valid id references`);
+        }
+    }
+    return sortList(normalized);
+}
+function normalizeIdRef(value, key, errors, filePath) {
+    const normalized = normalizeScalar(value).toLowerCase();
+    if (!ID_REF_RE.test(normalized)) {
+        errors.push(`${filePath}: ${key} must be a valid id reference`);
+    }
+    return normalized;
+}
+function normalizeFrontmatterValue(key, value, schema, errors, filePath) {
+    const expected = schema.keyKinds[key];
+    if (expected === "list") {
+        if (!Array.isArray(value)) {
+            errors.push(`${filePath}: ${key} must be a list`);
+            return [];
+        }
+        return normalizeList(value, key, errors, filePath);
+    }
+    if (expected === "boolean") {
+        if (typeof value !== "boolean") {
+            errors.push(`${filePath}: ${key} must be a boolean`);
+            return value;
+        }
+        return value;
+    }
+    if (Array.isArray(value) || typeof value === "boolean") {
+        errors.push(`${filePath}: ${key} must be a string`);
+        return value;
+    }
+    return normalizeScalar(value);
+}
+function normalizeFrontmatter(frontmatter, schema, type, workStatusEnum, priorityMin, priorityMax, filePath) {
+    const errors = [];
+    const normalized = {};
+    for (const key of Object.keys(frontmatter)) {
+        if (!schema.allowedKeys.has(key)) {
+            errors.push(`${filePath}: unknown key: ${key}`);
+        }
+    }
+    for (const key of schema.allowedKeys) {
+        const value = frontmatter[key];
+        if (value === undefined) {
+            if (schema.listKeys.has(key)) {
+                normalized[key] = [];
+            }
+            continue;
+        }
+        const normalizedValue = normalizeFrontmatterValue(key, value, schema, errors, filePath);
+        if (normalizedValue !== undefined) {
+            normalized[key] = normalizedValue;
+        }
+    }
+    const idValue = normalized.id;
+    if (typeof idValue !== "string") {
+        errors.push(`${filePath}: id is required`);
+    }
+    else {
+        const normalizedId = idValue.toLowerCase();
+        if (!isValidId(normalizedId)) {
+            errors.push(`${filePath}: id must match <prefix>-<number>`);
+        }
+        normalized.id = normalizedId;
+    }
+    normalized.type = type;
+    if (typeof normalized.title !== "string" || normalized.title.trim().length === 0) {
+        errors.push(`${filePath}: title is required`);
+    }
+    const createdValue = normalized.created;
+    if (typeof createdValue !== "string") {
+        errors.push(`${filePath}: created is required`);
+    }
+    else if (!DATE_RE.test(createdValue)) {
+        errors.push(`${filePath}: created must be YYYY-MM-DD`);
+    }
+    const updatedValue = normalized.updated;
+    if (typeof updatedValue !== "string") {
+        errors.push(`${filePath}: updated is required`);
+    }
+    else if (!DATE_RE.test(updatedValue)) {
+        errors.push(`${filePath}: updated must be YYYY-MM-DD`);
+    }
+    if (node_1.WORK_TYPES.has(type)) {
+        const statusValue = normalized.status;
+        if (typeof statusValue !== "string") {
+            errors.push(`${filePath}: status is required for work items`);
+        }
+        else {
+            const normalizedStatus = statusValue.toLowerCase();
+            const allowed = new Set(workStatusEnum.map((value) => value.toLowerCase()));
+            if (!allowed.has(normalizedStatus)) {
+                errors.push(`${filePath}: status must be one of ${Array.from(allowed).join(", ")}`);
+            }
+            normalized.status = normalizedStatus;
+        }
+    }
+    else if (node_1.DEC_TYPES.has(type)) {
+        const statusValue = normalized.status;
+        if (typeof statusValue !== "string") {
+            errors.push(`${filePath}: status is required for decision records`);
+        }
+        else {
+            const normalizedStatus = statusValue.toLowerCase();
+            if (!["proposed", "accepted", "rejected", "superseded"].includes(normalizedStatus)) {
+                errors.push(`${filePath}: status must be one of proposed, accepted, rejected, superseded`);
+            }
+            normalized.status = normalizedStatus;
+        }
+    }
+    if (normalized.priority !== undefined) {
+        const priorityValue = normalized.priority;
+        if (typeof priorityValue !== "string") {
+            errors.push(`${filePath}: priority must be an integer`);
+        }
+        else {
+            const parsed = Number.parseInt(priorityValue, 10);
+            if (!Number.isInteger(parsed)) {
+                errors.push(`${filePath}: priority must be an integer`);
+            }
+            else if (parsed < priorityMin || parsed > priorityMax) {
+                errors.push(`${filePath}: priority must be between ${priorityMin} and ${priorityMax}`);
+            }
+            else {
+                normalized.priority = String(parsed);
+            }
+        }
+    }
+    if (normalized.priority !== undefined && !node_1.WORK_TYPES.has(type)) {
+        errors.push(`${filePath}: priority is only allowed for work items`);
+    }
+    for (const key of ID_REF_SCALAR_KEYS) {
+        const value = normalized[key];
+        if (typeof value === "string") {
+            normalized[key] = normalizeIdRef(value, key, errors, filePath);
+        }
+    }
+    if (typeof normalized.supersedes === "string") {
+        const normalizedValue = normalizeScalar(normalized.supersedes).toLowerCase();
+        if (!DEC_ID_RE.test(normalizedValue)) {
+            errors.push(`${filePath}: supersedes must be a dec-# id`);
+        }
+        normalized.supersedes = normalizedValue;
+    }
+    if (normalized.supersedes !== undefined && !node_1.DEC_TYPES.has(type)) {
+        errors.push(`${filePath}: supersedes is only allowed for decision records`);
+    }
+    if (!node_1.WORK_TYPES.has(type) && !node_1.DEC_TYPES.has(type) && normalized.status !== undefined) {
+        errors.push(`${filePath}: status is not allowed for this type`);
+    }
+    return { normalized, errors };
+}
+function runFormatCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const templateSchemas = (0, template_schema_1.loadTemplateSchemas)(options.root, config, node_1.ALLOWED_TYPES);
+    const filesByAlias = (0, workspace_files_1.listWorkspaceDocFilesByAlias)(options.root, config);
+    const today = (0, date_1.formatDate)(options.now ?? new Date());
+    const errors = [];
+    const updates = [];
+    for (const files of Object.values(filesByAlias)) {
+        for (const filePath of files) {
+            if (isCoreListFile(filePath)) {
+                continue;
+            }
+            let content = "";
+            try {
+                content = fs_1.default.readFileSync(filePath, "utf8");
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : "unknown error";
+                errors.push(`${filePath}: failed to read file: ${message}`);
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = (0, frontmatter_1.parseFrontmatter)(content, filePath);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : "unknown error";
+                errors.push(message);
+                continue;
+            }
+            const typeValue = parsed.frontmatter.type;
+            if (typeof typeValue !== "string") {
+                errors.push(`${filePath}: type is required`);
+                continue;
+            }
+            const type = typeValue.toLowerCase();
+            if (!node_1.ALLOWED_TYPES.has(type)) {
+                errors.push(`${filePath}: type must be one of ${Array.from(node_1.ALLOWED_TYPES).join(", ")}`);
+                continue;
+            }
+            const schema = templateSchemas[type];
+            if (!schema) {
+                errors.push(`${filePath}: template schema missing for type ${type}`);
+                continue;
+            }
+            const { normalized, errors: fmErrors } = normalizeFrontmatter(parsed.frontmatter, schema, type, config.work.status_enum, config.work.priority_min, config.work.priority_max, filePath);
+            if (fmErrors.length > 0) {
+                errors.push(...fmErrors);
+                continue;
+            }
+            const keepTrailingNewline = content.endsWith("\n");
+            const frontmatterLines = (0, frontmatter_1.formatFrontmatter)(normalized, frontmatter_1.DEFAULT_FRONTMATTER_KEY_ORDER);
+            const frontmatterBlock = ["---", ...frontmatterLines, "---"].join("\n");
+            let formattedContent = parsed.body.length > 0 ? `${frontmatterBlock}\n${parsed.body}` : frontmatterBlock;
+            if (keepTrailingNewline && !formattedContent.endsWith("\n")) {
+                formattedContent = `${formattedContent}\n`;
+            }
+            if (formattedContent !== content) {
+                normalized.updated = today;
+                const updatedLines = (0, frontmatter_1.formatFrontmatter)(normalized, frontmatter_1.DEFAULT_FRONTMATTER_KEY_ORDER);
+                const updatedBlock = ["---", ...updatedLines, "---"].join("\n");
+                let updatedContent = parsed.body.length > 0 ? `${updatedBlock}\n${parsed.body}` : updatedBlock;
+                if (keepTrailingNewline && !updatedContent.endsWith("\n")) {
+                    updatedContent = `${updatedContent}\n`;
+                }
+                updates.push({ filePath, content: updatedContent });
+            }
+        }
+    }
+    if (errors.length > 0) {
+        for (const error of errors) {
+            console.error(error);
+        }
+        throw new errors_1.ValidationError(`format failed with ${errors.length} error(s)`);
+    }
+    for (const update of updates) {
+        fs_1.default.writeFileSync(update.filePath, update.content, "utf8");
+    }
+    console.log(`format updated ${updates.length} file(s)`);
+}

package/dist/commands/guide.js

@@ -0,0 +1,22 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runGuideCommand = runGuideCommand;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const errors_1 = require("../util/errors");
+function runGuideCommand(options) {
+    const guidePath = path_1.default.join(options.root, ".mdkg", "core", "guide.md");
+    if (!fs_1.default.existsSync(guidePath)) {
+        throw new errors_1.NotFoundError(`guide not found: ${guidePath}`);
+    }
+    const content = fs_1.default.readFileSync(guidePath, "utf8");
+    const trimmed = content.trimEnd();
+    if (trimmed.length === 0) {
+        console.log("");
+        return;
+    }
+    console.log(trimmed);
+}

package/dist/commands/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runIndexCommand = runIndexCommand;
+const path_1 = __importDefault(require("path"));
+const config_1 = require("../core/config");
+const indexer_1 = require("../graph/indexer");
+const index_cache_1 = require("../graph/index_cache");
+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)}`);
+}

package/dist/commands/init.js

@@ -0,0 +1,111 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInitCommand = runInitCommand;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const errors_1 = require("../util/errors");
+const DEFAULT_SEED_SUBDIR = path_1.default.resolve(__dirname, "..", "init");
+function listFiles(dir) {
+    if (!fs_1.default.existsSync(dir)) {
+        return [];
+    }
+    const entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path_1.default.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...listFiles(fullPath));
+        }
+        else if (entry.isFile()) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+function copySeedFile(src, dest, force, stats) {
+    if (fs_1.default.existsSync(dest) && !force) {
+        stats.skipped += 1;
+        return;
+    }
+    fs_1.default.mkdirSync(path_1.default.dirname(dest), { recursive: true });
+    fs_1.default.copyFileSync(src, dest);
+    stats.created += 1;
+}
+function copySeedDir(srcDir, destDir, force, stats) {
+    if (!fs_1.default.existsSync(srcDir)) {
+        return;
+    }
+    const files = listFiles(srcDir);
+    for (const filePath of files) {
+        const relPath = path_1.default.relative(srcDir, filePath);
+        const destPath = path_1.default.join(destDir, relPath);
+        copySeedFile(filePath, destPath, force, stats);
+    }
+}
+function appendIgnoreEntries(filePath, entries) {
+    const raw = fs_1.default.existsSync(filePath) ? fs_1.default.readFileSync(filePath, "utf8") : "";
+    const lines = raw.split(/\r?\n/);
+    const existing = new Set(lines.map((line) => line.trim()).filter(Boolean));
+    const additions = entries.filter((entry) => !existing.has(entry));
+    if (additions.length === 0) {
+        return false;
+    }
+    const suffix = raw.length === 0 || raw.endsWith("\n") ? "" : "\n";
+    const updated = `${raw}${suffix}${additions.join("\n")}\n`;
+    fs_1.default.mkdirSync(path_1.default.dirname(filePath), { recursive: true });
+    fs_1.default.writeFileSync(filePath, updated, "utf8");
+    return true;
+}
+function runInitCommand(options) {
+    const root = path_1.default.resolve(options.root);
+    const seedRoot = options.seedRoot ? path_1.default.resolve(options.seedRoot) : DEFAULT_SEED_SUBDIR;
+    const createAgents = Boolean(options.createAgents || options.createLlm);
+    const createClaude = Boolean(options.createClaude || options.createLlm);
+    const seedConfig = path_1.default.join(seedRoot, "config.json");
+    const seedCore = path_1.default.join(seedRoot, "core");
+    const seedTemplates = path_1.default.join(seedRoot, "templates");
+    const seedAgents = path_1.default.join(seedRoot, "AGENTS.md");
+    const seedClaude = path_1.default.join(seedRoot, "CLAUDE.md");
+    if (!fs_1.default.existsSync(seedConfig) || !fs_1.default.existsSync(seedCore) || !fs_1.default.existsSync(seedTemplates)) {
+        throw new errors_1.NotFoundError(`init assets not found at ${seedRoot} (try reinstalling mdkg)`);
+    }
+    if (createAgents && !fs_1.default.existsSync(seedAgents)) {
+        throw new errors_1.NotFoundError(`init assets missing AGENTS.md at ${seedRoot}`);
+    }
+    if (createClaude && !fs_1.default.existsSync(seedClaude)) {
+        throw new errors_1.NotFoundError(`init assets missing CLAUDE.md at ${seedRoot}`);
+    }
+    const mdkgDir = path_1.default.join(root, ".mdkg");
+    fs_1.default.mkdirSync(mdkgDir, { recursive: true });
+    fs_1.default.mkdirSync(path_1.default.join(mdkgDir, "work"), { recursive: true });
+    fs_1.default.mkdirSync(path_1.default.join(mdkgDir, "design"), { recursive: true });
+    const stats = { created: 0, skipped: 0 };
+    copySeedFile(seedConfig, path_1.default.join(mdkgDir, "config.json"), Boolean(options.force), stats);
+    copySeedDir(seedCore, path_1.default.join(mdkgDir, "core"), Boolean(options.force), stats);
+    copySeedDir(seedTemplates, path_1.default.join(mdkgDir, "templates"), Boolean(options.force), stats);
+    if (createAgents) {
+        copySeedFile(seedAgents, path_1.default.join(root, "AGENTS.md"), Boolean(options.force), stats);
+    }
+    if (createClaude) {
+        copySeedFile(seedClaude, path_1.default.join(root, "CLAUDE.md"), Boolean(options.force), stats);
+    }
+    if (options.updateGitignore) {
+        appendIgnoreEntries(path_1.default.join(root, ".gitignore"), [".mdkg/index/", ".mdkg/pack/"]);
+    }
+    if (options.updateNpmignore) {
+        appendIgnoreEntries(path_1.default.join(root, ".npmignore"), [".mdkg/", ".mdkg/index/", ".mdkg/pack/"]);
+    }
+    if (options.updateDockerignore) {
+        appendIgnoreEntries(path_1.default.join(root, ".dockerignore"), [".mdkg/"]);
+    }
+    console.log(`mdkg init complete: ${stats.created} file(s) created, ${stats.skipped} skipped`);
+    console.log("next:");
+    console.log("  mdkg index");
+    console.log('  mdkg new task "..." --status todo --priority 1');
+    console.log("  mdkg list --status todo");
+    console.log("  mdkg pack <id> --verbose");
+    console.log("  mdkg validate");
+}

package/dist/commands/list.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runListCommand = runListCommand;
+const config_1 = require("../core/config");
+const index_cache_1 = require("../graph/index_cache");
+const filter_1 = require("../util/filter");
+const errors_1 = require("../util/errors");
+const qid_1 = require("../util/qid");
+const sort_1 = require("../util/sort");
+const node_card_1 = require("./node_card");
+function normalizeWorkspace(value) {
+    if (!value || value === "all") {
+        return undefined;
+    }
+    return value;
+}
+function runListCommand(options) {
+    const config = (0, config_1.loadConfig)(options.root);
+    const ws = normalizeWorkspace(options.ws);
+    if (ws && !config.workspaces[ws]) {
+        throw new errors_1.NotFoundError(`workspace not found: ${ws}`);
+    }
+    const { index, rebuilt, stale } = (0, index_cache_1.loadIndex)({
+        root: options.root,
+        config,
+        useCache: !options.noCache,
+        allowReindex: !options.noReindex,
+    });
+    if (stale && !rebuilt && !options.noCache) {
+        console.error("warning: index is stale; run mdkg index to refresh");
+    }
+    let epicQid;
+    if (options.epic) {
+        const resolved = (0, qid_1.resolveQid)(index, options.epic, ws);
+        if (resolved.status !== "ok") {
+            throw new errors_1.NotFoundError((0, qid_1.formatResolveError)("epic", options.epic, resolved, ws));
+        }
+        epicQid = resolved.qid;
+    }
+    const filtered = (0, filter_1.filterNodes)(Object.values(index.nodes), {
+        ws,
+        type: options.type,
+        status: options.status,
+        epic: epicQid,
+        priority: options.priority,
+        blocked: options.blocked,
+    });
+    const sorted = (0, sort_1.sortNodesByQid)(filtered);
+    for (const node of sorted) {
+        console.log((0, node_card_1.formatNodeCard)(node));
+    }
+}