@nimbus-dev/connectors 0.6.0 → 0.8.0

package/shared/commit-files.ts

@@ -0,0 +1,138 @@
+/**
+ * commit-files: what the multi-file commit tools (`github_file_commit`, `gitlab_commit_create`) and
+ * their prepare tools (`github_commit_prepare`, `gitlab_commit_prepare`) agree on, so the preview the
+ * owner approves and the commit that runs are bounded by the same rules.
+ *
+ * - Text files only, written whole: no deletes, no mode changes, no symlinks, no submodules.
+ * - At most {@link COMMIT_MAX_FILES} files, and the combined size of the old content that is shown and
+ *   the new content that is sent at most {@link COMMIT_MAX_COMBINED_BYTES}. The prepare tool REFUSES a
+ *   bigger commit rather than truncating: the preview never shows less than is sent, and its reply
+ *   stays under the gateway's 256 KiB cap.
+ */
+
+import { z } from "zod";
+
+export const COMMIT_MAX_FILES = 20;
+export const COMMIT_MAX_COMBINED_BYTES = 192 * 1024;
+
+const FULL_SHA = /^[0-9a-f]{40}$/i;
+
+/** A full 40-hex commit sha, any case. */
+export const fullShaSchema = z.string().regex(FULL_SHA, "a full 40-hex commit sha");
+
+/**
+ * A character the approval preview cannot be trusted to show as it is: any Unicode control (Cc, which
+ * includes DEL and the C1 range U+0080..U+009F), format character (Cf: bidi overrides, zero-width
+ * spaces, the byte-order mark), line or paragraph separator (Zl, Zp), or lone surrogate (Cs).
+ */
+const UNSHOWABLE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{Cs}]/u;
+
+/**
+ * Whether a path segment spells `.git` on a filesystem that folds it: NTFS and HFS+ ignore trailing
+ * dots and spaces and compare case-insensitively, and NTFS also knows the short name `GIT~1`. A
+ * segment that is nothing but dots and spaces is refused too, since it folds to the empty name.
+ */
+function isGitSpelling(segment: string): boolean {
+  const folded = segment.replace(/[. ]+$/u, "").toLowerCase();
+  return folded === "" || folded === ".git" || folded === "git~1";
+}
+
+/**
+ * Whether `path` is a repository-relative file path the commit tools accept: 1..1024 characters, no
+ * leading or trailing `/`, no `//`, no backslash, no unshowable character (see {@link UNSHOWABLE}),
+ * and no `.` or `..` segment or spelling of `.git` (see {@link isGitSpelling}). The path reaches a
+ * URL path or a JSON body, never a shell.
+ */
+export function isSafeCommitPath(path: string): boolean {
+  if (path.length < 1 || path.length > 1024) return false;
+  if (path.startsWith("/") || path.endsWith("/") || path.includes("//") || path.includes("\\")) {
+    return false;
+  }
+  if (UNSHOWABLE.test(path)) return false;
+  return path.split("/").every((seg) => seg !== "." && seg !== ".." && !isGitSpelling(seg));
+}
+
+export const commitFilePathSchema = z
+  .string()
+  .refine(isSafeCommitPath, "not a safe repository file path");
+
+/** One file of a commit: its path and its whole new text. */
+export const commitFileSchema = z.object({
+  path: commitFilePathSchema,
+  content: z.string(),
+});
+
+export type CommitFile = z.infer<typeof commitFileSchema>;
+
+/** The `files` field: 1..{@link COMMIT_MAX_FILES} entries. Uniqueness is checked by {@link assertCommitFiles}. */
+export const commitFilesSchema = z.array(commitFileSchema).min(1).max(COMMIT_MAX_FILES);
+
+/** UTF-8 byte length of `text`. */
+export function utf8Length(text: string): number {
+  return new TextEncoder().encode(text).length;
+}
+
+/**
+ * The checks a schema cannot make (a schema holding them would have to be `.refine()`d, which loses
+ * `.shape`): paths unique, and the NEW content alone within the combined cap. Throws a fixed message.
+ */
+export function assertCommitFiles(files: readonly CommitFile[]): void {
+  if (files.length > COMMIT_MAX_FILES) {
+    throw new Error(`a commit may touch at most ${String(COMMIT_MAX_FILES)} files`);
+  }
+  const seen = new Set<string>();
+  for (const f of files) {
+    if (seen.has(f.path)) throw new Error(`duplicate file path in commit: ${f.path}`);
+    seen.add(f.path);
+  }
+  // A path and one beneath it (`a` and `a/b`) cannot both be files of one tree.
+  for (const path of seen) {
+    const segments = path.split("/");
+    for (let i = 1; i < segments.length; i++) {
+      const parent = segments.slice(0, i).join("/");
+      if (seen.has(parent)) {
+        throw new Error(
+          `path collision in commit: ${parent} is a file and also a directory of ${path}`,
+        );
+      }
+    }
+  }
+  const bytes = files.reduce((n, f) => n + utf8Length(f.content), 0);
+  if (bytes > COMMIT_MAX_COMBINED_BYTES) {
+    throw new Error(commitTooLarge());
+  }
+}
+
+/** The one refusal for a commit over the combined cap. */
+export function commitTooLarge(): string {
+  return `commit too large: the old and new content together exceed ${String(COMMIT_MAX_COMBINED_BYTES / 1024)} KiB`;
+}
+
+/** Throws when `oldBytes + newBytes` is over the combined cap. */
+export function assertCombinedSize(oldBytes: number, files: readonly CommitFile[]): void {
+  const newBytes = files.reduce((n, f) => n + utf8Length(f.content), 0);
+  if (oldBytes + newBytes > COMMIT_MAX_COMBINED_BYTES) throw new Error(commitTooLarge());
+}
+
+export type DecodedText = { readonly text: string } | { readonly binary: true };
+
+/**
+ * Decode base64 file bytes as UTF-8. Bytes that are not valid UTF-8, or that hold a NUL, are
+ * `binary`: their content is withheld and the commit tools refuse to overwrite them.
+ */
+export function decodeBase64Text(base64: string): DecodedText {
+  const bytes = Buffer.from(base64.replaceAll(/\s/g, ""), "base64");
+  if (bytes.includes(0)) return { binary: true };
+  try {
+    return { text: new TextDecoder("utf-8", { fatal: true }).decode(bytes) };
+  } catch {
+    return { binary: true };
+  }
+}
+
+/** The error a commit tool throws for an existing file it will not overwrite. */
+export function notOverwritable(path: string): Error {
+  return new Error(
+    `${path} is not a text file the commit tools can overwrite (binary, symlink, submodule, a directory in the way, or too large)`,
+  );
+}

