codetrellis 0.0.0-stage → 0.3.0

package/src/backend/mcp/tools/system-docs-tools.js

@@ -0,0 +1,168 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var system_docs_tools_exports = {};
+__export(system_docs_tools_exports, {
+  register: () => register
+});
+module.exports = __toCommonJS(system_docs_tools_exports);
+var import_zod = require("zod");
+var import_helpers = require("../helpers");
+function register(server, deps) {
+  server.registerTool(
+    "list_system_docs",
+    {
+      description: "List every system documentation entry for a project. Returns summaries (no body) ordered by most-recently-updated. Each entry carries title / slug / owner / tags / lastVerifiedAt / capturedAgainstCommit so the UI (or agent) can decide which doc to open next without reading bodies. System docs describe the system as it currently is; for plan-scoped specs use list_items + kind=object.",
+      inputSchema: {
+        project_path: import_zod.z.string().describe("Absolute path to the project root"),
+        search: import_zod.z.string().optional().describe("Optional substring filter over title + body (case-insensitive)")
+      }
+    },
+    async ({ project_path, search }) => {
+      const docs = search ? deps.systemDocsService.searchSystemDocs(project_path, search) : deps.systemDocsService.listSystemDocs(project_path);
+      return { content: [{ type: "text", text: JSON.stringify({ projectPath: project_path, count: docs.length, docs }, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "read_system_doc",
+    {
+      description: 'Read a single system doc by UID (preferred \u2014 stable across renames) or by (project_path + slug). Returns the full doc including markdown body, references, ownership, and freshness stamps. Use this when you need to *read* a doc to ground a plan or answer "how does X work?".',
+      inputSchema: {
+        uid: import_zod.z.string().optional().describe("Doc UID \u2014 preferred lookup"),
+        project_path: import_zod.z.string().optional().describe("Required when looking up by slug"),
+        slug: import_zod.z.string().optional().describe("Filesystem slug under .codetrellis/docs/")
+      }
+    },
+    async ({ uid, project_path, slug }) => {
+      let doc = uid ? deps.systemDocsService.getSystemDoc(uid) : null;
+      if (!doc && project_path && slug) {
+        doc = deps.systemDocsService.getSystemDocBySlug(project_path, slug);
+      }
+      if (!doc) {
+        return { content: [{ type: "text", text: `System doc not found (uid=${uid ?? ""}, slug=${slug ?? ""})` }], isError: true };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(doc, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "write_system_doc",
+    {
+      description: "Create or update a system doc. When `uid` is supplied the existing doc is updated (absent fields are preserved). When omitted, a new doc is created and assigned a fresh UID. The on-disk file at .codetrellis/docs/<slug>.md is written atomically. `references` may carry { files, symbols, items, plans, urls } \u2014 used by the freshness sensor and the inline links in the doc viewer. **Updating the body does NOT touch the captured commit stamp** \u2014 call verify_system_doc after meaningful edits to re-stamp.",
+      inputSchema: {
+        uid: import_zod.z.string().optional().describe("UID of an existing doc to update; omit to create a new one"),
+        project_path: import_zod.z.string().describe("Absolute path to the project root"),
+        title: import_zod.z.string().optional(),
+        body: import_zod.z.string().optional().describe("Markdown body \u2014 no frontmatter (added on serialise)"),
+        owner: import_zod.z.string().nullable().optional().describe("Free-form ownership label; null clears"),
+        tags: import_zod.z.array(import_zod.z.string()).optional(),
+        references: import_zod.z.object({
+          files: import_zod.z.array(import_zod.z.string()).optional(),
+          symbols: import_zod.z.array(import_zod.z.string()).optional(),
+          items: import_zod.z.array(import_zod.z.string()).optional(),
+          plans: import_zod.z.array(import_zod.z.string()).optional(),
+          urls: import_zod.z.array(import_zod.z.string()).optional()
+        }).optional(),
+        slug: import_zod.z.string().optional().describe("Override the auto-derived filesystem slug (rare)")
+      }
+    },
+    async (args, extra) => {
+      const { author, authorType } = (0, import_helpers.authorFromExtra)(deps, extra);
+      if (args.uid) {
+        const updated = deps.systemDocsService.updateSystemDoc(args.uid, {
+          author,
+          authorType,
+          title: args.title,
+          body: args.body,
+          owner: args.owner === void 0 ? void 0 : args.owner,
+          tags: args.tags,
+          references: args.references
+        });
+        if (!updated) {
+          return { content: [{ type: "text", text: `System doc ${args.uid} not found` }], isError: true };
+        }
+        const n2 = deps.broadcast("system-doc-updated", { uid: updated.uid, projectPath: updated.projectPath });
+        deps.saveNow(() => deps.exportDatabase());
+        return (0, import_helpers.resultWithMeta)(updated, n2);
+      }
+      if (!args.title) {
+        return { content: [{ type: "text", text: "title is required for new docs" }], isError: true };
+      }
+      const created = deps.systemDocsService.createSystemDoc({
+        projectPath: args.project_path,
+        title: args.title,
+        body: args.body,
+        owner: args.owner,
+        tags: args.tags,
+        references: args.references,
+        slug: args.slug,
+        author,
+        authorType
+      });
+      const n = deps.broadcast("system-doc-created", { uid: created.uid, projectPath: created.projectPath });
+      deps.saveNow(() => deps.exportDatabase());
+      return (0, import_helpers.resultWithMeta)(created, n);
+    }
+  );
+  server.registerTool(
+    "delete_system_doc",
+    {
+      description: "Delete a system doc and its on-disk file. An unknown uid is an error.",
+      inputSchema: { uid: import_zod.z.string() }
+    },
+    async ({ uid }) => {
+      const ok = deps.systemDocsService.deleteSystemDoc(uid);
+      if (!ok) return { content: [{ type: "text", text: `System doc ${uid} not found` }], isError: true };
+      const n = deps.broadcast("system-doc-removed", { uid });
+      deps.saveNow(() => deps.exportDatabase());
+      return (0, import_helpers.resultWithMeta)({ ok, uid }, n);
+    }
+  );
+  server.registerTool(
+    "verify_system_doc",
+    {
+      description: 'Mark a system doc as "accurate against current HEAD" \u2014 re-stamps captured_against_commit + last_verified_at to now. Use this after reading the doc end-to-end and confirming it still matches the code. The freshness sensor compares this stamp to the current HEAD to decide whether the doc badge should be green / yellow / red.',
+      inputSchema: { uid: import_zod.z.string() }
+    },
+    async ({ uid }) => {
+      const doc = deps.systemDocsService.verifySystemDoc(uid);
+      if (!doc) {
+        return { content: [{ type: "text", text: `System doc ${uid} not found` }], isError: true };
+      }
+      const n = deps.broadcast("system-doc-verified", { uid, capturedAgainstCommit: doc.capturedAgainstCommit });
+      deps.saveNow(() => deps.exportDatabase());
+      return (0, import_helpers.resultWithMeta)(doc, n);
+    }
+  );
+  server.registerTool(
+    "check_doc_freshness",
+    {
+      description: "Compute the freshness verdict for a system doc: current (green) / moved (yellow) / stale (red). Pure read \u2014 does not modify the doc. Useful for deciding when to re-verify, especially after a `git pull`.",
+      inputSchema: { uid: import_zod.z.string() }
+    },
+    async ({ uid }) => {
+      const report = deps.systemDocsService.getFreshness(uid);
+      if (!report) {
+        return { content: [{ type: "text", text: `System doc ${uid} not found` }], isError: true };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(report, null, 2) }] };
+    }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  register
+});

package/src/backend/mcp/tools/terminal-tools.js

@@ -0,0 +1,186 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var terminal_tools_exports = {};
+__export(terminal_tools_exports, {
+  register: () => register
+});
+module.exports = __toCommonJS(terminal_tools_exports);
+var import_zod = require("zod");
+const agentPresetEnum = import_zod.z.enum(["shell", "claude", "codex", "aider"]);
+function register(server, deps) {
+  function withSessionId(session) {
+    return { session_id: session.id, ...session };
+  }
+  server.registerTool(
+    "terminal_create",
+    {
+      description: 'Create a new terminal session in CodeTrellis. Returns `session_id`, which is what terminal_write / terminal_read / terminal_kill take. Preset "shell" opens a plain shell; "claude", "codex", "aider" open a shell and launch that agent after 500ms. Multiple terminals can run concurrently (up to 20). By default the new terminal is focused in the UI \u2014 set focus: false for background terminals that shouldn\'t steal the user\'s view.',
+      inputSchema: {
+        preset: agentPresetEnum.optional().describe('Agent preset or plain shell. Default: "shell".'),
+        cwd: import_zod.z.string().optional().describe("Working directory. Defaults to the active project root."),
+        title: import_zod.z.string().optional().describe("Tab title. Auto-generated if omitted."),
+        focus: import_zod.z.boolean().optional().describe("Focus the new terminal tab in the UI. Default true. Set false for background terminals.")
+      }
+    },
+    async ({ preset, cwd, title, focus }) => {
+      try {
+        const session = deps.terminalService.createTerminal({
+          preset: preset ?? "shell",
+          cwd,
+          title
+        });
+        deps.broadcast("terminal-created", { session, focus: focus !== false });
+        return {
+          content: [{ type: "text", text: JSON.stringify(withSessionId(session), null, 2) }]
+        };
+      } catch (err) {
+        return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+      }
+    }
+  );
+  server.registerTool(
+    "terminal_write",
+    {
+      description: 'Send input to a terminal session (keystrokes, commands). The text is written as-is \u2014 include "\\n" to press Enter. Use terminal_list to find active session IDs. Each terminal is independent \u2014 target the right one. Set focus: true to switch the UI to this terminal tab so the user sees the output live. IMPORTANT: Before writing, make sure you know what is running in the target terminal (use terminal_read first). Never write to your own host terminal \u2014 if you registered with host_terminal_id, writes to that terminal are blocked automatically.',
+      inputSchema: {
+        session_id: import_zod.z.string().describe("Terminal session ID (from terminal_create or terminal_list)."),
+        input: import_zod.z.string().describe('Text to write. Include "\\n" to execute a command.'),
+        focus: import_zod.z.boolean().optional().describe("Focus this terminal tab in the UI before writing. Default false.")
+      }
+    },
+    async ({ session_id, input, focus }, _extra) => {
+      const callerSessionId = deps.sessionId;
+      if (callerSessionId) {
+        const hostTerminalId = deps.sessionService.getHostTerminalId(callerSessionId);
+        if (hostTerminalId && hostTerminalId === session_id) {
+          return {
+            content: [{
+              type: "text",
+              text: `BLOCKED: Terminal ${session_id} is your own host terminal. Writing to it would create a feedback loop (you'd be typing into your own stdin). Use terminal_write only for OTHER terminals. If you need to run commands, execute them directly in your own shell \u2014 don't route them through terminal_write.`
+            }],
+            isError: true
+          };
+        }
+      }
+      const unescaped = input.replace(/\\n/g, "\n").replace(/\\r/g, "\r").replace(/\\t/g, "	");
+      if (focus) {
+        deps.broadcast("ui-terminal-focus", { sessionId: session_id });
+      }
+      const ok = deps.terminalService.writeTerminal(session_id, unescaped);
+      if (!ok) {
+        return { content: [{ type: "text", text: `Terminal ${session_id} not found or not alive.` }], isError: true };
+      }
+      return { content: [{ type: "text", text: `Wrote ${unescaped.length} chars to ${session_id}` }] };
+    }
+  );
+  server.registerTool(
+    "terminal_read",
+    {
+      description: "Read recent output from a terminal session. Returns the last N lines of terminal output with ANSI codes stripped (plain text). Useful for checking command results, build output, test results, or agent responses. The terminal keeps a 64KB scrollback buffer \u2014 older output is lost.",
+      inputSchema: {
+        session_id: import_zod.z.string().describe("Terminal session ID."),
+        lines: import_zod.z.number().int().min(1).max(500).optional().describe("Number of lines to return. Default 50.")
+      }
+    },
+    async ({ session_id, lines }) => {
+      const output = deps.terminalService.readTerminalOutput(session_id, lines);
+      if (output === null) {
+        return { content: [{ type: "text", text: `Terminal ${session_id} not found.` }], isError: true };
+      }
+      return { content: [{ type: "text", text: output }] };
+    }
+  );
+  server.registerTool(
+    "terminal_list",
+    {
+      description: "List all terminal sessions with their ID, preset, title, PID, and alive status. Use this to find the right session_id for terminal_write / terminal_read.",
+      inputSchema: {
+        alive_only: import_zod.z.boolean().optional().describe("Only show alive sessions. Default true.")
+      }
+    },
+    async ({ alive_only }) => {
+      let sessions = deps.terminalService.listTerminals();
+      if (alive_only !== false) {
+        sessions = sessions.filter((s) => s.alive);
+      }
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(sessions.map(withSessionId), null, 2)
+        }]
+      };
+    }
+  );
+  server.registerTool(
+    "terminal_kill",
+    {
+      description: "Kill a terminal session. The terminal tab is removed from the CodeTrellis UI.",
+      inputSchema: {
+        session_id: import_zod.z.string().describe("Terminal session ID to kill.")
+      }
+    },
+    async ({ session_id }) => {
+      const ok = deps.terminalService.killTerminal(session_id);
+      if (!ok) {
+        return { content: [{ type: "text", text: `Terminal ${session_id} not found.` }], isError: true };
+      }
+      deps.broadcast("terminal-killed", { id: session_id });
+      return { content: [{ type: "text", text: `Killed terminal ${session_id}` }] };
+    }
+  );
+  server.registerTool(
+    "terminal_resize",
+    {
+      description: "Resize a terminal session (cols x rows). Useful before reading output to ensure clean line wrapping.",
+      inputSchema: {
+        session_id: import_zod.z.string(),
+        cols: import_zod.z.number().int().min(40).max(400).describe("Column width."),
+        rows: import_zod.z.number().int().min(10).max(100).describe("Row height.")
+      }
+    },
+    async ({ session_id, cols, rows }) => {
+      const ok = deps.terminalService.resizeTerminal(session_id, cols, rows);
+      if (!ok) {
+        return { content: [{ type: "text", text: `Terminal ${session_id} not found or not alive.` }], isError: true };
+      }
+      return { content: [{ type: "text", text: `Resized ${session_id} to ${cols}x${rows}` }] };
+    }
+  );
+  server.registerTool(
+    "terminal_focus",
+    {
+      description: "Switch the terminal panel to show a specific terminal tab. Use this when you want the user to see a particular terminal's output \u2014 e.g. before writing commands the user should watch, or after a background terminal produces interesting results. Also opens the terminal panel if it's hidden.",
+      inputSchema: {
+        session_id: import_zod.z.string().describe("Terminal session ID to focus.")
+      }
+    },
+    async ({ session_id }) => {
+      const sessions = deps.terminalService.listTerminals();
+      const exists = sessions.some((s) => s.id === session_id);
+      if (!exists) {
+        return { content: [{ type: "text", text: `Terminal ${session_id} not found.` }], isError: true };
+      }
+      deps.broadcast("ui-terminal-focus", { sessionId: session_id });
+      return { content: [{ type: "text", text: `Focused terminal ${session_id}` }] };
+    }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  register
+});

package/src/backend/mcp/tools/test-tools.js

@@ -0,0 +1,117 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var test_tools_exports = {};
+__export(test_tools_exports, {
+  register: () => register
+});
+module.exports = __toCommonJS(test_tools_exports);
+var import_zod = require("zod");
+var import_helpers = require("../helpers");
+var import_test_results = require("../../services/tests/test-results");
+var import_grounding = require("../../services/tests/grounding");
+var import_teammate_runs = require("../../services/tests/teammate-runs");
+var import_confined_fs = require("../../services/confined-fs");
+const noProject = { isError: true, content: [{ type: "text", text: "No project is open, and none was named." }] };
+const text = (data) => ({ content: [{ type: "text", text: JSON.stringify(data, null, 2) }] });
+function register(server, deps) {
+  server.registerTool(
+    "report_tests",
+    {
+      description: "Hand over a test run's JUnit report so CodeTrellis keeps each test's result: which passed, failed, errored or was skipped, and the first line of each failure. CodeTrellis never runs tests; run them yourself with a JUnit reporter (vitest --reporter=junit, jest-junit, pytest --junitxml, go-junit-report, Playwright's junit reporter) and pass the file it wrote. Reporting the same file twice changes nothing; an older run never replaces a newer result. Returns the totals and the failing tests by name.",
+      inputSchema: {
+        path: import_zod.z.string().min(1).max(500).describe("The JUnit report, relative to the project root (or absolute inside it)."),
+        project_path: import_zod.z.string().optional().describe("Absolute path of an opened project. Defaults to the active project.")
+      }
+    },
+    async ({ path: file, project_path }, extra) => {
+      const root = project_path ?? deps.getActiveProjectPath();
+      if (!root) return noProject;
+      try {
+        const out = (0, import_test_results.ingestTestReport)(root, file, (0, import_helpers.authorFromExtra)(deps, extra));
+        if (!out.already) deps.broadcast("tests-reported", { project: root });
+        const r = out.report;
+        const failing = r.failed + r.errors;
+        return text({
+          report: r.path,
+          ran_at: new Date(r.ranAt).toISOString(),
+          totals: { tests: r.tests, passed: r.passed, failing, skipped: r.skipped },
+          says: `${r.tests} test${r.tests === 1 ? "" : "s"}, ${failing ? `${failing} failing` : "none failing"}${r.skipped ? `, ${r.skipped} skipped` : ""}${out.already ? " (already reported; nothing changed)" : ""}.`,
+          failing: out.failing.map((f) => ({ test: f.label, result: f.result, why: f.message })),
+          ...out.truncated ? { note: "The report has more tests than are read; the rest are not counted." } : {}
+        });
+      } catch (err) {
+        if (err instanceof import_test_results.TestReportError) return { isError: true, content: [{ type: "text", text: err.message }] };
+        throw err;
+      }
+    }
+  );
+  server.registerTool(
+    "get_test_results",
+    {
+      description: 'What the last test runs said, from the reports handed over with report_tests or as a test criterion\'s evidence: each test\'s last result and when that run happened, failing first. Pass match to narrow to tests whose file, class or suite contains it (e.g. "billing/invoice"), or failing_only. Pass for_file to ask about a source file instead: its tests are those whose test file imports it (directly or through a barrel), and it reads passing, failing, "tests older than the code" (it changed after they last ran \u2014 run them again before claiming done) or no tests. A teammate\'s run read from the plans folder (shared task state) counts too, judged by the commit it ran on, and is named in `from` and `teammates`. CodeTrellis never runs tests itself.',
+      inputSchema: {
+        match: import_zod.z.string().max(300).optional(),
+        failing_only: import_zod.z.boolean().optional(),
+        for_file: import_zod.z.string().min(1).max(500).optional().describe("A source file, relative to the project root: its tests and whether they still hold."),
+        project_path: import_zod.z.string().optional().describe("Absolute path of an opened project. Defaults to the active project.")
+      }
+    },
+    async ({ match, failing_only, for_file, project_path }) => {
+      const root = project_path ?? deps.getActiveProjectPath();
+      if (!root) return noProject;
+      if (for_file) {
+        try {
+          const g = (0, import_grounding.groundingOf)(root, for_file);
+          return text({
+            file: g.path,
+            state: g.state,
+            says: g.words,
+            test_files: g.testFiles,
+            ...g.from ? { from: { who: g.from.who, verified: g.from.verified, commit: g.from.commit, ran_at: new Date(g.from.at).toISOString() } } : {},
+            ...g.lastRunAt ? { last_run_at: new Date(g.lastRunAt).toISOString() } : {},
+            ...g.changedAt ? { changed_at: new Date(g.changedAt).toISOString() } : {},
+            tests: g.tests.filter((t) => !failing_only || t.result === "failed" || t.result === "error").map((t) => ({ test: t.label, result: t.result, ...t.message ? { why: t.message } : {}, test_file: t.testFile }))
+          });
+        } catch (err) {
+          if (err instanceof import_confined_fs.ConfinementError) return { isError: true, content: [{ type: "text", text: `${for_file} is not a file inside this project.` }] };
+          if (err instanceof import_grounding.NotAFileError) return { isError: true, content: [{ type: "text", text: err.message }] };
+          throw err;
+        }
+      }
+      const tests = (0, import_test_results.listTestResults)(root, { match, limit: 200 }).filter((t) => !failing_only || t.result === "failed" || t.result === "error");
+      return text({
+        says: (0, import_test_results.testsSummary)(root).words,
+        tests: tests.map((t) => ({
+          test: t.label,
+          file: t.file,
+          result: t.result,
+          ...t.message ? { why: t.message } : {},
+          ran_at: new Date(t.ranAt).toISOString(),
+          report: t.reportPath
+        })),
+        reports: (0, import_test_results.listTestReports)(root, 5).map((r) => ({ report: r.path, ran_at: new Date(r.ranAt).toISOString(), tests: r.tests, failing: r.failed + r.errors, by: r.reportedBy })),
+        // D1.5a: teammates' latest runs, from the plans folder.
+        teammates: (0, import_teammate_runs.teammateRunSummaries)(root).map((r) => ({ who: r.who, verified: r.verified, commit: r.commit, ran_at: new Date(r.at).toISOString(), says: r.says }))
+      });
+    }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  register
+});