@nimbus-dev/connectors 0.9.0 → 0.11.0

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.9.0",
+  "version": "0.11.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/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/line-diff.ts

@@ -0,0 +1,158 @@
+/**
+ * line-diff: a pure unified diff of two lists of lines (Myers' O(ND) shortest edit script).
+ *
+ * It exists so a tool can show an approver exactly what will change without starting a `diff`
+ * program: Windows ships none, and a program the environment names is not one to trust with the text
+ * an owner approves. Equal inputs give "". The output has the two header lines, then one hunk
+ * `@@ -a,b +c,d @@` per run of changes with `context` lines either side (hunks whose context touches
+ * are merged), every line ending with "\n". Counts are always written, `,1` included.
+ *
+ * Bounded: an edit script longer than {@link MAX_EDIT_DISTANCE} throws {@link LineDiffTooLargeError}
+ * (the caller refuses, it never cuts), so a pathological input cannot hold memory or the event loop.
+ */
+
+export const MAX_EDIT_DISTANCE = 2000;
+
+/** `V[j]` from a trace window that holds `V[-d..d]` (index `j + d`); 0 outside it. */
+function at(window: Int32Array, d: number, j: number): number {
+  return j < -d || j > d ? 0 : (window[j + d] ?? 0);
+}
+
+export class LineDiffTooLargeError extends Error {
+  constructor() {
+    super("the two sides differ by too many lines to diff");
+    this.name = "LineDiffTooLargeError";
+  }
+}
+
+type Op = { readonly kind: " " | "-" | "+"; readonly text: string };
+
+/** The edit script from `a` to `b`: the equal prefix and suffix are peeled off, Myers does the rest. */
+function editScript(a: readonly string[], b: readonly string[]): Op[] {
+  let start = 0;
+  while (start < a.length && start < b.length && a[start] === b[start]) start += 1;
+  let endA = a.length;
+  let endB = b.length;
+  while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+    endA -= 1;
+    endB -= 1;
+  }
+  const head: Op[] = a.slice(0, start).map((text) => ({ kind: " ", text }));
+  const tail: Op[] = a.slice(endA).map((text) => ({ kind: " ", text }));
+  return [...head, ...myers(a.slice(start, endA), b.slice(start, endB)), ...tail];
+}
+
+function myers(a: readonly string[], b: readonly string[]): Op[] {
+  const n = a.length;
+  const m = b.length;
+  if (n === 0) return b.map((text) => ({ kind: "+", text }));
+  if (m === 0) return a.map((text) => ({ kind: "-", text }));
+  const max = Math.min(n + m, MAX_EDIT_DISTANCE);
+  const offset = max + 1;
+  const v = new Int32Array(2 * max + 3);
+  // trace[d] is V[-d..d] as it stood BEFORE step d (index k + d), all the walk back reads. Storing
+  // the whole V at every step would hold (max + 1) * (2 * max + 3) values; the window holds about
+  // max * max, 16 MB at the bound.
+  const trace: Int32Array[] = [];
+  let found = -1;
+  for (let d = 0; d <= max && found < 0; d += 1) {
+    trace.push(v.slice(offset - d, offset + d + 1));
+    for (let k = -d; k <= d; k += 2) {
+      const down = k === -d || (k !== d && (v[offset + k - 1] ?? 0) < (v[offset + k + 1] ?? 0));
+      let x = down ? (v[offset + k + 1] ?? 0) : (v[offset + k - 1] ?? 0) + 1;
+      let y = x - k;
+      while (x < n && y < m && a[x] === b[y]) {
+        x += 1;
+        y += 1;
+      }
+      v[offset + k] = x;
+      if (x >= n && y >= m) {
+        found = d;
+        break;
+      }
+    }
+  }
+  if (found < 0) throw new LineDiffTooLargeError();
+  const ops: Op[] = [];
+  let x = n;
+  let y = m;
+  for (let d = found; d > 0; d -= 1) {
+    const prev = trace[d];
+    if (prev === undefined) throw new LineDiffTooLargeError();
+    const k = x - y;
+    const down = k === -d || (k !== d && at(prev, d, k - 1) < at(prev, d, k + 1));
+    const prevK = down ? k + 1 : k - 1;
+    const prevX = at(prev, d, prevK);
+    const prevY = prevX - prevK;
+    while (x > prevX && y > prevY) {
+      x -= 1;
+      y -= 1;
+      ops.push({ kind: " ", text: a[x] ?? "" });
+    }
+    if (down) {
+      y -= 1;
+      ops.push({ kind: "+", text: b[y] ?? "" });
+    } else {
+      x -= 1;
+      ops.push({ kind: "-", text: a[x] ?? "" });
+    }
+  }
+  while (x > 0 && y > 0) {
+    x -= 1;
+    y -= 1;
+    ops.push({ kind: " ", text: a[x] ?? "" });
+  }
+  return ops.reverse();
+}
+
+export function unifiedLineDiff(
+  from: readonly string[],
+  to: readonly string[],
+  opts: {
+    readonly fromLabel: string;
+    readonly toLabel: string;
+    readonly context?: number | undefined;
+  },
+): string {
+  const context = opts.context ?? 3;
+  const ops = editScript(from, to);
+  const changed: number[] = [];
+  ops.forEach((op, i) => {
+    if (op.kind !== " ") changed.push(i);
+  });
+  if (changed.length === 0) return "";
+
+  // Group the changes into hunks: [first, last] indexes into ops, widened by the context.
+  const ranges: [number, number][] = [];
+  for (const i of changed) {
+    const lo = Math.max(0, i - context);
+    const hi = Math.min(ops.length - 1, i + context);
+    const last = ranges[ranges.length - 1];
+    if (last !== undefined && lo <= last[1] + 1) last[1] = hi;
+    else ranges.push([lo, hi]);
+  }
+
+  // Lines of each side consumed before each op, so a hunk's start is a lookup.
+  const aBefore: number[] = [];
+  const bBefore: number[] = [];
+  let ai = 0;
+  let bi = 0;
+  for (const op of ops) {
+    aBefore.push(ai);
+    bBefore.push(bi);
+    if (op.kind !== "+") ai += 1;
+    if (op.kind !== "-") bi += 1;
+  }
+
+  const out = [`--- ${opts.fromLabel}`, `+++ ${opts.toLabel}`];
+  for (const [lo, hi] of ranges) {
+    const slice = ops.slice(lo, hi + 1);
+    const aCount = slice.filter((o) => o.kind !== "+").length;
+    const bCount = slice.filter((o) => o.kind !== "-").length;
+    const aStart = (aBefore[lo] ?? 0) + (aCount === 0 ? 0 : 1);
+    const bStart = (bBefore[lo] ?? 0) + (bCount === 0 ? 0 : 1);
+    out.push(`@@ -${String(aStart)},${String(aCount)} +${String(bStart)},${String(bCount)} @@`);
+    for (const op of slice) out.push(`${op.kind}${op.text}`);
+  }
+  return `${out.join("\n")}\n`;
+}