package/shared/consent-kit.ts

@@ -2,8 +2,9 @@ import type { McpListResult, ZodObjectSchema } from "@nimbus-dev/sdk/connector-k
 
 import { type AuditOutcome, appendAuditEntry } from "./audit-chain.ts";
 import { getConnectorMode } from "./connector-mode.ts";
+import { isPrepareToolId } from "./prepare-tool-ids.ts";
 import { createWriteBudget, parseWriteBudget, WRITE_BUDGET_ENV } from "./write-budget.ts";
-import { parseWriteScope, scopeAllows } from "./write-scope.ts";
+import { parseWriteScope, type ScopeTerm, scopeAllows } from "./write-scope.ts";
 
 /** The subset of the SDK's `RegisteredTool` this kit needs. */
 export type ToolHandle = { disable(): void };
@@ -158,40 +159,35 @@ function registerOn<T>(
   handles.push(handle);
 }
 
+/** What both registrars share: the parsed write scope and the audit/log record. */
+type ConsentContext = {
+  readonly scope: readonly ScopeTerm[];
+  readonly record: (
+    tool: string,
+    outcome: AuditOutcome,
+    detail: Record<string, unknown>,
+  ) => Promise<void>;
+};
+
+type RegistrarConfig = {
+  readonly connector: string;
+  readonly scopeEnv: string;
+  /**
+   * Scope kinds this connector accepts. Declared once per connector rather than per tool: the
+   * allow-list is parsed at registrar construction, before any tool has registered, so a
+   * per-tool declaration would arrive too late to validate the env value.
+   */
+  readonly scopeKinds: readonly string[];
+};
+
 /**
- * Build a connector's write-tool registrar.
- *
- * In `"gateway"` mode the raw handler is registered immediately: `executor.ts` (I2) is the gate
- * there, client capabilities are irrelevant, and the connector adds nothing.
- *
- * In `"standalone"` mode registration is QUEUED and flushed on `oninitialized`, because client
- * capabilities are not knowable at module scope — verified against the real SDK, where
- * `getClientCapabilities()` returns `undefined` before `initialize`. Deciding at registration time
- * would register nothing, for every client, forever.
+ * The scope parse and the record function, built once per registrar. Extracted (not copied) so the
+ * write registrar and the prepare registrar cannot drift apart on what a scope term means or on
+ * which channels a record reaches.
  */
