codetrellis 0.0.0-stage → 0.2.0

package/src/backend/services/material-signals.js

@@ -0,0 +1,141 @@
+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 material_signals_exports = {};
+__export(material_signals_exports, {
+  computeMaterialSignals: () => computeMaterialSignals
+});
+module.exports = __toCommonJS(material_signals_exports);
+var import_awareness_signals = require("./awareness-signals");
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+const listed = (names, max = 3) => names.length <= max ? names.join(", ") : `${names.slice(0, max).join(", ")} and ${names.length - max} more`;
+function computeMaterialSignals(tasks, current) {
+  const out = [];
+  const ordered = [...tasks].sort((a, b) => a.id.localeCompare(b.id));
+  const title = /* @__PURE__ */ new Map();
+  for (const t of ordered) for (const r of t.reads) title.set(r.owner, r.ownerTitle);
+  for (const t of ordered) title.set(t.id, t.title);
+  const labelsOf = (ids) => Object.fromEntries([...ids].sort().map((id) => [id, title.get(id) ?? id]));
+  const named = (ids) => listed(ids.map((id) => `\u201C${title.get(id) ?? id}\u201D`));
+  const withoutLabels = (subject) => {
+    const { labels: _labels, readBy: _readBy, ...rest } = subject;
+    return rest;
+  };
+  const emit = (kind, severity, key, subject, ids, summary) => out.push((0, import_awareness_signals.draft)(kind, severity, key, { ...subject, labels: labelsOf(ids) }, ids, summary, withoutLabels(subject)));
+  const readByOf = (m, ids) => {
+    const by = Object.fromEntries(ids.flatMap((id) => {
+      const who = ordered.find((t) => t.id === id)?.reads.find((r) => r.path === m)?.by;
+      return who ? [[id, who]] : [];
+    }));
+    return Object.keys(by).length ? { readBy: by } : {};
+  };
+  const materials = /* @__PURE__ */ new Set();
+  for (const t of ordered) {
+    for (const r of t.reads) materials.add(r.path);
+    for (const c of t.cited) materials.add(c.path);
+  }
+  for (const m of [...materials].sort()) {
+    const now = current[m] ?? null;
+    const readers = ordered.filter((t) => t.reads.some((r) => r.path === m));
+    const lastHash = (t) => t.reads.find((r) => r.path === m)?.sha256 ?? null;
+    const readersNamed = (ids) => listed(ids.map((id) => {
+      const by = ordered.find((t) => t.id === id)?.reads.find((r) => r.path === m)?.by;
+      return `\u201C${title.get(id) ?? id}\u201D${by ? ` (${by})` : ""}`;
+    }));
+    const changedCites = now === null ? [] : ordered.flatMap((t) => t.cited.filter((c) => c.path === m && c.sha256 !== null && c.sha256 !== now).map((c) => ({ task: t.id, ...c })));
+    const citers = [...new Set(changedCites.map((c) => c.task))];
+    const involved = [.../* @__PURE__ */ new Set([...citers, ...readers.map((t) => t.id)])].sort();
+    if (citers.length > 0 && involved.length >= 2) {
+      const parts = [...new Set(changedCites.map((c) => c.part))].sort();
+      const signedOff = [...new Set(changedCites.filter((c) => c.signedOff).map((c) => c.task))].sort();
+      const cites = `${citers.length === 1 ? `${named(citers)} cites` : `${plural(citers.length, "task")} cite`} ${listed(parts)}`;
+      const signed = signedOff.length === 0 ? "" : `; ${signedOff.length === citers.length && citers.length > 1 ? "all were" : signedOff.length === 1 && citers.length === 1 ? "it was" : `${signedOff.length} ${signedOff.length === 1 ? "was" : "were"}`} already signed off`;
+      const others = involved.filter((id) => !citers.includes(id));
+      const alsoUses = others.length ? `. ${named(others)} ${others.length === 1 ? "uses" : "use"} it too` : "";
+      emit(
+        "contract",
+        signedOff.length ? "high" : "medium",
+        `material:${m}`,
+        { material: m, parts, citedBy: citers.sort(), ...signedOff.length ? { signedOff } : {} },
+        involved,
+        `\`${m}\` changed. ${cites}${signed}${alsoUses}`
+      );
+      continue;
+    }
+    const hashes = new Set(readers.map(lastHash).filter((h) => h !== null));
+    if (readers.length >= 2 && hashes.size >= 2) {
+      const ids = readers.map((t) => t.id);
+      const readVersions = Object.fromEntries(readers.map((t) => [t.id, lastHash(t) === now ? "current" : "earlier"]));
+      const onCurrent = readers.filter((t) => lastHash(t) === now).map((t) => t.id);
+      const tail = onCurrent.length === 0 ? `; ${readers.length === 2 ? "neither" : "none"} has the current one` : `; ${named(onCurrent)} ${onCurrent.length === 1 ? "has" : "have"} the current one`;
+      emit(
+        "version-split",
+        "medium",
+        `material:${m}`,
+        { material: m, readVersions, ...readByOf(m, ids) },
+        ids,
+        `${readersNamed(ids)} read different versions of \`${m}\`${tail}`
+      );
+      continue;
+    }
+    if (now !== null && readers.length >= 2 && readers.every((t) => lastHash(t) !== null && lastHash(t) !== now)) {
+      const ids = readers.map((t) => t.id);
+      emit(
+        "stale-base",
+        "low",
+        `material:${m}`,
+        { material: m, ...readByOf(m, ids) },
+        ids,
+        `\`${m}\` changed after ${readersNamed(ids)} read it, and ${ids.length === 2 ? "neither" : "none"} has read it since`
+      );
+    }
+  }
+  const writers = /* @__PURE__ */ new Map();
+  for (const t of ordered) for (const o of new Set(t.outputs)) (writers.get(o) ?? writers.set(o, []).get(o)).push(t.id);
+  for (const [file, ids] of [...writers].sort(([a], [b]) => a.localeCompare(b))) {
+    if (ids.length < 2) continue;
+    emit(
+      "collision",
+      "medium",
+      `output:${file}`,
+      { material: file, file },
+      ids,
+      `${named(ids)} ${ids.length === 2 ? "both" : "all"} record \`${file}\` as their output`
+    );
+  }
+  for (const t of ordered) {
+    const brief = new Set(t.brief);
+    const outside = t.reads.filter((r) => !brief.has(r.path) && r.owner !== t.id);
+    if (outside.length === 0) continue;
+    const files = [...new Set(outside.map((r) => r.path))].sort();
+    const owners = [...new Set(outside.map((r) => r.owner))].filter((o) => o !== t.id).sort();
+    const ids = [t.id, ...owners];
+    emit(
+      "drift",
+      "low",
+      `material-drift:${t.id}`,
+      { material: files[0], files, by: t.id },
+      ids,
+      `${named([t.id])} read ${listed(files.map((f) => `\`${f}\``))}, which ${files.length === 1 ? "is" : "are"} not in its brief (given to ${named(owners)})`
+    );
+  }
+  return out;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  computeMaterialSignals
+});

package/src/backend/services/mcp-capabilities.js

@@ -0,0 +1,390 @@
+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 mcp_capabilities_exports = {};
+__export(mcp_capabilities_exports, {
+  McpAuthorizationError: () => McpAuthorizationError,
+  TOOL_CAPABILITIES: () => TOOL_CAPABILITIES,
+  assertMcpMayCall: () => assertMcpMayCall,
+  assertMcpProjectInScope: () => assertMcpProjectInScope,
+  listAuthorisedTools: () => listAuthorisedTools
+});
+module.exports = __toCommonJS(mcp_capabilities_exports);
+var import_peer_capabilities = require("./peer-capabilities");
+var import_trusted_roots = require("./trusted-roots");
+const TOOL_CAPABILITIES = Object.freeze({
+  // ── architecture-tools ──────────────────────────────────────────────
+  search_symbols: "read",
+  get_dependencies: "read",
+  check_architecture: "read",
+  list_cross_system_edges: "read",
+  check_conformity: "read",
+  // ── budget-tools ────────────────────────────────────────────────────
+  get_budget: "read",
+  set_budget: "write",
+  check_budget: "read",
+  // ── channel-tools ───────────────────────────────────────────────────
+  post_channel_event: "write",
+  list_channel_events: "read",
+  get_channel_thread: "read",
+  resolve_channel_event: "write",
+  dismiss_channel_event: "write",
+  // ── drift-tools ─────────────────────────────────────────────────────
+  get_deviations: "read",
+  reconcile: "write",
+  detect_deviations: "read",
+  list_proposed_changes: "read",
+  get_changes_summary: "read",
+  get_change_status: "read",
+  get_drift_report: "read",
+  capture_checkpoint: "write",
+  // ── git-tools ───────────────────────────────────────────────────────
+  // `commit_manifest_changes` and `resolve_conflict` mutate the repository,
+  // but only under `.codetrellis/` — the manifest this product owns. That is
+  // persisting plan state, which is what `write` means here.
+  commit_manifest_changes: "write",
+  get_team_activity: "read",
+  get_plan_history: "read",
+  get_plan_at_commit: "read",
+  diff_plan_between_commits: "read",
+  search_plan_history: "read",
+  detect_conflicts: "read",
+  resolve_conflict: "write",
+  // ── test-tools (Phase 32 B8.1) ──────────────────────────────────────
+  // Handing over a report keeps results in this machine's database: a write.
+  // Reading what the runs said is a read. Neither runs anything.
+  report_tests: "write",
+  get_test_results: "read",
+  // ── governance-tools ────────────────────────────────────────────────
+  get_freeze_status: "read",
+  verify_record: "read",
+  export_evidence: "read",
+  line_history: "read",
+  set_freeze: "write",
+  check_freeze: "read",
+  exempt_plan_from_freeze: "write",
+  // ── graph-tools ─────────────────────────────────────────────────────
+  // Driving the graph changes what is on the user's screen. That is not
+  // `read`, even though no data is written: an agent granted only `read`
+  // should not be able to move the view the user is looking at. `graph_export`
+  // and `graph_snapshot` return the graph's own contents and are `read`.
+  graph_focus: "write",
+  graph_set_mode: "write",
+  graph_set_scope: "write",
+  graph_select: "write",
+  graph_set_layout: "write",
+  graph_set_depth: "write",
+  graph_toggle_projection: "write",
+  graph_export: "read",
+  graph_snapshot: "read",
+  // Not `capture`: this returns whether the window is usable, never what
+  // is on it. Any agent about to drive the UI should be able to ask
+  // first — gating it behind a capability most installs withhold would
+  // leave exactly the agents that need it unable to check.
+  ui_ready: "read",
+  // ── intake-tools ────────────────────────────────────────────────────
+  create_plan_from_external: "write",
+  set_plan_external_ref: "write",
+  get_external_sync_state: "read",
+  mark_external_synced: "write",
+  list_plan_external_refs: "read",
+  // ── mobile-tools ────────────────────────────────────────────────────
+  // These drive a PAIRED DEVICE. `mobile_screenshot` returns a picture of
+  // someone's phone screen, which is `capture` for the same reason the
+  // desktop screenshot is.
+  mobile_navigate: "write",
+  mobile_screenshot: "capture",
+  mobile_present: "write",
+  // ── plan-item-tools ─────────────────────────────────────────────────
+  add_item: "write",
+  bulk_add_items: "write",
+  get_item: "read",
+  read_item_full: "read",
+  update_item: "write",
+  move_item: "write",
+  delete_item: "write",
+  claim_item: "write",
+  // A project skill's text; records the read as proof of use on the caller's own tasks (A8.4).
+  get_skill: "read",
+  // Phase 32 C5.1 — which worktree a section is worked in: a plan edit.
+  assign_workstream: "write",
+  get_next_item: "read",
+  // Retired in Phase 31.1 — it refuses. Kept one release so an agent that
+  // learned it gets a direction rather than a missing tool.
+  approve_gate: "read",
+  list_criteria: "read",
+  record_artefact: "write",
+  add_criterion: "write",
+  submit_criterion: "write",
+  // Phase 31 §8 — the loops. Reads: they report, and a check run is a
+  // record of what was found, never a decision.
+  check_criterion: "read",
+  get_worklist: "read",
+  run_checks: "read",
+  // Phase 31 §5 — the Brief. Reading a material hands over a file's
+  // contents, so it is `files`, as reading any project file is.
+  get_brief: "read",
+  list_materials: "read",
+  read_material: "files",
+  list_items: "read",
+  search_items: "read",
+  get_plan_timeline: "read",
+  restore_item_version: "write",
+  list_item_versions: "read",
+  list_item_comments: "read",
+  resolve_reference: "read",
+  add_item_comment: "write",
+  update_item_progress: "write",
+  set_item_blocked: "write",
+  add_item_attachment: "write",
+  delete_item_comment: "write",
+  delete_item_attachment: "write",
+  list_external_refs: "read",
+  add_external_ref: "write",
+  remove_external_ref: "write",
+  suggest_specs: "read",
+  get_plan_summary: "read",
+  // ── plan-tools ──────────────────────────────────────────────────────
+  // The four file-mapping tools are `files`: they read and write plan
+  // documents on disk rather than rows in the database.
+  create_plan: "write",
+  get_plan: "read",
+  update_plan: "write",
+  list_plans: "read",
+  get_stack: "read",
+  get_play_forward: "read",
+  list_recurring: "read",
+  list_rules: "read",
+  // Phase 33 R3: proposes only; a person decides in the app. No tool writes a rule.
+  propose_rule: "write",
+  // Phase 33 V1: what a change does to the architecture, between two commits. Read only.
+  review_change: "read",
+  get_spec_links: "read",
+  list_spec_proposals: "read",
+  reply_to_spec_proposal: "write",
+  propose_spec_change: "write",
+  // Asks the person; deletes nothing (plan deletion left MCP in Phase 32 §0.4c-3).
+  request_plan_deletion: "write",
+  export_plan_to_files: "files",
+  import_plan_from_files: "files",
+  discover_plan_files: "files",
+  unlink_plan_from_files: "write",
+  publish_plan_as_template: "write",
+  list_plan_templates: "read",
+  create_plan_from_template: "write",
+  import_external: "write",
+  copy_plan_as_prompt: "read",
+  set_plan_home_repo: "write",
+  add_plan_scope: "write",
+  remove_plan_scope: "write",
+  list_plan_pointers: "read",
+  list_plans_by_repo: "read",
+  // ── presence-tools ──────────────────────────────────────────────────
+  // These interrupt the user with a modal and wait for them. Intrusive,
+  // and squarely a change to desktop state.
+  present: "write",
+  await_ack: "write",
+  dismiss_presence: "write",
+  await_user_input: "write",
+  // Waiting on a person's answer changes nothing; the answer is spent by the next call.
+  await_decision: "read",
+  // Asks whether a file is held by a breakpoint; records the hit so the person can answer it (B4.2).
+  check_breakpoint: "read",
+  check_changes: "read",
+  list_check_runs: "read",
+  // Phase 33 C4b: a review bundle, and a review reported and kept as a check run, as check_changes keeps one.
+  get_review_bundle: "read",
+  report_review: "read",
+  // Another workstream's changed lines, from git (B3.1): the repository, not an agent's words.
+  get_line_changes: "read",
+  // ── project-config-tools ────────────────────────────────────────────
+  get_project_config: "read",
+  update_project_config: "write",
+  // ── review-tools ────────────────────────────────────────────────────
+  // Read-only by construction: review and pr-draft never touch the
+  // repository, and comparands / compare only read snapshots. Same call
+  // the peer matrix makes for the identical four methods.
+  list_comparands: "read",
+  compare_snapshots: "read",
+  review_plan: "read",
+  get_pr_draft: "read",
+  get_review_queue: "read",
+  // ── session-tools ───────────────────────────────────────────────────
+  // `register_session` is the handshake and is deliberately the cheapest
+  // grant: an agent that cannot register cannot report itself at all, and
+  // refusing it would make the Timeline lie about who is connected.
+  //
+  // `setup_agent_permissions` WRITES `.claude/settings.local.json` to
+  // auto-approve every CodeTrellis MCP tool. That is a tool which widens the
+  // caller's own approval posture, so it sits with `settings` and out of the
+  // defaults — the same reasoning that keeps `settings.update` off a paired
+  // phone.
+  register_session: "read",
+  set_active_plan: "write",
+  navigate_to: "write",
+  open_plan: "write",
+  toggle_panel: "write",
+  refresh_ui: "write",
+  rescan_project: "project",
+  set_baseline: "write",
+  list_recent_projects: "read",
+  pin_project: "project",
+  unpin_project: "project",
+  remove_recent_project: "project",
+  close_project: "project",
+  get_repo_identity: "read",
+  set_repo_alias: "project",
+  refresh_repo_origin: "project",
+  navigate_item_back: "write",
+  navigate_item_forward: "write",
+  toggle_activity_drawer: "write",
+  open_history_drawer: "write",
+  open_settings: "write",
+  close_settings: "write",
+  open_mcp_guide: "write",
+  setup_agent_permissions: "settings",
+  // ── system-docs-tools ───────────────────────────────────────────────
+  list_system_docs: "read",
+  read_system_doc: "read",
+  write_system_doc: "write",
+  delete_system_doc: "write",
+  verify_system_doc: "write",
+  check_doc_freshness: "read",
+  // ── terminal-tools — COMMAND EXECUTION ──────────────────────────────
+  // Every one of them, including the read-shaped ones. A terminal's
+  // scrollback is the output of commands and frequently holds secrets; the
+  // peer matrix makes the same call for `terminal.read` and `terminal.list`.
+  terminal_create: "terminal",
+  terminal_write: "terminal",
+  terminal_read: "terminal",
+  terminal_list: "terminal",
+  terminal_kill: "terminal",
+  terminal_resize: "terminal",
+  terminal_focus: "terminal",
+  // ── ui-tools ────────────────────────────────────────────────────────
+  // `screenshot` captures the CodeTrellis window and `clipboard_read` returns
+  // whatever the user last copied — which is routinely a password or a token.
+  // Neither is a file, so `files` does not describe them, and putting them in
+  // `read` would have handed both to every client by default.
+  screenshot: "capture",
+  select_item: "write",
+  open_project: "project",
+  clipboard_write: "write",
+  clipboard_read: "capture",
+  get_settings: "read",
+  update_settings: "settings",
+  get_logs: "read",
+  get_log_path: "read",
+  get_app_guide: "read",
+  // ── contribution-tools ──────────────────────────────────────────────
+  resolve_pantry_references: "read",
+  promote_to_contribution: "write",
+  list_contributions: "read",
+  accept_contributions: "write",
+  prepare_contributor_branch: "write",
+  // ── audio-tools — THE USER'S MICROPHONE ─────────────────────────────
+  start_audio_capture: "capture",
+  stop_audio_capture: "capture",
+  push_audio_chunk: "capture",
+  get_audio_context: "capture",
+  get_audio_status: "capture",
+  // ── peer-tools ──────────────────────────────────────────────────────
+  // `write_remote_terminal` drives a terminal on a PAIRED DEVICE. It is
+  // command execution wearing a different name, and it is the single tool
+  // this whole phase exists for: it was registered through the deprecated
+  // `server.tool()` API, so it was not even visible in the Agent Timeline.
+  get_peer_status: "read",
+  list_discovered_peers: "read",
+  list_paired_devices: "read",
+  list_peer_connections: "read",
+  unpair_device: "settings",
+  get_remote_state: "read",
+  list_remote_terminals: "terminal",
+  write_remote_terminal: "terminal",
+  get_remote_audio: "capture",
+  list_remote_input_requests: "read",
+  respond_remote_input: "write",
+  // ── awareness-tools ─────────────────────────────────────────────────
+  // Phase 32 A1.3. Reads only: who else is working, and where.
+  list_workstreams: "read",
+  get_awareness: "read",
+  check_footprint: "read",
+  // A2.4: an agent says what it is about to change. It writes only its own
+  // session's intent, which ends with the session.
+  declare_intent: "write",
+  // A2.6: the agent's own note beside a signal; it never sets the person's answer.
+  acknowledge_signal: "write",
+  // B5.4: the project as it was at a moment. Reads only, like replay.
+  get_state_at: "read"
+});
+class McpAuthorizationError extends Error {
+  code = "EMCP_FORBIDDEN";
+  /** The capability the caller was missing, for the settings hint. */
+  required;
+  constructor(message, required) {
+    super(message);
+    this.name = "McpAuthorizationError";
+    this.required = required;
+  }
+}
+function assertMcpMayCall(tool, grants) {
+  const required = TOOL_CAPABILITIES[tool];
+  if (!required) {
+    throw new McpAuthorizationError(
+      `Tool "${tool}" is not authorised for MCP clients. Every tool must be listed in TOOL_CAPABILITIES; unlisted tools are refused.`,
+      null
+    );
+  }
+  const held = grants ?? import_peer_capabilities.DEFAULT_GRANTS;
+  if (!held.includes(required)) {
+    throw new McpAuthorizationError(
+      `"${tool}" needs the "${required}" capability, which this installation does not grant to MCP clients. Turn it on in Settings \u2192 MCP Server, then try again.`,
+      required
+    );
+  }
+  return required;
+}
+function listAuthorisedTools() {
+  return Object.keys(TOOL_CAPABILITIES).sort();
+}
+function assertMcpProjectInScope(tool, args, scope) {
+  if (scope === "anywhere") return;
+  const planDir = args?.plan_dir;
+  if (typeof planDir === "string" && planDir.trim().length > 0 && !(0, import_trusted_roots.isTrustedPlanDir)(planDir)) {
+    throw new McpAuthorizationError(
+      `"${tool}" named a plan directory outside the projects this app has opened: "${planDir}". Plan directories are read from <opened project>/.codetrellis/plans/<slug>. Open the project first, or set MCP project scope to "anywhere" in Settings \u2192 MCP Server.`,
+      null
+    );
+  }
+  const candidate = args?.project_path;
+  if (typeof candidate !== "string" || candidate.trim().length === 0) return;
+  if (!(0, import_trusted_roots.isTrustedProjectRoot)(candidate)) {
+    const evicted = (0, import_trusted_roots.evictedHint)(candidate);
+    throw new McpAuthorizationError(
+      `"${tool}" named a project that is not open: "${candidate}". ` + (evicted ? evicted : 'Project roots come from the projects this app has opened, not from the request. Open it first, or set MCP project scope to "anywhere" in Settings \u2192 MCP Server.'),
+      null
+    );
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  McpAuthorizationError,
+  TOOL_CAPABILITIES,
+  assertMcpMayCall,
+  assertMcpProjectInScope,
+  listAuthorisedTools
+});