@diffci.com/diffci 0.1.11 → 0.1.12

package/dist-client/src/client/mcp.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+import { execFile } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+const SERVER_INFO = { name: "diffci-mcp", version: "0.1.0" };
+const tools = [
+    {
+        name: "diffci_check",
+        description: "Run DiffCI's observation-only AI-agent validation command. It sends nothing by default and does not run, skip, cancel, or reorder tests.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                repo: { type: "string", description: "Repository path. Defaults to the MCP server working directory." },
+                base: { type: "string", description: "Optional base commit SHA." },
+                head: { type: "string", description: "Optional head commit SHA." },
+                json: { type: "boolean", description: "Print the full JSON observation report." },
+                quiet: { type: "boolean", description: "Suppress the human summary." },
+                redactPaths: { type: "boolean", description: "Replace paths with stable digests in the report." },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "diffci_init",
+        description: "Seed a repository with AI-agent instruction files for DiffCI.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                repo: { type: "string", description: "Repository path. Defaults to the MCP server working directory." },
+                workflow: { type: "boolean", description: "Also add the non-blocking GitHub Actions observer workflow." },
+                force: { type: "boolean", description: "Overwrite existing instruction files." },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "diffci_verify_workflow",
+        description: "Check that a DiffCI GitHub Actions job cannot affect the rest of CI.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                repo: { type: "string", description: "Repository path. Defaults to the MCP server working directory." },
+            },
+            additionalProperties: false,
+        },
+    },
+];
+function cliPath() {
+    return join(dirname(import.meta.filename), "cli.js");
+}
+function stringArg(args, name) {
+    const value = args[name];
+    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+function booleanArg(args, name) {
+    return args[name] === true;
+}
+function commandForTool(name, args) {
+    const repo = stringArg(args, "repo");
+    switch (name) {
+        case "diffci_check": {
+            const command = ["check"];
+            if (repo)
+                command.push("--repo", resolve(repo));
+            for (const flag of ["base", "head"]) {
+                const value = stringArg(args, flag);
+                if (value)
+                    command.push(`--${flag}`, value);
+            }
+            if (booleanArg(args, "json"))
+                command.push("--json");
+            if (booleanArg(args, "quiet"))
+                command.push("--quiet");
+            if (booleanArg(args, "redactPaths"))
+                command.push("--redact-paths");
+            return command;
+        }
+        case "diffci_init": {
+            const command = ["init"];
+            if (repo)
+                command.push("--repo", resolve(repo));
+            if (booleanArg(args, "workflow"))
+                command.push("--workflow");
+            if (booleanArg(args, "force"))
+                command.push("--force");
+            return command;
+        }
+        case "diffci_verify_workflow": {
+            const command = ["verify-workflow"];
+            if (repo)
+                command.push("--repo", resolve(repo));
+            return command;
+        }
+        default:
+            throw new Error(`unknown tool: ${name}`);
+    }
+}
+function runCli(args) {
+    return new Promise((resolveRun) => {
+        execFile(process.execPath, [cliPath(), ...args], {
+            cwd: process.cwd(),
+            env: { ...process.env, DIFFCI_MCP: "1" },
+            encoding: "utf8",
+            maxBuffer: 8 * 1024 * 1024,
+            windowsHide: true,
+        }, (error, stdout, stderr) => {
+            const code = error?.code;
+            const exitCode = typeof code === "number" ? code : error ? 1 : 0;
+            resolveRun({ exitCode, stdout, stderr });
+        });
+    });
+}
+function writeMessage(message) {
+    const body = JSON.stringify(message);
+    process.stdout.write(`Content-Length: ${Buffer.byteLength(body, "utf8")}\r\n\r\n${body}`);
+}
+function success(id, result) {
+    if (id === undefined)
+        return;
+    writeMessage({ jsonrpc: "2.0", id, result });
+}
+function failure(id, code, message) {
+    if (id === undefined)
+        return;
+    writeMessage({ jsonrpc: "2.0", id, error: { code, message } });
+}
+async function handle(request) {
+    const id = request.id;
+    switch (request.method) {
+        case "initialize":
+            success(id, {
+                protocolVersion: "2024-11-05",
+                capabilities: { tools: {} },
+                serverInfo: SERVER_INFO,
+            });
+            return;
+        case "notifications/initialized":
+            return;
+        case "tools/list":
+            success(id, { tools });
+            return;
+        case "tools/call": {
+            const params = request.params;
+            if (!params?.name) {
+                failure(id, -32602, "tools/call requires params.name");
+                return;
+            }
+            const args = params.arguments ?? {};
+            const run = await runCli(commandForTool(params.name, args));
+            const text = [
+                run.stdout.trim(),
+                run.stderr.trim() ? `stderr:\n${run.stderr.trim()}` : "",
+                `exitCode: ${run.exitCode}`,
+            ].filter(Boolean).join("\n\n");
+            success(id, {
+                content: [{ type: "text", text }],
+                isError: run.exitCode !== 0,
+            });
+            return;
+        }
+        default:
+            failure(id, -32601, `unknown method: ${request.method ?? ""}`);
+    }
+}
+let buffer = Buffer.alloc(0);
+const decoder = new StringDecoder("utf8");
+function readMessages() {
+    while (true) {
+        const headerEnd = buffer.indexOf("\r\n\r\n");
+        if (headerEnd === -1)
+            return;
+        const header = decoder.write(buffer.subarray(0, headerEnd));
+        const match = /^Content-Length:\s*(\d+)\s*$/im.exec(header);
+        if (!match) {
+            buffer = buffer.subarray(headerEnd + 4);
+            continue;
+        }
+        const length = Number(match[1]);
+        const bodyStart = headerEnd + 4;
+        const bodyEnd = bodyStart + length;
+        if (buffer.length < bodyEnd)
+            return;
+        const body = buffer.subarray(bodyStart, bodyEnd).toString("utf8");
+        buffer = buffer.subarray(bodyEnd);
+        const request = JSON.parse(body);
+        void handle(request).catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            failure(request.id, -32603, message);
+        });
+    }
+}
+process.stdin.on("data", (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    readMessages();
+});
+process.stdin.resume();