-export function createWriteToolRegistrar(
-  server: ConsentServer,
-  cfg: {
-    readonly connector: string;
-    readonly scopeEnv: string;
-    /**
-     * Scope kinds this connector accepts. Declared once per connector rather than per tool: the
-     * allow-list is parsed at registrar construction, before any tool has registered, so a
-     * per-tool declaration would arrive too late to validate the env value.
-     */
-    readonly scopeKinds: readonly string[];
-  },
-): WriteToolRegistrar {
-  const handles: ToolHandle[] = [];
-  const pending: Array<() => void> = [];
-  let flushed = false;
-
+function createConsentContext(server: ConsentServer, cfg: RegistrarConfig): ConsentContext {
   const scope = parseWriteScope(process.env[cfg.scopeEnv], cfg.scopeKinds);
   const auditLog = process.env["NIMBUS_MCP_AUDIT_LOG"];
-  // Throws on a value that is not plain digits, an empty one included, as the scope parse above
-  // does on a malformed term: read with `Number()`, `abc` became NaN, which `remaining <= 0` never
-  // refused.
-  const budget = createWriteBudget(parseWriteBudget(process.env[WRITE_BUDGET_ENV]));
 
   async function record(
     tool: string,
@@ -227,6 +223,34 @@ export function createWriteToolRegistrar(
     }
   }
 
+  return { scope, record };
+}
+
+/**
+ * Build a connector's write-tool registrar.
+ *
+ * In `"gateway"` mode the raw handler is registered immediately: `executor.ts` (I2) is the gate
+ * there, client capabilities are irrelevant, and the connector adds nothing.
+ *
+ * In `"standalone"` mode registration is QUEUED and flushed on `oninitialized`, because client
+ * capabilities are not knowable at module scope — verified against the real SDK, where
+ * `getClientCapabilities()` returns `undefined` before `initialize`. Deciding at registration time
+ * would register nothing, for every client, forever.
+ */
+export function createWriteToolRegistrar(
+  server: ConsentServer,
+  cfg: RegistrarConfig,
+): WriteToolRegistrar {
+  const handles: ToolHandle[] = [];
+  const pending: Array<() => void> = [];
+  let flushed = false;
+
+  const { scope, record } = createConsentContext(server, cfg);
+  // Throws on a value that is not plain digits, an empty one included, as the scope parse above
+  // does on a malformed term: read with `Number()`, `abc` became NaN, which `remaining <= 0` never
+  // refused.
+  const budget = createWriteBudget(parseWriteBudget(process.env[WRITE_BUDGET_ENV]));
+
   /**
    * Take one unit of budget if any is left. Spending the last unit disables every write tool and
    * tells the client.
@@ -398,3 +422,89 @@ export function createWriteToolRegistrar(
     });
   };
 }
+
+/** What a prepare tool declares: only the scope target, since it mutates nothing. */
+export type PrepareToolConfig<T> = {
+  /** The scope target this invocation reads on behalf of, checked against the allow-list. */
+  readonly scopeTargetOf: (args: T) => { kind: string; value: string };
+};
+
+export type PrepareToolRegistrar = <T>(
+  name: string,
+  cfg: PrepareToolConfig<T>,
+  description: string,
+  schema: ZodObjectSchema<T>,
+  handler: (args: T) => Promise<McpListResult>,
+) => void;
+
+/**
+ * Build a connector's prepare-tool registrar.
+ *
+ * A prepare tool reads the state a write is bound to (the head a commit is prepared against) and is
+ * called by the gateway BEFORE the write's approval prompt. It is not a write: it is registered
+ * under its own registrar so the gateway's manifest scan, which follows the write registrar's data
+ * flow, does not list it as one. And it is not an ordinary read either: a tool is accepted only when
+ * its name is in {@link PREPARE_TOOL_IDS} (shared/prepare-tool-ids.ts), so the class is one literal
+ * list and not a naming convention.
+ *
+ * In `"gateway"` mode the raw handler is registered: the executor's prepare step is the gate there.
+ * In `"standalone"` mode it is registered at once for EVERY client (a prepare tool prompts no one,
+ * so no elicitation capability is needed), behind the same write scope as the writes it serves, and
+ * each in-scope run is audited as `prepared`. It spends no write budget and is never disabled by
+ * the budget running out: a second prompt before the apply prompt would only train click-through.
+ */
+export function createPrepareToolRegistrar(
+  server: ConsentServer,
+  cfg: RegistrarConfig,
+): PrepareToolRegistrar {
+  const { scope, record } = createConsentContext(server, cfg);
+  // Prepare tools are not budget-gated, so nothing ever disables them; the handles are not kept.
+  const handles: ToolHandle[] = [];
+
+  return <T>(
+    name: string,
+    toolCfg: PrepareToolConfig<T>,
+    description: string,
+    schema: ZodObjectSchema<T>,
+    handler: (args: T) => Promise<McpListResult>,
+  ): void => {
+    if (!isPrepareToolId(name)) {
+      throw new Error(
+        `${name}: not a listed prepare tool — add the id to PREPARE_TOOL_IDS in ` +
+          "shared/prepare-tool-ids.ts, or register it as a read or a write",
+      );
+    }
+
+    if (getConnectorMode() === "gateway") {
+      registerOn(server, name, description, schema, handler, handles);
+      return;
+    }
+
+    const guarded = async (args: T): Promise<McpListResult> => {
+      const target = toolCfg.scopeTargetOf(args);
+      if (!scopeAllows(scope, target.kind, target.value)) {
+        await record(name, "refused", { reason: "out of scope", target });
+        return refused(`out of scope: ${target.kind}:${target.value} is not in ${cfg.scopeEnv}`);
+      }
+      let result: McpListResult;
+      try {
+        result = await handler(args);
+      } catch (e) {
+        // As a write does: record the failure, and if recording it fails too, the tool's own error
+        // still leads, since an audit error alone would read as a prepare that never started.
+        try {
+          await record(name, "failed", { target, error: messageOf(e) });
+        } catch (error_) {
+          throw new Error(
+            `${name} failed: ${messageOf(e)}. Recording that failure also failed: ${messageOf(error_)}`,
+            { cause: e },
+          );
+        }
+        throw e;
+      }
+      await record(name, "prepared", { target });
+      return result;
+    };
+    registerOn(server, name, description, schema, guarded, handles);
+  };
+}

package/shared/github-files.ts

@@ -0,0 +1,195 @@
+/**
+ * github-files: read files at a commit through the Git Data API, for the batch read
+ * (`github_files_get`), the prepare tool (`github_commit_prepare`) and the commit
+ * (`github_file_commit`), so what the owner was shown and what is committed come from one reader.
+ *
+ * Sources (https://docs.github.com/en/rest/git/{commits,trees,blobs,refs}):
+ * - `GET /git/commits/{sha}` returns `tree.sha`.
+ * - `GET /git/trees/{sha}` (non-recursive) lists `path, mode, type, sha, size`, with a top-level
+ *   `truncated` and the advice to "fetch subtrees one at a time": a path is walked one level at a
+ *   time, and a truncated level is an error, never a guess that the file is absent.
+ * - `GET /git/blobs/{sha}` returns base64 `content`.
+ * - `PATCH /git/refs/heads/{branch}` with `force` false must be a fast-forward; the documented
+ *   statuses are 200, 409 and 422.
+ */
+
+import { decodeBase64Text } from "./commit-files.ts";
+import { ghFetch, ghRepoPath } from "./github-rest.ts";
+
+type TreeEntry = { path: string; mode: string; type: string; sha: string; size?: number };
+
+export type GithubFileRead =
+  | { readonly path: string; readonly exists: false }
+  | {
+      readonly path: string;
+      readonly exists: true;
+      readonly kind: "text";
+      readonly mode: string;
+      readonly sha: string;
+      readonly size: number;
+      /** Present only when content was asked for. */
+      readonly content?: string;
+    }
+  | {
+      readonly path: string;
+      readonly exists: true;
+      readonly kind: "binary" | "not-regular" | "too-large" | "budget";
+      readonly mode: string;
+      readonly sha: string;
+      readonly size?: number;
+    };
+
+function fail(res: { status: number; text: string }): never {
+  throw new Error(`GitHub ${String(res.status)}: ${res.text.slice(0, 300)}`);
+}
+
+async function getJson(token: string, path: string): Promise<unknown> {
+  const res = await ghFetch(token, path);
+  if (!res.ok) fail(res);
+  return res.json;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** `tree.sha` of a commit. */
+export async function commitTreeSha(
+  token: string,
+  owner: string,
+  repo: string,
+  commitSha: string,
+): Promise<string> {
+  const json = await getJson(token, `${ghRepoPath(owner, repo)}/git/commits/${commitSha}`);
+  const tree = isRecord(json) && isRecord(json["tree"]) ? json["tree"]["sha"] : undefined;
+  if (typeof tree !== "string") throw new Error("GitHub returned no tree for the commit");
+  return tree;
+}
+
+function parseTree(json: unknown): TreeEntry[] {
+  if (!isRecord(json)) throw new Error("GitHub returned no tree");
+  if (json["truncated"] === true) {
+    throw new Error("GitHub truncated a directory listing; refusing to guess a file is absent");
+  }
+  const entries = Array.isArray(json["tree"]) ? json["tree"] : [];
+  const out: TreeEntry[] = [];
+  for (const e of entries) {
+    if (
+      isRecord(e) &&
+      typeof e["path"] === "string" &&
+      typeof e["mode"] === "string" &&
+      typeof e["type"] === "string" &&
+      typeof e["sha"] === "string"
+    ) {
+      out.push({
+        path: e["path"],
+        mode: e["mode"],
+        type: e["type"],
+        sha: e["sha"],
+        ...(typeof e["size"] === "number" ? { size: e["size"] } : {}),
+      });
+    }
+  }
+  return out;
+}
+
+/** The tree entry for `path` under `rootTreeSha`, one directory level at a time; undefined if absent. */
+async function findEntry(
+  token: string,
+  owner: string,
+  repo: string,
+  rootTreeSha: string,
+  path: string,
+  cache: Map<string, TreeEntry[]>,
+): Promise<TreeEntry | undefined> {
+  const segments = path.split("/");
+  let treeSha = rootTreeSha;
+  for (const [i, segment] of segments.entries()) {
+    let entries = cache.get(treeSha);
+    if (entries === undefined) {
+      entries = parseTree(await getJson(token, `${ghRepoPath(owner, repo)}/git/trees/${treeSha}`));
+      cache.set(treeSha, entries);
+    }
+    const entry = entries.find((e) => e.path === segment);
+    if (entry === undefined) return undefined;
+    if (i === segments.length - 1) return entry;
+    if (entry.type !== "tree") {
+      // A file sits where a directory is needed: the path cannot exist, and a commit cannot create it.
+      throw new Error(`${path}: ${segments.slice(0, i + 1).join("/")} is a file, not a directory`);
+    }
+    treeSha = entry.sha;
+  }
+  return undefined;
+}
+
+/**
+ * Read `paths` at `commitSha`, returning the commit's root tree sha beside the files. With `withContent`, each text file's content is fetched (a file over
+ * `maxReadBytes` is reported `too-large` without fetching it); without, only the tree entry is read,
+ * which is enough for a mode, a blob sha and a size.
+ *
+ * `totalBudget` caps the content of ALL the files together. The first file that does not fit in what
+ * is left, and every file after it, is reported `budget` with its metadata and no content, and its
+ * blob is not fetched; the read as a whole is not refused.
+ */
+export async function readGithubFilesAt(
+  token: string,
+  owner: string,
+  repo: string,
+  commitSha: string,
+  paths: readonly string[],
+  opts: {
+    readonly withContent: boolean;
+    readonly maxReadBytes: number;
+    readonly totalBudget?: number;
+  },
+): Promise<{ readonly treeSha: string; readonly files: GithubFileRead[] }> {
+  const rootTree = await commitTreeSha(token, owner, repo, commitSha);
+  const cache = new Map<string, TreeEntry[]>();
+  const out: GithubFileRead[] = [];
+  let used = 0;
+  let exhausted = false;
+  for (const path of paths) {
+    const entry = await findEntry(token, owner, repo, rootTree, path, cache); // NOSONAR S9382: sequential on purpose; the tree cache makes later paths cheap.
+    if (entry === undefined) {
+      out.push({ path, exists: false });
+      continue;
+    }
+    if (entry.type !== "blob" || entry.mode === "120000") {
+      out.push({ path, exists: true, kind: "not-regular", mode: entry.mode, sha: entry.sha });
+      continue;
+    }
+    const size = entry.size ?? 0;
+    if (size > opts.maxReadBytes) {
+      out.push({ path, exists: true, kind: "too-large", mode: entry.mode, sha: entry.sha, size });
+      continue;
+    }
+    if (!opts.withContent) {
+      out.push({ path, exists: true, kind: "text", mode: entry.mode, sha: entry.sha, size });
+      continue;
+    }
+    if (opts.totalBudget !== undefined && (exhausted || used + size > opts.totalBudget)) {
+      exhausted = true;
+      out.push({ path, exists: true, kind: "budget", mode: entry.mode, sha: entry.sha, size });
+      continue;
+    }
+    used += size;
+    const blob = await getJson(token, `${ghRepoPath(owner, repo)}/git/blobs/${entry.sha}`); // NOSONAR S9382
+    const b64 = isRecord(blob) && blob["encoding"] === "base64" ? blob["content"] : undefined;
+    if (typeof b64 !== "string") throw new Error(`GitHub returned no base64 content for ${path}`);
+    const decoded = decodeBase64Text(b64);
+    out.push(
+      "binary" in decoded
+        ? { path, exists: true, kind: "binary", mode: entry.mode, sha: entry.sha, size }
+        : {
+            path,
+            exists: true,
+            kind: "text",
+            mode: entry.mode,
+            sha: entry.sha,
+            size,
+            content: decoded.text,
+          },
+    );
+  }
+  return { treeSha: rootTree, files: out };
+}

package/shared/github-rest.ts

@@ -172,6 +172,18 @@ function refCandidates(ref: string): { readonly name: string; readonly kind: "br
   ];
 }
 
+/**
+ * The names to ask `GET /commits/<name>` for, in order, for a user-supplied `ref`. A full sha is one
+ * name; a 7 to 39 hex string is tried as an abbreviated sha first and then as a branch and a tag;
+ * anything else is the `heads/` / `tags/` forms of {@link refCandidates}. `ref` must already
+ * satisfy {@link isSafeGitRef}.
+ */
+export function commitRefCandidates(ref: string): string[] {
+  if (FULL_SHA.test(ref)) return [ref];
+  const named = refCandidates(ref).map((c) => c.name);
+  return /^[0-9a-f]{7,39}$/i.test(ref) ? [ref, ...named] : named;
+}
+
 /**
  * Resolve a branch, tag or commit to a COMMIT sha. `ref` must already satisfy {@link isSafeGitRef}.
  *

package/shared/k8s-deployment-view.ts

@@ -0,0 +1,68 @@
+/**
+ * k8s-deployment-view: the one projection of `kubectl get deployment -o json` that the
+ * `kubernetes` and `gcp` before-state reads share, so a rollout restart or a scale is previewed
+ * from the same fields whichever connector runs it.
+ *
+ * Field sources: apps/v1 Deployment (https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/deployment-v1/).
+ * `status.readyReplicas` is omitted by the API server when zero (the Go field is `omitempty`), so an
+ * absent value is reported as 0; `spec.replicas` is reported as given and is absent when the server
+ * did not return one. The restart time is the annotation `kubectl rollout restart` sets.
+ */
+
+export type DeploymentView = {
+  readonly name: string;
+  readonly namespace: string;
+  readonly replicas?: number;
+  readonly readyReplicas: number;
+  readonly generation?: number;
+  readonly observedGeneration?: number;
+  readonly restartedAt?: string;
+  readonly images: readonly string[];
+};
+
+const RESTARTED_AT = "kubectl.kubernetes.io/restartedAt";
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function num(v: unknown): number | undefined {
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+
+/** Project a Deployment object; throws when `raw` is not one (no name). */
+export function projectDeployment(raw: unknown): DeploymentView {
+  if (!isRecord(raw)) throw new Error("deployment not found");
+  const meta = isRecord(raw["metadata"]) ? raw["metadata"] : {};
+  const spec = isRecord(raw["spec"]) ? raw["spec"] : {};
+  const status = isRecord(raw["status"]) ? raw["status"] : {};
+  const name = meta["name"];
+  if (typeof name !== "string" || name === "") throw new Error("deployment not found");
+  const template = isRecord(spec["template"]) ? spec["template"] : {};
+  const tmeta = isRecord(template["metadata"]) ? template["metadata"] : {};
+  const annotations = isRecord(tmeta["annotations"]) ? tmeta["annotations"] : {};
+  const podSpec = isRecord(template["spec"]) ? template["spec"] : {};
+  const containers = Array.isArray(podSpec["containers"]) ? podSpec["containers"] : [];
+  const images = containers
+    .map((c) => (isRecord(c) && typeof c["image"] === "string" ? c["image"] : undefined))
+    .filter((i): i is string => i !== undefined);
+  const replicas = num(spec["replicas"]);
+  const generation = num(meta["generation"]);
+  const observedGeneration = num(status["observedGeneration"]);
+  const restartedAt = annotations[RESTARTED_AT];
+  return {
+    name,
+    namespace: typeof meta["namespace"] === "string" ? meta["namespace"] : "",
+    ...(replicas === undefined ? {} : { replicas }),
+    readyReplicas: num(status["readyReplicas"]) ?? 0,
+    ...(generation === undefined ? {} : { generation }),
+    ...(observedGeneration === undefined ? {} : { observedGeneration }),
+    ...(typeof restartedAt === "string" ? { restartedAt } : {}),
+    images,
+  };
+}
+
+/** Whether a kubectl failure message says the object does not exist. */
+export function isKubectlNotFound(message: string): boolean {
+  return /NotFound|not found/i.test(message);
+}

package/shared/prepare-tool-ids.ts

@@ -0,0 +1,21 @@
+/**
+ * The prepare class: tools the gateway calls BEFORE a write's approval prompt to read the state the
+ * write is bound to (the branch head a commit was prepared against).
+ *
+ * This is ONE literal list on purpose. The gateway reads it as text, the way it scans the write
+ * manifest, and `createPrepareToolRegistrar` (consent-kit.ts) registers a tool only when its name
+ * 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.
+ */
+export const PREPARE_TOOL_IDS = ["github_commit_prepare", "gitlab_commit_prepare"] as const;
+
+export type PrepareToolId = (typeof PREPARE_TOOL_IDS)[number];
+
+/** Whether `name` is a listed prepare tool id. */
+export function isPrepareToolId(name: string): name is PrepareToolId {
+  return (PREPARE_TOOL_IDS as readonly string[]).includes(name);
+}