@nimbus-dev/connectors 0.1.0

package/shared/imap-tool-kit.ts

@@ -0,0 +1,293 @@
+import type { WriteToolRegistrar } from "./consent-kit.ts";
+/**
+ * Shared tool-layer helpers for the IMAP/JMAP email connectors (imap, protonmail).
+ * Extracted to eliminate byte-identical duplication in tools.ts across those two
+ * connectors. FastMail (JMAP) uses a different view shape (id vs uid, no mailbox
+ * field) and different arg schemas — its view transformer stays local.
+ *
+ * Scope: Zod arg schemas, the shared message view transformer, and the shared
+ * `envInt` + `previewFromParts` server-layer helpers. Class bodies and
+ * connector-specific envelope/meta mappers are deliberately NOT extracted here
+ * (they implement different local interfaces and are out of scope per the dedup
+ * brief).
+ */
+
+import { z } from "zod";
+
+import { headerLine } from "./header-safe.ts";
+import { capPreview, clampLimit } from "./imap-mail-core.ts";
+import { createRegisterSimpleTool, type McpListResult, mcpJsonResult } from "./mcp-tool-kit.ts";
+
+// ---------------------------------------------------------------------------
+// Shared Zod arg schemas (byte-identical across imap + protonmail tools.ts)
+// ---------------------------------------------------------------------------
+
+const listArgs = z.object({
+  mailbox: z.string().min(1).optional(),
+  limit: z.number().int().min(1).max(200).optional(),
+});
+
+const getArgs = z.object({
+  uid: z.number().int().min(1),
+  mailbox: z.string().min(1).optional(),
+});
+
+const searchArgs = z.object({
+  query: z.string().min(1).max(500),
+  mailbox: z.string().min(1).optional(),
+  limit: z.number().int().min(1).max(200).optional(),
+});
+
+const sendArgs = z.object({
+  to: headerLine({ min: 1 }),
+  subject: headerLine({ min: 1, max: 998 }),
+  body: z.string().max(1_000_000),
+  cc: headerLine().optional(),
+  bcc: headerLine().optional(),
+});
+
+/** Shared Zod schemas for the IMAP/protonmail tool arg payloads. */
+export const emailToolSchemas = {
+  listArgs,
+  getArgs,
+  searchArgs,
+  sendArgs,
+} as const;
+
+// ---------------------------------------------------------------------------
+// Shared view transformer (imap + protonmail tools.ts — viewMessage)
+// ---------------------------------------------------------------------------
+
+/**
+ * The minimal shape that `viewEmailMessage` reads from a message meta object.
+ * imap's `ImapMessageMeta` and protonmail's `MailMessageMeta` both satisfy this.
+ */
+export interface EmailMessageMeta {
+  readonly uid: number;
+  readonly mailbox: string;
+  readonly uidValidity: string | null;
+  readonly envelope: {
+    readonly date?: Date | string | null;
+    readonly subject?: string | null;
+    readonly messageId?: string | null;
+    readonly from?: readonly { readonly name?: string; readonly address?: string }[];
+    readonly to?: readonly { readonly name?: string; readonly address?: string }[];
+    readonly cc?: readonly { readonly name?: string; readonly address?: string }[];
+  };
+  readonly attachments: readonly {
+    readonly filename: string | null;
+    readonly sizeBytes: number | null;
+    readonly mimeType: string | null;
+  }[];
+  readonly preview: string;
+}
+
+/**
+ * Reduce an {@link EmailMessageMeta} to a JSON-safe view. Returns HEADERS,
+ * attachment METADATA (filename/size/mimetype), and the capped preview — never
+ * attachment bytes or a full body. Addresses are formatted by the caller-supplied
+ * `formatAddr` so each connector can use its own local `formatAddress` helper.
+ */
+export function viewEmailMessage(
+  m: EmailMessageMeta,
+  formatAddr: (a: { readonly name?: string; readonly address?: string }) => string,
+): Record<string, unknown> {
+  const env = m.envelope;
+  return {
+    uid: m.uid,
+    mailbox: m.mailbox,
+    uidValidity: m.uidValidity,
+    messageId: env.messageId ?? null,
+    subject: env.subject ?? null,
+    date: env.date instanceof Date ? env.date.toISOString() : (env.date ?? null),
+    from: (env.from ?? []).map(formatAddr),
+    to: (env.to ?? []).map(formatAddr),
+    cc: (env.cc ?? []).map(formatAddr),
+    attachments: m.attachments.map((a) => ({
+      filename: a.filename,
+      sizeBytes: a.sizeBytes,
+      mimeType: a.mimeType,
+    })),
+    preview: m.preview,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Shared server-layer helpers (server.ts — envInt, previewFromParts)
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse an environment variable as an integer in the range [1, 65535]. Returns
+ * `fallback` if the variable is absent, empty, non-numeric, or out of range.
+ * Byte-identical to the `envInt` helper in imap/server.ts and protonmail/server.ts.
+ */
+export function envInt(name: string, fallback: number): number {
+  const raw = process.env[name]?.trim();
+  if (raw === undefined || raw === "") {
+    return fallback;
+  }
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 && n <= 65535 ? Math.trunc(n) : fallback;
+}
+
+/**
+ * Extract and cap a plain-text body preview from the map of IMAP body parts
+ * fetched by imapflow. Looks up part keys `partKey → "1" → "TEXT"` in order.
+ * Returns an empty string when nothing is found. Byte-equivalent to the
+ * `previewFromParts` helpers in imap/server.ts and protonmail/server.ts.
+ */
+export function previewFromParts(parts: Map<string, Buffer> | undefined, partKey: string): string {
+  if (parts === undefined) {
+    return "";
+  }
+  const buf = parts.get(partKey) ?? parts.get("1") ?? parts.get("TEXT");
+  if (buf === undefined) {
+    return "";
+  }
+  return capPreview(buf.toString("utf8"));
+}
+
+// ---------------------------------------------------------------------------
+// Shared tool-registration factory (imap + protonmail tools.ts — the 4 blocks)
+// ---------------------------------------------------------------------------
+
+/** Read surface the email tool factory depends on (imap's ImapClient / protonmail's MailClient both satisfy it). */
+export interface EmailReadClient {
+  list(options: { mailbox?: string; limit?: number }): Promise<EmailMessageMeta[]>;
+  get(uid: number, mailbox?: string): Promise<EmailMessageMeta | null>;
+  search(options: { query: string; mailbox?: string; limit?: number }): Promise<EmailMessageMeta[]>;
+}
+
+/** Send surface the email tool factory depends on (imap's/protonmail's SmtpMailer satisfy it). */
+export interface EmailSendMailer {
+  send(input: { to: string; subject: string; body: string; cc?: string; bcc?: string }): Promise<{
+    messageId: string | null;
+    accepted: readonly string[];
+    rejected: readonly string[];
+  }>;
+}
+
+/** The four tool descriptions, supplied verbatim by each connector. */
+export interface EmailToolDescriptions {
+  readonly list: string;
+  readonly get: string;
+  readonly search: string;
+  readonly send: string;
+}
+
+/**
+ * Register the 4 email tools (`<prefix>_list|_get|_search|_mail_send`) onto an
+ * MCP server. The IMAP client + SMTP mailer are injected so tests exercise the
+ * tool surface without opening sockets. Byte-equivalent to the hand-written
+ * `registerImapTools` / `registerProtonmailTools` bodies it replaces — the tool
+ * names (via `toolPrefix`) and descriptions are the only per-connector inputs.
+ */
+export function registerEmailConnectorTools(opts: {
+  server: { tool: (...args: never) => unknown };
+  toolPrefix: string;
+  descriptions: EmailToolDescriptions;
+  client: EmailReadClient;
+  mailer: EmailSendMailer;
+  formatAddr: (a: { readonly name?: string; readonly address?: string }) => string;
+  /**
+   * The connector's write registrar, for `<prefix>_mail_send`.
+   *
+   * Passed IN rather than built here on purpose: `standaloneEligibility` reads a connector's own
+   * `server.ts`/`tools.ts` to decide whether its mutations are gated, and a registrar constructed
+   * inside this shared module would be invisible there — the connector would be refused despite
+   * being hardened. Requiring it also means a new email connector cannot forget it.
+   */
+  registerWriteTool: WriteToolRegistrar;
+}): void {
+  const { server, toolPrefix, descriptions, client, mailer, formatAddr, registerWriteTool } = opts;
+  const registerSimpleTool = createRegisterSimpleTool(server);
+  const { listArgs, getArgs, searchArgs, sendArgs } = emailToolSchemas;
+
+  registerSimpleTool(
+    `${toolPrefix}_list`,
+    descriptions.list,
+    listArgs.shape,
+    async (args: unknown): Promise<McpListResult> => {
+      const parsed = listArgs.safeParse(args);
+      if (!parsed.success) {
+        throw new Error(parsed.error.message);
+      }
+      const o: { mailbox?: string; limit?: number } = {};
+      if (parsed.data.mailbox !== undefined) {
+        o.mailbox = parsed.data.mailbox;
+      }
+      o.limit = clampLimit(parsed.data.limit);
+      const items = await client.list(o);
+      return mcpJsonResult({ items: items.map((m) => viewEmailMessage(m, formatAddr)) });
+    },
+  );
+
+  registerSimpleTool(
+    `${toolPrefix}_get`,
+    descriptions.get,
+    getArgs.shape,
+    async (args: unknown): Promise<McpListResult> => {
+      const parsed = getArgs.safeParse(args);
+      if (!parsed.success) {
+        throw new Error(parsed.error.message);
+      }
+      const m = await client.get(parsed.data.uid, parsed.data.mailbox);
+      return mcpJsonResult(m === null ? { item: null } : { item: viewEmailMessage(m, formatAddr) });
+    },
+  );
+
+  registerSimpleTool(
+    `${toolPrefix}_search`,
+    descriptions.search,
+    searchArgs.shape,
+    async (args: unknown): Promise<McpListResult> => {
+      const parsed = searchArgs.safeParse(args);
+      if (!parsed.success) {
+        throw new Error(parsed.error.message);
+      }
+      const o: { query: string; mailbox?: string; limit?: number } = {
+        query: parsed.data.query,
+        limit: clampLimit(parsed.data.limit),
+      };
+      if (parsed.data.mailbox !== undefined) {
+        o.mailbox = parsed.data.mailbox;
+      }
+      const items = await client.search(o);
+      return mcpJsonResult({ matches: items.map((m) => viewEmailMessage(m, formatAddr)) });
+    },
+  );
+
+  registerWriteTool(
+    `${toolPrefix}_mail_send`,
+    {
+      mutates: `${toolPrefix}.mail.send`,
+      // A sent mail cannot be recalled and nothing remains to query, so the recipient and
+      // subject ARE the pre-state.
+      recoverable: false,
+      capturePreState: (p) => Promise.resolve({ to: p.to, subject: p.subject }),
+      scopeTargetOf: (p) => ({ kind: "recipient", value: p.to }),
+    },
+    descriptions.send,
+    sendArgs,
+    async (parsedData): Promise<McpListResult> => {
+      const parsed = { success: true as const, data: parsedData };
+      const input: { to: string; subject: string; body: string; cc?: string; bcc?: string } = {
+        to: parsed.data.to,
+        subject: parsed.data.subject,
+        body: parsed.data.body,
+      };
+      if (parsed.data.cc !== undefined && parsed.data.cc !== "") {
+        input.cc = parsed.data.cc;
+      }
+      if (parsed.data.bcc !== undefined && parsed.data.bcc !== "") {
+        input.bcc = parsed.data.bcc;
+      }
+      const res = await mailer.send(input);
+      return mcpJsonResult({
+        messageId: res.messageId,
+        accepted: res.accepted,
+        rejected: res.rejected,
+      });
+    },
+  );
+}

package/shared/join-api-path.ts

@@ -0,0 +1,18 @@
+/**
+ * Join `path` onto `baseUrl`, passing an already-absolute URL straight through
+ * (pagination cursors commonly arrive absolute).
+ *
+ * The absolute test is the full `http://` / `https://` scheme, not a bare
+ * `http` prefix: a RELATIVE path that merely starts with those four letters —
+ * `httpbin/status`, or an `http-headers` endpoint — was returned unjoined,
+ * silently dropping the base URL and issuing the request against a relative
+ * path. Narrow enough that it would have surfaced in production rather than in
+ * review.
+ */
+export function joinApiPath(baseUrl: string, path: string): string {
+  if (path.startsWith("http://") || path.startsWith("https://")) {
+    return path;
+  }
+  const suffix = path.startsWith("/") ? path : `/${path}`;
+  return `${baseUrl}${suffix}`;
+}

package/shared/kb-markdown.ts

@@ -0,0 +1,142 @@
+/**
+ * Minimal, robust converter from the SIMPLE markdown the tribal answer-synthesizer emits
+ * (plain paragraphs + `-` bulleted lists; no headers/tables/code/HTML) into Notion blocks and
+ * Confluence storage HTML, plus a Sources section built from citations. The body parser is a
+ * line-walker that NEVER throws on unexpected markup: any non-empty, non-bullet line becomes a
+ * paragraph (so a stray `#` or ``` line degrades to literal paragraph text, not an error).
+ */
+
+export interface KbCitation {
+  itemId: string;
+  channelId: string;
+  url: string | null;
+}
+
+export type KbLine = { kind: "bullet" | "paragraph"; text: string };
+
+/** Classify each non-blank line as a bullet (`- ` prefix) or a paragraph (everything else). */
+export function parseSimpleMarkdown(md: string): KbLine[] {
+  const out: KbLine[] = [];
+  for (const raw of md.split("\n")) {
+    const line = raw.trim();
+    if (line === "") continue;
+    const bullet = /^[-*]\s+(\S.*)?$/.exec(line);
+    if (bullet === null) {
+      out.push({ kind: "paragraph", text: line });
+    } else {
+      out.push({ kind: "bullet", text: bullet[1] ?? "" });
+    }
+  }
+  return out;
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+function citationLabel(c: KbCitation): string {
+  return `${c.channelId} · ${c.itemId}`;
+}
+
+function notionRichText(content: string, url?: string | null): Record<string, unknown>[] {
+  const text: Record<string, unknown> = { content: content.slice(0, 2000) };
+  if (url !== undefined && url !== null && url !== "") text["link"] = { url };
+  return [{ type: "text", text }];
+}
+
+/** Body → Notion blocks, then a "Sources:" paragraph + one bulleted link per citation. */
+export function markdownToNotionBlocks(
+  md: string,
+  citations: readonly KbCitation[],
+): Record<string, unknown>[] {
+  const blocks: Record<string, unknown>[] = [];
+  for (const line of parseSimpleMarkdown(md)) {
+    if (line.kind === "bullet") {
+      blocks.push({
+        object: "block",
+        type: "bulleted_list_item",
+        bulleted_list_item: { rich_text: notionRichText(line.text) },
+      });
+    } else {
+      blocks.push({
+        object: "block",
+        type: "paragraph",
+        paragraph: { rich_text: notionRichText(line.text) },
+      });
+    }
+  }
+  if (citations.length > 0) {
+    blocks.push({
+      object: "block",
+      type: "paragraph",
+      paragraph: { rich_text: notionRichText("Sources:") },
+    });
+    for (const c of citations) {
+      blocks.push({
+        object: "block",
+        type: "bulleted_list_item",
+        bulleted_list_item: { rich_text: notionRichText(citationLabel(c), c.url) },
+      });
+    }
+  }
+  return blocks;
+}
+
+/** Body → Confluence storage HTML, then a Sources `<p>` + `<ul>` of citation links. */
+export function markdownToConfluenceStorage(md: string, citations: readonly KbCitation[]): string {
+  const parts: string[] = [];
+  let bulletBuffer: string[] = [];
+  const flushBullets = (): void => {
+    if (bulletBuffer.length === 0) return;
+    const lis = bulletBuffer.map((b) => `<li>${b}</li>`).join("");
+    parts.push(`<ul>${lis}</ul>`);
+    bulletBuffer = [];
+  };
+  for (const line of parseSimpleMarkdown(md)) {
+    if (line.kind === "bullet") {
+      bulletBuffer.push(escapeHtml(line.text));
+    } else {
+      flushBullets();
+      parts.push(`<p>${escapeHtml(line.text)}</p>`);
+    }
+  }
+  flushBullets();
+  if (citations.length > 0) {
+    parts.push("<p>Sources:</p>");
+    const items = citations.map((c) => {
+      const label = escapeHtml(citationLabel(c));
+      return c.url !== null && c.url !== ""
+        ? `<li><a href="${escapeHtml(c.url)}">${label}</a></li>`
+        : `<li>${label}</li>`;
+    });
+    parts.push(`<ul>${items.join("")}</ul>`);
+  }
+  return parts.join("");
+}
+
+/** Parse + validate a citations JSON string into KbCitation[]; tolerant, never throws on shape. */
+export function parseCitationsJson(raw: string): KbCitation[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  const out: KbCitation[] = [];
+  for (const v of parsed) {
+    if (v === null || typeof v !== "object") continue;
+    const rec = v as Record<string, unknown>;
+    const itemId = rec["itemId"];
+    const channelId = rec["channelId"];
+    const url = rec["url"];
+    if (typeof itemId !== "string" || typeof channelId !== "string") continue;
+    out.push({ itemId, channelId, url: typeof url === "string" ? url : null });
+  }
+  return out;
+}

package/shared/mcp-search-tool.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { type McpListResult, mcpJsonResult, type ZodObjectSchema } from "./mcp-tool-kit.ts";
+import type { SearchMatchOptions } from "./search-filter.ts";
+
+/** A `makeQueryFilter(...)` result — the shape every connector search filter has. */
+export type SearchFilter = (
+  rows: readonly unknown[],
+  opts: SearchMatchOptions,
+) => readonly unknown[];
+
+/**
+ * Build the shared connector search input schema. `query` is always a non-empty
+ * string; `maxLimit` is the per-connector cap (varies: 100/200/500/50/1000/2000)
+ * and MUST be passed verbatim from each call site so behavior is unchanged.
+ */
+export function searchToolInputSchema(maxLimit = 100): ZodObjectSchema<SearchMatchOptions> {
+  return z.object({
+    query: z.string().min(1),
+    limit: z.number().int().min(1).max(maxLimit).optional(),
+  });
+}
+
+/**
+ * Build the `{ matches }` envelope: filter the rows when they are an array, else
+ * return an empty match set. Verbatim equivalent of the per-connector tail
+ * `const matches = Array.isArray(X) ? filter(X, { query, limit }) : []; return jsonResult({ matches })`.
+ * `rows` stays `unknown` because external payloads are untyped at the boundary
+ * (Non-Negotiable #7).
+ */
+export function matchesResult(
+  rows: unknown,
+  filter: SearchFilter,
+  opts: SearchMatchOptions,
+): McpListResult {
+  const matches = Array.isArray(rows) ? filter(rows, opts) : [];
+  return mcpJsonResult({ matches });
+}

package/shared/mcp-tool-kit.ts

@@ -0,0 +1,35 @@
+/**
+ * mcp-tool-kit — re-export of the MCP connector helpers now owned by
+ * `@nimbus-dev/sdk/connector-kit`.
+ *
+ * These helpers originated here and were upstreamed to the SDK in 1.11.0. The
+ * SDK is now the single owner; this module stays as the connector-facing import
+ * path so the ~99 connectors keep their existing relative imports.
+ *
+ * Named re-exports, deliberately not `export *`: a star would also re-export the
+ * sibling kits' symbols (fetch-bearer-json, rest-tool-kit) through this path,
+ * widening the surface each connector sees and making a two-module import
+ * ambiguous. Keep this list matched to the symbols this file used to define.
+ */
+
+export type {
+  HttpJsonBodyResponse,
+  HttpTextResponse,
+  McpListResult,
+  RegisterSimpleToolFn,
+  ZodObjectSchema,
+} from "@nimbus-dev/sdk/connector-kit";
+export {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  encodeBasicAuthHeader,
+  fetchWithTimeout,
+  mcpJsonResult,
+  mcpJsonResultFromTextIfOk,
+  mcpJsonResultIfOk,
+  parseJsonTextIfOk,
+  putOptionalBoolean,
+  putOptionalNonEmptyString,
+  registerZodTool,
+  requireProcessEnv,
+} from "@nimbus-dev/sdk/connector-kit";

package/shared/nimbus-spawn.ts

@@ -0,0 +1,128 @@
+import { spawn } from "node:child_process";
+
+export type SpawnResult = { code: number; stdout: string; stderr: string };
+
+/**
+ * Node implementation. Exported so it can be tested directly: the suite runs under Bun, so
+ * `nimbusSpawn` would otherwise never exercise this branch and it would ship unverified.
+ *
+ * Two Node APIs are deliberately NOT used, and the reasons are not obvious:
+ *
+ *  - `spawnSync` blocks the event loop. In a stdio MCP server that must keep answering JSON-RPC —
+ *    including an in-flight `elicitation/create` round-trip — a synchronous spawn deadlocks the
+ *    consent gate against itself.
+ *  - `execFile` caps captured output at a 1 MB `maxBuffer` by default and errors past it. The
+ *    `Bun.spawn` path reads stdout uncapped, and `aws logs` / `gcloud logging` JSON routinely
+ *    exceeds 1 MB, so `execFile` would be a silent-truncation regression dressed up as a
+ *    portability fix.
+ *
+ * Output is accumulated as raw `Buffer`s and decoded ONCE at the end. Decoding each chunk with
+ * `chunk.toString("utf8")` corrupts any multi-byte character that straddles a chunk boundary, and
+ * chunk boundaries are a function of pipe timing — so it fails intermittently, on non-ASCII data,
+ * in production.
+ */
+export function spawnViaNode(
+  command: readonly string[],
+  env: Record<string, string | undefined>,
+): Promise<SpawnResult> {
+  const [bin, ...args] = command;
+  if (bin === undefined) {
+    return Promise.resolve({ code: 1, stdout: "", stderr: "empty command" });
+  }
+  return new Promise((resolveP) => {
+    const child = spawn(bin, args, { env: { ...process.env, ...env } });
+    const outChunks: Buffer[] = [];
+    const errChunks: Buffer[] = [];
+    child.stdout.on("data", (c: Buffer) => {
+      outChunks.push(c);
+    });
+    child.stderr.on("data", (c: Buffer) => {
+      errChunks.push(c);
+    });
+    const decode = (): { stdout: string; stderr: string } => ({
+      stdout: Buffer.concat(outChunks).toString("utf8"),
+      stderr: Buffer.concat(errChunks).toString("utf8"),
+    });
+    child.on("error", (e: Error) => {
+      const d = decode();
+      resolveP({ code: 1, stdout: d.stdout, stderr: `${d.stderr}${e.message}` });
+    });
+    child.on("close", (code: number | null) => {
+      resolveP({ code: code ?? 1, ...decode() });
+    });
+  });
+}
+
+/** Bun implementation. Draining the whole stream decodes multi-byte characters correctly. */
+export async function spawnViaBun(
+  command: readonly string[],
+  env: Record<string, string | undefined>,
+): Promise<SpawnResult> {
+  if (command.length === 0) {
+    return { code: 1, stdout: "", stderr: "empty command" };
+  }
+  // `Bun.spawn` THROWS synchronously when the binary does not exist, where `child_process` emits
+  // an "error" event instead. Both branches must honour the same contract — resolve with a
+  // non-zero code, never reject — or a caller's behaviour would depend on the runtime.
+  try {
+    const proc = Bun.spawn([...command], {
+      env: { ...process.env, ...env },
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const code = await proc.exited;
+    const stdout = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+    return { code, stdout, stderr };
+  } catch (e) {
+    return { code: 1, stdout: "", stderr: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+/**
+ * Whether `Bun.spawn` is usable on the given global.
+ *
+ * Takes the global as a PARAMETER rather than reading `globalThis` directly, because Bun defines
+ * its global as non-writable AND non-configurable — it cannot be stubbed or redefined, so the
+ * "absent" side is otherwise unreachable from a suite that runs under Bun. That side is the one
+ * the standalone npx artifact always takes, so it must be exercisable.
+ */
+export function detectBunSpawn(g: unknown = globalThis): boolean {
+  const bun = (g as { Bun?: { spawn?: unknown } }).Bun;
+  return typeof bun?.spawn === "function";
+}
+
+/** The shape both implementations share, and what `selectSpawnImpl` hands back. */
+export type SpawnImpl = (
+  command: readonly string[],
+  env: Record<string, string | undefined>,
+) => Promise<SpawnResult>;
+
+/**
+ * Which implementation a given global calls for.
+ *
+ * Returning the FUNCTION rather than taking a `useBun` flag is deliberate: a boolean selector
+ * argument makes one entry point mean two things, and the two implementations are already exported
+ * as the two things it selected between. Injecting the global — for the same
+ * non-writable/non-configurable reason `detectBunSpawn` takes one — is what keeps the Node side
+ * reachable from a suite that runs under Bun.
+ */
+export function selectSpawnImpl(g: unknown = globalThis): SpawnImpl {
+  return detectBunSpawn(g) ? spawnViaBun : spawnViaNode;
+}
+
+/**
+ * Spawn a CLI and collect its output, on Bun or Node.
+ *
+ * Detection happens at CALL time, not module load, so a test that swaps `Bun.spawn` is still
+ * honoured. That is not incidental: `cloudwatch/test/tools.test.ts` stubs `Bun.spawn` globally, and
+ * routing unconditionally through Node made it spawn a real `aws` and hang the suite.
+ *
+ * Never rejects: a spawn failure resolves with a non-zero code, matching the previous behaviour.
+ */
+export function nimbusSpawn(
+  command: readonly string[],
+  env: Record<string, string | undefined>,
+): Promise<SpawnResult> {
+  return selectSpawnImpl()(command, env);
+}

package/shared/rest-tool-kit.ts

@@ -0,0 +1,18 @@
+/**
+ * rest-tool-kit — re-export of the shared REST fetch wrapper for Bearer-auth
+ * connectors, now owned by `@nimbus-dev/sdk/connector-kit`.
+ *
+ * These helpers originated here and were upstreamed to the SDK in 1.11.0. The
+ * SDK is now the single owner; this module stays as the connector-facing import
+ * path so the ~99 connectors keep their existing relative imports.
+ *
+ * Named re-exports, deliberately not `export *` — see the note in
+ * `mcp-tool-kit.ts`.
+ */
+
+export type {
+  RestFetcherConfig,
+  RestFetchResult,
+  RestToolRegistrar,
+} from "@nimbus-dev/sdk/connector-kit";
+export { makeRestFetcher, makeRestToolRegistrar } from "@nimbus-dev/sdk/connector-kit";