package/dist-client/src/client/observe.js

@@ -22,11 +22,7 @@
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { relative, resolve } from "node:path";
-import { analyzeGitDelta } from "@diffci.com/core/git/git-diff";
-import { classifyRepositoryProject, buildDependencyGraph } from "@diffci.com/core/repo/graph";
-import { ImpactAnalyzer } from "@diffci.com/core/repo/impact";
-import { runPathBaseline } from "@diffci.com/core/planner/path-baseline";
-import { commandSpecToString, planSelectiveTestCommands } from "@diffci.com/core/planner/test-command";
+import { economicsContext, evaluateEconomics } from "./economics.js";
 import { readCiEnvironment, resolveCommitRange, } from "./context.js";
 import { OBSERVATION_SCHEMA, redactPath, } from "./report.js";
 import { auditWorkflows } from "./workflow-guard.js";
@@ -72,6 +68,10 @@ export function isInsideRepository(repoPath, candidate) {
 }
 export async function observe(options) {
     const startedAt = Date.now();
+    const preObserveMs = Math.round(process.uptime() * 1000);
+    const phasesMs = {};
+    let phaseStart = performance.now();
+    const markPhase = (name) => { const now = performance.now(); phasesMs[name] = Math.round(now - phaseStart); phaseStart = now; };
     const repoPath = resolve(options.repoPath);
     const git = options.git ?? makeGitRunner(repoPath);
     const ci = readCiEnvironment(options.env);
@@ -81,6 +81,7 @@ export async function observe(options) {
     // Declared before `finish` closes over it: the range is part of every report, including the reports
     // produced by failures that happen after it was resolved.
     let range;
+    let economics;
     const finish = (status, stage, extra) => {
         const after = { head: headSha(git), worktree: worktreeDigest(git) };
         const nonInterference = {
@@ -95,6 +96,7 @@ export async function observe(options) {
             reportWrittenOutsideRepository: options.reportPath === undefined ? true : !isInsideRepository(repoPath, options.reportPath),
             workflowFindings: safeAuditWorkflows(repoPath),
         };
+        markPhase("finalization");
         return {
             schema: OBSERVATION_SCHEMA,
             producedAt: new Date().toISOString(),
@@ -125,6 +127,7 @@ export async function observe(options) {
             stage,
             reason: extra.reason,
             result: extra.result,
+            economics,
             payload: {
                 includesFilePaths: options.redactPaths !== true,
                 includesFileContents: false,
@@ -133,7 +136,7 @@ export async function observe(options) {
                 pathRedaction: options.redactPaths ? "sha256-12" : undefined,
             },
             nonInterference,
-            timings: { totalMs: Date.now() - startedAt },
+            timings: { totalMs: Date.now() - startedAt, preObserveMs, phasesMs },
         };
     };
     try {
@@ -146,12 +149,31 @@ export async function observe(options) {
         if (!resolved.ok)
             return finish("REFUSED", "context", { reason: resolved.reason });
         range = resolved.range;
+        markPhase("context");
+        if (options.economicsJobKey || options.economicsHistory) {
+            const remote = git(["remote", "get-url", "origin"]);
+            const repository = remote.ok ? /^(?:https:\/\/github\.com\/|git@github\.com:)([^/\s]+\/[^/\s]+?)(?:\.git)?$/.exec(remote.stdout.trim())?.[1] : undefined;
+            economics = evaluateEconomics(options.economicsHistory, { repository, jobKey: options.economicsJobKey, contextKey: economicsContext(repoPath), observerVersion: options.version });
+            if (economics.decision === "BYPASS_FULL") {
+                const samples = options.economicsHistory.samples;
+                if (options.forceAnalysis || samples.some(sample => !git(["merge-base", "--is-ancestor", sample.headSha, range.baseSha]).ok))
+                    economics = { ...economics, decision: "ANALYZE", reason: "Forced resampling or history is not ancestral to this change" };
+            }
+            markPhase("economics");
+            if (economics.decision === "BYPASS_FULL")
+                return finish("REFUSED", "eligibility", { reason: `ECONOMICS_FULL_BYPASS: ${economics.reason}. No selective command is authorized.` });
+        }
+        const [{ analyzeGitDelta }, { classifyRepositoryProject, buildDependencyGraph }, { ImpactAnalyzer }, { runPathBaseline }, { commandSpecToString, planSelectiveTestCommands }] = await Promise.all([
+            import("@diffci.com/core/git/git-diff"), import("@diffci.com/core/repo/graph"), import("@diffci.com/core/repo/impact"), import("@diffci.com/core/planner/path-baseline"), import("@diffci.com/core/planner/test-command"),
+        ]);
+        markPhase("engineLoad");
         // The eligibility gate is asked of the graph builder itself (classifyRepositoryProject), not of a
         // separate list of conditions that can drift away from it. Phase 01 F3 is what that drift costs.
         const capability = classifyRepositoryProject(repoPath);
+        markPhase("eligibility");
         if (!capability.capable) {
             return finish("REFUSED", "eligibility", {
-                reason: `DiffCI supports TypeScript/JavaScript projects, Vue components, and root Go modules: ${capability.reason}`,
+                reason: `DiffCI supports TypeScript/JavaScript projects, Vue components, root Go modules, and conventional Maven reactors: ${capability.reason}`,
             });
         }
         const deltaResult = await analyzeGitDelta({ baseSha: range.baseSha, headSha: range.headSha, repoPath });
@@ -159,10 +181,13 @@ export async function observe(options) {
             return finish("REFUSED", "delta", { reason: deltaResult.error });
         }
         const delta = deltaResult.delta;
-        const graphResult = await buildDependencyGraph({ repoPath, excludeDirs: EXCLUDE_DIRS });
+        markPhase("delta");
+        const graphResult = await buildDependencyGraph({ repoPath, excludeDirs: EXCLUDE_DIRS, vueAnalysisCache: options.vueAnalysisCacheDir ? { directory: options.vueAnalysisCacheDir, version: `${options.version}:${options.engineSha ?? ""}` } : undefined });
+        markPhase("graph");
         if (graphResult.graph.nodes.length === 0) {
             return finish("REFUSED", "graph", {
-                reason: "the dependency graph came back empty - DiffCI will not propose a selection from a graph that sees none of this repository",
+                reason: "the dependency graph came back empty - DiffCI will not propose a selection from a graph that sees none of this repository" +
+                    (graphResult.adapterBlockers?.length ? `; ${graphResult.adapterBlockers.join("; ")}` : ""),
             });
         }
         const profile = graphResult.profile;
@@ -177,6 +202,7 @@ export async function observe(options) {
         const commandPlan = impact.fallbackRequired
             ? undefined
             : planSelectiveTestCommands(profile, selectedTests);
+        markPhase("impactAndCommands");
         return finish("OBSERVED", "complete", {
             result: {
                 mode: impact.fallbackRequired ? "FULL" : "SELECTIVE",
@@ -187,6 +213,9 @@ export async function observe(options) {
                 totalTestCount: profile.testFilePaths.length,
                 fallbackReasons: impact.fallbackReasons,
                 proposedCommands: (commandPlan?.commands ?? []).map(commandSpecToString),
+                goScope: profile.diffciConfig?.go?.scope,
+                vueScope: profile.vueScope ? { packageRoot: hashPath(profile.vueScope.packageRoot), testConfig: hashPath(profile.vueScope.testConfig) } : undefined,
+                scopedTestFiles: profile.vueScope ? profile.testFilePaths.map(hashPath) : undefined,
                 commandRefusalReason: commandPlan?.refusalReason,
                 unroutedTestPaths: (commandPlan?.unroutedPaths ?? []).map(hashPath),
                 blindSpot: profile.testUniverse?.blindSpot === true,
@@ -197,6 +226,8 @@ export async function observe(options) {
                     confidence: graphResult.confidence,
                     effectiveConfidence: impact.effectiveGraphConfidence,
                     durationMs: Math.round(graphResult.performance.durationMs),
+                    phasesMs: graphResult.performance.phasesMs,
+                    adapterMetrics: graphResult.performance.adapterMetrics,
                 },
                 pathBaseline: {
                     mode: baseline.fallbackRequired ? "FULL" : "SELECTIVE",

package/docs/agent-adoption-kit.md

@@ -0,0 +1,95 @@
+# DiffCI Agent Adoption Kit
+
+Use this when adding DiffCI to a repository or opening a small adoption PR.
+
+## One-Sentence Positioning
+
+DiffCI gives AI coding agents a safe default CI/CD validation command.
+
+## Maintainer Install Snippet
+
+```md
+## Add DiffCI for AI coding agents
+
+Run:
+
+```bash
+npx @diffci.com/diffci@latest init
+```
+
+Then ask your coding agent to run:
+
+```bash
+npx @diffci.com/diffci@latest check
+```
+
+DiffCI is observation-only by default: it analyzes the change, writes a report outside the checkout,
+sends nothing unless explicitly configured, and does not run, skip, cancel, or reorder tests.
+```
+
+## Agent Instruction Snippet
+
+```md
+Before marking changes PR-ready, run:
+
+```bash
+npx @diffci.com/diffci@latest check
+```
+
+Use DiffCI output to understand which tests and CI paths are relevant. Do not treat a DiffCI selection
+as permission to skip required project CI.
+```
+
+## GitHub Search Queries
+
+Find repositories already prepared for coding agents:
+
+```text
+filename:AGENTS.md
+filename:CLAUDE.md
+path:.cursor/rules
+filename:copilot-instructions.md
+```
+
+Prioritize repositories that:
+
+- use JavaScript, TypeScript, Vue, or Go in a normal GitHub Actions workflow;
+- already accept small docs/config PRs;
+- have active maintainers and recent CI runs;
+- already document agent behavior.
+
+Avoid repositories where:
+
+- CI is security-sensitive and maintainers ask not to add tools;
+- there is no clear test command or GitHub Actions setup;
+- the project is inactive.
+
+## Small PR Template
+
+```md
+Title: Add optional DiffCI instructions for AI coding agents
+
+This adds an optional instruction for coding agents to run DiffCI before marking changes PR-ready.
+
+DiffCI is observation-only by default:
+
+- it analyzes the change and writes a local report;
+- it sends nothing without explicit configuration;
+- it does not run, skip, cancel, or reorder tests;
+- the repository's existing required CI remains authoritative.
+
+Default command:
+
+```bash
+npx @diffci.com/diffci@latest check
+```
+
+This PR does not make DiffCI a required check.
+```
+
+## Links
+
+- Agent docs: https://diffci.com/docs/ai-agents.html
+- llms.txt: https://diffci.com/llms.txt
+- npm: https://www.npmjs.com/package/@diffci.com/diffci
+- GitHub release: https://github.com/DiffCI/DiffCI.com/releases/latest

package/docs/agent-adoption-targets.md

@@ -0,0 +1,52 @@
+# Agent Adoption Targets
+
+Generated 2026-09-21 from GitHub search for repositories already centered on `AGENTS.md`,
+`CLAUDE.md`, Cursor/Codex/Claude Code workflows, or agent instruction templates.
+
+Do not open drive-by PRs blindly. Review each repository's contribution policy first and use the
+small optional-instruction PR from [`agent-adoption-kit.md`](agent-adoption-kit.md).
+
+## Best First Targets
+
+| Repository | Why it fits |
+| --- | --- |
+| [`agentsmd/agents.md`](https://github.com/agentsmd/agents.md) | Defines the `AGENTS.md` convention. A DiffCI example would reach the broadest agent-instruction audience. |
+| [`FerroxLabs/agents-md`](https://github.com/FerroxLabs/agents-md) | Explicitly targets Claude Code, Codex, Gemini, Cursor, and verification loops. |
+| [`ciembor/agent-rules-books`](https://github.com/ciembor/agent-rules-books) | Curated rules for AI coding agents; good fit for a validation command snippet. |
+| [`jbarbier/CLAUDE.md`](https://github.com/jbarbier/CLAUDE.md) | Drop-in Claude/Codex/Cursor instruction file; likely accepts concise validation guidance. |
+| [`agent-sh/agnix`](https://github.com/agent-sh/agnix) | Linter/LSP for agent instruction files; possible future integration target. |
+| [`jsynowiec/node-typescript-boilerplate`](https://github.com/jsynowiec/node-typescript-boilerplate) | Real Node/TypeScript boilerplate with GitHub Actions and `AGENTS.md`, useful as a practical adoption example. |
+
+## Secondary Targets
+
+| Repository | Why it fits |
+| --- | --- |
+| [`BayramAnnakov/claude-reflect`](https://github.com/BayramAnnakov/claude-reflect) | Syncs learning into `CLAUDE.md` and `AGENTS.md`; validation-command guidance may fit. |
+| [`josix/awesome-claude-md`](https://github.com/josix/awesome-claude-md) | Curated collection; submit DiffCI as a validation-pattern example. |
+| [`TheDecipherist/claude-code-mastery`](https://github.com/TheDecipherist/claude-code-mastery) | Guide-style repo; useful place for the agent-safe validation command. |
+| [`microsoft/skills`](https://github.com/microsoft/skills) | Agent skills and MCP ecosystem. Higher bar; review contribution rules before proposing. |
+| [`mxyhi/ok-skills`](https://github.com/mxyhi/ok-skills) | Curated skills/playbooks for Codex, Claude Code, Cursor, and other tools. |
+
+## PR Order
+
+1. Start with documentation/example repos, not large application repos.
+2. Add only an optional validation instruction, never a required check.
+3. Link to `https://diffci.com/docs/ai-agents.html` and `https://diffci.com/llms.txt`.
+4. State that DiffCI sends nothing and changes no CI behavior by default.
+5. If maintainers ask for a workflow, suggest `npx @diffci.com/diffci@latest init --workflow`.
+
+## Minimal Patch Shape
+
+Add this to the repository's agent instruction file:
+
+```md
+Before marking changes PR-ready, run:
+
+```bash
+npx @diffci.com/diffci@latest check
+```
+
+DiffCI is observation-only by default: it analyzes the change, writes a report outside the checkout,
+sends nothing unless explicitly configured, and does not run, skip, cancel, or reorder tests. Existing
+required CI remains authoritative.
+```

package/docs/ai-agents.md

@@ -42,6 +42,29 @@ Then verify the workflow:
 npx @diffci.com/diffci@latest verify-workflow
 ```
 
+## Copy-Paste Adoption
+
+For a maintainer-facing snippet, PR template, and GitHub search queries for repositories that already
+use agent instruction files, see [`agent-adoption-kit.md`](agent-adoption-kit.md).
+For a first-pass list of repositories to review before opening PRs, see
+[`agent-adoption-targets.md`](agent-adoption-targets.md).
+
+Examples:
+
+- [`examples/agent-node`](../examples/agent-node)
+- [`examples/agent-python`](../examples/agent-python)
+- [`examples/agent-monorepo`](../examples/agent-monorepo)
+
+## MCP
+
+Agents that support MCP can run DiffCI as a native stdio tool server:
+
+```bash
+npx -p @diffci.com/diffci@latest diffci-mcp
+```
+
+See [`mcp.md`](mcp.md).
+
 ## Agent Policy
 
 Agents should: