truthtrail 0.1.0 → 0.2.0

package/README.md

@@ -41,6 +41,24 @@ npx truthtrail check --base main
 
 `--approver <name>` is only for when someone explicitly approved. TruthTrail never guesses approvers.
 
+## MCP (Claude Code, Cursor, Copilot)
+
+`npx truthtrail init` also writes a `truthtrail` MCP server entry for each AI tool:
+
+| Tool | File |
+|---|---|
+| Claude Code | `.mcp.json` |
+| Cursor | `.cursor/mcp.json` |
+| Copilot (VS Code) | `.vscode/mcp.json` |
+
+Commit these files, and every teammate's AI gets the TruthTrail tools: `record_decision`, `list_decisions`, `why`, `check_branch`, `list_pending` and `resolve_pending`. When you ask "A or B?" and answer, the AI saves the decision itself.
+
+- Each tool asks once to allow or enable the `truthtrail` server. In Claude Code, approve the project MCP server. In Cursor, enable it under Settings → MCP. In VS Code, start or trust it from `mcp.json` and use Copilot Chat in **Agent** mode.
+- Existing entries and comments in these files are left alone. Only a missing `truthtrail` entry is added.
+- Skip all of this with `npx truthtrail init --no-mcp`.
+- If your company blocks MCP servers, the AI falls back to the `npx truthtrail` commands. The rules in `AGENTS.md` describe both.
+- For faster startup, install locally (`npm i -D truthtrail`) and point the entry at `node_modules/.bin/truthtrail`. `init` won't overwrite your change.
+
 ## Claude Code plugin
 
 The plugin (in `plugin/` of the TruthTrail repo) adds:

package/dist/index.js

@@ -4,8 +4,8 @@
 import { Command } from "commander";
 
 // src/commands/init.ts
-import { access, appendFile, mkdir as mkdir3, readFile as readFile5, realpath, writeFile as writeFile3 } from "fs/promises";
-import { join as join5 } from "path";
+import { access, appendFile, mkdir as mkdir3, readFile as readFile5, realpath as realpath2, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname2, join as join5 } from "path";
 
 // ../core/src/types.ts
 var DECISION_TYPES = ["decision", "assumption", "impact"];
@@ -293,6 +293,8 @@ This repo records product decisions in \`.decisions/\`. Follow these rules.
 
 **Find the ticket.** Take the ticket key from the branch name (e.g. \`feature/JIRA-231-\u2026\`). If there is none, ask the user once.
 
+**Tools.** If TruthTrail MCP tools are available (\`record_decision\`, \`list_decisions\`, \`why\`, \`check_branch\`, \`list_pending\`, \`resolve_pending\`), use them. Otherwise use the \`npx truthtrail\` commands below.
+
 **Before you implement,** run \`npx truthtrail list --ticket <KEY>\` and follow the decisions it shows. Treat \`rejected\` ones as must-rework.
 
 **Record a decision** with \`npx truthtrail decide\` when:
@@ -510,10 +512,109 @@ async function stopDecision(root, payload) {
     decision: "block",
     reason: `TruthTrail: ${pending.length} answered questions are not classified yet:
 ${items}
-For each one that changes behaviour a user or QA can see, run \`npx truthtrail decide --from-pending <n> --reason "\u2026"\`. Otherwise run \`npx truthtrail pending dismiss <n>\`.`
+Record each one that changes behaviour a user or QA can see; dismiss the rest. If TruthTrail MCP tools are available, use \`resolve_pending\` (action "record" or "dismiss"); otherwise run \`npx truthtrail decide --from-pending <n> --reason "\u2026"\` or \`npx truthtrail pending dismiss <n>\`.`
   };
 }
 
