@synovitec/trellis 0.0.0-stage → 0.6.0-rc.3

package/schema/trellis.config.schema.json

@@ -0,0 +1,349 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/@synovitec/trellis/schema/trellis.config.schema.json",
+  "title": "trellis.config.json",
+  "description": "Which tools a repository uses. false is a decision on record (the tool does not apply here), not a gap.",
+  "type": "object",
+  "required": [
+    "tools"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "tools": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "abatty": {
+          "type": "boolean"
+        },
+        "agentshield": {
+          "type": "boolean"
+        },
+        "graphify": {
+          "type": "boolean"
+        },
+        "context7": {
+          "type": "boolean"
+        },
+        "postgres-mcp": {
+          "oneOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "object",
+              "properties": {
+                "uriEnv": {
+                  "type": "string",
+                  "description": "The environment variable holding the connection string; never the string itself."
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "find-skills": {
+          "type": "boolean"
+        },
+        "ecc": {
+          "type": "boolean"
+        },
+        "playwright-mcp": {
+          "oneOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "object",
+              "properties": {
+                "origin": {
+                  "type": "string",
+                  "description": "The one origin the agent's browser may open, e.g. http://localhost:3000."
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        },
+        "playwright": {
+          "type": "boolean"
+        },
+        "gitleaks": {
+          "type": "boolean"
+        },
+        "osv-scanner": {
+          "type": "boolean"
+        },
+        "lighthouse": {
+          "type": "boolean"
+        }
+      }
+    },
+    "agents": {
+      "type": "object",
+      "description": "The session rules the agent hooks enforce. Each is active only when the tool it asks for is enabled.",
+      "additionalProperties": false,
+      "properties": {
+        "mode": {
+          "enum": [
+            "block",
+            "warn",
+            "off"
+          ],
+          "description": "The default for every rule: block sends the agent back, warn tells the person, off skips it."
+        },
+        "rules": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "evidence-intact": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            },
+            "config-unchanged": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            },
+            "ui-verified": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            },
+            "agent-setup-scanned": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            },
+            "schema-before-change": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            },
+            "graph-before-edit": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            },
+            "docs-looked-up": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            },
+            "graph-first": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            },
+            "secrets-scanned": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            }
+          }
+        },
+        "uiPaths": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Globs of the files a browser check must follow."
+        },
+        "agentSetupPaths": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Globs of the agent setup an AgentShield scan must follow."
+        },
+        "graphAfterSearches": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "uiIgnore": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Globs under uiPaths that are not UI (tests, stories, build output)."
+        },
+        "maxBlocks": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Times the agent is sent back before the person decides. Default 2."
+        },
+        "codePaths": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Globs of the source files the code graph must be asked about before they change."
+        },
+        "codeIgnore": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Globs under codePaths and schemaPaths that are generated, not written."
+        },
+        "schemaPaths": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Globs of migrations, models and schema files the database schema must be looked at before they change."
+        }
+      }
+    },
+    "verify": {
+      "type": "object",
+      "description": "The commit checkpoint (`trellis verify`, pre-commit and CI): a preset and per-rule modes. Blocking rules are the deterministic ones; the rest warn.",
+      "additionalProperties": false,
+      "properties": {
+        "preset": {
+          "enum": [
+            "recommended",
+            "strict"
+          ],
+          "default": "recommended"
+        },
+        "unattested": {
+          "enum": [
+            "refuse",
+            "judge"
+          ],
+          "default": "refuse",
+          "description": "In CI, a commit with no Trellis attestation (a fork's contributor without Trellis, Dependabot, Renovate, the web editor): refused, or judged on its own as an agent's (secrets, dependencies, protected tests, the net change), read at the base."
+        },
+        "tests": {
+          "type": "array",
+          "description": "The project's test commands: only a run of exactly one of them counts for tests-run (no extra arguments: a filter can match nothing). Default: read from the project (package.json's test script, pytest, go test ./..., cargo test).",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "minItems": 1
+        },
+        "rules": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "secrets-scanned": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            },
+            "deps-verified": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            },
+            "deps-pinned": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            },
+            "deps-registry": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            },
+            "tests-protected": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            },
+            "escalation": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            },
+            "tests-run": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            },
+            "graph-before-edit": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            },
+            "docs-looked-up": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            },
+            "ui-verified": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            },
+            "schema-before-change": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            },
+            "review": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            },
+            "plan-before-change": {
+              "enum": [
+                "block",
+                "warn",
+                "off"
+              ]
+            }
+          }
+        }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/src/agents/adapters.mjs

