mcp-probe-kit 3.0.9 → 3.0.10

package/README.md

@@ -66,11 +66,21 @@ A powerful MCP (Model Context Protocol) server providing **22 tools** covering t
 
 - `code_insight` bridges GitNexus by default for query/context/impact analysis
 - The bridge launches `npx -y gitnexus@latest mcp` by default to reduce stale package risk
-- `start_feature` and `start_bugfix` automatically enrich plans with graph context when available
+- `init_project_context` bootstraps baseline graph docs under `docs/graph-insights/`; if `docs/project-context.md` already exists, it preserves the old context docs and only backfills graph docs plus the index entry
+- `start_feature` refreshes the GitNexus index and runs task-level `query/context/impact` narrowing before spec generation to reduce over-scoping
+- `start_bugfix` refreshes the GitNexus index and runs task-level graph analysis before TBP RCA to constrain failure boundary and blast radius
+- Older projects that already have `project-context.md` but no graph docs are bootstrapped automatically through the `init_project_context` step
 - If GitNexus is unavailable, the server falls back automatically without breaking orchestration
+- Real graph queries read the `.gitnexus` index; `docs/graph-insights/latest.md|json` are readable snapshots for humans and AI agents
 - Graph snapshots are exposed as resources (`probe://graph/latest`, `probe://graph/history`, `probe://graph/latest.md`)
 - Graph snapshots are also persisted to readable files in `.mcp-probe-kit/graph-snapshots` (customizable via `MCP_GRAPH_SNAPSHOT_DIR`)
 - Tool responses include `_meta.graph` with snapshot URI and local JSON/Markdown file paths
+
+### 🐛 TBP 8-Step RCA for Bug Workflows
+
+- `start_bugfix` defaults to Toyota-style TBP 8-step root-cause analysis before repair
+- `fix_bug` returns a structured TBP skeleton covering phenomenon, timeline, ruled-out paths, boundary, root cause, evidence, and repair plan
+- This makes bug, regression, anomaly, and "why didn't it work" investigations follow analyze-first discipline instead of patching symptoms
 
 ### 🎯 Structured Output
 
@@ -173,7 +183,7 @@ This mode performs 1-2 rounds of structured clarification before entering spec/f
 
 6 intelligent orchestration tools that automatically combine multiple basic tools for one-click complex development workflows:
 - `start_feature` - New feature development (Requirements → Design → Estimation)
-- `start_bugfix` - Bug fixing (Analysis → Fix → Testing)
+- `start_bugfix` - Bug fixing (TBP 8-step RCA → Fix → Testing)
 - `start_onboard` - Project onboarding (Generate project context docs)
 - `start_ui` - UI development (Design system → Components → Code)
 - `start_product` - Product design (PRD → Prototype → Design system → HTML)
@@ -252,8 +262,8 @@ This ensures `start_ui` can generate professional-grade UI code even offline.
 |---------|-----------------|--------|
 | Develop new feature (complete flow) | `start_feature` | Auto-complete: spec→estimation |
 | Only need feature spec docs | `add_feature` | More lightweight, only generates docs |
-| Fix bug (complete flow) | `start_bugfix` | Auto-complete: analysis→fix→test |
-| Only need bug analysis | `fix_bug` | Faster, only analyzes problem |
+| Fix bug (complete flow) | `start_bugfix` | Root-cause-first flow: TBP RCA → fix → test |
+| Only need bug analysis | `fix_bug` | TBP 8-step RCA only, without full orchestration |
 | Generate design system | `ui_design_system` | Directly generate design specs |
 | Develop UI components | `start_ui` | Complete flow: design→components→code |
 | Product design (requirements to prototype) | `start_product` | One-click: PRD→prototype→HTML |

package/build/lib/__tests__/gitnexus-bridge.unit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/lib/__tests__/gitnexus-bridge.unit.test.js

