@luckychen1993/pm-mcp 0.1.1

package/dist/knowledge-tools.js

@@ -0,0 +1,204 @@
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { foldLines, normSep } from "./budget.js";
+import { refreshDerived } from "./dashboard.js";
+import { decisionsDir, requireInitialized } from "./paths.js";
+import { formatCodeSearch, searchCode, searchKnowledge } from "./search.js";
+import { loadDebugLog, loadFeatures, loadFileNotes, loadProject, loadSessions, nextId, saveDebugLog, saveFeatures, saveFileNotes, saveSessions, } from "./store.js";
+import { budgetLines, tool, toolW } from "./tool-base.js";
+import { now } from "./types.js";
+export function registerFeatureTools(server, root) {
+    toolW(server, root, "register_feature", "登记功能（回答「这个项目有哪些功能」）。entry_files=入口文件（漂移对账锚点），test_files=测试文件（测试背书）。", {
+        name: z.string().min(1),
+        description: z.string().optional(),
+        entry_files: z.array(z.string()).optional().describe("入口/实现文件相对路径"),
+        module: z.string().optional().describe("所属模块"),
+        test_files: z.array(z.string()).optional().describe("对应测试文件"),
+        status: z.enum(["planned", "implemented", "deprecated"]).optional().describe("默认 implemented"),
+    }, (args) => {
+        requireInitialized(root);
+        const data = loadFeatures(root);
+        const id = nextId("F", data.seq);
+        const t = now();
+        data.seq += 1;
+        data.features.push({
+            id,
+            name: args.name,
+            description: args.description ?? "",
+            module: args.module ?? "",
+            entry_files: (args.entry_files ?? []).map(normSep),
+            test_files: (args.test_files ?? []).map(normSep),
+            status: args.status ?? "implemented",
+            created: t,
+            updated: t,
+        });
+        saveFeatures(root, data);
+        refreshDerived(root);
+        const dup = data.features.find((f) => f.id !== id && f.name === args.name);
+        const hint = dup
+            ? `\n⚠️ 已存在同名功能 ${dup.id}（${dup.status}）——若是一物重复登记请梳理，别让功能账出现双胞胎。`
+            : "";
+        return `✅ 功能 ${id}「${args.name}」已登记${args.module ? `（${args.module}）` : ""}。audit_structure 会核对其入口文件是否真实存在（防幻觉对账）。${hint}`;
+    });
+    tool(server, "list_features", "列出功能清单（可按模块/状态过滤）。", { module: z.string().optional(), status: z.enum(["planned", "implemented", "deprecated"]).optional() }, (args) => {
+        requireInitialized(root);
+        let list = loadFeatures(root).features;
+        if (args.module)
+            list = list.filter((f) => f.module === args.module);
+        if (args.status)
+            list = list.filter((f) => f.status === args.status);
+        const L = list.map((f) => {
+            const missing = f.entry_files.filter((p) => !fs.existsSync(path.join(root, p)));
+            const mark = f.status !== "implemented" ? "○" : missing.length > 0 ? "⚠️漂移" : f.test_files.length === 0 ? "🧪无测试" : "✅";
+            return `${mark} ${f.id} ${f.name}${f.module ? `（${f.module}）` : ""}${f.description ? ` — ${f.description.slice(0, 80)}` : ""}`;
+        });
+        return foldLines([`共 ${list.length} 个功能:`, ...L], { maxLines: budgetLines(root), hint: "用 module/status 过滤" });
+    });
+}
+export function registerDecisionTools(server, root) {
+    toolW(server, root, "record_decision", "记录架构决策（ADR）：为什么这么选、决定了什么、有什么后果。认知债务的解药——半年后还能回答「当时为什么」。", {
+        title: z.string().min(1),
+        context: z.string().describe("背景与约束（为什么需要做选择）"),
+        decision: z.string().describe("决定与理由"),
+        consequences: z.string().optional().describe("后果/代价/被放弃的方案"),
+    }, (args) => {
+        requireInitialized(root);
+        ensureDecisionDir(root);
+        const existing = fs.readdirSync(decisionsDir(root)).filter((n) => n.endsWith(".md"));
+        const num = String(existing.length + 1).padStart(3, "0");
+        const slug = args.title
+            .replace(/[\\/:*?"<>|\s]+/g, "-")
+            .replace(/^-+|-+$/g, "")
+            .slice(0, 40) || "decision";
+        const file = `ADR-${num}-${slug}.md`;
+        const content = [
+            `# ADR-${num} ${args.title}`,
+            "",
+            `- 日期: ${new Date().toISOString().slice(0, 10)}`,
+            "- 状态: 已接受",
+            "",
+            "## 背景",
+            "",
+            args.context,
+            "",
+            "## 决定",
+            "",
+            args.decision,
+            "",
+            "## 后果",
+            "",
+            args.consequences ?? "（未记录）",
+            "",
+        ].join("\n");
+        fs.writeFileSync(path.join(decisionsDir(root), file), content, "utf8");
+        refreshDerived(root);
+        return `✅ 决策已记录: .pm/decisions/${file}（不可变编号，git 友好）。search_knowledge 可检索。`;
+    });
+    tool(server, "list_decisions", "列出全部架构决策（ADR）。", {}, () => {
+        requireInitialized(root);
+        const dir = decisionsDir(root);
+        const names = fs.existsSync(dir) ? fs.readdirSync(dir).filter((n) => n.endsWith(".md")).sort() : [];
+        if (names.length === 0)
+            return "（暂无决策记录。重要取舍用 record_decision 留痕。）";
+        return foldLines(names.map((n) => `- ${n.replace(/\.md$/, "")}`), { maxLines: budgetLines(root) });
+    });
+}
+function ensureDecisionDir(root) {
+    fs.mkdirSync(decisionsDir(root), { recursive: true });
+}
+export function registerSessionTools(server, root) {
+    toolW(server, root, "log_session", "收工仪式：记录本次会话（做了什么、改了哪些文件、下一步）。files 是变更足迹（churn 账与波及面告警的数据源），务必如实列出。", {
+        summary: z.string().min(1).describe("本次做了什么（一两句）"),
+        files: z.array(z.string()).optional().describe("本次改动/新增/删除的文件（相对路径）"),
+        next_steps: z.array(z.string()).optional().describe("留给下次的下一步"),
+        author: z.string().optional().describe("署名：zcode / codex / human:名字"),
+    }, (args) => {
+        requireInitialized(root);
+        const project = loadProject(root);
+        const data = loadSessions(root);
+        const id = nextId("S", data.seq, 4);
+        data.seq += 1;
+        data.sessions.push({
+            id,
+            date: now(),
+            author: args.author ?? "",
+            summary: args.summary,
+            files: (args.files ?? []).map(normSep),
+            next_steps: args.next_steps ?? [],
+        });
+        saveSessions(root, data);
+        refreshDerived(root);
+        const L = [`✅ 会话 ${id} 已记录，changelog.md 已更新。`];
+        if ((args.files ?? []).length > project.budgets.sessionBlastRadius) {
+            L.push(`⚠️ 本次波及 ${(args.files ?? []).length} 个文件，超过阈值 ${project.budgets.sessionBlastRadius}——波及面过大，考虑拆任务或立重构任务。`);
+        }
+        return L.join("\n");
+    });
+    toolW(server, root, "log_debug", "记录调试过程：症状 / 根因 / 修法 / 怎么验证的。调试知识账——下次同样的错不用从零猜，search_knowledge 可查。", {
+        symptom: z.string().describe("症状：什么现象、报什么错"),
+        root_cause: z.string().describe("根因（诊断出的真正原因，不是表面现象）"),
+        fix: z.string().describe("修法"),
+        verified_how: z.string().optional().describe("怎么确认修好了"),
+        files: z.array(z.string()).optional(),
+        task_id: z.string().optional().describe("关联任务 id"),
+    }, (args) => {
+        requireInitialized(root);
+        const data = loadDebugLog(root);
+        const id = nextId("D", data.seq, 4);
+        data.seq += 1;
+        data.entries.push({
+            id,
+            date: now(),
+            author: "",
+            symptom: args.symptom,
+            root_cause: args.root_cause,
+            fix: args.fix,
+            verified_how: args.verified_how ?? "",
+            files: (args.files ?? []).map(normSep),
+            task_id: args.task_id ?? null,
+        });
+        saveDebugLog(root, data);
+        refreshDerived(root);
+        return `✅ 调试记录 ${id} 已存档。这份诊断经验已进入项目知识库。`;
+    });
+}
+export function registerSearchTools(server, root) {
+    tool(server, "search_code", "在真实代码里检索（防幻觉事中防线）：谈某个功能/文件之前先搜实码。返回 file:line 片段而非整文件（token 经济）。默认按字面量匹配；regex=true 时按 JavaScript 正则（仅在你确需时开启）。", {
+        query: z.string().min(1).describe("关键词（默认字面量匹配）"),
+        glob: z.string().optional().describe("限定文件范围，如 src/**/*.ts"),
+        max_results: z.number().int().min(1).max(100).optional().describe("默认 30"),
+        regex: z.boolean().optional().describe("默认 false；true 时 query 按正则解释"),
+    }, (args) => {
+        requireInitialized(root);
+        const res = searchCode(root, args.query, args.glob, args.max_results ?? 30, args.regex ?? false);
+        return formatCodeSearch(res, args.query);
+    });
+    tool(server, "search_knowledge", "检索六类项目知识源（ADR/任务/功能/会话/调试记录/文件索引）——回答「之前为什么这么做」「上次这个错怎么解的」，用历史结论代替重新推理。代码内容请用 search_code。", { query: z.string().min(1) }, (args) => {
+        requireInitialized(root);
+        return searchKnowledge(root, args.query);
+    });
+    toolW(server, root, "annotate_file", "给文件登记一行用途（文件用途索引）：之后任何会话靠索引定位，不用打开文件。引用外部代码时可登记 source/license（provenance）。", {
+        path: z.string().min(1).describe("相对路径"),
+        purpose: z.string().min(1).describe("一句话用途"),
+        source: z.string().optional().describe("代码来源（URL/仓库），如引用自外部"),
+        license: z.string().optional().describe("该文件引用代码的许可证"),
+    }, (args) => {
+        requireInitialized(root);
+        const rel = normSep(args.path);
+        if (!fs.existsSync(path.join(root, rel))) {
+            throw new Error(`文件不存在: ${rel}（注意用相对路径，如 src/index.ts）`);
+        }
+        const data = loadFileNotes(root);
+        data.notes[rel] = {
+            ...(data.notes[rel] ?? {}),
+            purpose: args.purpose,
+            source: args.source ?? data.notes[rel]?.source ?? "",
+            license: args.license ?? data.notes[rel]?.license ?? "",
+            updated: now(),
+        };
+        saveFileNotes(root, data);
+        refreshDerived(root);
+        return `✅ 已登记 ${rel}: ${args.purpose}。索引覆盖率上升，后续会话省 token。`;
+    });
+}

package/dist/language-adapters.js

@@ -0,0 +1,450 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { parseManifestDependencies } from "./language-dependencies.js";
+const DEFAULT_IGNORE_DIRS = new Set([
+    ".git", ".pm", ".idea", ".vscode", ".venv", "venv", "env", "__pycache__",
+    "node_modules", "dist", "build", "out", "target", ".gradle", ".next", ".nuxt",
+    ".output", ".turbo", "coverage", ".cache",
+]);
+const LANGUAGE_ORDER = [
+    "javascript", "typescript", "python", "go", "rust", "java", "kotlin", "csharp",
+];
+const KIND_ORDER = ["test", "build", "lint", "typecheck", "coverage", "security"];
+const DEFAULT_TIMEOUT_MS = 5 * 60_000;
+const DEFAULT_OUTPUT_BYTES = 64 * 1024;
+function normalize(value) {
+    return value.replace(/\\/g, "/");
+}
+function manifestKind(name) {
+    const lower = name.toLowerCase();
+    if (lower === "package.json")
+        return "node";
+    if (lower === "pyproject.toml" || /^requirements(?:[-_.][^.]+)?\.txt$/i.test(name))
+        return "python";
+    if (lower === "go.mod")
+        return "go";
+    if (name === "Cargo.toml")
+        return "rust";
+    if (lower === "pom.xml")
+        return "maven";
+    if (/^(?:build|settings)\.gradle(?:\.kts)?$/i.test(name))
+        return "gradle";
+    if (/\.(?:sln|csproj)$/i.test(name))
+        return "dotnet";
+    return null;
+}
+function readJson(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw new Error("root is not an object");
+        return parsed;
+    }
+    catch (error) {
+        throw new Error(`Cannot parse manifest ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function packageManager(unitRoot, repositoryRoot, pkg) {
+    const declared = typeof pkg.packageManager === "string" ? pkg.packageManager.split("@")[0].trim() : "";
+    if (["npm", "pnpm", "yarn", "bun"].includes(declared))
+        return declared;
+    let cursor = unitRoot;
+    while (true) {
+        if (fs.existsSync(path.join(cursor, "pnpm-lock.yaml")))
+            return "pnpm";
+        if (fs.existsSync(path.join(cursor, "yarn.lock")))
+            return "yarn";
+        if (fs.existsSync(path.join(cursor, "bun.lock")) || fs.existsSync(path.join(cursor, "bun.lockb")))
+            return "bun";
+        if (cursor === repositoryRoot)
+            break;
+        const parent = path.dirname(cursor);
+        const relativeParent = path.relative(repositoryRoot, parent);
+        if (parent === cursor || relativeParent.startsWith("..") || path.isAbsolute(relativeParent))
+            break;
+        cursor = parent;
+    }
+    return "npm";
+}
+function nodeToolInvocation(manager) {
+    if (process.platform === "win32" && manager === "npm") {
+        const candidates = [
+            process.env.npm_execpath,
+            path.join(path.dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js"),
+        ].filter((candidate) => Boolean(candidate));
+        const cli = candidates.find((candidate) => fs.existsSync(candidate));
+        if (cli)
+            return { executable: process.execPath, prefix: [cli] };
+    }
+    return { executable: manager, prefix: [] };
+}
+function repositoryWrapper(unitRoot, repositoryRoot, posixName, windowsName) {
+    const names = process.platform === "win32" ? [windowsName, posixName] : [posixName, windowsName];
+    let cursor = unitRoot;
+    while (true) {
+        for (const name of names) {
+            const candidate = path.join(cursor, name);
+            if (fs.existsSync(candidate) && fs.statSync(candidate).isFile())
+                return candidate;
+        }
+        if (cursor === repositoryRoot)
+            break;
+        const parent = path.dirname(cursor);
+        const relativeParent = path.relative(repositoryRoot, parent);
+        if (parent === cursor || relativeParent.startsWith("..") || path.isAbsolute(relativeParent))
+            break;
+        cursor = parent;
+    }
+    return null;
+}
+function command(cwd, kind, executable, args, requiredExecutable = executable) {
+    return {
+        command: executable,
+        args: [...args],
+        cwd,
+        kind,
+        requiredExecutable,
+        timeoutMs: DEFAULT_TIMEOUT_MS,
+        maxOutputBytes: DEFAULT_OUTPUT_BYTES,
+    };
+}
+function nodeCommands(unitRoot, repositoryRoot, packageFile) {
+    let pkg;
+    try {
+        pkg = readJson(packageFile);
+    }
+    catch {
+        return [];
+    }
+    const scripts = pkg.scripts && typeof pkg.scripts === "object" && !Array.isArray(pkg.scripts)
+        ? pkg.scripts
+        : {};
+    const manager = packageManager(unitRoot, repositoryRoot, pkg);
+    const invocation = nodeToolInvocation(manager);
+    const out = [];
+    // Deliberately exact and closed: arbitrary lifecycle scripts never enter the plan.
+    for (const kind of KIND_ORDER) {
+        if (typeof scripts[kind] === "string" && scripts[kind].trim()) {
+            out.push(command(unitRoot, kind, invocation.executable, [...invocation.prefix, "run", kind], manager));
+        }
+    }
+    return out;
+}
+function pythonCommands(unitRoot, manifests) {
+    const pyproject = manifests.find((m) => path.basename(m.path).toLowerCase() === "pyproject.toml");
+    const out = [command(unitRoot, "test", "python", ["-m", "pytest"], "python")];
+    if (!pyproject)
+        return out;
+    const text = fs.readFileSync(pyproject.path, "utf8");
+    if (/^\s*\[build-system\]\s*$/m.test(text))
+        out.push(command(unitRoot, "build", "python", ["-m", "build"], "python"));
+    if (/^\s*\[tool\.ruff(?:\.|\])/.test(text) || /^\s*\[tool\.ruff(?:\.|\])/m.test(text)) {
+        out.push(command(unitRoot, "lint", "python", ["-m", "ruff", "check", "."], "python"));
+    }
+    if (/^\s*\[tool\.mypy(?:\.|\])/.test(text) || /^\s*\[tool\.mypy(?:\.|\])/m.test(text)) {
+        out.push(command(unitRoot, "typecheck", "python", ["-m", "mypy", "."], "python"));
+    }
+    if (/^\s*\[tool\.coverage(?:\.|\])/m.test(text) || /pytest-cov/.test(text)) {
+        out.push(command(unitRoot, "coverage", "python", ["-m", "coverage", "run", "-m", "pytest"], "python"));
+    }
+    if (/^\s*\[tool\.bandit(?:\.|\])/m.test(text) || /pip-audit/.test(text)) {
+        out.push(command(unitRoot, "security", "python", ["-m", "bandit", "-r", "."], "python"));
+    }
+    return out;
+}
+function commandsForUnit(unitRoot, repositoryRoot, manifests) {
+    const out = [];
+    const byKind = (kind) => manifests.filter((m) => m.kind === kind);
+    for (const pkg of byKind("node"))
+        out.push(...nodeCommands(unitRoot, repositoryRoot, pkg.path));
+    if (byKind("python").length > 0)
+        out.push(...pythonCommands(unitRoot, byKind("python")));
+    if (byKind("go").length > 0) {
+        out.push(command(unitRoot, "test", "go", ["test", "./..."]));
+        out.push(command(unitRoot, "build", "go", ["build", "./..."]));
+        out.push(command(unitRoot, "lint", "go", ["vet", "./..."]));
+        out.push(command(unitRoot, "coverage", "go", ["test", "-coverprofile=coverage.out", "./..."]));
+    }
+    if (byKind("rust").length > 0) {
+        out.push(command(unitRoot, "test", "cargo", ["test", "--all-targets"]));
+        out.push(command(unitRoot, "build", "cargo", ["build"]));
+        out.push(command(unitRoot, "lint", "cargo", ["clippy", "--all-targets", "--", "-D", "warnings"]));
+        out.push(command(unitRoot, "typecheck", "cargo", ["check"]));
+    }
+    if (byKind("maven").length > 0) {
+        const wrapper = repositoryWrapper(unitRoot, repositoryRoot, "mvnw", "mvnw.cmd");
+        const executable = wrapper ?? "mvn";
+        out.push(command(unitRoot, "test", executable, ["-B", "test"], executable));
+        out.push(command(unitRoot, "build", executable, ["-B", "-DskipTests", "package"], executable));
+    }
+    if (byKind("gradle").length > 0) {
+        const wrapper = repositoryWrapper(unitRoot, repositoryRoot, "gradlew", "gradlew.bat");
+        const executable = wrapper ?? "gradle";
+        out.push(command(unitRoot, "test", executable, ["test"], executable));
+        out.push(command(unitRoot, "build", executable, ["build"], executable));
+    }
+    const dotnet = byKind("dotnet");
+    if (dotnet.length > 0) {
+        const target = dotnet.find((m) => m.path.toLowerCase().endsWith(".sln")) ?? dotnet[0];
+        const rel = path.relative(unitRoot, target.path) || path.basename(target.path);
+        out.push(command(unitRoot, "test", "dotnet", ["test", rel]));
+        out.push(command(unitRoot, "build", "dotnet", ["build", rel]));
+    }
+    const seen = new Set();
+    return out.filter((item) => {
+        const key = JSON.stringify([item.kind, item.command, item.args, item.cwd]);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    }).sort((a, b) => KIND_ORDER.indexOf(a.kind) - KIND_ORDER.indexOf(b.kind));
+}
+function languagesFor(unitRoot, manifests) {
+    const found = new Set();
+    for (const item of manifests) {
+        switch (item.kind) {
+            case "node": {
+                found.add("javascript");
+                try {
+                    const pkg = readJson(item.path);
+                    const allDeps = { ...asRecord(pkg.dependencies), ...asRecord(pkg.devDependencies) };
+                    if (fs.existsSync(path.join(unitRoot, "tsconfig.json")) || "typescript" in allDeps)
+                        found.add("typescript");
+                }
+                catch {
+                    if (fs.existsSync(path.join(unitRoot, "tsconfig.json")))
+                        found.add("typescript");
+                }
+                break;
+            }
+            case "python":
+                found.add("python");
+                break;
+            case "go":
+                found.add("go");
+                break;
+            case "rust":
+                found.add("rust");
+                break;
+            case "maven":
+                found.add("java");
+                break;
+            case "gradle":
+                found.add("java");
+                if (item.path.toLowerCase().endsWith(".kts"))
+                    found.add("kotlin");
+                break;
+            case "dotnet":
+                found.add("csharp");
+                break;
+        }
+    }
+    return LANGUAGE_ORDER.filter((lang) => found.has(lang));
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+/**
+ * Recursively discovers manifest-bearing project units. Node workspace packages are
+ * naturally separate units because each workspace package.json is discovered.
+ */
+export function discoverProjectUnits(root, options = {}) {
+    const repositoryRoot = path.resolve(root);
+    const stat = fs.statSync(repositoryRoot);
+    if (!stat.isDirectory())
+        throw new Error(`Project root is not a directory: ${repositoryRoot}`);
+    const maxDepth = options.maxDepth ?? 64;
+    if (!Number.isInteger(maxDepth) || maxDepth < 0)
+        throw new Error("maxDepth must be a non-negative integer");
+    const ignored = new Set([...DEFAULT_IGNORE_DIRS, ...(options.ignoreDirs ?? [])]);
+    const grouped = new Map();
+    const walk = (dir, depth) => {
+        if (depth > maxDepth)
+            throw new Error(`Manifest discovery exceeded maxDepth=${maxDepth}: ${dir}`);
+        const entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            const absolute = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!ignored.has(entry.name))
+                    walk(absolute, depth + 1);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const kind = manifestKind(entry.name);
+            if (!kind)
+                continue;
+            const list = grouped.get(dir) ?? [];
+            list.push({ kind, path: absolute });
+            grouped.set(dir, list);
+        }
+    };
+    walk(repositoryRoot, 0);
+    return [...grouped.entries()].map(([unitRoot, manifest]) => {
+        manifest.sort((a, b) => a.path.localeCompare(b.path));
+        const relative = normalize(path.relative(repositoryRoot, unitRoot));
+        const dependencyResult = parseManifestDependencies(manifest);
+        return {
+            id: relative || ".",
+            root: unitRoot,
+            languages: languagesFor(unitRoot, manifest),
+            manifest,
+            ...dependencyResult,
+            qualityCommands: commandsForUnit(unitRoot, repositoryRoot, manifest),
+        };
+    }).sort((a, b) => a.id.localeCompare(b.id));
+}
+export function createQualityPlan(units) {
+    return units.flatMap((unit) => unit.qualityCommands.map((item) => ({ ...item, args: [...item.args] })));
+}
+export function assessQualityCoverage(units) {
+    const covered = units.filter((unit) => unit.qualityCommands.length > 0);
+    const languages = new Set();
+    const commandKinds = new Set();
+    for (const unit of units) {
+        for (const language of unit.languages)
+            languages.add(language);
+        for (const item of unit.qualityCommands)
+            commandKinds.add(item.kind);
+    }
+    return {
+        totalUnits: units.length,
+        unitsWithCommands: covered.length,
+        withoutCommands: units.filter((unit) => unit.qualityCommands.length === 0).map((unit) => unit.id),
+        languages: LANGUAGE_ORDER.filter((language) => languages.has(language)),
+        commandKinds: KIND_ORDER.filter((kind) => commandKinds.has(kind)),
+        coveragePct: units.length === 0 ? 0 : Math.round((covered.length / units.length) * 100),
+    };
+}
+function executableExists(executable) {
+    if (!executable.trim() || /[\r\n\0]/.test(executable))
+        return false;
+    const hasPath = path.isAbsolute(executable) || executable.includes("/") || executable.includes("\\");
+    const candidates = [];
+    if (hasPath)
+        candidates.push(path.resolve(executable));
+    else {
+        const pathDirs = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+        const extensions = process.platform === "win32"
+            ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean)
+            : [""];
+        for (const dir of pathDirs) {
+            for (const ext of extensions)
+                candidates.push(path.join(dir.replace(/^"|"$/g, ""), executable + ext));
+            candidates.push(path.join(dir.replace(/^"|"$/g, ""), executable));
+        }
+    }
+    return candidates.some((candidate) => {
+        try {
+            const st = fs.statSync(candidate);
+            if (!st.isFile())
+                return false;
+            if (process.platform !== "win32")
+                fs.accessSync(candidate, fs.constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function validateCommand(item) {
+    if (!item.command.trim() || /[\r\n\0]/.test(item.command))
+        return "invalid command";
+    if (!Array.isArray(item.args) || item.args.some((arg) => typeof arg !== "string" || /\0/.test(arg)))
+        return "invalid args";
+    if (!path.isAbsolute(item.cwd) || !fs.existsSync(item.cwd) || !fs.statSync(item.cwd).isDirectory())
+        return "invalid cwd";
+    if (!Number.isFinite(item.timeoutMs) || item.timeoutMs < 1 || item.timeoutMs > 60 * 60_000)
+        return "invalid timeoutMs";
+    if (!Number.isFinite(item.maxOutputBytes) || item.maxOutputBytes < 1 || item.maxOutputBytes > 16 * 1024 * 1024)
+        return "invalid maxOutputBytes";
+    return null;
+}
+function baseResult(item, status) {
+    return { command: item, status, exitCode: null, signal: null, stdout: "", stderr: "", truncated: false, durationMs: 0 };
+}
+async function runOne(item) {
+    const invalid = validateCommand(item);
+    if (invalid)
+        return { ...baseResult(item, "failed"), error: invalid };
+    if (!executableExists(item.requiredExecutable)) {
+        return { ...baseResult(item, "missing"), error: `Required executable not found: ${item.requiredExecutable}` };
+    }
+    const started = Date.now();
+    return await new Promise((resolve) => {
+        let stdout = Buffer.alloc(0);
+        let stderr = Buffer.alloc(0);
+        let used = 0;
+        let truncated = false;
+        let timedOut = false;
+        let settled = false;
+        const capture = (stream, chunk) => {
+            const remaining = Math.max(0, item.maxOutputBytes - used);
+            if (chunk.length > remaining)
+                truncated = true;
+            const kept = chunk.subarray(0, remaining);
+            used += kept.length;
+            if (stream === "stdout")
+                stdout = Buffer.concat([stdout, kept]);
+            else
+                stderr = Buffer.concat([stderr, kept]);
+        };
+        let timer;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve({ ...result, stdout: stdout.toString("utf8"), stderr: stderr.toString("utf8"), truncated, durationMs: Date.now() - started });
+        };
+        // shell:false is intentional: arguments never undergo shell parsing.
+        let child;
+        try {
+            child = spawn(item.command, item.args, { cwd: item.cwd, shell: false, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
+        }
+        catch (error) {
+            const err = error;
+            finish({ ...baseResult(item, err.code === "ENOENT" ? "missing" : "failed"), error: err.message });
+            return;
+        }
+        child.stdout?.on("data", (chunk) => capture("stdout", chunk));
+        child.stderr?.on("data", (chunk) => capture("stderr", chunk));
+        child.once("error", (error) => {
+            finish({
+                ...baseResult(item, error.code === "ENOENT" ? "missing" : "failed"),
+                error: error.message,
+            });
+        });
+        child.once("close", (code, signal) => {
+            const status = timedOut ? "timed_out" : code === 0 ? "passed" : "failed";
+            finish({ ...baseResult(item, status), exitCode: code, signal });
+        });
+        timer = setTimeout(() => {
+            timedOut = true;
+            child.kill();
+        }, item.timeoutMs);
+        timer.unref();
+    });
+}
+/** Runs a plan only when execute:true. Missing tools, timeout and non-zero exits all make ok=false. */
+export async function runQualityPlan(plan, options = {}) {
+    if (!options.execute) {
+        return { execute: false, ok: true, results: plan.map((item) => baseResult(item, "planned")) };
+    }
+    const results = [];
+    const stopOnFailure = options.stopOnFailure ?? true;
+    for (let index = 0; index < plan.length; index++) {
+        const result = await runOne(plan[index]);
+        results.push(result);
+        if (result.status !== "passed" && stopOnFailure) {
+            for (const blocked of plan.slice(index + 1)) {
+                results.push({ ...baseResult(blocked, "blocked"), error: "Blocked by an earlier failed quality command" });
+            }
+            break;
+        }
+    }
+    return { execute: true, ok: results.every((result) => result.status === "passed"), results };
+}