@nimbus-dev/sdk 1.1.2

package/src/distribution-channel.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from "bun:test";
+import { channelUpgradeHint, resolveDistributionChannel } from "./distribution-channel.ts";
+
+describe("resolveDistributionChannel", () => {
+  test("returns null for an ordinary install path with no env marker", () => {
+    expect(
+      resolveDistributionChannel({ env: {}, execPath: "/home/u/.local/bin/nimbus" }),
+    ).toBeNull();
+  });
+
+  test("honors a valid NIMBUS_DISTRIBUTION_CHANNEL env marker", () => {
+    expect(
+      resolveDistributionChannel({
+        env: { NIMBUS_DISTRIBUTION_CHANNEL: "msi" },
+        execPath: "/home/u/.local/bin/nimbus",
+      }),
+    ).toBe("msi");
+  });
+
+  test("ignores an unknown env marker value (fails closed to path detection)", () => {
+    expect(
+      resolveDistributionChannel({
+        env: { NIMBUS_DISTRIBUTION_CHANNEL: "bogus" },
+        execPath: "/home/u/.local/bin/nimbus",
+      }),
+    ).toBeNull();
+  });
+
+  test("detects a macOS Homebrew Cellar path", () => {
+    expect(
+      resolveDistributionChannel({
+        env: {},
+        execPath: "/opt/homebrew/Cellar/nimbus/0.1.0/bin/nimbus",
+      }),
+    ).toBe("homebrew");
+  });
+
+  test("detects a Linuxbrew path", () => {
+    expect(
+      resolveDistributionChannel({
+        env: {},
+        execPath: "/home/linuxbrew/.linuxbrew/Cellar/nimbus/0.1.0/bin/nimbus-gateway",
+      }),
+    ).toBe("homebrew");
+  });
+
+  test("detects a Scoop apps path (Windows-style backslashes)", () => {
+    expect(
+      resolveDistributionChannel({
+        env: {},
+        execPath: "C:\\Users\\u\\scoop\\apps\\nimbus\\current\\nimbus.exe",
+      }),
+    ).toBe("scoop");
+  });
+
+  test("env marker wins over a conflicting path", () => {
+    expect(
+      resolveDistributionChannel({
+        env: { NIMBUS_DISTRIBUTION_CHANNEL: "homebrew" },
+        execPath: "C:\\Users\\u\\scoop\\apps\\nimbus\\current\\nimbus.exe",
+      }),
+    ).toBe("homebrew");
+  });
+
+  test("resolves a Homebrew bin symlink to its Cellar target before matching", () => {
+    expect(
+      resolveDistributionChannel({
+        env: {},
+        execPath: "/opt/homebrew/bin/nimbus",
+        realpath: (p) =>
+          p === "/opt/homebrew/bin/nimbus" ? "/opt/homebrew/Cellar/nimbus/0.1.0/bin/nimbus" : p,
+      }),
+    ).toBe("homebrew");
+  });
+
+  test("an explicit NIMBUS_DISTRIBUTION_CHANNEL=msi env marker resolves to the msi channel", () => {
+    const channel = resolveDistributionChannel({
+      env: { NIMBUS_DISTRIBUTION_CHANNEL: "msi" },
+      execPath: "C:\\Users\\me\\AppData\\Local\\Programs\\Nimbus\\bin\\nimbus.exe",
+      realpath: (p) => p,
+    });
+    expect(channel).toBe("msi");
+  });
+
+  test("a scripted install.ps1 path (same %LOCALAPPDATA%\\Programs\\Nimbus dir, no env) is NOT msi", () => {
+    const channel = resolveDistributionChannel({
+      env: {},
+      execPath: "C:\\Users\\me\\AppData\\Local\\Programs\\Nimbus\\bin\\nimbus.exe",
+      realpath: (p) => p,
+    });
+    expect(channel).toBeNull();
+  });
+});
+
+describe("channelUpgradeHint", () => {
+  test.each([
+    ["homebrew", "brew upgrade nimbus"],
+    ["scoop", "scoop update nimbus"],
+    ["winget", "winget upgrade NimbusAgent.Nimbus"],
+    ["apt", "apt upgrade nimbus"],
+    ["yum", "dnf upgrade nimbus"],
+    ["msi", ".msi"],
+    ["pkg", ".pkg"],
+  ] as const)("%s hint mentions the right command", (channel, needle) => {
+    expect(channelUpgradeHint(channel)).toContain(needle);
+  });
+});