@@ -0,0 +1,86 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, expect, test } from "vitest";
+import { prepareBridgeWorkspace, resolveExecutableCommand, resolveSpawnCommand } from "../gitnexus-bridge.js";
+const tempRoots = [];
+afterEach(() => {
+    while (tempRoots.length > 0) {
+        const dir = tempRoots.pop();
+        if (dir) {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    }
+});
+function makeTempDir(prefix) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    tempRoots.push(dir);
+    return dir;
+}
+describe("gitnexus-bridge workspace preparation", () => {
+    test("Windows 下将 npx/git 解析为 cmd 可执行文件", () => {
+        const npxResolved = resolveExecutableCommand("npx", "win32").toLowerCase();
+        expect(npxResolved).toContain("npx");
+        if (npxResolved.includes("\\")) {
+            expect(npxResolved.endsWith(".cmd") || npxResolved.endsWith("\\npx")).toBe(true);
+        }
+        expect(resolveExecutableCommand("git", "win32").toLowerCase()).toContain("git");
+        expect(resolveExecutableCommand("npx", "linux").toLowerCase()).toContain("npx");
+    });
+    test("Windows 下将 cmd 工具包装为 cmd.exe /c 启动", () => {
+        const wrapped = resolveSpawnCommand("npx", ["-y", "gitnexus@latest", "mcp"], "win32");
+        expect(wrapped.command.toLowerCase()).toContain("cmd");
+        expect(wrapped.args.slice(0, 3)).toEqual(["/d", "/s", "/c"]);
+        expect(String(wrapped.args[3]).toLowerCase()).toContain("npx");
+    });
+    test("Windows 下 git.exe 直接启动，不走 git.cmd 壳层", () => {
+        const resolved = resolveExecutableCommand("git", "win32").toLowerCase();
+        const spawned = resolveSpawnCommand("git", ["init", "-q"], "win32");
+        expect(resolved).toContain("git");
+        expect(resolved.endsWith(".exe") || resolved === "git").toBe(true);
+        expect(spawned.command.toLowerCase()).not.toContain("cmd.exe /d /s /c git.cmd");
+        if (spawned.command.toLowerCase().includes("cmd")) {
+            expect(String(spawned.args[3]).toLowerCase()).not.toContain("git.cmd");
+        }
+        else {
+            expect(spawned.command.toLowerCase()).toContain("git");
+        }
+    });
+    test("git 目录直接使用源仓库", async () => {
+        const repoRoot = makeTempDir("gitnexus-direct-");
+        fs.mkdirSync(path.join(repoRoot, ".git"));
+        fs.mkdirSync(path.join(repoRoot, "src"), { recursive: true });
+        fs.writeFileSync(path.join(repoRoot, "package.json"), JSON.stringify({ name: "video-pipeline" }, null, 2), "utf-8");
+        const nested = path.join(repoRoot, "src");
+        const workspace = await prepareBridgeWorkspace(nested);
+        expect(workspace.workspaceMode).toBe("direct");
+        expect(workspace.sourceRoot).toBe(repoRoot);
+        expect(workspace.analysisRoot).toBe(repoRoot);
+        expect(workspace.repoName).toBe("video-pipeline");
+        expect(workspace.pathMapped).toBe(false);
+        expect(workspace.cleanup).toBeUndefined();
+    });
+    test("non-git 目录创建项目内一次性工作区并忽略敏感目录", async () => {
+        const sourceRoot = makeTempDir("gitnexus-temp-");
+        fs.writeFileSync(path.join(sourceRoot, "index.ts"), "export const ok = true;\n", "utf-8");
+        fs.mkdirSync(path.join(sourceRoot, "node_modules", "left-pad"), { recursive: true });
+        fs.writeFileSync(path.join(sourceRoot, "node_modules", "left-pad", "index.js"), "module.exports = 1;\n", "utf-8");
+        fs.mkdirSync(path.join(sourceRoot, ".mcp-probe-kit"), { recursive: true });
+        fs.writeFileSync(path.join(sourceRoot, ".env"), "TOKEN=secret\n", "utf-8");
+        fs.mkdirSync(path.join(sourceRoot, "output"), { recursive: true });
+        fs.writeFileSync(path.join(sourceRoot, "output", "video.mp4"), "binary-ish\n", "utf-8");
+        const workspace = await prepareBridgeWorkspace(sourceRoot, undefined, { bootstrap: false });
+        expect(workspace.workspaceMode).toBe("temp-repo");
+        expect(workspace.sourceRoot).toBe(sourceRoot);
+        expect(workspace.analysisRoot).toContain(path.join(sourceRoot, ".mcp-probe-kit", "gitnexus-temp"));
+        expect(fs.existsSync(path.join(workspace.analysisRoot, "index.ts"))).toBe(true);
+        expect(fs.existsSync(path.join(workspace.analysisRoot, "node_modules"))).toBe(false);
+        expect(fs.existsSync(path.join(workspace.analysisRoot, ".mcp-probe-kit"))).toBe(false);
+        expect(fs.existsSync(path.join(workspace.analysisRoot, ".env"))).toBe(false);
+        expect(fs.existsSync(path.join(workspace.analysisRoot, "output"))).toBe(false);
+        const tempWorkspaceRoot = path.dirname(workspace.analysisRoot);
+        await workspace.cleanup?.();
+        expect(fs.existsSync(workspace.analysisRoot)).toBe(false);
+        expect(fs.existsSync(tempWorkspaceRoot)).toBe(false);
+    });
+});

package/build/lib/gitnexus-bridge.d.ts

@@ -5,6 +5,7 @@ export interface CodeInsightRequest {
     query?: string;
     target?: string;
     repo?: string;
+    projectRoot?: string;
     goal?: string;
     taskContext?: string;
     direction?: CodeInsightDirection;
@@ -32,6 +33,10 @@ export interface CodeInsightBridgeResult {
     executions: CodeInsightExecution[];
     warnings: string[];
     repo?: string;
+    workspaceMode: "direct" | "temp-repo";
+    sourceRoot: string;
+    analysisRoot: string;
+    pathMapped: boolean;
 }
 export interface EmbeddedGraphContext {
     enabled: boolean;
@@ -43,16 +48,34 @@ export interface EmbeddedGraphContext {
     mode: "query" | "context" | "impact";
     highlights: string[];
 }
+export declare function resolveExecutableCommand(command: string, platform?: NodeJS.Platform): string;
+export declare function resolveSpawnCommand(command: string, args: string[], platform?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+};
+export interface BridgeWorkspace {
+    workspaceMode: "direct" | "temp-repo";
+    sourceRoot: string;
+    analysisRoot: string;
+    repoName?: string;
+    pathMapped: boolean;
+    cleanup?: () => Promise<void>;
+}
+export declare function prepareBridgeWorkspace(cwd?: string, signal?: AbortSignal, options?: {
+    bootstrap?: boolean;
+}): Promise<BridgeWorkspace>;
 export declare function runCodeInsightBridge(request: CodeInsightRequest): Promise<CodeInsightBridgeResult>;
 export declare function buildFeatureGraphContext(input: {
     featureName: string;
     description: string;
     signal?: AbortSignal;
     repo?: string;
+    projectRoot?: string;
 }): Promise<EmbeddedGraphContext>;
 export declare function buildBugfixGraphContext(input: {
     errorMessage: string;
     stackTrace?: string;
     signal?: AbortSignal;
     repo?: string;
+    projectRoot?: string;
 }): Promise<EmbeddedGraphContext>;