@nimbus-dev/connectors 0.8.0 → 0.10.0

package/connectors/testflight/src/tools.ts

@@ -1,9 +1,18 @@
 import { signAppStoreConnectJwt } from "@nimbus-dev/sdk";
 import { z } from "zod";
-import { createJsonGetter } from "../../../shared/env-json-api.ts";
+import { capText } from "../../../shared/cap-text.ts";
+import { type ConsentServer, createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import {
+  createJsonGetter,
+  createJsonSender,
+  type JsonApiConfig,
+} from "../../../shared/env-json-api.ts";
 import { matchesResult } from "../../../shared/mcp-search-tool.ts";
-import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
-import type { ZodToolRegistrar } from "../../../shared/run-read-only-mcp-connector.ts";
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResult as jsonResult,
+} from "../../../shared/mcp-tool-kit.ts";
 import { jwtParamsFromEnv } from "./jwt.ts";
 import { filterTestflightBuilds } from "./search-filter.ts";
 
@@ -14,11 +23,15 @@ function authHeader(): Record<string, string> {
   return { Authorization: `Bearer ${token}`, Accept: "application/json" };
 }
 
-const appstoreGet = createJsonGetter({
+const api: JsonApiConfig = {
   base: APPSTORECONNECT_API,
   label: "App Store Connect",
   headers: authHeader,
-});
+};
+
+const appstoreGet = createJsonGetter(api);
+// A mutation's 3xx is refused (never followed), so the token is not replayed anywhere.
+const appstoreSend = createJsonSender(api);
 
 function buildsPath(appId: string, limit: number): string {
   return `/v1/builds?filter[app]=${encodeURIComponent(appId)}&sort=-uploadedDate&limit=${String(limit)}`;
@@ -29,9 +42,78 @@ export const TESTFLIGHT_TOOL_NAMES = [
   "testflight_list",
   "testflight_get",
   "testflight_search",
+  "testflight_build_groups_get",
+  "testflight_beta_groups_list",
+  "testflight_build_distribute",
 ] as const;
 
-export function registerTestflightTools(reg: ZodToolRegistrar): void {
+/** App Store Connect resource ids (UUIDs and numeric app ids); never a dot segment. */
+const idArg = z
+  .string()
+  .regex(/^(?!\.{1,2}$)[A-Za-z0-9._-]{1,64}$/, "letters, digits, '.', '_' and '-' only");
+
+type Obj = Record<string, unknown>;
+
+function asObj(v: unknown): Obj {
+  return typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Obj) : {};
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v !== "" ? v : undefined;
+}
+
+/**
+ * The beta groups a build is in, projected to what an approver needs. `publicLinkEnabled` is kept
+ * on purpose: a group with a public link is open to anyone who holds the link, whoever is in it.
+ */
+async function readBuildGroups(buildId: string): Promise<Obj[]> {
+  return projectGroups(
+    await appstoreGet(`/v1/builds/${encodeURIComponent(buildId)}/betaGroups?limit=200`),
+    200,
+  );
+}
+
+/** At most `cap` groups of an App Store Connect list reply, as `{id, name, isInternalGroup, publicLinkEnabled}`. */
+function projectGroups(reply: unknown, cap: number): Obj[] {
+  const data = Array.isArray(asObj(reply)["data"]) ? (asObj(reply)["data"] as unknown[]) : [];
+  return data.slice(0, cap).map((raw) => {
+    const g = asObj(raw);
+    const attrs = asObj(g["attributes"]);
+    return {
+      id: capText(g["id"]),
+      name: capText(attrs["name"]),
+      isInternalGroup: attrs["isInternalGroup"],
+      publicLinkEnabled: attrs["publicLinkEnabled"],
+    };
+  });
+}
+
+/** The ids of the beta groups an app has, from `GET /v1/apps/{appId}/betaGroups`. */
+async function appGroupIds(appId: string): Promise<Set<string>> {
+  const groups = projectGroups(
+    await appstoreGet(`/v1/apps/${encodeURIComponent(appId)}/betaGroups?limit=200`),
+    200,
+  );
+  return new Set(groups.map((g) => g["id"]).filter((id): id is string => typeof id === "string"));
+}
+
+/** The app a build belongs to, from `GET /v1/builds/{id}?include=app`. */
+async function appOfBuild(buildId: string): Promise<string | undefined> {
+  const root = asObj(await appstoreGet(`/v1/builds/${encodeURIComponent(buildId)}?include=app`));
+  const rel = asObj(asObj(asObj(root["data"])["relationships"])["app"]);
+  return str(asObj(rel["data"])["id"]);
+}
+
+export function registerTestflightTools(
+  server: ConsentServer & { tool: (...args: never) => unknown },
+): void {
+  const reg = createZodToolRegistrar(createRegisterSimpleTool(server));
+  const registerWriteTool = createWriteToolRegistrar(server, {
+    connector: "testflight",
+    scopeEnv: "NIMBUS_MCP_TESTFLIGHT_WRITE_SCOPE",
+    scopeKinds: ["app"],
+  });
+
   reg(
     "testflight_list",
     "List TestFlight resources via the App Store Connect API. When `appId` is omitted, returns the user's accessible apps via `GET /v1/apps`. When `appId` is provided, returns that app's most-recent builds via `GET /v1/builds?filter[app]=<id>&sort=-uploadedDate` (limit optional).",
@@ -76,4 +158,76 @@ export function registerTestflightTools(reg: ZodToolRegistrar): void {
       return matchesResult(data, filterTestflightBuilds, p);
     },
   );
+
+  reg(
+    "testflight_build_groups_get",
+    "Read the beta groups a TestFlight build is already in (`GET /v1/builds/{buildId}/betaGroups`), projected to `{ groups: [{ id, name, isInternalGroup, publicLinkEnabled }] }`. A group with `publicLinkEnabled: true` is reachable by anyone who has its public link.",
+    z.object({ buildId: idArg }),
+    async (p) => jsonResult({ groups: await readBuildGroups(p.buildId) }),
+  );
+
+  reg(
+    "testflight_beta_groups_list",
+    "List an app's TestFlight beta groups (`GET /v1/apps/{appId}/betaGroups`), at most `limit` (default 100, max 200), projected to `{ groups: [{ id, name, isInternalGroup, publicLinkEnabled }] }`. Read it BEFORE `testflight_build_distribute` to see which target groups are public: a group with `publicLinkEnabled: true` is reachable by anyone who holds its link.",
+    z.object({ appId: idArg, limit: z.number().int().min(1).max(200).optional() }),
+    async (p) => {
+      const search = new URLSearchParams({ limit: String(p.limit ?? 100) });
+      const root = await appstoreGet(
+        `/v1/apps/${encodeURIComponent(p.appId)}/betaGroups?${search.toString()}`,
+      );
+      return jsonResult({ groups: projectGroups(root, p.limit ?? 100) });
+    },
+  );
+
+  registerWriteTool(
+    "testflight_build_distribute",
+    {
+      mutates: "testflight.build.distribute",
+      // Testers who were given the build cannot be un-invited from here; the groups the build was
+      // already in are recorded in the audit pre-state.
+      recoverable: false,
+      capturePreState: async (p: { buildId: string }) => ({
+        buildId: p.buildId,
+        groups: await readBuildGroups(p.buildId),
+      }),
+      scopeTargetOf: (p: { appId: string }) => ({ kind: "app", value: p.appId }),
+    },
+    'Add a TestFlight build to beta groups (`POST /v1/builds/{buildId}/relationships/betaGroups`, body `{ data: [{ type: "betaGroups", id }] }`). The build must belong to `appId`: it is read first (`GET /v1/builds/{buildId}?include=app`) and a build of another app sends nothing. Adding a build to a group makes it available to every tester in it, and a group with a public link reaches anyone holding the link (see `testflight_build_groups_get`). Apple may refuse (409/422) a build that is not VALID or a external group that has not passed beta review; the body is returned in the error. The reply is `accepted`.',
+    z.object({
+      appId: idArg,
+      buildId: idArg,
+      betaGroupIds: z.array(idArg).min(1).max(20),
+    }),
+    async (p) => {
+      if (new Set(p.betaGroupIds).size !== p.betaGroupIds.length) {
+        throw new Error("betaGroupIds has a duplicate; nothing was sent");
+      }
+      const owner = await appOfBuild(p.buildId);
+      if (owner !== p.appId) {
+        throw new Error(`build ${p.buildId} does not belong to app ${p.appId}; nothing was sent`);
+      }
+      // Every target group must be one of this app's: one GET, and nothing is sent on a mismatch.
+      const known = await appGroupIds(p.appId);
+      const stray = p.betaGroupIds.filter((id) => !known.has(id));
+      if (stray.length > 0) {
+        throw new Error(
+          `beta group(s) ${stray.join(", ")} do not belong to app ${p.appId}; nothing was sent`,
+        );
+      }
+      await appstoreSend(
+        "POST",
+        `/v1/builds/${encodeURIComponent(p.buildId)}/relationships/betaGroups`,
+        {
+          data: p.betaGroupIds.map((id) => ({ type: "betaGroups", id })),
+        },
+      );
+      return jsonResult({
+        ok: true,
+        status: "accepted",
+        appId: p.appId,
+        buildId: p.buildId,
+        betaGroupIds: p.betaGroupIds,
+      });
+    },
+  );
 }

package/connectors/vercel/nimbus.extension.json

@@ -2,14 +2,14 @@
   "id": "com.nimbus.vercel",
   "displayName": "Vercel",
   "version": "0.1.0",
-  "description": "Vercel deployment connector (read-only). Surfaces deployment uid, project name, state, target (production/staging), the *.vercel.app host, inspector URL, git commit metadata (sha/message/ref/PR id), and creator into the local index as `vercel:deployment` items — useful for correlating deploys with PR / Slack history (\"which deploy shipped this commit?\"). Bearer-token auth. Optional `vercel.team_id` scopes requests to a team. The SaaS host (api.vercel.com) is fixed. Projects / domains / env vars / aliases / logs are deferred follow-ups.",
+  "description": "Vercel deployment connector. Surfaces deployment uid, project name, state, target (production/staging), the *.vercel.app host, inspector URL, git commit metadata (sha/message/ref/PR id), and creator into the local index as `vercel:deployment` items — useful for correlating deploys with PR / Slack history (\"which deploy shipped this commit?\"). Bearer-token auth. Optional `vercel.team_id` scopes requests to a team. The SaaS host (api.vercel.com) is fixed. Write tools (each needs owner approval): `vercel.deployment.redeploy` and `vercel.deployment.promote`. Projects / domains / env vars / aliases / logs are deferred follow-ups.",
   "author": "Nimbus",
   "entrypoint": "dist/server.js",
   "runtime": "bun",
   "permissions": {
     "network": ["api.vercel.com"]
   },
-  "hitlRequired": [],
+  "hitlRequired": ["write"],
   "syncInterval": 600,
   "minNimbusVersion": "0.2.0"
 }

package/connectors/vercel/src/server.ts

@@ -1,6 +1,14 @@
-import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CONSENT_SERVER_CAPABILITIES } from "../../../shared/consent-kit.ts";
 import { registerVercelTools } from "./tools.ts";
 
-await runReadOnlyMcpConnector("nimbus-vercel", (reg) => {
-  registerVercelTools(reg);
-});
+const server = new McpServer(
+  { name: "nimbus-vercel", version: "0.1.0" },
+  { capabilities: CONSENT_SERVER_CAPABILITIES },
+);
+
+registerVercelTools(server);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/connectors/vercel/src/tools.ts

@@ -1,8 +1,17 @@
 import { z } from "zod";
-import { createJsonGetter, envAuthHeaders } from "../../../shared/env-json-api.ts";
+import { type ConsentServer, createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import {
+  createJsonGetter,
+  createJsonSender,
+  envAuthHeaders,
+  type JsonApiConfig,
+} from "../../../shared/env-json-api.ts";
 import { matchesResult, searchToolInputSchema } from "../../../shared/mcp-search-tool.ts";
-import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
-import type { ZodToolRegistrar } from "../../../shared/run-read-only-mcp-connector.ts";
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResult as jsonResult,
+} from "../../../shared/mcp-tool-kit.ts";
 import { filterVercelDeployments } from "./search-filter.ts";
 
 const BASE = "https://api.vercel.com";
