@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/kernel/project/mcp/registerVerb.test.ts

@@ -0,0 +1,238 @@
+import { existsSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { describe, expect, it, type Mock, vi } from "vitest";
+import { z } from "zod";
+import {
+  fixtureEffectsModule,
+  fixtureModule,
+  touchPath,
+} from "../../../testing/fixtures/fixtureCapability.js";
+import { projectMcp } from "../../../testing/helpers/projectMcp.js";
+import { bootRuntime } from "../../runtime/boot.js";
+import type {
+  GlobalFlags,
+  LazyStore,
+  PragmaRuntime,
+} from "../../runtime/types.js";
+import type {
+  CapabilityModule,
+  ParamSpec,
+  VerbSpec,
+} from "../../spec/types.js";
+import { buildZodSchema, registerVerb } from "./registerVerb.js";
+
+const passthroughFormatters = {
+  plain: (d: unknown) => String(d),
+  llm: (d: unknown) => String(d),
+  json: (d: unknown) => JSON.stringify(d),
+};
+
+describe("buildZodSchema (params → zod)", () => {
+  const params: ParamSpec[] = [
+    {
+      kind: "string",
+      name: "name",
+      doc: "n",
+      positional: true,
+      required: true,
+    },
+    { kind: "boolean", name: "withHistory", doc: "h" },
+    { kind: "enum", name: "mode", doc: "m", values: ["a", "b"] },
+    { kind: "number", name: "count", doc: "c" },
+    { kind: "string[]", name: "tags", doc: "t" },
+  ];
+  const schema = z.object(buildZodSchema(params));
+
+  it("maps each param kind and keys by param name", () => {
+    expect(Object.keys(buildZodSchema(params)).sort()).toEqual([
+      "count",
+      "mode",
+      "name",
+      "tags",
+      "withHistory",
+    ]);
+  });
+
+  it("makes non-required params optional but keeps required ones", () => {
+    expect(schema.safeParse({ name: "x" }).success).toBe(true);
+    expect(schema.safeParse({}).success).toBe(false);
+  });
+
+  it("validates enum, number, and array fields", () => {
+    expect(schema.safeParse({ name: "x", mode: "z" }).success).toBe(false);
+    expect(
+      schema.safeParse({
+        name: "x",
+        mode: "a",
+        count: 2,
+        tags: ["p"],
+        withHistory: true,
+      }).success,
+    ).toBe(true);
+  });
+
+  it("applies a declared default when the field is omitted (CLI parity)", () => {
+    const withDefault = z.object(
+      buildZodSchema([
+        { kind: "string", name: "mode", doc: "m", default: "fast" },
+      ]),
+    );
+    expect(withDefault.parse({})).toEqual({ mode: "fast" });
+    expect(withDefault.parse({ mode: "slow" })).toEqual({ mode: "slow" });
+  });
+});
+
+describe("tool error envelope parity", () => {
+  it("wraps a thrown non-PragmaError as the INTERNAL_ERROR envelope", async () => {
+    const boom: CapabilityModule = {
+      name: "boom",
+      verbs: [
+        {
+          path: ["boom", "go"],
+          summary: "Throws a plain Error.",
+          params: [],
+          output: { formatters: passthroughFormatters },
+          capability: {
+            needsStore: false,
+            mutates: false,
+            mcp: { expose: true },
+          },
+          run: async () => {
+            throw new Error("kaboom");
+          },
+        },
+      ],
+    };
+    const mcp = await projectMcp([boom]);
+    const envelope = await mcp.callTool("boom_go");
+    await mcp.cleanup();
+
+    expect(envelope.ok).toBe(false);
+    const error = envelope.error as { code: string; message: string };
+    expect(error.code).toBe("INTERNAL_ERROR");
+    expect(error.message).toContain("kaboom");
+  });
+});
+
+describe("tool registration", () => {
+  it("names tools by path and excludes non-exposed verbs", async () => {
+    const mcp = await projectMcp([fixtureModule]);
+    const names = (await mcp.listTools()).map((t) => t.name).sort();
+    await mcp.cleanup();
+    expect(names).toEqual(["widget_list", "widget_make"]);
+  });
+
+  it("derives annotations from the capability", async () => {
+    const mcp = await projectMcp([fixtureModule]);
+    const tools = await mcp.listTools();
+    await mcp.cleanup();
+    expect(
+      tools.find((t) => t.name === "widget_list")?.annotations,
+    ).toMatchObject({ readOnlyHint: true, openWorldHint: false });
+    expect(
+      tools.find((t) => t.name === "widget_make")?.annotations,
+    ).toMatchObject({
+      readOnlyHint: false,
+      destructiveHint: true,
+      openWorldHint: false,
+    });
+  });
+
+  it("records a reason for a verb withheld from MCP", () => {
+    const internal = fixtureModule.verbs.find((v) => v.path[1] === "internal");
+    expect(internal?.capability.mcp).toEqual({
+      expose: false,
+      reason: "internal probe, not an agent tool",
+    });
+  });
+});
+
+describe("real MCP mutation invalidates the shared server-lifetime store (C2 hook)", () => {
+  const MCP_FLAGS: GlobalFlags = {
+    llm: true,
+    autoLlm: false,
+    format: "json",
+    verbose: false,
+  };
+  const touchVerb = fixtureEffectsModule.verbs.find(
+    (v) => v.path[1] === "touch",
+  ) as VerbSpec;
+
+  /**
+   * A real `bootRuntime` (real cwd/config), but with its store swapped for one
+   * whose `invalidate` is observable. `probe touch` is `needsStore: false`, so
+   * `get()` is never called — only the mutate handler's post-run invalidation is.
+   */
+  function runtimeWithSpyStore(): { runtime: PragmaRuntime; invalidate: Mock } {
+    const base = bootRuntime(
+      MCP_FLAGS,
+      mkdtempSync(join(tmpdir(), "pragma-c2-hook-")),
+    );
+    const invalidate = vi.fn();
+    const store: LazyStore = {
+      get booted() {
+        return base.store.booted;
+      },
+      get: base.store.get.bind(base.store),
+      invalidate,
+    };
+    return { runtime: { ...base, store }, invalidate };
+  }
+
+  /** Register `touchVerb` and hand back the raw tool handler (no transport). */
+  function captureHandler(
+    runtime: PragmaRuntime,
+  ): (args: Record<string, unknown>) => Promise<CallToolResult> {
+    let handler:
+      | ((args: Record<string, unknown>) => Promise<CallToolResult>)
+      | undefined;
+    const server = {
+      registerTool: (
+        _name: string,
+        _config: unknown,
+        h: (args: Record<string, unknown>) => Promise<CallToolResult>,
+      ) => {
+        handler = h;
+      },
+    } as unknown as McpServer;
+    registerVerb(server, touchVerb, runtime);
+    if (!handler) throw new Error("registerVerb registered no handler");
+    return handler;
+  }
+
+  const envelopeOf = (result: CallToolResult): Record<string, unknown> =>
+    JSON.parse((result.content[0] as { text: string }).text);
+
+  it("invalidates the store after a real (confirm:true) mutation settles", async () => {
+    const { runtime, invalidate } = runtimeWithSpyStore();
+    const handler = captureHandler(runtime);
+    const name = `c2-confirm-${Date.now()}`;
+
+    const result = await handler({ name, confirm: true });
+
+    // The real run wrote the file AND dropped the shared server-lifetime caches
+    // afterwards, so the next read tool re-boots against the new on-disk state.
+    expect(existsSync(touchPath(name))).toBe(true);
+    expect(invalidate).toHaveBeenCalledTimes(1);
+    expect(envelopeOf(result).ok).toBe(true);
+  });
+
+  it("does NOT invalidate the store on a plan-only preview (no confirm)", async () => {
+    const { runtime, invalidate } = runtimeWithSpyStore();
+    const handler = captureHandler(runtime);
+    const name = `c2-preview-${Date.now()}`;
+
+    const result = await handler({ name });
+
+    // A preview touches no disk and leaves the caches intact — no invalidation.
+    expect(existsSync(touchPath(name))).toBe(false);
+    expect(invalidate).not.toHaveBeenCalled();
+    expect(envelopeOf(result).meta).toEqual({
+      planOnly: true,
+      confirmRequired: true,
+    });
+  });
+});

package/src/kernel/project/mcp/registerVerb.ts

@@ -0,0 +1,296 @@
+/**
+ * Adapter: {@link VerbSpec} → an MCP tool.
+ *
+ * This is the one seam where the grammar meets the MCP SDK — the only place a
+ * projector reaches for zod (to build the input schema the SDK validates). The
+ * tool name follows the grammar's naming rule, annotations derive from the
+ * capability, and a mutating verb gains the plan-first `confirm` flow: without
+ * `confirm`, the verb's `Task` is dry-run and a plan is returned
+ * (`{ planOnly: true, confirmRequired: true }`); with `confirm: true`, it runs
+ * for real.
+ */
+
+import { statSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { describeEffect, dryRun, type Task } from "@canonical/task";
+import { runTask } from "@canonical/task/node";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { asPragmaError } from "../../error/fromTaskError.js";
+import { PragmaError } from "../../error/PragmaError.js";
+import type { InteractionRuntime, PragmaRuntime } from "../../runtime/types.js";
+import { toolName } from "../../spec/emitSurface.js";
+import type { McpAnnotations, ParamSpec, VerbSpec } from "../../spec/types.js";
+import { toolError, toolSuccess } from "./envelope.js";
+
+/**
+ * Resolve the effective per-call write root for a mutating tool call.
+ *
+ * The MCP-only injected `cwd` arg lets an agent target a project directory other
+ * than the server's launch dir. It MUST be an absolute, existing directory —
+ * this is the SINGLE cwd the SEC-2 jail validates AND the interpreter resolves
+ * effect paths against, so a write dir the jail never checked can never exist.
+ *
+ * @throws PragmaError INVALID_INPUT for a relative or non-directory `cwd`.
+ */
+function resolveEffectiveCwd(rawCwd: unknown, fallback: string): string {
+  if (typeof rawCwd !== "string" || rawCwd === "") return fallback;
+  if (!isAbsolute(rawCwd)) {
+    throw PragmaError.invalidInput("cwd", rawCwd, {
+      recovery: { message: "Provide an absolute project directory path." },
+    });
+  }
+  let isDir = false;
+  try {
+    isDir = statSync(rawCwd).isDirectory();
+  } catch {
+    isDir = false;
+  }
+  if (!isDir) {
+    throw PragmaError.invalidInput("cwd", rawCwd, {
+      recovery: { message: "The cwd must be an existing directory." },
+    });
+  }
+  return rawCwd;
+}
+
+/** The base zod type for a param, before `.describe()`/`.optional()`. */
+function zodForParam(param: ParamSpec): z.ZodTypeAny {
+  switch (param.kind) {
+    case "string":
+      return z.string();
+    case "number":
+      return z.number();
+    case "boolean":
+      return z.boolean();
+    case "enum":
+      return z.enum(param.values as unknown as [string, ...string[]]);
+    case "string[]":
+      return z.array(z.string());
+  }
+}
+
+/**
+ * Build the zod input shape for a verb's params.
+ *
+ * Each param becomes a described field; non-required params are optional. The
+ * returned raw shape is what the MCP SDK validates tool arguments against.
+ *
+ * @param params - The verb's parameter specs.
+ * @returns A zod raw shape keyed by param name.
+ */
+export function buildZodSchema(params: readonly ParamSpec[]): z.ZodRawShape {
+  const shape: z.ZodRawShape = {};
+  for (const param of params) {
+    let field = zodForParam(param);
+    if (param.doc) field = field.describe(param.doc);
+    // Apply a declared default so the MCP schema matches the CLI, which fills
+    // ParamSpec.default when a flag is omitted (dispatch.extractParams).
+    if ("default" in param && param.default !== undefined) {
+      field = field.default(param.default);
+    } else if (!param.required) {
+      field = field.optional();
+    }
+    shape[param.name] = field;
+  }
+  return shape;
+}
+
+/** Derive the MCP annotations for a verb from its capability. */
+function annotationsFor(verb: VerbSpec): McpAnnotations {
+  return {
+    readOnlyHint: !verb.capability.mutates,
+    ...(verb.capability.destructive !== undefined
+      ? { destructiveHint: verb.capability.destructive }
+      : {}),
+    openWorldHint: false,
+  };
+}
+
+/** Pick just the verb's declared params out of the parsed tool arguments. */
+function paramsFromArgs(
+  verb: VerbSpec,
+  args: Record<string, unknown>,
+): Record<string, unknown> {
+  const params: Record<string, unknown> = {};
+  for (const param of verb.params) {
+    if (param.name in args) params[param.name] = args[param.name];
+  }
+  return params;
+}
+
+/**
+ * Apply the injected `detail` argument to a per-call runtime.
+ *
+ * A verb with a {@link DisclosureSpec} gains a `detail` enum tool param (see
+ * {@link registerVerb}); when the agent sets it, this seeds `globalFlags.detail`
+ * for THIS call so the verb's `run` resolves the level through the same uniform
+ * `resolveDetail` the CLI `--detail` flag feeds — no VerbSpec field, no
+ * Formatters-signature change, no MCP-opts-out asymmetry.
+ */
+function withDetail(
+  verb: VerbSpec,
+  runtime: PragmaRuntime,
+  args: Record<string, unknown>,
+): PragmaRuntime {
+  if (!verb.disclosure || typeof args.detail !== "string") return runtime;
+  return {
+    ...runtime,
+    globalFlags: { ...runtime.globalFlags, detail: args.detail as never },
+  };
+}
+
+/** The tool handler for a read verb: run, project, envelope. */
+function readHandler(verb: VerbSpec, runtime: PragmaRuntime) {
+  return async (args: Record<string, unknown>): Promise<CallToolResult> => {
+    try {
+      if (verb.capability.needsStore) await runtime.store.get();
+      const params = paramsFromArgs(verb, args);
+      const result = await Promise.resolve(
+        verb.run(params, withDetail(verb, runtime, args)) as Promise<unknown>,
+      );
+      return toolSuccess(JSON.parse(verb.output.formatters.json(result)));
+    } catch (error) {
+      return toolError(asPragmaError(error));
+    }
+  };
+}
+
+/**
+ * Route a Task's log effects to STDERR. The default interpreter logs to
+ * `console.log` (stdout), which would corrupt the MCP stdio JSON-RPC frame;
+ * diagnostics belong on stderr. Mirrors the CLI dispatcher's `logToStderr`.
+ */
+const logToStderr = (_level: string, message: string): void => {
+  process.stderr.write(`${message}\n`);
+};
+
+/** The tool handler for a mutating verb: plan-first unless `confirm: true`. */
+function mutateHandler(verb: VerbSpec, runtime: PragmaRuntime) {
+  return async (args: Record<string, unknown>): Promise<CallToolResult> => {
+    try {
+      // The SINGLE per-call write root: validated here (absolute + existing dir)
+      // and threaded as `rt.cwd`, so the SEC-2 jail and the interpreter's
+      // effect-path base are literally the same value — no jail bypass.
+      const effectiveCwd = resolveEffectiveCwd(args.cwd, runtime.cwd);
+      if (verb.capability.needsStore) await runtime.store.get();
+      const params = paramsFromArgs(verb, args);
+      // Without `confirm`, this is a plan-only preview: tell the verb so a
+      // network-touching mutation stays offline and never fetches on discovery.
+      const preview = args.confirm !== true;
+      // MCP has no interactive channel: transport "mcp" makes an interactive
+      // verb pick the params-or-error prompt strategy, so a tool call can never
+      // hang waiting for input.
+      const interaction: InteractionRuntime = {
+        isTTY: false,
+        transport: "mcp",
+        yes: args.confirm === true,
+      };
+      const mutationRuntime: PragmaRuntime = {
+        ...runtime,
+        cwd: effectiveCwd,
+        mutation: { preview },
+        interaction,
+      };
+      const task = await Promise.resolve(
+        verb.run(params, mutationRuntime) as
+          | Task<unknown>
+          | Promise<Task<unknown>>,
+      );
+      if (preview) {
+        const plan = dryRun(task)
+          .effects.filter((effect) => effect._tag !== "Prompt")
+          .map(describeEffect);
+        return toolSuccess({ plan }, { planOnly: true, confirmRequired: true });
+      }
+      // Real execution: spread the verb's runner options (prompt handler,
+      // stamping) into the interpreter; run teardown afterwards.
+      const exec = mutationRuntime.exec ?? {};
+      try {
+        const result = await runTask(task, { onLog: logToStderr, ...exec });
+        return toolSuccess(JSON.parse(verb.output.formatters.json(result)));
+      } finally {
+        // A real mutation may have changed the pack/config on disk. This runtime
+        // is booted ONCE for the whole server lifetime and shared by every tool,
+        // so drop its server-lifetime caches (store session + the config memo the
+        // boot depends on) FIRST — before teardown, so a throwing `dispose` can
+        // never skip the cache-drop — then the next read re-boots against the new
+        // state instead of serving a stale pack/config. `mutationRuntime` spreads
+        // `runtime`, so this is the same shared LazyStore. Only reached on the
+        // real-run branch (`confirm: true`); the plan-only preview never mutates.
+        runtime.store.invalidate();
+        await exec.dispose?.();
+      }
+    } catch (error) {
+      return toolError(asPragmaError(error));
+    }
+  };
+}
+
+/**
+ * Register one exposed verb as an MCP tool on the server.
+ *
+ * @param server - The MCP server to register onto.
+ * @param verb - The verb to expose (caller ensures `mcp.expose === true`).
+ * @param runtime - The runtime handed to the verb's `run`.
+ * @note Impure — mutates the server's tool registry.
+ */
+export function registerVerb(
+  server: McpServer,
+  verb: VerbSpec,
+  runtime: PragmaRuntime,
+): void {
+  const shape = buildZodSchema(verb.params);
+  // A verb with progressive disclosure gains a `detail` enum param derived from
+  // its DisclosureSpec (Risk2 — NO new VerbSpec field). The handler seeds
+  // globalFlags.detail from it per call, so MCP and CLI share one resolveDetail.
+  if (verb.disclosure) {
+    shape.detail = z
+      .enum(verb.disclosure.levels as unknown as [string, ...string[]])
+      .optional()
+      .describe(
+        `Progressive-disclosure level (${verb.disclosure.levels.join(", ")}); default ${verb.disclosure.default}.`,
+      );
+  }
+  if (verb.capability.mutates) {
+    shape.confirm = z
+      .boolean()
+      .default(false)
+      .describe("Set true to execute; otherwise a plan is returned.");
+    // Injected MCP-only per-call write root — added to the zod shape but NOT to
+    // verb.params (like `confirm`/`detail`), so `emitVerb` never emits it and the
+    // surface golden is untouched. The handler validates it and threads it as the
+    // single `rt.cwd` the jail + interpreter share (SEC-2 atomicity).
+    shape.cwd = z
+      .string()
+      .optional()
+      .describe(
+        "Absolute project directory to write into; defaults to the server's working directory.",
+      );
+  }
+
+  const config: {
+    description: string;
+    inputSchema?: z.ZodRawShape;
+    annotations: McpAnnotations;
+  } = {
+    // The agent-facing tool description is the verb's richer `doc` when present
+    // (pack `toolDescription`s compile into it; hand-written verbs author it
+    // directly), falling back to the one-line `summary`. Tool descriptions are
+    // NOT part of the frozen surface, so this stays covenant-safe.
+    description: verb.doc ?? verb.summary,
+    annotations: annotationsFor(verb),
+  };
+  if (Object.keys(shape).length > 0) config.inputSchema = shape;
+
+  const handler = verb.capability.mutates
+    ? mutateHandler(verb, runtime)
+    : readHandler(verb, runtime);
+
+  server.registerTool(
+    toolName(verb.path),
+    config,
+    handler as Parameters<McpServer["registerTool"]>[2],
+  );
+}

package/src/kernel/project/mcp/serve.ts

@@ -0,0 +1,34 @@
+/**
+ * Serve the MCP projector over stdio.
+ *
+ * The bin's `mcp` special-case (D9) and the hidden `mcp` meta verb both call
+ * this: build the server from the capabilities and connect it to a stdio
+ * transport. Kept separate from {@link buildServer} so tests can build a server
+ * without touching stdio.
+ */
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadEffectiveModules } from "../../packs/collect.js";
+import type { CapabilityModule } from "../../spec/types.js";
+import { buildServer } from "./buildServer.js";
+
+/**
+ * Build the MCP server and serve it over stdio until the transport closes.
+ *
+ * The server is a real invocation (not a fast path), so it merges config-declared
+ * story packs into the static capabilities before projecting the tool surface.
+ *
+ * @param modules - The static capability modules to project.
+ * @param cwd - The working directory for the server's runtime.
+ * @note Impure — reads config, connects to stdin/stdout.
+ */
+export async function serveMcp(
+  modules: readonly CapabilityModule[],
+  cwd?: string,
+): Promise<void> {
+  const dir = cwd ?? process.cwd();
+  const effective = await loadEffectiveModules(modules, dir);
+  const server = await buildServer(effective, dir);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/kernel/project/mcp/toolDescriptions.test.ts

@@ -0,0 +1,80 @@
+/**
+ * MCP tool descriptions carry NO CLI-syntax leaks (a PR8 doc→MCP residue).
+ *
+ * A verb's `doc` doubles as its MCP tool description (`registerVerb`), so a doc
+ * authored in CLI terms leaks flags an agent can't use — `--all-tiers`,
+ * `--dry-run`/`--yes`, or a `pragma …` shell command — into the agent-facing
+ * catalog. Tool descriptions are NOT frozen in the covenant, so this is the guard
+ * against the leak (and its recurrence). Storeless: listing tools never boots the
+ * store, so no fixture graph is needed.
+ */
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { capabilities } from "../../../capabilities/index.js";
+import {
+  type McpHarness,
+  projectMcp,
+} from "../../../testing/helpers/projectMcp.js";
+
+let cwd: string;
+let mcp: McpHarness;
+let descriptions: { name: string; description: string }[];
+
+beforeAll(async () => {
+  cwd = mkdtempSync(join(tmpdir(), "pragma-tooldesc-"));
+  mcp = await projectMcp(capabilities, cwd);
+  const tools = await mcp.listTools();
+  descriptions = tools.map((tool) => ({
+    name: tool.name,
+    description: tool.description ?? "",
+  }));
+});
+
+afterAll(async () => {
+  await mcp.cleanup();
+  rmSync(cwd, { recursive: true, force: true });
+});
+
+describe("MCP tool descriptions — no CLI-syntax leaks (doc→MCP residue)", () => {
+  it("has a description for every registered tool", () => {
+    expect(descriptions.length).toBeGreaterThan(0);
+    for (const { name, description } of descriptions) {
+      expect(description.length, name).toBeGreaterThan(0);
+    }
+  });
+
+  it("no tool description embeds a CLI flag (`--flag`)", () => {
+    const leaks = descriptions.filter((tool) =>
+      /--[a-z]/.test(tool.description),
+    );
+    expect(leaks.map((tool) => `${tool.name}: ${tool.description}`)).toEqual(
+      [],
+    );
+  });
+
+  it("no tool description embeds a backtick-quoted `pragma …` command", () => {
+    const leaks = descriptions.filter((tool) =>
+      /`pragma /.test(tool.description),
+    );
+    expect(leaks.map((tool) => `${tool.name}: ${tool.description}`)).toEqual(
+      [],
+    );
+  });
+
+  it("the named leak sites are scrubbed but still substantive", () => {
+    const byName = new Map(
+      descriptions.map((tool) => [tool.name, tool.description]),
+    );
+    expect(byName.get("block_list")).not.toContain("--all-tiers");
+    expect(byName.get("graph_query")).not.toContain("pragma ontology list");
+    expect(byName.get("setup")).not.toMatch(/--dry-run|--yes/);
+    expect(byName.get("upgrade")).not.toContain("--dry-run");
+    // The scrub rephrases; it must not gut the description.
+    for (const tool of ["block_list", "graph_query", "setup", "upgrade"]) {
+      expect((byName.get(tool) ?? "").length, tool).toBeGreaterThan(20);
+    }
+  });
+});