package/src/distribution-channel.ts

@@ -0,0 +1,105 @@
+import { realpathSync } from "node:fs";
+
+/**
+ * Channels a Nimbus binary can be distributed through. When Nimbus runs from a
+ * package-manager install, the self-updater steps aside so the package manager
+ * owns updates.
+ *
+ * Lives in the SDK so the gateway and CLI share one copy: the `cli` package
+ * reaches the gateway over IPC only (no source imports), so a shared pure helper
+ * must live in a package both may depend on — the same pattern the manifest
+ * signer uses.
+ */
+export type DistributionChannel = "homebrew" | "scoop" | "winget" | "apt" | "yum" | "msi" | "pkg";
+
+const KNOWN_CHANNELS = new Set<DistributionChannel>([
+  "homebrew",
+  "scoop",
+  "winget",
+  "apt",
+  "yum",
+  "msi",
+  "pkg",
+] satisfies readonly DistributionChannel[]);
+
+export interface ResolveChannelOptions {
+  /** Defaults to `process.env`. */
+  env?: Record<string, string | undefined>;
+  /** Defaults to `process.execPath`. */
+  execPath?: string;
+  /**
+   * Resolves symlinks so a package manager's real install path (e.g. Homebrew's
+   * Cellar) is inspected rather than the `bin` symlink that launched the process.
+   * Injectable for tests; defaults to a safe `realpathSync` that falls back to the
+   * input path if resolution fails.
+   */
+  realpath?: (p: string) => string;
+}
+
+function safeRealpath(p: string): string {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+function fromEnv(env: Record<string, string | undefined>): DistributionChannel | null {
+  const raw = env["NIMBUS_DISTRIBUTION_CHANNEL"];
+  if (raw && KNOWN_CHANNELS.has(raw as DistributionChannel)) {
+    return raw as DistributionChannel;
+  }
+  return null;
+}
+
+function fromPath(execPath: string, realpath: (p: string) => string): DistributionChannel | null {
+  // Resolve symlinks first: package managers expose the binary via a symlink whose
+  // own path may not contain the tell-tale Cellar/apps segment.
+  const resolved = realpath(execPath);
+  const p = resolved.replaceAll("\\", "/").toLowerCase();
+  // Homebrew: macOS `/opt/homebrew/Cellar/...` or `/usr/local/Cellar/...`,
+  // Linuxbrew `/home/linuxbrew/.linuxbrew/...`.
+  if (p.includes("/cellar/") || p.includes("/.linuxbrew/")) {
+    return "homebrew";
+  }
+  // Scoop: `~/scoop/apps/<app>/...`.
+  if (p.includes("/scoop/apps/")) {
+    return "scoop";
+  }
+  return null;
+}
+
+/**
+ * Resolve the distribution channel this binary was installed through, or `null`
+ * for a plain/direct-download install (where the self-updater stays enabled).
+ * An explicit `NIMBUS_DISTRIBUTION_CHANNEL` env marker takes precedence over
+ * path heuristics; an unknown marker value is ignored.
+ */
+export function resolveDistributionChannel(
+  opts: ResolveChannelOptions = {},
+): DistributionChannel | null {
+  const env = opts.env ?? process.env;
+  const execPath = opts.execPath ?? process.execPath;
+  const realpath = opts.realpath ?? safeRealpath;
+  return fromEnv(env) ?? fromPath(execPath, realpath);
+}
+
+/** Human-facing upgrade hint per channel, used by `nimbus update`. */
+export function channelUpgradeHint(channel: DistributionChannel): string {
+  switch (channel) {
+    case "homebrew":
+      return "Installed via Homebrew — run 'brew upgrade nimbus' to update.";
+    case "scoop":
+      return "Installed via Scoop — run 'scoop update nimbus' to update.";
+    case "winget":
+      return "Installed via winget — run 'winget upgrade NimbusAgent.Nimbus' to update.";
+    case "apt":
+      return "Installed via apt — run 'sudo apt update && sudo apt upgrade nimbus' to update.";
+    case "yum":
+      return "Installed via dnf/yum — run 'sudo dnf upgrade nimbus' to update.";
+    case "msi":
+      return "Installed via the Windows installer — download the latest .msi from the releases page.";
+    case "pkg":
+      return "Installed via the macOS installer — download the latest .pkg from the releases page.";
+  }
+}

package/src/hitl-request.ts

@@ -0,0 +1,22 @@
+export interface HitlRequest {
+  actionId: string;
+  summary: string;
+  diff?: string;
+}
+
+export function isHitlRequest(value: unknown): value is HitlRequest {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value as Record<string, unknown>;
+  const actionId = candidate["actionId"];
+  const summary = candidate["summary"];
+  const diff = candidate["diff"];
+  return (
+    typeof actionId === "string" &&
+    actionId.length > 0 &&
+    typeof summary === "string" &&
+    summary.length > 0 &&
+    (diff === undefined || typeof diff === "string")
+  );
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+/**
+ * @nimbus-dev/sdk v1.0.0 — Plugin API v1 (stable baseline)
+ * MIT License
+ *
+ * Typed scaffolding for building Nimbus extensions (MCP connectors).
+ * See CHANGELOG.md for the stable surface guarantee.
+ */
+
+export type { AuditEmit, AuditLogger } from "./audit-logger";
+export { createScopedAuditLogger } from "./audit-logger";
+export {
+  assertNoRowDataTools,
+  ExtensionContractError,
+  ROW_DATA_TOOL_SEGMENTS,
+  type RowDataToolCandidate,
+  runContractTests,
+} from "./contract-tests";
+export {
+  type AppStoreConnectJwtParams,
+  signAppStoreConnectJwt,
+} from "./crypto/app-store-connect-jwt";
+export {
+  canonicalize,
+  canonicalizeManifest,
+  ManifestNestedTooDeep,
+  NonIntegerNumberInManifest,
+  UnsupportedManifestValueType,
+} from "./crypto/canonical-json";
+export { base64UrlJson, type SignJwtOptions, signJwt } from "./crypto/jwt";
+export {
+  type FetchLike,
+  type GoogleServiceAccount,
+  mintGoogleAccessToken,
+  parseServiceAccountJson,
+  signServiceAccountAssertion,
+} from "./crypto/service-account-token";
+export type { SignatureDisableReason } from "./crypto/verify-signature";
+export {
+  decodeBase64,
+  encodeBase64,
+  errorToHardDisableReason,
+  generateEd25519Keypair,
+  PublisherKeyMismatch,
+  SignatureInvalid,
+  SignatureInvalidFormat,
+  signManifest,
+  verifyManifestSignature,
+} from "./crypto/verify-signature";
+export {
+  channelUpgradeHint,
+  type DistributionChannel,
+  type ResolveChannelOptions,
+  resolveDistributionChannel,
+} from "./distribution-channel";
+export type { HitlRequest } from "./hitl-request";
+export { isHitlRequest } from "./hitl-request";
+export { NimbusExtensionServer } from "./server";
+export { MockGateway } from "./testing/index";
+export type { ExtensionManifest, NimbusItem } from "./types";

package/src/ipc/index.ts

@@ -0,0 +1,5 @@
+export {
+  IPC_MAX_LINE_BYTES,
+  NdjsonLineReader,
+  type NdjsonLineReaderOptions,
+} from "./ndjson-line-reader.js";

package/src/ipc/ndjson-line-reader.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+
+import { IPC_MAX_LINE_BYTES, NdjsonLineReader } from "./ndjson-line-reader.ts";
+
+describe("NdjsonLineReader", () => {
+  test("emits non-empty lines and skips blanks", () => {
+    const r = new NdjsonLineReader();
+    const lines = r.push(new TextEncoder().encode('{"a":1}\n\n{"b":2}\n'));
+    expect(lines).toEqual(['{"a":1}', '{"b":2}']);
+  });
+
+  test("throws when a line exceeds IPC_MAX_LINE_BYTES", () => {
+    const r = new NdjsonLineReader();
+    const huge = `${"x".repeat(IPC_MAX_LINE_BYTES + 1)}\n`;
+    expect(() => r.push(new TextEncoder().encode(huge))).toThrow("Message exceeds 1MB line limit");
+  });
+
+  test("buffers a partial line across push() calls", () => {
+    const r = new NdjsonLineReader();
+    const enc = new TextEncoder();
+    expect(r.push(enc.encode('{"a"'))).toEqual([]);
+    expect(r.push(enc.encode(":1}\n"))).toEqual(['{"a":1}']);
+  });
+  test("strips a trailing carriage return", () => {
+    const r = new NdjsonLineReader();
+    expect(r.push(new TextEncoder().encode('{"a":1}\r\n'))).toEqual(['{"a":1}']);
+  });
+  test("decodes multi-byte UTF-8 split across chunk boundaries", () => {
+    const r = new NdjsonLineReader();
+    const full = new TextEncoder().encode('"é"\n');
+    const cut = 2;
+    expect(r.push(full.slice(0, cut))).toEqual([]);
+    expect(r.push(full.slice(cut))).toEqual(['"é"']);
+  });
+  test("flush() returns a pending line with no trailing newline", () => {
+    const r = new NdjsonLineReader();
+    r.push(new TextEncoder().encode("partial"));
+    expect(r.flush()).toEqual(["partial"]);
+  });
+  test("flush() strips a trailing carriage return", () => {
+    const r = new NdjsonLineReader();
+    r.push(new TextEncoder().encode("partial\r"));
+    expect(r.flush()).toEqual(["partial"]);
+  });
+  test("flush() returns [] when nothing is pending", () => {
+    expect(new NdjsonLineReader().flush()).toEqual([]);
+  });
+  test("throws when the pending buffer (no newline yet) exceeds the limit", () => {
+    const r = new NdjsonLineReader();
+    const huge = "x".repeat(IPC_MAX_LINE_BYTES + 1);
+    expect(() => r.push(new TextEncoder().encode(huge))).toThrow("Message exceeds 1MB line limit");
+  });
+  test("uses the custom lineLimitError constructor", () => {
+    class TooBig extends Error {}
+    const r = new NdjsonLineReader({ lineLimitError: TooBig });
+    const huge = `${"x".repeat(IPC_MAX_LINE_BYTES + 1)}\n`;
+    expect(() => r.push(new TextEncoder().encode(huge))).toThrow(TooBig);
+  });
+  test("flush() drains a partial multi-byte codepoint held by the decoder", () => {
+    const r = new NdjsonLineReader();
+    expect(r.push(new Uint8Array([0xc3]))).toEqual([]);
+    expect(r.flush()).toEqual(["�"]);
+  });
+});

package/src/ipc/ndjson-line-reader.ts

@@ -0,0 +1,70 @@
+/** Max bytes per NDJSON line (UTF-8), aligned with IPC protocol limits. */
+export const IPC_MAX_LINE_BYTES = 1024 * 1024;
+
+function byteLengthUtf8(s: string): number {
+  return new TextEncoder().encode(s).length;
+}
+
+export type NdjsonLineReaderOptions = {
+  /** When set, oversized lines throw this type instead of `Error`. */
+  lineLimitError?: new (
+    message: string,
+  ) => Error;
+};
+
+/**
+ * Buffers UTF-8 chunks and emits complete non-empty lines (trailing `\r` stripped).
+ * Shared by Gateway JSON-RPC and the CLI IPC client.
+ */
+export class NdjsonLineReader {
+  private readonly lineLimitCtor: new (
+    message: string,
+  ) => Error;
+  private readonly decoder = new TextDecoder("utf-8", { fatal: false });
+  private pending = "";
+
+  constructor(opts: NdjsonLineReaderOptions = {}) {
+    this.lineLimitCtor = opts.lineLimitError ?? Error;
+  }
+
+  private throwLineTooLong(message: string): never {
+    throw new this.lineLimitCtor(message);
+  }
+
+  push(chunk: Uint8Array): string[] {
+    this.pending += this.decoder.decode(chunk, { stream: true });
+    const out: string[] = [];
+    while (true) {
+      const nl = this.pending.indexOf("\n");
+      if (nl < 0) {
+        break;
+      }
+      const line = this.pending.slice(0, nl);
+      this.pending = this.pending.slice(nl + 1);
+      const trimmed = line.endsWith("\r") ? line.slice(0, -1) : line;
+      if (trimmed.length === 0) {
+        continue;
+      }
+      if (byteLengthUtf8(trimmed) > IPC_MAX_LINE_BYTES) {
+        this.throwLineTooLong("Message exceeds 1MB line limit");
+      }
+      out.push(trimmed);
+    }
+    if (byteLengthUtf8(this.pending) > IPC_MAX_LINE_BYTES) {
+      this.throwLineTooLong("Message exceeds 1MB line limit");
+    }
+    return out;
+  }
+
+  flush(): string[] {
+    const rest = this.pending + this.decoder.decode();
+    this.pending = "";
+    if (rest.length === 0) {
+      return [];
+    }
+    if (byteLengthUtf8(rest) > IPC_MAX_LINE_BYTES) {
+      this.throwLineTooLong("Message exceeds 1MB line limit");
+    }
+    return [rest.endsWith("\r") ? rest.slice(0, -1) : rest];
+  }
+}

package/src/plugin-api-v1.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  AuditEmit,
+  AuditLogger,
+  ExtensionManifest,
+  HitlRequest,
+  NimbusItem,
+} from "./index.ts";
+import {
+  createScopedAuditLogger,
+  ExtensionContractError,
+  isHitlRequest,
+  MockGateway,
+  NimbusExtensionServer,
+  runContractTests,
+} from "./index.ts";
+
+describe("Plugin API v1 — stable surface", () => {
+  test("every v1 export is reachable from the package root", () => {
+    expect(typeof createScopedAuditLogger).toBe("function");
+    expect(typeof isHitlRequest).toBe("function");
+    expect(typeof runContractTests).toBe("function");
+    expect(typeof NimbusExtensionServer).toBe("function");
+    expect(typeof MockGateway).toBe("function");
+    expect(typeof ExtensionContractError).toBe("function");
+  });
+
+  test("v1 types can be used in user code", () => {
+    const manifest: ExtensionManifest = {
+      id: "ext.example",
+      displayName: "Example",
+      version: "0.1.0",
+      description: "Example extension",
+      author: "Nimbus",
+      entrypoint: "index.ts",
+      runtime: "bun",
+      permissions: [],
+      hitlRequired: [],
+      minNimbusVersion: "0.1.0",
+    };
+    const item: NimbusItem = { id: "x", service: "test", itemType: "file", name: "n" };
+    const emit: AuditEmit = async () => {};
+    const logger: AuditLogger = createScopedAuditLogger(manifest.id, emit);
+    const hitl: HitlRequest = { actionId: "delete", summary: "Delete one file" };
+    expect(manifest.id).toBe("ext.example");
+    expect(item.service).toBe("test");
+    expect(logger).toBeDefined();
+    expect(isHitlRequest(hitl)).toBe(true);
+  });
+});

package/src/sdk.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from "bun:test";
+import { NimbusExtensionServer } from "./server";
+
+describe("@nimbus-dev/sdk", () => {
+  test("NimbusExtensionServer is constructible", () => {
+    const server = new NimbusExtensionServer({
+      manifest: {
+        id: "test.ext",
+        displayName: "Test",
+        version: "0.0.1",
+        description: "test",
+        author: "test",
+        entrypoint: "dist/server.js",
+        runtime: "bun",
+        permissions: ["read"],
+        hitlRequired: [],
+        minNimbusVersion: "0.1.0",
+      },
+    });
+    expect(server).toBeDefined();
+    expect(() => server.start()).not.toThrow();
+  });
+});

package/src/server.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, test } from "bun:test";
+
+import { NimbusExtensionServer } from "./server";
+import type { ExtensionManifest } from "./types";
+
+/** Minimal valid ExtensionManifest fixture */
+function makeManifest(id: string): ExtensionManifest {
+  return {
+    id,
+    displayName: "Test Extension",
+    version: "1.0.0",
+    description: "A test extension",
+    author: "tester",
+    entrypoint: "index.ts",
+    runtime: "bun",
+    permissions: ["read"],
+    hitlRequired: [],
+    minNimbusVersion: "0.1.0",
+  };
+}
+
+describe("NimbusExtensionServer", () => {
+  describe("constructor", () => {
+    test("stores options without throwing", () => {
+      const manifest = makeManifest("my-ext");
+      const server = new NimbusExtensionServer({ manifest });
+      // The server object is constructed and is an instance of NimbusExtensionServer
+      expect(server).toBeInstanceOf(NimbusExtensionServer);
+    });
+
+    test("stores optional onAuth callback without throwing", () => {
+      const manifest = makeManifest("my-ext-with-auth");
+      const onAuth = (ctx: { accessToken: string }) => ({ token: ctx.accessToken });
+      const server = new NimbusExtensionServer({ manifest, onAuth });
+      expect(server).toBeInstanceOf(NimbusExtensionServer);
+    });
+  });
+
+  describe("registerTool", () => {
+    test("is a no-op and returns void without throwing", () => {
+      const server = new NimbusExtensionServer({ manifest: makeManifest("ext-1") });
+      const result = server.registerTool("search", {
+        description: "Search items",
+        inputSchema: { query: { type: "string" } },
+        handler: async (input: { query: string }) => ({ results: [input.query] }),
+      });
+      // registerTool is documented as a no-op — it returns undefined
+      expect(result).toBeUndefined();
+    });
+
+    test("accepts multiple tool registrations without throwing", () => {
+      const server = new NimbusExtensionServer({ manifest: makeManifest("ext-multi") });
+      // registerTool is a documented no-op → each call returns undefined.
+      expect(
+        server.registerTool("tool-a", {
+          description: "Tool A",
+          inputSchema: {},
+          handler: async (_input: unknown) => "a",
+        }),
+      ).toBeUndefined();
+      expect(
+        server.registerTool("tool-b", {
+          description: "Tool B",
+          inputSchema: { count: { type: "number" } },
+          handler: async (_input: unknown) => 42,
+        }),
+      ).toBeUndefined();
+    });
+  });
+
+  describe("start()", () => {
+    test("does NOT throw when manifest.id is a non-empty string", () => {
+      const server = new NimbusExtensionServer({ manifest: makeManifest("valid-id") });
+      // This must not throw — covers the false arm of the id.length === 0 check
+      expect(() => server.start()).not.toThrow();
+    });
+
+    test("throws 'manifest.id is required' when manifest.id is empty string", () => {
+      const server = new NimbusExtensionServer({ manifest: makeManifest("") });
+      // Covers the true arm of the id.length === 0 guard
+      expect(() => server.start()).toThrow("NimbusExtensionServer: manifest.id is required");
+    });
+
+    test("thrown error is an instance of Error", () => {
+      const server = new NimbusExtensionServer({ manifest: makeManifest("") });
+      let caught: unknown;
+      try {
+        server.start();
+      } catch (err) {
+        caught = err;
+      }
+      expect(caught).toBeInstanceOf(Error);
+      expect((caught as Error).message).toBe("NimbusExtensionServer: manifest.id is required");
+    });
+  });
+});

