@luckychen1993/pm-mcp 0.1.2 → 0.1.4

package/dist/security.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { loadExtraRules, loadProject, loadSecurity, saveSecurity } from "./store.js";
 import { latestSnapshot } from "./audit.js";
 import { readDirectDeps } from "./scan.js";
-import { ensureFresh, getIndex, iterateFileRows } from "./index-store.js";
+import { ensureFresh, getIndex, iterateFileRows, walkRefresh } from "./index-store.js";
 import { readText } from "./search.js";
 import { now } from "./types.js";
 const SECRET_PATTERNS = [
@@ -69,7 +69,7 @@ function findSecretRule(value) {
 function fingerprint(ruleId, rel, matched) {
     return createHash("sha1").update(ruleId + "|" + rel + "|" + matched).digest("hex").slice(0, 16);
 }
-function scanDetections(root) {
+function scanDetections(root, forceContent = false, indexPrepared = false) {
     const out = [];
     const rules = [...SECRET_PATTERNS, ...DANGEROUS_PATTERNS];
     // 用户自定义规则
@@ -87,7 +87,8 @@ function scanDetections(root) {
             /* 非法自定义规则跳过 */
         }
     }
-    ensureFresh(root);
+    if (!indexPrepared)
+        ensureFresh(root);
     const db = getIndex(root);
     // .env 类文件存在性检查（是否被 git 提交需人工确认）
     for (const row of iterateFileRows(db, { excludeOversize: false })) {
@@ -109,7 +110,7 @@ function scanDetections(root) {
             continue;
         if (rel.startsWith(".pm/"))
             continue;
-        const content = readText(root, rel);
+        const content = readText(root, rel, forceContent);
         if (content === null)
             continue;
         const lines = content.split("\n");
@@ -134,11 +135,19 @@ function scanDetections(root) {
     }
     return out;
 }
+/** 昂贵的全仓扫描阶段；调用方可在账本锁外完成，再把脱敏发现提交到账本。 */
+export function prepareSecurityAudit(root, options = {}) {
+    const forceIndex = options.forceIndex ?? true;
+    const forceContent = options.forceContent ?? true;
+    if (forceIndex)
+        walkRefresh(root, { forceContent: true });
+    return { detections: scanDetections(root, forceContent, forceIndex || options.indexPrepared === true) };
+}
 /** 扫描并更新台账（幂等：重复扫描不产生重复条目） */
-export function auditSecurity(root) {
+export function auditSecurity(root, prepared) {
     const project = loadProject(root);
     const stamp = now();
-    const detections = scanDetections(root);
+    const detections = prepared?.detections ?? scanDetections(root);
     const security = loadSecurity(root);
     const existing = new Map(security.findings.map((f) => [f.fingerprint, f]));
     const acceptedRefound = [];

package/dist/setup.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-export const PACKAGE_SPEC = "@luckychen1993/pm-mcp@0.1.2";
+export const PACKAGE_SPEC = "@luckychen1993/pm-mcp@0.1.4";
 export const SERVER_NAME = "pm-mcp";
 const CLIENTS = ["codex", "claude", "zcode", "cursor", "vscode"];
 export function parseSetupArgs(argv) {

package/dist/store.js

@@ -1,5 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
 import { DebugLogFileSchema, FeaturesFileSchema, FileNotesFileSchema, now, ProjectSchema, RoadmapFileSchema, SecurityFileSchema, SessionsFileSchema, TasksFileSchema, } from "./types.js";
 import { DEBUGLOG_JSON, EXTRA_RULES_FILE, FEATURES_JSON, FILE_NOTES_JSON, PROJECT_JSON, ROADMAP_JSON, SECURITY_JSON, SESSIONS_JSON, TASKS_JSON, pmPath, } from "./paths.js";
 import { ExtraRulesFileSchema } from "./types.js";
@@ -37,60 +39,208 @@ export function atomicWrite(file, content) {
 export function saveJson(file, data) {
     atomicWrite(file, JSON.stringify(data, null, 2) + "\n");
 }
+const FILE_LOCK_TIMEOUT_MS = 3_000;
+const FILE_LOCK_STALE_MS = 10_000;
+const FILE_LOCK_POLL_MS = 20;
+const FILE_LOCK_PROTOCOL = "sqlite-guard-v1";
+const FILE_LOCK_WAIT = new Int32Array(new SharedArrayBuffer(4));
+function readFileLockOwner(lockFile) {
+    let raw;
+    try {
+        raw = fs.readFileSync(lockFile, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Number.isSafeInteger(parsed.pid) || parsed.pid <= 0)
+            return null;
+        return {
+            pid: parsed.pid,
+            ...(typeof parsed.token === "string" && parsed.token.length > 0 ? { token: parsed.token } : {}),
+            ...(typeof parsed.created_at === "string" && parsed.created_at.length > 0 ? { created_at: parsed.created_at } : {}),
+            ...(typeof parsed.protocol === "string" && parsed.protocol.length > 0 ? { protocol: parsed.protocol } : {}),
+        };
+    }
+    catch {
+        const pid = Number(raw.trim());
+        return Number.isSafeInteger(pid) && pid > 0 ? { pid } : null;
+    }
+}
+function fileLockOwnerAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM proves that the process exists even when signalling it is forbidden.
+        return error.code === "EPERM";
+    }
+}
+function sqliteBusy(error) {
+    const candidate = error;
+    return candidate.errcode === 5 ||
+        (typeof candidate.message === "string" && /database is (?:locked|busy)/i.test(candidate.message));
+}
+function rollbackRecoveryGuard(db) {
+    if (!db.isTransaction)
+        return;
+    try {
+        db.exec("ROLLBACK");
+    }
+    catch {
+        // close() below is the final fail-safe and also rolls an open transaction back.
+    }
+}
 /**
- * 账本互斥锁：把「读账本 → 改 → 写」整个事务串行化，多客户端（如 ZCode+Codex 并行）
- * 不再互相覆盖丢数据。锁文件 .pm/.lock（O_EXCL 创建）；持有超过 10s 视为残留强制接管
- * （进程崩溃不留死锁）；等待上限 3s，超时明确报错而非静默丢写。
+ * 通用跨进程文件锁。SQLite 写事务覆盖 .lock 的检查、接管、创建、调用方临界区和
+ * 释放，从而消除 check-then-rm ABA，并在进程崩溃时由操作系统释放真实所有权。
+ * 成功取得同一 guard 后，带当前 protocol 的残留 .lock 可立即核销，即使 PID 已复用；
+ * 无 protocol 的旧版锁仍须「超过 staleMs 且 PID 已死」才接管，以兼容滚动升级。
+ * 释放必须完整匹配 protocol、PID、token 与 created_at，否则保留并 fail-closed。
+ * 共享同一 guardFile 的不同 lockFile 会串行，调用方应只在短元数据事务中共享 guard。
  */
-export function withLedgerLock(root, fn) {
-    const lockFile = pmPath(root, ".lock");
-    fs.mkdirSync(pmPath(root), { recursive: true });
-    const acquire = () => {
+export function withFileRecoveryLock(lockFile, fn, options = {}) {
+    const timeoutMs = options.timeoutMs ?? FILE_LOCK_TIMEOUT_MS;
+    const staleMs = options.staleMs ?? FILE_LOCK_STALE_MS;
+    const guardFile = options.guardFile ?? path.join(path.dirname(lockFile), ".file-recovery-guard.db");
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || !Number.isFinite(staleMs) || staleMs < 0) {
+        throw new RangeError("文件锁 timeoutMs 必须大于 0，staleMs 不得小于 0。");
+    }
+    fs.mkdirSync(path.dirname(lockFile), { recursive: true });
+    fs.mkdirSync(path.dirname(guardFile), { recursive: true });
+    const token = randomUUID();
+    const createdAt = new Date().toISOString();
+    const payload = JSON.stringify({ pid: process.pid, token, created_at: createdAt, protocol: FILE_LOCK_PROTOCOL });
+    const deadline = Date.now() + timeoutMs;
+    let fileLockHeld = false;
+    const acquireFileLock = () => {
         try {
-            fs.writeFileSync(lockFile, String(process.pid), { flag: "wx" });
+            fs.writeFileSync(lockFile, payload, { flag: "wx" });
             return true;
         }
-        catch {
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        let stat;
+        try {
+            stat = fs.statSync(lockFile);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return false;
+            throw error;
+        }
+        const current = readFileLockOwner(lockFile);
+        const guardedResidual = current?.protocol === FILE_LOCK_PROTOCOL;
+        if (!guardedResidual && (Date.now() - stat.mtimeMs <= staleMs || (current && fileLockOwnerAlive(current.pid)))) {
+            return false;
+        }
+        // Every current-version acquirer and releaser holds the SQLite write transaction
+        // here, so no compliant peer can replace .lock between this removal and creation.
+        try {
+            fs.rmSync(lockFile);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return false;
+            throw error;
+        }
+        try {
+            fs.writeFileSync(lockFile, payload, { flag: "wx" });
+            return true;
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                return false;
+            throw error;
+        }
+    };
+    const beginGuard = (db, until) => {
+        while (Date.now() < until) {
+            const remaining = until - Date.now();
+            if (remaining <= 0)
+                return false;
+            db.exec(`PRAGMA busy_timeout=${Math.max(1, Math.min(100, remaining))}`);
             try {
-                const st = fs.statSync(lockFile);
-                if (Date.now() - st.mtimeMs > 10_000) {
-                    fs.rmSync(lockFile, { force: true });
-                    try {
-                        fs.writeFileSync(lockFile, String(process.pid), { flag: "wx" });
-                        return true;
-                    }
-                    catch {
-                        return false;
-                    }
-                }
+                db.exec("BEGIN IMMEDIATE");
+                return true;
             }
-            catch {
-                /* 锁文件刚好消失，下轮重试 */
+            catch (error) {
+                if (!sqliteBusy(error))
+                    throw error;
+                const pause = Math.min(FILE_LOCK_POLL_MS, Math.max(0, until - Date.now()));
+                if (pause > 0)
+                    Atomics.wait(FILE_LOCK_WAIT, 0, 0, pause);
             }
-            return false;
         }
+        return false;
     };
-    let held = false;
-    for (let i = 0; i < 150 && !held; i++) {
-        held = acquire();
-        if (!held)
-            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
-    }
-    if (!held) {
-        throw new Error("账本锁获取超时（3s）：另一进程正在写入本项目，请稍后重试。");
-    }
+    const acquisitionGuard = new DatabaseSync(guardFile);
     try {
-        return fn();
+        while (!fileLockHeld && Date.now() < deadline) {
+            if (!beginGuard(acquisitionGuard, deadline))
+                break;
+            try {
+                fileLockHeld = acquireFileLock();
+            }
+            catch (error) {
+                rollbackRecoveryGuard(acquisitionGuard);
+                throw error;
+            }
+            if (!fileLockHeld) {
+                rollbackRecoveryGuard(acquisitionGuard);
+                const pause = Math.min(FILE_LOCK_POLL_MS, Math.max(0, deadline - Date.now()));
+                if (pause > 0)
+                    Atomics.wait(FILE_LOCK_WAIT, 0, 0, pause);
+            }
+        }
+        if (!fileLockHeld) {
+            throw new Error(options.timeoutMessage ?? "文件锁获取超时（3s），请稍后重试。");
+        }
+        try {
+            return fn();
+        }
+        finally {
+            try {
+                const current = readFileLockOwner(lockFile);
+                if (current?.protocol === FILE_LOCK_PROTOCOL &&
+                    current.pid === process.pid &&
+                    current.token === token &&
+                    current.created_at === createdAt) {
+                    fs.rmSync(lockFile);
+                }
+            }
+            catch {
+                // Ownership cannot be proven: leave the file for guarded recovery.
+            }
+        }
     }
     finally {
+        rollbackRecoveryGuard(acquisitionGuard);
         try {
-            fs.rmSync(lockFile, { force: true });
+            acquisitionGuard.close();
         }
         catch {
-            /* 尽力释放 */
+            /* close after rollback is best effort */
         }
     }
 }
+/**
+ * 账本专用互斥锁：把「读账本 → 改 → 写」整个事务串行化。活着的长任务不会被误抢，
+ * 等待上限 3s，超时明确报错而非静默丢写。
+ */
+export function withLedgerLock(root, fn) {
+    const runtimeDirectory = pmPath(root, ".runtime");
+    return withFileRecoveryLock(pmPath(root, ".lock"), fn, {
+        guardFile: path.join(runtimeDirectory, "ledger-lock.db"),
+        timeoutMessage: "账本锁获取超时（3s）：另一进程正在写入本项目，请稍后重试。",
+    });
+}
 export function loadJson(file, schema, fallback) {
     if (!fs.existsSync(file))
         return fallback;

package/dist/task-tools.js

@@ -4,7 +4,7 @@ import { foldLines, normSep } from "./budget.js";
 import { requireInitialized } from "./paths.js";
 import { loadRoadmap, loadTasks, nextId, saveTasks } from "./store.js";
 import { now } from "./types.js";
-import { budgetLines, tool, toolW } from "./tool-base.js";
+import { budgetLines, toolR, toolW } from "./tool-base.js";
 const stepSchema = z.object({ text: z.string(), done: z.boolean().optional() });
 export function registerTaskTools(server, root) {
     toolW(server, root, "add_task", "添加任务。长任务务必给 steps（显式步骤清单，断点续做的载体）；走了捷径 type=debt 登记（债务账）；修 bug type=fix。", {
@@ -55,7 +55,7 @@ export function registerTaskTools(server, root) {
             : "";
         return `✅ 任务 ${id}「${args.title}」已创建（${args.type ?? "feature"}/${args.milestone ?? "无里程碑"}）。${tip}`;
     });
-    tool(server, "list_tasks", "列出任务（默认不含 done/cancelled）。可按状态/类型/里程碑/标签过滤。", {
+    toolR(server, root, "list_tasks", "列出任务（默认不含 done/cancelled）。可按状态/类型/里程碑/标签过滤。", {
         status: z.enum(["backlog", "todo", "in_progress", "blocked", "done", "cancelled"]).optional(),
         type: z.enum(["feature", "refactor", "fix", "chore", "debt"]).optional(),
         milestone: z.string().optional(),

package/dist/tool-base.js

@@ -1,21 +1,44 @@
-import { loadProject, withLedgerLock } from "./store.js";
-export function tool(server, name, description, schema, fn) {
-    server.registerTool(name, { description, inputSchema: schema }, (async (args) => {
+import { loadProject } from "./store.js";
+import { IdempotencyKeySchema, runCoalescedRead, runIdempotentWrite, runIdempotentWriteSync } from "./idempotency.js";
+/** 只读工具：跨 Agent/进程合并完全相同的并行请求，短窗复用结果。 */
+export function toolR(server, root, name, description, schema, fn) {
+    server.registerTool(name, { description, inputSchema: schema, annotations: { readOnlyHint: true } }, (async (args) => {
         try {
-            const text = await fn(args);
-            return { content: [{ type: "text", text }] };
+            const result = await runCoalescedRead(root, name, args, fn);
+            return { content: [{ type: "text", text: result.text }] };
         }
         catch (error) {
             return { content: [{ type: "text", text: `错误: ${error.message}` }], isError: true };
         }
     }));
 }
-/** 写工具必须使用同步 handler，保证跨进程账本锁覆盖完整读-改-写。 */
-export function toolW(server, root, name, description, schema, fn) {
-    server.registerTool(name, { description, inputSchema: schema }, ((args) => {
+const idempotencyDescription = "多 Agent 执行同一业务时传相同 idempotency_key；同键同参数只执行一次，同键不同参数拒绝。";
+function writeSchema(schema) {
+    return {
+        ...schema,
+        idempotency_key: IdempotencyKeySchema.optional().describe("跨 Agent 业务幂等键，建议格式 task-id:operation，如 T-123:add-task"),
+    };
+}
+/** 同步写工具：业务幂等占位 + 跨进程账本锁覆盖完整读-改-写。 */
+export function toolW(server, root, name, description, schema, fn, prepare) {
+    server.registerTool(name, { description: `${description} ${idempotencyDescription}`, inputSchema: writeSchema(schema), annotations: { readOnlyHint: false } }, ((args) => {
+        try {
+            const result = runIdempotentWriteSync(root, name, args, fn, prepare);
+            const prefix = result.replayed ? `↩️ 幂等复用 ${result.key}\n` : result.pending ? `⏳ 幂等占位 ${result.key}\n` : "";
+            return { content: [{ type: "text", text: prefix + result.text }], ...(result.pending ? { isError: true } : {}) };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `错误: ${error.message}` }], isError: true };
+        }
+    }));
+}
+/** 已自带内部锁或异步执行的写工具：先跨进程占位，完成后缓存结果。 */
+export function toolI(server, root, name, description, schema, fn) {
+    server.registerTool(name, { description: `${description} ${idempotencyDescription}`, inputSchema: writeSchema(schema), annotations: { readOnlyHint: false } }, (async (args) => {
         try {
-            const text = withLedgerLock(root, () => fn(args));
-            return { content: [{ type: "text", text }] };
+            const result = await runIdempotentWrite(root, name, args, fn);
+            const prefix = result.replayed ? `↩️ 幂等复用 ${result.key}\n` : result.pending ? `⏳ 幂等占位 ${result.key}\n` : "";
+            return { content: [{ type: "text", text: prefix + result.text }], ...(result.pending ? { isError: true } : {}) };
         }
         catch (error) {
             return { content: [{ type: "text", text: `错误: ${error.message}` }], isError: true };

package/dist/tools.js

@@ -15,7 +15,7 @@ export function registerAllTools(server, root) {
     registerSessionTools(server, root);
     registerSearchTools(server, root);
     registerAuditTools(server, root);
-    registerRegistryTools(server);
+    registerRegistryTools(server, root);
     registerGovernanceTools(server, root);
     registerAcceptanceTools(server, root);
 }

package/dist/watcher-coordinator.js

@@ -0,0 +1,182 @@
+import fs from "node:fs";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+const ELECTION_POLL_MS = 1_000;
+const ELECTION_BUSY_MS = 20;
+export function watcherDirtyFile(root) {
+    return path.join(path.resolve(root), ".pm", ".runtime", "watcher-dirty");
+}
+export function markWatcherDirty(root) {
+    const file = watcherDirtyFile(root);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${new Date().toISOString()}\n`, "utf8");
+}
+export function clearWatcherDirty(root) {
+    try {
+        fs.rmSync(watcherDirtyFile(root));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+export function watcherIsClean(root) {
+    return !fs.existsSync(watcherDirtyFile(root));
+}
+function sqliteBusy(error) {
+    const candidate = error;
+    return candidate.errcode === 5 ||
+        (typeof candidate.message === "string" && /database is (?:locked|busy)/i.test(candidate.message));
+}
+function openElection(root) {
+    const file = path.join(path.resolve(root), ".pm", ".runtime", "watcher-leader.db");
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const db = new DatabaseSync(file);
+    try {
+        db.exec(`PRAGMA busy_timeout=${ELECTION_BUSY_MS}`);
+        return db;
+    }
+    catch (error) {
+        try {
+            db.close();
+        }
+        catch { /* best effort */ }
+        throw error;
+    }
+}
+function acquire(db) {
+    if (db.isTransaction)
+        return true;
+    try {
+        // Avoid startup DDL so late standbys can join while a leader holds the DB.
+        // The transactional header write forces ownership even when an empty DB
+        // would otherwise defer materializing the write reservation on this OS.
+        db.exec("BEGIN IMMEDIATE");
+        db.exec("PRAGMA user_version=1");
+        return true;
+    }
+    catch (error) {
+        if (db.isTransaction) {
+            try {
+                db.exec("ROLLBACK");
+            }
+            catch { /* close remains the fail-safe */ }
+        }
+        if (sqliteBusy(error))
+            return false;
+        throw error;
+    }
+}
+function release(db) {
+    if (db.isTransaction)
+        db.exec("ROLLBACK");
+}
+/**
+ * Elect exactly one watcher with a dedicated SQLite write transaction held for
+ * its lifetime. The OS releases the transaction after a force kill; standbys
+ * poll and take over without PID guesses, leases, or stale-file deletion.
+ */
+export function coordinateWatcherLeader(root, activate, report) {
+    let election;
+    try {
+        election = openElection(root);
+    }
+    catch (error) {
+        report("leader election unavailable", error);
+        return null;
+    }
+    let cleanup = null;
+    let timer = null;
+    let stopped = false;
+    let unavailable = false;
+    const relinquish = () => {
+        try {
+            cleanup?.();
+        }
+        catch (error) {
+            report("leader cleanup", error);
+        }
+        cleanup = null;
+        try {
+            release(election);
+        }
+        catch (error) {
+            report("leadership release", error);
+            unavailable = true;
+            try {
+                election.close();
+            }
+            catch { /* OS close releases the transaction */ }
+        }
+    };
+    const elect = () => {
+        if (stopped || unavailable || cleanup)
+            return;
+        let acquired = false;
+        try {
+            acquired = acquire(election);
+        }
+        catch (error) {
+            report("leader election", error);
+            unavailable = true;
+            stopped = true;
+            if (timer)
+                clearInterval(timer);
+            timer = null;
+            try {
+                election.close();
+            }
+            catch { /* best effort */ }
+            return;
+        }
+        if (!acquired)
+            return;
+        try {
+            const activated = activate();
+            if (!activated)
+                unavailable = true;
+            else
+                cleanup = activated;
+        }
+        catch (error) {
+            report("leader activation", error);
+        }
+        if (!cleanup)
+            relinquish();
+        if (unavailable) {
+            if (timer)
+                clearInterval(timer);
+            timer = null;
+            stopped = true;
+            try {
+                election.close();
+            }
+            catch { /* best effort */ }
+        }
+    };
+    elect();
+    if (unavailable) {
+        try {
+            election.close();
+        }
+        catch { /* best effort */ }
+        return null;
+    }
+    timer = setInterval(elect, ELECTION_POLL_MS);
+    timer.unref();
+    return {
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            if (timer)
+                clearInterval(timer);
+            timer = null;
+            relinquish();
+            try {
+                election.close();
+            }
+            catch { /* best effort */ }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckychen1993/pm-mcp",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "AI 编码项目的单一事实来源 + 健康台账 MCP 服务（事实来源 / 路线图 / 防幻觉 / 七本账 / 断点续做 / token 经济）",
   "keywords": [
     "mcp",