@@ -21,11 +30,15 @@ function withTeam(path: string): string {
   return `${path}${sep}teamId=${encodeURIComponent(team)}`;
 }
 
-const getJson = createJsonGetter({
+const api: JsonApiConfig = {
   base: BASE,
   label: "Vercel",
   headers: envAuthHeaders({ env: "VERCEL_TOKEN" }),
-});
+};
+
+const getJson = createJsonGetter(api);
+// A mutation's 3xx is refused (never followed), so the token is not replayed anywhere.
+const sendJson = createJsonSender(api);
 
 /** Every request is scoped to `VERCEL_TEAM_ID` when one is configured. */
 async function vercelGet(path: string): Promise<unknown> {
@@ -33,9 +46,71 @@ async function vercelGet(path: string): Promise<unknown> {
 }
 
 /** Tool names exposed by this connector — for contract/introspection tests. */
-export const VERCEL_TOOL_NAMES = ["vercel_get", "vercel_list", "vercel_search"] as const;
+export const VERCEL_TOOL_NAMES = [
+  "vercel_list",
+  "vercel_get",
+  "vercel_search",
+  "vercel_project_production_get",
+  "vercel_deployment_redeploy",
+  "vercel_deployment_promote",
+] as const;
+
+/** Deployment and project ids: never `.` or `..` (a URL parser collapses them out of the path). */
+const idArg = z
+  .string()
+  .regex(/^(?!\.{1,2}$)[A-Za-z0-9._-]{1,128}$/, "letters, digits, '.', '_' and '-' only");
+
+type Obj = Record<string, unknown>;
+
+function asObj(v: unknown): Obj {
+  return typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Obj) : {};
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v !== "" ? v : undefined;
+}
+
+/** The facts of one deployment a redeploy needs and an approver wants to see. */
+async function readDeployment(deploymentId: string): Promise<Obj & { name: string | undefined }> {
+  const d = asObj(await vercelGet(`/v13/deployments/${encodeURIComponent(deploymentId)}`));
+  return {
+    id: str(d["id"]) ?? str(d["uid"]) ?? deploymentId,
+    name: str(d["name"]),
+    target: d["target"] ?? null,
+    readyState: str(d["readyState"]) ?? str(d["state"]),
+  };
+}
+
+/** `{projectId, name, production}`: the deployment a promote makes stop being current. */
+async function readProductionState(projectId: string): Promise<Obj> {
+  const project = asObj(await vercelGet(`/v9/projects/${encodeURIComponent(projectId)}`));
+  const prod = asObj(asObj(project["targets"])["production"]);
+  const id = str(prod["id"]) ?? str(prod["uid"]);
+  return {
+    projectId: str(project["id"]) ?? projectId,
+    name: str(project["name"]),
+    production:
+      id === undefined
+        ? null
+        : {
+            id,
+            url: str(prod["url"]),
+            readyState: str(prod["readyState"]) ?? str(prod["state"]),
+            createdAt: prod["createdAt"],
+          },
+  };
+}
+
+export function registerVercelTools(
+  server: ConsentServer & { tool: (...args: never) => unknown },
+): void {
+  const reg = createZodToolRegistrar(createRegisterSimpleTool(server));
+  const registerWriteTool = createWriteToolRegistrar(server, {
+    connector: "vercel",
+    scopeEnv: "NIMBUS_MCP_VERCEL_WRITE_SCOPE",
+    scopeKinds: ["project", "deployment"],
+  });
 
-export function registerVercelTools(reg: ZodToolRegistrar): void {
   reg(
     "vercel_list",
     "List recent Vercel deployments (`GET /v6/deployments`), most-recent-first, capped at `limit` (default 100). Returns the `{ deployments, pagination }` envelope.",
@@ -70,4 +145,83 @@ export function registerVercelTools(reg: ZodToolRegistrar): void {
       return matchesResult(deployments, filterVercelDeployments, p);
     },
   );
+
+  reg(
+    "vercel_project_production_get",
+    "Read which deployment is the CURRENT production deployment of a Vercel project (`GET /v9/projects/{projectId}`, `targets.production`), projected to `{ projectId, name, production: { id, url, readyState, createdAt } | null }`. `production` is null when the project has none. This is what `vercel_deployment_promote` replaces.",
+    z.object({ projectId: idArg }),
+    async (p) => jsonResult(await readProductionState(p.projectId)),
+  );
+
+  registerWriteTool(
+    "vercel_deployment_redeploy",
+    {
+      mutates: "vercel.deployment.redeploy",
+      // A production redeploy can supersede the deployment that is live, and nothing here puts it
+      // back. The source deployment is recorded in the audit pre-state.
+      recoverable: false,
+      capturePreState: async (p: { deploymentId: string }) => {
+        const { id, target, readyState } = await readDeployment(p.deploymentId);
+        return { id, target, readyState };
+      },
+      scopeTargetOf: (p: { deploymentId: string }) => ({
+        kind: "deployment",
+        value: p.deploymentId,
+      }),
+    },
+    "Redeploy an existing Vercel deployment as a NEW build (`POST /v13/deployments?forceNew=1`, body `{ name, deploymentId, target, withLatestCommit? }`). `target` is required and always sent: `production` replaces the live site once the new build is ready, `preview` does not (omitting it would make a preview). The project `name` is read from the source deployment first, and an unknown deployment sends nothing. The reply is `accepted` with the NEW deployment's id: Vercel builds it afterwards, so poll `vercel_get` until `readyState` is READY. Not undone by this tool.",
+    z.object({
+      deploymentId: idArg,
+      target: z.enum(["production", "preview"]),
+      withLatestCommit: z.boolean().optional(),
+    }),
+    async (p) => {
+      const source = await readDeployment(p.deploymentId);
+      if (source.name === undefined) {
+        throw new Error(
+          `Vercel deployment ${p.deploymentId} has no project name; nothing was sent`,
+        );
+      }
+      const body: Obj = { name: source.name, deploymentId: p.deploymentId, target: p.target };
+      if (p.withLatestCommit !== undefined) {
+        body["withLatestCommit"] = p.withLatestCommit;
+      }
+      const reply = asObj(await sendJson("POST", withTeam("/v13/deployments?forceNew=1"), body));
+      return jsonResult({
+        ok: true,
+        status: "accepted",
+        deploymentId: str(reply["id"]) ?? str(reply["uid"]),
+        url: str(reply["url"]),
+        readyState: str(reply["readyState"]) ?? str(reply["state"]),
+      });
+    },
+  );
+
+  registerWriteTool(
+    "vercel_deployment_promote",
+    {
+      mutates: "vercel.deployment.promote",
+      // The previous production deployment is recorded; promoting it back is a second promote.
+      recoverable: false,
+      capturePreState: (p: { projectId: string }) => readProductionState(p.projectId),
+      scopeTargetOf: (p: { projectId: string }) => ({ kind: "project", value: p.projectId }),
+    },
+    "Promote an existing Vercel deployment to production WITHOUT rebuilding it (`POST /v10/projects/{projectId}/promote/{deploymentId}`, no body). The deployment that is production now stops being current: read it first with `vercel_project_production_get`. The reply is `accepted`; Vercel applies the promotion afterwards.",
+    z.object({ projectId: idArg, deploymentId: idArg }),
+    async (p) => {
+      await sendJson(
+        "POST",
+        withTeam(
+          `/v10/projects/${encodeURIComponent(p.projectId)}/promote/${encodeURIComponent(p.deploymentId)}`,
+        ),
+        undefined,
+      );
+      return jsonResult({
+        ok: true,
+        status: "accepted",
+        projectId: p.projectId,
+        deploymentId: p.deploymentId,
+      });
+    },
+  );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-dev/connectors",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "publishConfig": {
     "access": "public"
   },

package/shared/cap-text.ts

@@ -0,0 +1,15 @@
+/** Longest vendor string a read projection returns, in UTF-16 code units. */
+export const MAX_VENDOR_TEXT = 500;
+
+/** Appended to a string that was cut, so a reader can tell it is not the whole value. */
+export const TRUNCATION_MARKER = "...[truncated]";
+
+/**
+ * A vendor string capped at `max` characters, with an explicit marker when it was cut; `undefined`
+ * for anything that is not a non-empty string. Read projections use it so one unbounded field
+ * (an error message, a commit message) cannot flood the model's context.
+ */
+export function capText(value: unknown, max: number = MAX_VENDOR_TEXT): string | undefined {
+  if (typeof value !== "string" || value === "") return undefined;
+  return value.length <= max ? value : `${value.slice(0, max)}${TRUNCATION_MARKER}`;
+}

package/shared/consent-kit.ts

@@ -82,6 +82,14 @@ export type WriteToolConfig<T> = {
   readonly capturePreState?: (args: T) => Promise<Record<string, unknown>>;
   /** The scope target this invocation would touch, checked against the allow-list. */
   readonly scopeTargetOf: (args: T) => { kind: string; value: string };
+  /**
+   * A refusal no consent can lift (an input the tool will reject, a tool that is refused outright),
+   * as its message, or `undefined` to proceed. Standalone only, and checked FIRST, before scope,
+   * budget and prompt: asking a human to approve a call that is certain to fail trains them to
+   * click through. It does NOT replace the handler's own check: in gateway mode the raw handler is
+   * registered and this is never called, so the handler must refuse the same input itself.
+   */
+  readonly refuseBefore?: (args: T) => string | undefined;
 };
 
 export type WriteToolRegistrar = <T>(
@@ -348,6 +356,13 @@ export function createWriteToolRegistrar(
     const guarded = async (args: T): Promise<McpListResult> => {
       const target = toolCfg.scopeTargetOf(args);
 
+      // 0. A refusal no consent can lift comes before everything that could involve a human.
+      const early = toolCfg.refuseBefore?.(args);
+      if (early !== undefined) {
+        await record(name, "refused", { reason: early, target });
+        return refused(early);
+      }
+
       // 1. SCOPE FIRST — before prompting. Asking a human to approve something the operator
       //    already forbade cannot change the outcome, and training people to click through
       //    prompts that do not matter is how you make the prompts that do matter ineffective.

package/shared/env-json-api.ts

@@ -222,17 +222,35 @@ export function createJsonSender(
   return async (method, path, body, extraHeaders) => {
     const text = await send(
       path,
-      (headers) => ({
-        method,
-        headers: { ...headers, "Content-Type": "application/json", ...extraHeaders },
-        body: JSON.stringify(body),
-      }),
+      // An `undefined` body is a bodiless request (Netlify's build trigger, Vercel's promote): no
+      // entity, so no Content-Type either, which a server may read as a body that must parse.
+      (headers) =>
+        body === undefined
+          ? { method, headers: { ...headers, ...extraHeaders } }
+          : {
+              method,
+              headers: { ...headers, "Content-Type": "application/json", ...extraHeaders },
+              body: JSON.stringify(body),
+            },
       errorPrefix(method, path),
     );
-    return text === "" ? {} : (JSON.parse(text) as unknown);
+    return parsedOrEmpty(text);
   };
 }
 
+/**
+ * A 2xx body as JSON, or `{}` when it is empty or not JSON. The write was applied either way, and a
+ * throw here would invite the caller to retry it (a duplicate build, a second invitation email).
+ */
+function parsedOrEmpty(text: string): unknown {
+  if (text === "") return {};
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return {};
+  }
+}
+
 /**
  * The mutating twin of {@link createJsonGetter}: a `(path, body) => Promise<unknown>`
  * POST client that sends `body` as JSON (adding `Content-Type: application/json` to

package/shared/prepare-tool-ids.ts

@@ -7,11 +7,20 @@
  * is here. A naming convention would not do: a suffix rule passes `*_files_get`-style names that
  * the gateway treats as plain reads, and ids of the same class do not share a suffix.
  *
- * Grows per release: this one lists the two commit tools; the IaC, CloudFormation and Kubernetes
- * ones are added by the PR that registers them. `prepare-tool-ids.test.ts` requires every id here
- * to be registered exactly once, through `createPrepareToolRegistrar` and nothing else.
+ * Grows per release: 0.8.0 listed the two commit tools; the next release adds the Terraform plan,
+ * destroy-plan and show-json tools, the CloudFormation change-set create and the Kubernetes
+ * manifest plan. `prepare-tool-ids.test.ts` requires every id here to be registered exactly once,
+ * through `createPrepareToolRegistrar` and nothing else.
  */
-export const PREPARE_TOOL_IDS = ["github_commit_prepare", "gitlab_commit_prepare"] as const;
+export const PREPARE_TOOL_IDS = [
+  "github_commit_prepare",
+  "gitlab_commit_prepare",
+  "iac_terraform_plan",
+  "iac_terraform_destroy_plan",
+  "iac_terraform_show_json",
+  "iac_cloudformation_changeset_create",
+  "k8s_manifest_plan",
+] as const;
 
 export type PrepareToolId = (typeof PREPARE_TOOL_IDS)[number];
 

package/shared/private-kubeconfig.ts

@@ -21,10 +21,11 @@
 import { constants } from "node:fs";
 import { lstat, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { delimiter, isAbsolute, join } from "node:path";
+import { delimiter, join } from "node:path";
+import { configuredScratchBase } from "./private-scratch.ts";
 
 /** Names the directory private kubeconfigs are made in; an absolute path, else `os.tmpdir()`. */
-export const SCRATCH_DIR_ENV = "NIMBUS_CONNECTOR_SCRATCH_DIR";
+export { SCRATCH_DIR_ENV } from "./private-scratch.ts";
 
 /**
  * The one path `raw` (a `KUBECONFIG` value) names. A list of paths throws: a tool that cannot say
@@ -57,14 +58,14 @@ export function singleKubeconfigPath(
   return only;
 }
 
-/** The base directory private kubeconfigs are made under. */
+/**
+ * The base directory private kubeconfigs are made under: the configured scratch base, else
+ * `os.tmpdir()` on every platform. Unlike `withScratchDir` (private-scratch.ts) this does NOT
+ * refuse on Windows under the gateway: the before-state reads shipped in 0.8.0 run there today
+ * without the env var, and the gateway grants it with the Kubernetes write rows (D3).
+ */
 function scratchBase(): string {
-  const configured = process.env[SCRATCH_DIR_ENV]?.trim();
-  if (configured === undefined || configured === "") return tmpdir();
-  if (!isAbsolute(configured)) {
-    throw new Error(`${SCRATCH_DIR_ENV} must be an absolute path`);
-  }
-  return configured;
+  return configuredScratchBase() ?? tmpdir();
 }
 
 /** Refuse a source that is not a plain file: a symlink, a directory, a device. */

package/shared/private-scratch.ts

@@ -0,0 +1,68 @@
+/**
+ * private-scratch — a private directory for one tool call's files, removed when the call settles.
+ *
+ * The CLI-backed write tools hand their CLI a file rather than an argument: a CloudFormation
+ * template, a Kubernetes manifest. Each call gets its own 0700 directory under the configured
+ * scratch base, so concurrent calls never share a file and nothing outlives the call.
+ *
+ * The base is `NIMBUS_CONNECTOR_SCRATCH_DIR` (absolute) when set. When it is not, `os.tmpdir()`,
+ * with one exception: a Windows connector running under the gateway REFUSES. The gateway sandboxes
+ * a Windows connector in an AppContainer and grants it a per-action directory through that env
+ * var; the user temp directory is not that grant, so a file written there is either refused by
+ * the sandbox or, worse, shared with every other process of the user. Failing closed names the
+ * missing grant instead.
+ */
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { getConnectorMode } from "./connector-mode.ts";
+
+/** Names the directory scratch directories are made in; an absolute path. */
+export const SCRATCH_DIR_ENV = "NIMBUS_CONNECTOR_SCRATCH_DIR";
+
+/**
+ * The configured scratch base, or `undefined` when none is configured. Throws on a relative
+ * value: a relative base would resolve against whatever the connector's cwd happens to be.
+ */
+export function configuredScratchBase(): string | undefined {
+  const configured = process.env[SCRATCH_DIR_ENV]?.trim();
+  if (configured === undefined || configured === "") return undefined;
+  if (!isAbsolute(configured)) {
+    throw new Error(`${SCRATCH_DIR_ENV} must be an absolute path`);
+  }
+  return configured;
+}
+
+/**
+ * The base a {@link withScratchDir} directory is made under (see the module comment for the
+ * Windows-under-the-gateway refusal). `platform` is a parameter so both sides are testable.
+ */
+export function scratchDirBase(platform: NodeJS.Platform = process.platform): string {
+  const configured = configuredScratchBase();
+  if (configured !== undefined) return configured;
+  if (platform === "win32" && getConnectorMode() === "gateway") {
+    throw new Error(
+      `${SCRATCH_DIR_ENV} is not set: on Windows the gateway must grant this connector a scratch ` +
+        "directory, and the user temp directory is not one",
+    );
+  }
+  return tmpdir();
+}
+
+/**
+ * Run `body` with a fresh 0700 directory of its own, removed when `body` settles, success or
+ * failure. `prefix` names the directory (`nimbus-cfn-`, `nimbus-k8s-`).
+ */
+export async function withScratchDir<T>(
+  prefix: string,
+  body: (dir: string) => Promise<T>,
+): Promise<T> {
+  const base = scratchDirBase();
+  const dir = await mkdtemp(join(base, prefix));
+  try {
+    return await body(dir);
+  } finally {
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
+  }
+}