package/src/server.ts

@@ -0,0 +1,39 @@
+/**
+ * NimbusExtensionServer — base class for all Nimbus MCP extension servers
+ *
+ * Usage:
+ *   const server = new NimbusExtensionServer({ manifest, onAuth });
+ *   server.registerTool("search", { description, inputSchema, handler });
+ *   server.start();
+ */
+
+import type { ExtensionManifest } from "./types";
+
+export interface ExtensionServerOptions<TClient> {
+  manifest: ExtensionManifest;
+  onAuth?: (ctx: { accessToken: string }) => TClient;
+}
+
+export interface ToolDefinition<TInput, TClient> {
+  description: string;
+  inputSchema: Record<string, unknown>;
+  handler: (input: TInput, ctx: { client: TClient }) => Promise<unknown>;
+}
+
+export class NimbusExtensionServer<TClient = unknown> {
+  private readonly _options: ExtensionServerOptions<TClient>;
+
+  constructor(options: ExtensionServerOptions<TClient>) {
+    this._options = options;
+  }
+
+  registerTool<TInput>(_name: string, _definition: ToolDefinition<TInput, TClient>): void {
+    // Roadmap Q3: register tool with MCP server
+  }
+
+  start(): void {
+    if (this._options.manifest.id.length === 0) {
+      throw new Error("NimbusExtensionServer: manifest.id is required");
+    }
+  }
+}

package/src/testing/index.ts

@@ -0,0 +1,18 @@
+/**
+ * `@nimbus-dev/sdk/testing` — utilities for extension authors and the
+ * gateway's own connector tests.
+ *
+ * Exports:
+ *   - `MockGateway` — mock Gateway IPC for unit tests (Phase 4).
+ *   - `runSandboxContractTests(manifestPath)` — fork the probe binary and
+ *     verify the runtime sandbox enforces the manifest's declared
+ *     `permissions.network` + `permissions.filesystem` (Phase 5 T2 PR 1).
+ */
+
+export { runSandboxContractTests } from "./sandbox-contract";
+
+export class MockGateway {
+  async callTool(_toolName: string, _input: Record<string, unknown>): Promise<unknown> {
+    return {};
+  }
+}