@@ -0,0 +1,155 @@
+// The hooks of agents other than Claude Code: Cursor, Codex and Copilot. Each sends its own
+// payload and expects its own answer; an adapter turns the payload into one shape, applies the
+// same guard and gates as for Claude Code, feeds the shared evidence log, and answers in the
+// agent's format (sources: each agent's hook reference, read 2026-10-30).
+//
+// Weaker than the Claude Code path: these agents' transcripts are not documented, so a call is not
+// cross-checked against one. A hook run by hand is still refused by the shell guard, and CI, which
+// re-runs the deterministic checks, stays the authority.
+import { appendEvent, readWindow } from "../core/evidence.mjs";
+import { CONFIG_FILE, enabledTools } from "../core/config.mjs";
+import { DEFAULTS, gate, isBrowser, isContext7, isSchemaLookup } from "./rules.mjs";
+import { emptyLedger } from "./state.mjs";
+import { graphAnswered, succeeded, tampering } from "./hooks.mjs";
+import { relativeTo } from "./transcript.mjs";
+import { treeOf, worktreeDiff } from "../core/diff.mjs";
+import { matchesAny } from "./glob.mjs";
+import { parseJson } from "../core/context.mjs";
+
+/** The agents an adapter speaks for. */
+export const ADAPTED = Object.freeze(["cursor", "codex", "copilot"]);
+
+/**
+ * @typedef {object} Call
+ * @property {string} name      Claude-style: Bash, Edit, Write, mcp__<server>__<tool>...
+ * @property {Record<string, any>} input
+ * @property {any} output
+ * @property {boolean} ok
+ * @property {string[]} edits   files the call writes, relative as given
+ */
+
+/** Cursor names an MCP tool `MCP:<tool>`, without its server: the server, from the tool's name. @param {string} tool */
+function cursorServer(tool) {
+  if (/^browser_/.test(tool)) return "playwright";
+  if (/^(resolve-library-id|query-docs|get-library-docs)$/.test(tool)) return "context7";
+  if (/^(list_schemas|list_objects|get_object_details|execute_sql|explain_query|analyze_\w+|get_top_queries)$/.test(tool)) return "postgres";
+  return "unknown";
+}
+
+/** The files an apply_patch writes, from the patch's own headers. @param {string} patch */
+const patchFiles = (patch) => [...patch.matchAll(/^\*\*\* (?:Add|Update|Delete) File: (.+)$|^\*\*\* Move to: (.+)$/gm)].map((m) => (m[1] ?? m[2]).trim());
+
+/** @param {Record<string, any>} input */
+const pathOf = (input) => input.file_path ?? input.filePath ?? input.path ?? input.target_file ?? null;
+
+/**
+ * One shape for every agent's tool-call payload.
+ * @param {string} agent
+ * @param {Record<string, any>} p
+ * @returns {Call}
+ */
+export function normalize(agent, p) {
+  const input = p.tool_input && typeof p.tool_input === "object" ? p.tool_input : {};
+  let name = String(p.tool_name ?? "");
+  /** @type {any} */
+  let output = p.tool_response;
+  let ok = true;
+  if (agent === "cursor") {
+    if (name === "Shell") name = "Bash";
+    const mcp = name.match(/^MCP:(.+)$/);
+    if (mcp) name = `mcp__${cursorServer(mcp[1])}__${mcp[1]}`;
+    output = typeof p.tool_output === "string" ? (parseJson(p.tool_output) ?? p.tool_output) : p.tool_output;
+    ok = succeeded(output);
+  } else if (agent === "copilot") {
+    const r = p.tool_result ?? {};
+    output = { output: r.text_result_for_llm ?? "" };
+    ok = r.result_type == null || r.result_type === "success";
+  } else {
+    ok = succeeded(output);
+  }
+  const edits = name === "apply_patch" ? patchFiles(String(input.input ?? input.patch ?? input.command ?? "")) : ["Edit", "Write", "MultiEdit"].includes(name) && pathOf(input) ? [String(pathOf(input))] : [];
+  return { name, input, output, ok, edits };
+}
+
+/** @typedef {{ code: number, stdout?: string, stderr?: string }} HookResult */
+
+/**
+ * The answer to a refused pre-tool call, as the agent reads it: Cursor a JSON permission, Codex
+ * its JSON deny (an exit code would not survive Windows PowerShell, which turns any failure into
+ * 1), Copilot exit 2 with the reason on stderr (all documented).
+ * @param {string} agent
+ * @param {string} reason
+ * @returns {HookResult}
+ */
+function deny(agent, reason) {
+  const text = `[trellis] ${reason}`;
+  if (agent === "cursor") return { code: 0, stdout: `${JSON.stringify({ permission: "deny", user_message: text, agent_message: text })}\n` };
+  if (agent === "codex") return { code: 0, stdout: `${JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: text } })}\n` };
+  return { code: 2, stderr: `${text}\n` };
+}
+
+/** The repository's config, read as it is (the commit checkpoint judges the rest). @param {import("../core/context.mjs").Context} ctx */
+const configOf = (ctx) => parseJson(ctx.read(CONFIG_FILE));
+
+/**
+ * @param {string} agent
+ * @param {string} event          pre-tool | post-tool
+ * @param {Record<string, any>} payload
+ * @param {import("../core/context.mjs").Context} ctx
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {HookResult}
+ */
+export function agentHook(agent, event, payload, ctx, env) {
+  if (!ADAPTED.includes(agent)) return { code: 2, stderr: `[trellis] unknown agent "${agent}" (known: ${ADAPTED.join(", ")}, and Claude Code without --agent).\n` };
+  const call = normalize(agent, payload);
+  const config = configOf(ctx);
+  if (event === "pre-tool") {
+    if (call.name === "Bash") {
+      const why = tampering(String(call.input.command ?? ""));
+      if (why) return deny(agent, why);
+    }
+    if (!call.edits.length) return { code: 0 };
+    const window = readWindow(ctx.root, env);
+    if (window.status === "tampered") return deny(agent, "The evidence log was altered; nothing in it can be trusted. Tell the person.");
+    const ledger = { ...emptyLedger(), graph: window.events.some((e) => e.kind === "graph"), schema: window.events.some((e) => e.kind === "schema") };
+    const enabled = new Set(enabledTools(ctx, config).map((e) => e.tool.id));
+    for (const file of call.edits) {
+      const path = relativeTo(file, ctx.root, ctx.platform) ?? file;
+      const refusal = gate(path, ledger, enabled, config?.agents, { graphReady: ctx.exists("graphify-out/graph.json") });
+      if (refusal?.mode === "block") return deny(agent, refusal.reason);
+    }
+    return { code: 0 };
+  }
+  if (event === "post-tool") {
+    const feed = (/** @type {Omit<import("../core/evidence.mjs").Event, "agent">} */ e) => appendEvent(ctx.root, { ...e, agent }, env);
+    // That an agent is at work, once per window: it makes the change an agent's (tests-protected,
+    // escalation), even when it edits through the shell and looks nothing up.
+    const window = readWindow(ctx.root, env);
+    if (window.status === "ok" && !window.events.some((e) => e.agent === agent)) feed({ kind: "agent", tool: call.name });
+    if (!call.ok) return { code: 0 };
+    const use = { name: call.name, input: call.input };
+    const none = new Set();
+    if (call.name === "Bash" && graphAnswered(use, call.output, ctx)) feed({ kind: "graph", tool: "graphify", subject: String(call.input.command).slice(0, 300) });
+    else if (isContext7(none, use)) feed({ kind: "docs", tool: call.name, subject: JSON.stringify(call.input).toLowerCase().slice(0, 500) });
+    else if (isSchemaLookup(none, use)) feed({ kind: "schema", tool: call.name });
+    else if (isBrowser(none, use) && /browser_(snapshot|take_screenshot)$/.test(call.name)) {
+      const blobs = uiBlobs(ctx);
+      if (blobs) feed({ kind: "browser", tool: call.name, blobs });
+    }
+    return { code: 0 };
+  }
+  return { code: 0 };
+}
+
+/** The git blob of each changed UI file as it is on disk now; null when git cannot tell. @param {import("../core/context.mjs").Context} ctx */
+export function uiBlobs(ctx) {
+  try {
+    /** @type {Record<string, string>} */
+    const blobs = {};
+    for (const c of worktreeDiff(ctx.root, treeOf(ctx.root, "HEAD"))) if (c.newBlob && matchesAny(c.path, DEFAULTS.uiPaths)) blobs[c.path] = c.newBlob;
+    return blobs;
+  } catch {
+    return null;
+  }
+}
+