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

package/src/tools/registry.mjs

@@ -0,0 +1,370 @@
+// Every tool Trellis knows, as data: its role, what it is for, how to install it, and how to tell
+// that it is not only installed but actually wired. The last part is the point. A tool that is
+// installed and configured but called from nowhere looks set up and protects nothing, so each
+// `check` decides "wired" from a call site or a live config entry, never from a file's presence.
+import { dependencyNames, parseJson } from "../core/context.mjs";
+import { hookState } from "../agents/install.mjs";
+
+/** @typedef {import("../core/context.mjs").Context} Context */
+/** @typedef {import("./roles.mjs").Role} Role */
+
+/**
+ * @typedef {object} Check
+ * @property {boolean | "on-demand"} installed  "on-demand": fetched by npx or docker when used
+ * @property {boolean} wired
+ * @property {string[]} warnings  wired, but risky or incomplete
+ * @property {string} detail      one line on what was found
+ */
+
+/**
+ * @typedef {object} Tool
+ * @property {string} id
+ * @property {string} name
+ * @property {Role} role
+ * @property {boolean} ai          used by a coding agent (as opposed to a classic check)
+ * @property {string} use          when to reach for it
+ * @property {string} [rule]       the rule an agent follows with it
+ * @property {{ win?: string, mac?: string, linux?: string, any?: string }} install
+ * @property {string} wire         what makes it wired
+ * @property {(ctx: Context) => boolean} applies   whether init enables it by default here
+ * @property {(ctx: Context, opts: Record<string, any>) => Check} check
+ * @property {(opts: Record<string, any>) => Record<string, any>} [mcp]  its .mcp.json entry
+ * @property {(opts: { history?: boolean }) => { cmd: string, args: string[], nothingToScan?: { code: number, why: string } }} [scan]
+ */
+
+/** A front end, in any ecosystem Trellis reads: a page a browser check can open. */
+const WEB_DEPS = [
+  "react", "vue", "svelte", "vite", "next", "@angular/core", "astro", "solid-js", "nuxt", "preact", "@sveltejs/kit", "@remix-run/react", "gatsby",
+  "django", "flask", "rails", "laravel/framework", "symfony/twig-bundle", "phoenix_live_view",
+];
+/** A Postgres client, in any ecosystem Trellis reads. */
+const PG_DEPS = [
+  "pg", "postgres", "sequelize", "prisma", "@prisma/client", "knex", "typeorm", "drizzle-orm", "@neondatabase/serverless",
+  "psycopg", "psycopg2", "psycopg2-binary", "asyncpg", "github.com/lib/pq", "github.com/jackc/pgx/v5", "github.com/jackc/pgx/v4", "tokio-postgres", "sqlx",
+];
+
+/** The image the Postgres MCP runs, pinned by digest so a re-tag upstream cannot change it. */
+export const POSTGRES_MCP_IMAGE =
+  "crystaldba/postgres-mcp@sha256:dbbd346860d29f1543e991f30f3284bf4ab5f096d049ecc3426528f20b1b6e6b";
+export const CONTEXT7_MCP = "@upstash/context7-mcp@4.4.4";
+export const PLAYWRIGHT_MCP = "@playwright/mcp@0.0.83";
+
+/** @param {Context} ctx @param {string[]} names */
+const hasAnyDep = (ctx, names) => {
+  const deps = dependencyNames(ctx);
+  return names.some((n) => deps.has(n));
+};
+const always = () => true;
+
+/**
+ * The repository's MCP servers whose command line matches `pattern`.
+ * @param {Context} ctx
+ * @param {RegExp} pattern
+ * @returns {Array<[string, any]>}
+ */
+export function mcpServers(ctx, pattern) {
+  const servers = parseJson(ctx.read(".mcp.json"))?.mcpServers ?? {};
+  return Object.entries(servers).filter(([, s]) => pattern.test([s.command, ...(s.args ?? [])].join(" ")));
+}
+
+/** An entry whose package is not pinned to an exact version can change under you. @param {any} server @param {string} pkg */
+const unpinned = (server, pkg) => {
+  const arg = (server.args ?? []).find((/** @type {string} */ a) => a.startsWith(pkg));
+  return !arg || !/@\d+\.\d+\.\d+/.test(arg.slice(pkg.length));
+};
+
+/**
+ * A binary on PATH, wired when some script, hook or CI file calls it.
+ * @param {Context} ctx
+ * @param {string} bin
+ * @param {(c: import("../agents/shell.mjs").Command) => boolean} call  the command that runs it
+ * @returns {Check}
+ */
+function binaryCalled(ctx, bin, call) {
+  const at = ctx.which(bin);
+  const callers = ctx.callers(call);
+  return {
+    installed: at != null,
+    wired: callers.length > 0,
+    warnings: [],
+    detail: callers.length ? `called from ${callers.slice(0, 3).join(", ")}` : "no script, hook or CI file calls it",
+  };
+}
+
+/** @type {ReadonlyArray<Tool>} */
+/** `trellis scan` covering `tool` (no --only, or --only naming it). @param {import("../agents/shell.mjs").Command} c @param {string} tool */
+const trellisScans = (c, tool) =>
+  c.prog === "trellis" && c.args[0] === "scan" && (!c.args.includes("--only") || String(c.args[c.args.indexOf("--only") + 1] ?? "").split(",").includes(tool));
+
+export const TOOLS = Object.freeze([
+  {
+    id: "abatty",
+    name: "abatty",
+    role: "guard",
+    ai: false,
+    use: "Before a push: the gate, the debt ratchet, and proof that every check can still go red.",
+    rule: "The gate runs before a push and is never bypassed; a failure is explained with `abatty explain <ID>`.",
+    install: { any: "npm i -D abatty && npx abatty init" },
+    wire: "abatty.config.json exists and a hook, script or CI file calls abatty",
+    applies: always,
+    check(ctx) {
+      const installed = dependencyNames(ctx).has("abatty") && ctx.exists("node_modules/abatty/package.json");
+      const configured = ctx.exists("abatty.config.json");
+      const callers = ctx.callers((c) => c.prog === "abatty");
+      return {
+        installed,
+        wired: configured && callers.length > 0,
+        warnings: [],
+        detail: !configured ? "no abatty.config.json" : callers.length ? `called from ${callers.slice(0, 3).join(", ")}` : "configured, but nothing calls it",
+      };
+    },
+  },
+  {
+    id: "agentshield",
+    name: "AgentShield",
+    role: "frame",
+    ai: true,
+    use: "When agents, hooks, skills or MCP servers change: scans the AI setup itself for unsafe permissions and injection paths.",
+    install: { any: "nothing to install: npx ecc-agentshield@1.6.0 scan" },
+    wire: "a script, hook or CI file runs `ecc-agentshield scan`, or the agent hooks demand it",
+    applies: always,
+    check(ctx) {
+      const callers = ctx.callers((c) => (c.prog === "ecc-agentshield" && c.args.includes("scan")) || trellisScans(c, "agentshield"));
+      // With the agent hooks in place, the Stop rule makes the agent run it whenever the setup changes.
+      const demanded = hookState(ctx).present.includes("Stop");
+      return {
+        installed: "on-demand",
+        wired: callers.length > 0 || demanded,
+        warnings: [],
+        detail: callers.length ? `called from ${callers.slice(0, 3).join(", ")}` : demanded ? "run by agents when the agent setup changes" : "allowed perhaps, but run by nothing",
+      };
+    },
+    // Pinned: an unpinned npx fetches whatever is newest and runs it, in CI with secrets present.
+    // `--path .` (the scan runs in the repository): without it AgentShield scans the user's ~/.claude.
+    scan: () => ({ cmd: "npx", args: ["--yes", "ecc-agentshield@1.6.0", "scan", "--path", "."] }),
+  },
+  {
+    id: "graphify",
+    name: "graphify",
+    role: "guide",
+    ai: true,
+    use: "Any question about this codebase: `graphify query \"<question>\"` before grepping or reading files one by one.",
+    rule: "Local backend only on a repository holding personal data (GRAPHIFY_BACKEND=none); `graphify update .` after a change.",
+    install: { any: "uv tool install graphifyy && graphify install" },
+    wire: "a built graph (graphify-out/graph.json) and the agent skill (.claude/skills/graphify)",
+    applies: always,
+    check(ctx) {
+      const graph = ctx.exists("graphify-out/graph.json");
+      const skill = ctx.exists(".claude/skills/graphify");
+      const warnings = [];
+      if (graph && !skill) warnings.push("the graph is built but no agent skill points at it: run `graphify install`");
+      if (graph && !(ctx.read(".gitignore") ?? "").includes("graphify-out")) warnings.push("graphify-out/ is not git-ignored");
+      return {
+        installed: ctx.which("graphify") != null,
+        wired: graph,
+        warnings,
+        detail: graph ? "graph built" : "no graph built yet",
+        // One known step left, not a gap: building the graph.
+        todo: graph ? undefined : "build the graph: graphify update .",
+      };
+    },
+  },
+  {
+    id: "context7",
+    name: "Context7",
+    role: "guide",
+    ai: true,
+    use: "Any question about a third-party library's API: current docs instead of memory.",
+    rule: "Library names and versions only in a query, never this repository's code or data.",
+    install: { any: "nothing to install: an MCP server run by npx" },
+    wire: "a context7 entry in .mcp.json",
+    applies: always,
+    mcp: () => ({ type: "stdio", command: "npx", args: [CONTEXT7_MCP], env: {} }),
+    check(ctx) {
+      const found = mcpServers(ctx, /context7-mcp/);
+      const warnings = found.length && unpinned(found[0][1], "@upstash/context7-mcp") ? ["not pinned to an exact version"] : [];
+      return { installed: "on-demand", wired: found.length > 0, warnings, detail: found.length ? `MCP server "${found[0][0]}"` : "no MCP entry" };
+    },
+  },
+  {
+    id: "postgres-mcp",
+    name: "Postgres MCP",
+    role: "guide",
+    ai: true,
+    use: "Questions about the database schema: tables, columns, indexes.",
+    rule: "Structure only, through a read-only role on a schema-only database; never pointed at a database holding real rows.",
+    install: { any: "docker (the server runs as a pinned image)" },
+    wire: "a postgres-mcp entry in .mcp.json, restricted, reading its URI from an environment variable",
+    applies: (ctx) => hasAnyDep(ctx, PG_DEPS),
+    mcp: (opts) => ({
+      type: "stdio",
+      command: "docker",
+      args: ["run", "-i", "--rm", "-e", "DATABASE_URI", POSTGRES_MCP_IMAGE, "--access-mode=restricted"],
+      env: { DATABASE_URI: `\${${opts.uriEnv ?? "MCP_PG_URI"}}` },
+    }),
+    check(ctx) {
+      const found = mcpServers(ctx, /postgres-mcp/);
+      if (!found.length) return { installed: ctx.which("docker") != null, wired: false, warnings: [], detail: "no MCP entry" };
+      const [name, s] = found[0];
+      const args = (s.args ?? []).join(" ");
+      const warnings = [];
+      if (!args.includes("--access-mode=restricted")) warnings.push("unrestricted access mode: the agent can write to the database");
+      if (/:\/\/[^$\s]+:[^@\s]+@/.test(JSON.stringify(s))) warnings.push("a connection string with a password is written in .mcp.json: read it from an environment variable");
+      if (s.command === "docker" && !/@sha256:/.test(args)) warnings.push("the image is not pinned by digest");
+      // The URI comes from a variable (`${MCP_PG_URI}`): unset, the server starts with no database.
+      for (const [, name] of JSON.stringify(s.env ?? {}).matchAll(/\$\{(\w+)\}/g)) {
+        if (!ctx.env[name]) warnings.push(`${name} is not set in this environment: the server Claude Code starts would have no database to read`);
+      }
+      return { installed: s.command === "docker" ? ctx.which("docker") != null : "on-demand", wired: true, warnings, detail: `MCP server "${name}"` };
+    },
+  },
+  {
+    id: "find-skills",
+    name: "Find Skills",
+    role: "guide",
+    ai: true,
+    use: "Looking for a capability: `npx skills find <topic>` lists skills with their source and install count.",
+    rule: "Installing a skill is a person's decision: show the package, its source and its install count first; never `-y`.",
+    install: { any: "npx skills add vercel-labs/skills --skill find-skills (after a person has agreed)" },
+    wire: "the skill is present for the agent (.claude/skills, .agents/skills, or ~/.claude/skills)",
+    applies: always,
+    check(ctx) {
+      const where = [".claude/skills/find-skills", ".agents/skills/find-skills"].find((p) => ctx.exists(p)) ??
+        (ctx.existsHome(".claude/skills/find-skills") ? "~/.claude/skills/find-skills" : null);
+      return { installed: where != null, wired: where != null, warnings: [], detail: where ?? "not present" };
+    },
+  },
+  {
+    id: "ecc",
+    name: "ECC",
+    role: "help",
+    ai: true,
+    use: "Planning and review: /ecc:plan, the code-reviewer and security-reviewer agents, and its hooks.",
+    install: { any: "install the ECC plugin in Claude Code (/plugin), then enable it for the project" },
+    wire: "\"ecc@...\": true under enabledPlugins in .claude/settings.json",
+    applies: always,
+    check(ctx) {
+      const plugins = parseJson(ctx.read(".claude/settings.json"))?.enabledPlugins ?? {};
+      const key = Object.keys(plugins).find((k) => k.startsWith("ecc@") && plugins[k] === true);
+      return {
+        installed: ctx.existsHome(".claude/plugins/cache/ecc"),
+        wired: key != null,
+        warnings: [],
+        detail: key ? `enabled as ${key}` : "installed, not enabled for this project",
+        // One known step left: enabling the installed plugin here.
+        todo: key ? undefined : "enable it for this project: /plugin in Claude Code, or \"ecc@<marketplace>\": true under enabledPlugins in .claude/settings.json",
+      };
+    },
+  },
+  {
+    id: "playwright-mcp",
+    name: "Playwright MCP",
+    role: "help",
+    ai: true,
+    use: "A UI change: the agent opens the page in a browser and verifies it before calling the task done.",
+    rule: "Isolated and headless, allowed on the local dev origin only; its snapshot folder is git-ignored and emptied after use.",
+    install: { any: "nothing to install: an MCP server run by npx" },
+    wire: "a @playwright/mcp entry in .mcp.json",
+    applies: (ctx) => hasAnyDep(ctx, WEB_DEPS),
+    mcp: (opts) => ({
+      type: "stdio",
+      command: "npx",
+      args: [PLAYWRIGHT_MCP, "--isolated", "--headless", "--allowed-origins", opts.origin ?? "http://localhost:3000"],
+      env: {},
+    }),
+    check(ctx) {
+      const found = mcpServers(ctx, /@playwright\/mcp/);
+      if (!found.length) return { installed: "on-demand", wired: false, warnings: [], detail: "no MCP entry" };
+      const [name, s] = found[0];
+      const args = s.args ?? [];
+      const warnings = [];
+      if (!args.includes("--isolated")) warnings.push("not --isolated: the agent shares a browser profile, cookies included");
+      if (!args.includes("--allowed-origins")) warnings.push("no --allowed-origins: the agent can browse anywhere");
+      if (unpinned(s, "@playwright/mcp")) warnings.push("not pinned to an exact version");
+      if (!(ctx.read(".gitignore") ?? "").includes(".playwright-mcp")) warnings.push(".playwright-mcp/ is not git-ignored: page snapshots can hold real data");
+      return { installed: "on-demand", wired: true, warnings, detail: `MCP server "${name}"` };
+    },
+  },
+  {
+    id: "playwright",
+    name: "Playwright E2E",
+    role: "guard",
+    ai: false,
+    use: "Behaviour end to end, in a real browser, on every push or nightly.",
+    install: { any: "npm i -D @playwright/test && npx playwright install" },
+    wire: "a playwright config and a script, hook or CI file that runs `playwright test`",
+    applies: (ctx) => hasAnyDep(ctx, WEB_DEPS),
+    check(ctx) {
+      const config = ctx.list(".").some((f) => /^playwright\.config\.[cm]?[jt]s$/.test(f));
+      const callers = ctx.callers((c) => c.prog === "playwright" && c.args[0] === "test");
+      return {
+        installed: dependencyNames(ctx).has("@playwright/test"),
+        wired: config && callers.length > 0,
+        warnings: [],
+        detail: !config ? "no playwright.config" : callers.length ? `called from ${callers.slice(0, 3).join(", ")}` : "configured, but nothing runs it",
+      };
+    },
+  },
+  {
+    id: "gitleaks",
+    name: "Gitleaks",
+    role: "guard",
+    ai: false,
+    use: "Before any commit that could carry a secret, and over the history in CI.",
+    install: { win: "winget install Gitleaks.Gitleaks", mac: "brew install gitleaks", linux: "download a release from github.com/gitleaks/gitleaks" },
+    wire: "a hook, script or CI file calls gitleaks",
+    applies: always,
+    // A run, not a mention: `gitleaks version` or `echo gitleaks` scans nothing.
+    // `trellis verify` (the commit checkpoint) runs gitleaks itself.
+    check: (ctx) => binaryCalled(ctx, "gitleaks", (c) => (c.prog === "gitleaks" && ["git", "dir", "detect", "protect", "stdin"].includes(c.args[0])) || trellisScans(c, "gitleaks") || (c.prog === "trellis" && c.args[0] === "verify")),
+    scan: ({ history }) => ({
+      cmd: "gitleaks",
+      args: history ? ["git", "--redact", "--no-banner"] : ["git", "--pre-commit", "--staged", "--redact", "--no-banner"],
+    }),
+  },
+  {
+    id: "osv-scanner",
+    name: "OSV-Scanner",
+    role: "guard",
+    ai: false,
+    use: "Known vulnerabilities in the dependency tree, from the lockfiles.",
+    install: { win: "winget install Google.OSVScanner", mac: "brew install osv-scanner", linux: "a pinned release from github.com/google/osv-scanner/releases (or your distribution's package)" },
+    wire: "a hook, script or CI file calls osv-scanner",
+    applies: always,
+    check: (ctx) => binaryCalled(ctx, "osv-scanner", (c) => c.prog === "osv-scanner"),
+    // Exit 128 is OSV-Scanner's "no package sources found": nothing to scan, not a finding.
+    scan: () => ({ cmd: "osv-scanner", args: ["scan", "source", "-r", "."], nothingToScan: { code: 128, why: "no lockfile or manifest found" } }),
+  },
+  {
+    id: "lighthouse",
+    name: "Lighthouse",
+    role: "guard",
+    ai: false,
+    use: "Performance, accessibility and best-practice budgets on the built front end.",
+    install: { any: "npm i -D @lhci/cli and a lighthouserc file" },
+    wire: "a lighthouserc file and a script or CI file that runs lhci",
+    applies: (ctx) => hasAnyDep(ctx, WEB_DEPS),
+    check(ctx) {
+      const config = ctx.list(".").some((f) => /^\.?lighthouserc(\.[cm]?js|\.json|\.ya?ml)?$/.test(f));
+      const callers = ctx.callers((c) => c.prog === "lhci" && ["autorun", "collect", "assert"].includes(c.args[0]));
+      return {
+        installed: dependencyNames(ctx).has("@lhci/cli"),
+        wired: config && callers.length > 0,
+        warnings: [],
+        detail: !config ? "no lighthouserc" : callers.length ? `called from ${callers.slice(0, 3).join(", ")}` : "configured, but nothing runs it",
+      };
+    },
+  },
+]);
+
+/** @param {string} id */
+export function toolById(id) {
+  return TOOLS.find((t) => t.id === id) ?? null;
+}
+
+/** The install line for this platform. @param {Tool} tool @param {NodeJS.Platform} platform */
+export function installHint(tool, platform) {
+  const i = tool.install;
+  const own = platform === "win32" ? i.win : platform === "darwin" ? i.mac : i.linux;
+  return own ?? i.any ?? "see the tool's documentation";
+}

package/src/tools/roles.mjs

@@ -0,0 +1,17 @@
+// The four roles a tool plays. Trellis frames a repository with these, in this order: the rules
+// that shape the work, where to look, who helps, and what stops a bad change.
+
+/** @typedef {"frame" | "guide" | "help" | "guard"} Role */
+
+/** @type {ReadonlyArray<{ id: Role, title: string, question: string }>} */
+export const ROLES = Object.freeze([
+  { id: "frame", title: "Frame", question: "What are the rules here, and is the setup itself safe?" },
+  { id: "guide", title: "Guide", question: "Where do I look before I write?" },
+  { id: "help", title: "Help", question: "Who plans, reviews and verifies with me?" },
+  { id: "guard", title: "Guard", question: "What stops a bad change before it lands?" },
+]);
+
+/** @param {string} id */
+export function roleById(id) {
+  return ROLES.find((r) => r.id === id) ?? null;
+}