+// ../core/src/decide.ts
+import { realpath } from "fs/promises";
+var clean = (xs) => (xs ?? []).map((x) => x.trim()).filter(Boolean);
+async function recordDecision(root, cwd, cfg, input, now) {
+  if (!input.question?.trim()) throw new Error("--question is required");
+  if (!input.chosen?.trim()) throw new Error("--chosen is required");
+  const type = input.type ?? "decision";
+  if (!DECISION_TYPES.includes(type)) throw new Error(`--type must be one of ${DECISION_TYPES.join(", ")}`);
+  let ticket = input.ticket?.trim().toUpperCase() || null;
+  if (ticket && !new RegExp(`^(?:${cfg.ticketPattern})$`, "i").test(ticket)) {
+    throw new Error(`'${input.ticket}' is not a valid ticket key (expected pattern ${cfg.ticketPattern})`);
+  }
+  if (!ticket) {
+    const branch = await currentBranch(root);
+    ticket = detectTicket({ branch }, cfg.ticketPattern);
+    if (!ticket) throw new Error(`No ticket key found in branch '${branch ?? "(detached)"}'. Pass --ticket <KEY>.`);
+  }
+  const base = await realpath(cwd).catch(() => cwd);
+  const files = clean(input.files).map((f) => {
+    const rel = toRepoPath(root, base, f);
+    if (!rel) throw new Error(`--files: ${f} is outside the repository`);
+    return rel;
+  });
+  return writeRecord(
+    root,
+    cfg,
+    {
+      ticket,
+      type,
+      question: input.question.trim(),
+      options: clean(input.options),
+      chosen: input.chosen.trim(),
+      reason: input.reason?.trim() ?? "",
+      decided_by: await userName(root),
+      approver_claimed: input.approver?.trim() || null,
+      agent: input.agent,
+      source: input.source,
+      files,
+      supersedes: clean(input.supersedes),
+      body: input.body?.trim() ?? ""
+    },
+    now
+  );
+}
+async function resolvePending(root, cwd, cfg, index, overrides, now) {
+  const entry = (await listPending(root)).find((p) => p.index === index);
+  if (!entry) throw new Error(`No pending question #${index}. Run \`npx truthtrail pending list\`.`);
+  const given = Object.fromEntries(Object.entries(overrides).filter(([, v]) => v !== void 0));
+  const record = await recordDecision(
+    root,
+    cwd,
+    cfg,
+    { question: entry.question, chosen: entry.answer, options: entry.options, ...given },
+    now
+  );
+  await removePending(root, index);
+  return record;
+}
+
+// ../core/src/mcpConfig.ts
+import { execFile as execFile2 } from "child_process";
+import { promisify as promisify2 } from "util";
+import { applyEdits, findNodeAtLocation, modify, parseTree } from "jsonc-parser";
+var exec2 = promisify2(execFile2);
+var ARGS = ["-y", "truthtrail", "mcp"];
+var MCP_TARGETS = [
+  { file: ".mcp.json", key: "mcpServers", entry: { command: "npx", args: ARGS } },
+  { file: ".cursor/mcp.json", key: "mcpServers", entry: { command: "npx", args: ARGS } },
+  { file: ".vscode/mcp.json", key: "servers", entry: { type: "stdio", command: "npx", args: ARGS } }
+];
+var FORMAT = {};
+function upsertMcpEntry(existing, target) {
+  if (existing === null || existing.trim() === "") {
+    return { status: "created", text: `${JSON.stringify({ [target.key]: { truthtrail: target.entry } }, null, 2)}
+` };
+  }
+  const errors = [];
+  const tree = parseTree(existing, errors, { allowTrailingComma: true, disallowComments: false });
+  if (errors.length || !tree) return { status: "skipped", reason: "not valid JSON" };
+  if (tree.type !== "object") return { status: "skipped", reason: "top level is not a JSON object" };
+  const parent = findNodeAtLocation(tree, [target.key]);
+  if (parent && parent.type !== "object") return { status: "skipped", reason: `"${target.key}" is not an object` };
+  if (findNodeAtLocation(tree, [target.key, "truthtrail"])) return { status: "unchanged", text: existing };
+  try {
+    const text = applyEdits(existing, modify(existing, [target.key, "truthtrail"], target.entry, FORMAT));
+    return { status: "added", text };
+  } catch (e) {
+    return { status: "skipped", reason: e.message };
+  }
+}
+async function isGitIgnored(root, rel) {
+  try {
+    await exec2("git", ["check-ignore", "-q", "--", rel], { cwd: root });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // src/commands/init.ts
 async function readOrNull(path) {
   try {
@@ -524,7 +625,7 @@ async function readOrNull(path) {
   }
 }
 var exists = (p) => access(p).then(() => true, () => false);
-var real = (p) => realpath(p).catch(() => p);
+var real = (p) => realpath2(p).catch(() => p);
 function upsertIn(file, existing, inner) {
   try {
     return upsertBlock(existing, inner);
@@ -532,7 +633,7 @@ function upsertIn(file, existing, inner) {
     throw new Error(`${file}: ${e.message}`);
   }
 }
-async function runInit(cwd, log) {
+async function runInit(cwd, log, opts = {}) {
   const root = await repoRoot(cwd);
   const changes = [];
   const note = (file, what) => {
@@ -546,6 +647,9 @@ async function runInit(cwd, log) {
   const claude = await readOrNull(claudePath);
   const claudeIsAgents = claude !== null && await real(claudePath) === await real(agentsPath);
   const c = claude !== null && !claudeIsAgents ? upsertIn("CLAUDE.md", claude, CLAUDE_POINTER) : null;
+  const mcpPlan = opts.mcp === false ? [] : await Promise.all(
+    MCP_TARGETS.map(async (t) => ({ target: t, result: upsertMcpEntry(await readOrNull(join5(root, t.file)), t) }))
+  );
   const keep = join5(root, DEFAULT_CONFIG.decisionsDir, ".gitkeep");
   if (!await exists(keep)) {
     await mkdir3(join5(root, DEFAULT_CONFIG.decisionsDir), { recursive: true });
@@ -560,6 +664,23 @@ async function runInit(cwd, log) {
     await writeFile3(claudePath, c.text);
     note("CLAUDE.md", "updated");
   }
+  for (const { target, result } of mcpPlan) {
+    if (result.status === "skipped") {
+      log(`skipped ${target.file} (${result.reason})`);
+      continue;
+    }
+    if (result.status === "unchanged") continue;
+    const path = join5(root, target.file);
+    await mkdir3(dirname2(path), { recursive: true });
+    await writeFile3(path, result.text);
+    note(target.file, result.status === "created" ? "added" : "updated");
+    if (await isGitIgnored(root, target.file)) {
+      const dir = target.file.split("/")[0];
+      log(
+        `note: ${target.file} is git-ignored, so teammates won't get it (to share it: git add -f ${target.file}, or change "${dir}/" to "${dir}/*" and add !${target.file})`
+      );
+    }
+  }
   const configPath = join5(root, CONFIG_FILE);
   if (!await exists(configPath)) {
     await writeFile3(configPath, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}
@@ -579,16 +700,7 @@ async function runInit(cwd, log) {
 }
 
 // src/commands/decide.ts
-import { realpath as realpath2 } from "fs/promises";
-var list = (s, sep) => (s ?? "").split(sep).map((x) => x.trim()).filter(Boolean);
-async function repoFiles(root, cwd, files) {
-  const base = await realpath2(cwd);
-  return files.map((f) => {
-    const rel = toRepoPath(root, base, f);
-    if (!rel) throw new Error(`--files: ${f} is outside the repository`);
-    return rel;
-  });
-}
+var split = (s, sep) => s === void 0 ? void 0 : s.split(sep);
 function detectAgent(o, env) {
   if (o.agent) {
     if (!AGENT_NAMES.includes(o.agent)) throw new Error(`--agent must be one of ${AGENT_NAMES.join(", ")}`);
@@ -596,55 +708,26 @@ function detectAgent(o, env) {
   }
   return env.CLAUDECODE === "1" ? "claude-code" : "none";
 }
-async function runDecide(cwd, input, env, now) {
-  let o = input;
-  if (input.fromPending !== void 0) {
-    const entry = (await listPending(await repoRoot(cwd))).find((p) => p.index === Number(input.fromPending));
-    if (!entry) throw new Error(`No pending question #${input.fromPending}. Run \`npx truthtrail pending list\`.`);
-    const given = Object.fromEntries(Object.entries(input).filter(([, v]) => v !== void 0));
-    o = { question: entry.question, chosen: entry.answer, options: entry.options.join("|"), ...given };
-  }
-  const record = await decide(cwd, o, env, now);
-  if (input.fromPending !== void 0) await removePending(await repoRoot(cwd), Number(input.fromPending));
-  return record;
-}
-async function decide(cwd, o, env, now) {
-  if (!o.question?.trim()) throw new Error("--question is required");
-  if (!o.chosen?.trim()) throw new Error("--chosen is required");
-  const type = o.type ?? "decision";
-  if (!DECISION_TYPES.includes(type)) throw new Error(`--type must be one of ${DECISION_TYPES.join(", ")}`);
+async function runDecide(cwd, o, env, now) {
   const root = await repoRoot(cwd);
   const cfg = await loadConfig(root);
-  let ticket = o.ticket?.trim().toUpperCase() || null;
-  if (ticket && !new RegExp(`^(?:${cfg.ticketPattern})$`, "i").test(ticket)) {
-    throw new Error(`'${o.ticket}' is not a valid ticket key (expected pattern ${cfg.ticketPattern})`);
-  }
-  if (!ticket) {
-    const branch = await currentBranch(root);
-    ticket = detectTicket({ branch }, cfg.ticketPattern);
-    if (!ticket) throw new Error(`No ticket key found in branch '${branch ?? "(detached)"}'. Pass --ticket <KEY>.`);
-  }
   const agent = detectAgent(o, env);
-  return writeRecord(
-    root,
-    cfg,
-    {
-      ticket,
-      type,
-      question: o.question.trim(),
-      options: list(o.options, "|"),
-      chosen: o.chosen.trim(),
-      reason: o.reason?.trim() ?? "",
-      decided_by: await userName(root),
-      approver_claimed: o.approver?.trim() || null,
-      agent,
-      source: agent === "none" ? "manual" : "ai-session",
-      files: await repoFiles(root, cwd, list(o.files, ",")),
-      supersedes: list(o.supersedes, ","),
-      body: o.body?.trim() ?? ""
-    },
-    now
-  );
+  const input = {
+    question: o.question,
+    chosen: o.chosen,
+    options: split(o.options, "|"),
+    reason: o.reason,
+    type: o.type,
+    ticket: o.ticket,
+    files: split(o.files, ","),
+    approver: o.approver,
+    supersedes: split(o.supersedes, ","),
+    body: o.body,
+    agent,
+    source: agent === "none" ? "manual" : "ai-session"
+  };
+  if (o.fromPending !== void 0) return resolvePending(root, cwd, cfg, Number(o.fromPending), input, now);
+  return recordDecision(root, cwd, cfg, input, now);
 }
 
 // src/commands/list.ts
@@ -764,12 +847,151 @@ async function readStdin() {
   return Buffer.concat(chunks).toString("utf8");
 }
 
+// src/mcp/server.ts
+import { fileURLToPath } from "url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// src/mcp/agent.ts
+function agentFromClient(name) {
+  const n = (name ?? "").toLowerCase();
+  if (n.includes("claude")) return "claude-code";
+  if (n.includes("cursor")) return "cursor";
+  if (n.includes("codex")) return "codex";
+  if (/visual studio code|vscode|copilot/.test(n)) return "copilot";
+  return "other";
+}
+
+// src/mcp/server.ts
+var NO_REPO = "TruthTrail: not inside a git repository (open the project folder)";
+var ok = (value) => ({ content: [{ type: "text", text: JSON.stringify(value, null, 2) }] });
+var fail = (e) => ({
+  isError: true,
+  content: [{ type: "text", text: (e instanceof Error ? e.message : String(e)).split("\n")[0] }]
+});
+var decisionFields = {
+  question: z.string().describe("What needed deciding, e.g. 'Discount before or after tax?'"),
+  chosen: z.string().describe("What was picked"),
+  options: z.array(z.string()).optional().describe("The choices that were considered"),
+  reason: z.string().optional().describe("Why it was chosen"),
+  type: z.enum(DECISION_TYPES).optional().describe("decision (default), assumption (you assumed it without asking), or impact"),
+  ticket: z.string().optional().describe("Ticket key; defaults to the key in the branch name"),
+  files: z.array(z.string()).optional().describe("Files this decision affects"),
+  approver: z.string().optional().describe("Only if the user explicitly named who approved it. Never guess."),
+  supersedes: z.array(z.string()).optional().describe("Ids of older decisions this replaces"),
+  body: z.string().optional().describe("Short extra explanation")
+};
+function createServer(opts) {
+  const now = opts.now ?? (() => /* @__PURE__ */ new Date());
+  const server = new McpServer({ name: "truthtrail", version: "0.2.0" });
+  async function workspace() {
+    const candidates = [];
+    if (server.server.getClientCapabilities()?.roots) {
+      try {
+        const { roots } = await server.server.listRoots();
+        for (const r of roots) if (r.uri.startsWith("file://")) candidates.push(fileURLToPath(r.uri));
+      } catch {
+      }
+    }
+    candidates.push(opts.cwd);
+    for (const dir of candidates) {
+      try {
+        const root = await repoRoot(dir);
+        return { root, cwd: dir, cfg: await loadConfig(root) };
+      } catch {
+      }
+    }
+    throw new Error(NO_REPO);
+  }
+  const who = () => ({ agent: agentFromClient(server.server.getClientVersion()?.name), source: "ai-session" });
+  const run = (fn) => fn().then(ok, fail);
+  server.registerTool(
+    "record_decision",
+    {
+      description: "Record a product decision or assumption for the current ticket. Use it when the ticket was silent or ambiguous and the choice changes behaviour a user or QA can see, when following the ticket would break something, or when you assumed something visible (type: assumption). Not for pure implementation details.",
+      inputSchema: decisionFields
+    },
+    (args) => run(async () => {
+      const w = await workspace();
+      const r = await recordDecision(w.root, w.cwd, w.cfg, { ...args, ...who() }, now());
+      return { id: r.id, path: r.path, ticket: r.ticket };
+    })
+  );
+  server.registerTool(
+    "list_decisions",
+    {
+      description: "List recorded decisions (optionally for one ticket). Read these before implementing or testing a ticket and follow them.",
+      inputSchema: { ticket: z.string().optional() }
+    },
+    ({ ticket }) => run(async () => {
+      const w = await workspace();
+      return listRecords(w.root, w.cfg, ticket?.trim().toUpperCase() || void 0);
+    })
+  );
+  server.registerTool(
+    "why",
+    {
+      description: "Explain a file or line: last commit, AI or human authorship, linked decisions and the ticket.",
+      inputSchema: { target: z.string().describe("file or file:line, relative to the workspace") }
+    },
+    ({ target }) => run(async () => {
+      const w = await workspace();
+      return whyLocal(w.root, w.cfg, parseTarget(target), w.cwd);
+    })
+  );
+  server.registerTool(
+    "check_branch",
+    {
+      description: "Check this branch: ticket key, decisions and assumptions recorded, AI-assisted commits, and reminders.",
+      inputSchema: { base: z.string().optional().describe("branch to compare against (default main)") }
+    },
+    ({ base }) => run(async () => {
+      const w = await workspace();
+      return checkRepo(w.root, w.cfg, base ?? "main");
+    })
+  );
+  server.registerTool(
+    "list_pending",
+    { description: "Questions the user answered during this work that are not yet recorded or dismissed." },
+    () => run(async () => {
+      const w = await workspace();
+      return listPending(w.root);
+    })
+  );
+  server.registerTool(
+    "resolve_pending",
+    {
+      description: "Resolve a pending answered question: action 'record' if it changes behaviour a user or QA can see (fields override the captured values), otherwise 'dismiss'.",
+      inputSchema: {
+        index: z.number().int(),
+        action: z.enum(["record", "dismiss"]),
+        ...Object.fromEntries(Object.entries(decisionFields).map(([k, v]) => [k, v.optional()]))
+      }
+    },
+    (args) => run(async () => {
+      const w = await workspace();
+      const { index, action, ...fields } = args;
+      if (action === "dismiss") {
+        const hit = await removePending(w.root, index);
+        if (!hit) throw new Error(`No pending question #${index}.`);
+        return { dismissed: hit };
+      }
+      return resolvePending(w.root, w.cwd, w.cfg, index, { ...fields, ...who() }, now());
+    })
+  );
+  return server;
+}
+async function runMcp() {
+  await createServer({ cwd: process.cwd() }).connect(new StdioServerTransport());
+}
+
 // src/index.ts
 function buildProgram() {
   const program = new Command();
-  program.name("truthtrail").description("Record the decisions your AI coding agent makes, right next to the code.").version("0.1.0");
-  program.command("init").description("Set up TruthTrail in this repo (.decisions/, AGENTS.md rules, config)").action(async () => {
-    await runInit(process.cwd(), (l) => console.log(l));
+  program.name("truthtrail").description("Record the decisions your AI coding agent makes, right next to the code.").version("0.2.0");
+  program.command("init").description("Set up TruthTrail in this repo (.decisions/, AGENTS.md rules, MCP config, config)").option("--no-mcp", "don't write MCP config for Claude Code, Cursor and Copilot").action(async (o) => {
+    await runInit(process.cwd(), (l) => console.log(l), { mcp: o.mcp });
   });
   program.command("decide").description("Record a decision (or assumption) for the current ticket").option("--question <text>", "what needed deciding").option("--chosen <text>", "what was picked").option("--options <list>", "choices considered, separated by |").option("--reason <text>", "why").option("--type <type>", "decision | assumption | impact", "decision").option("--ticket <key>", "ticket key (default: from branch name)").option("--files <list>", "affected files, comma separated").option("--approver <name>", "who the user said approved it (never guess)").option("--supersedes <ids>", "ids of older decisions this replaces, comma separated").option("--agent <name>", "AI agent involved").option("--body <text>", "short extra explanation").option("--from-pending <n>", "record a question captured by the Claude Code hook", (v) => Number(v)).action(async (o) => {
     const r = await runDecide(process.cwd(), o, process.env, /* @__PURE__ */ new Date());
@@ -787,6 +1009,9 @@ function buildProgram() {
     console.log(output);
     process.exitCode = exitCode;
   });
+  program.command("mcp").description("Run the TruthTrail MCP server over stdio (used by Claude Code, Cursor, Copilot)").action(async () => {
+    await runMcp();
+  });
   const pending = program.command("pending").description("Questions captured by the Claude Code hook, not yet classified");
   pending.command("list").description("List pending questions").action(async () => console.log(await runPendingList(process.cwd())));
   pending.command("dismiss").description("Drop a pending question that does not change visible behaviour").argument("<n>", "pending index", (v) => Number(v)).action(async (n) => console.log(await runPendingDismiss(process.cwd(), n)));

package/package.json

@@ -1,13 +1,30 @@
 {
   "name": "truthtrail",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Record the decisions your AI coding agent makes, right next to the code.",
   "type": "module",
-  "bin": { "truthtrail": "dist/index.js" },
-  "files": ["dist", "README.md"],
-  "engines": { "node": ">=20" },
-  "scripts": { "build": "tsup" },
-  "dependencies": { "commander": "^12.1.0", "yaml": "^2.5.0" },
-  "devDependencies": { "@truthtrail/core": "*" },
+  "bin": {
+    "truthtrail": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "commander": "^12.1.0",
+    "jsonc-parser": "^3.3.1",
+    "yaml": "^2.5.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@truthtrail/core": "*"
+  },
   "license": "MIT"
 }