@nimbus-dev/connectors 0.2.0 → 0.2.2

package/connectors/hubspot/src/server.ts

@@ -1,81 +1,6 @@
-import { z } from "zod";
-import { searchToolInputSchema } from "../../../shared/mcp-search-tool.ts";
-import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
 import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
-import { filterHubspotDeals } from "./search-filter.ts";
-
-const BASE = "https://api.hubapi.com";
-const DEAL_PROPERTIES =
-  "dealname,amount,dealstage,pipeline,closedate,createdate,hs_lastmodifieddate";
-
-function apiToken(): string {
-  const t = process.env["HUBSPOT_TOKEN"]?.trim();
-  if (t === undefined || t === "") {
-    throw new Error("HUBSPOT_TOKEN is not set");
-  }
-  return t;
-}
-
-function authHeader(): Record<string, string> {
-  return { Authorization: `Bearer ${apiToken()}`, Accept: "application/json" };
-}
-
-async function hubspotGet(path: string): Promise<unknown> {
-  const res = await fetch(`${BASE}${path}`, { headers: authHeader() });
-  const text = await res.text();
-  if (!res.ok) {
-    throw new Error(`HubSpot ${String(res.status)}: ${text.slice(0, 400)}`);
-  }
-  return JSON.parse(text) as unknown;
-}
-
-function dealsFrom(root: unknown): unknown[] {
-  const results = (root as { results?: unknown } | null)?.results;
-  return Array.isArray(results) ? results : [];
-}
+import { registerHubspotTools } from "./tools.ts";
 
 await runReadOnlyMcpConnector("nimbus-hubspot", (reg) => {
-  reg(
-    "hubspot_list",
-    "List the authenticated portal's HubSpot deals (GET /crm/v3/objects/deals?limit=N&properties=dealname,amount,dealstage,pipeline,closedate,createdate,hs_lastmodifieddate). Returns the { results: [...], paging?: { next?: { after } } } envelope — `results` holds the deal objects, each shaped { id, properties: { dealname, amount, dealstage, pipeline, closedate, createdate, hs_lastmodifieddate }, createdAt, updatedAt }. `limit` (default 100, max 100) caps page_size of the single first-page request.",
-    z.object({
-      limit: z.number().int().min(1).max(100).optional(),
-    }),
-    async (p) => {
-      const params = new URLSearchParams({
-        limit: String(p.limit ?? 100),
-        properties: DEAL_PROPERTIES,
-      });
-      return jsonResult(await hubspotGet(`/crm/v3/objects/deals?${params.toString()}`));
-    },
-  );
-
-  reg(
-    "hubspot_get",
-    "Fetch one HubSpot deal by its id (GET /crm/v3/objects/deals/{dealId}?properties=dealname,amount,dealstage,pipeline,closedate,createdate,hs_lastmodifieddate). Returns the deal object directly (NOT wrapped in `results`). Throws when no deal with that id exists.",
-    z.object({
-      id: z.string().min(1),
-    }),
-    async (p) => {
-      const params = new URLSearchParams({ properties: DEAL_PROPERTIES });
-      return jsonResult(
-        await hubspotGet(`/crm/v3/objects/deals/${encodeURIComponent(p.id)}?${params.toString()}`),
-      );
-    },
-  );
-
-  reg(
-    "hubspot_search",
-    "**Substring search over the FIRST PAGE only** (up to 100 most-recently-listed deals) of the authenticated portal's HubSpot deals. This tool fetches GET /crm/v3/objects/deals?limit=100 once and matches the query locally (case-insensitive) against the deal name, deal stage, and pipeline. **Deals beyond the first page are not searchable here — query the local Nimbus index instead for full coverage.** Returns a { matches: [...] } envelope.",
-    searchToolInputSchema(100),
-    async (p) => {
-      const params = new URLSearchParams({ limit: "100", properties: DEAL_PROPERTIES });
-      const root = await hubspotGet(`/crm/v3/objects/deals?${params.toString()}`);
-      const matches = filterHubspotDeals(dealsFrom(root), {
-        query: p.query,
-        limit: p.limit,
-      });
-      return jsonResult({ matches });
-    },
-  );
+  registerHubspotTools(reg);
 });

package/connectors/hubspot/src/tools.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { createJsonGetter, envAuthHeaders } from "../../../shared/env-json-api.ts";
+import { 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 { filterHubspotDeals } from "./search-filter.ts";
+
+const BASE = "https://api.hubapi.com";
+const DEAL_PROPERTIES =
+  "dealname,amount,dealstage,pipeline,closedate,createdate,hs_lastmodifieddate";
+
+const hubspotGet = createJsonGetter({
+  base: BASE,
+  label: "HubSpot",
+  headers: envAuthHeaders({ env: "HUBSPOT_TOKEN" }),
+});
+
+function dealsFrom(root: unknown): unknown[] {
+  const results = (root as { results?: unknown } | null)?.results;
+  return Array.isArray(results) ? results : [];
+}
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const HUBSPOT_TOOL_NAMES = ["hubspot_get", "hubspot_list", "hubspot_search"] as const;
+
+export function registerHubspotTools(reg: ZodToolRegistrar): void {
+  reg(
+    "hubspot_list",
+    "List the authenticated portal's HubSpot deals (GET /crm/v3/objects/deals?limit=N&properties=dealname,amount,dealstage,pipeline,closedate,createdate,hs_lastmodifieddate). Returns the { results: [...], paging?: { next?: { after } } } envelope — `results` holds the deal objects, each shaped { id, properties: { dealname, amount, dealstage, pipeline, closedate, createdate, hs_lastmodifieddate }, createdAt, updatedAt }. `limit` (default 100, max 100) caps page_size of the single first-page request.",
+    z.object({
+      limit: z.number().int().min(1).max(100).optional(),
+    }),
+    async (p) => {
+      const params = new URLSearchParams({
+        limit: String(p.limit ?? 100),
+        properties: DEAL_PROPERTIES,
+      });
+      return jsonResult(await hubspotGet(`/crm/v3/objects/deals?${params.toString()}`));
+    },
+  );
+
+  reg(
+    "hubspot_get",
+    "Fetch one HubSpot deal by its id (GET /crm/v3/objects/deals/{dealId}?properties=dealname,amount,dealstage,pipeline,closedate,createdate,hs_lastmodifieddate). Returns the deal object directly (NOT wrapped in `results`). Throws when no deal with that id exists.",
+    z.object({
+      id: z.string().min(1),
+    }),
+    async (p) => {
+      const params = new URLSearchParams({ properties: DEAL_PROPERTIES });
+      return jsonResult(
+        await hubspotGet(`/crm/v3/objects/deals/${encodeURIComponent(p.id)}?${params.toString()}`),
+      );
+    },
+  );
+
+  reg(
+    "hubspot_search",
+    "**Substring search over the FIRST PAGE only** (up to 100 most-recently-listed deals) of the authenticated portal's HubSpot deals. This tool fetches GET /crm/v3/objects/deals?limit=100 once and matches the query locally (case-insensitive) against the deal name, deal stage, and pipeline. **Deals beyond the first page are not searchable here — query the local Nimbus index instead for full coverage.** Returns a { matches: [...] } envelope.",
+    searchToolInputSchema(100),
+    async (p) => {
+      const params = new URLSearchParams({ limit: "100", properties: DEAL_PROPERTIES });
+      const root = await hubspotGet(`/crm/v3/objects/deals?${params.toString()}`);
+      const matches = filterHubspotDeals(dealsFrom(root), {
+        query: p.query,
+        limit: p.limit,
+      });
+      return jsonResult({ matches });
+    },
+  );
+}

package/connectors/iac/src/server.ts

@@ -1,145 +1,10 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-import {
-  createRegisterSimpleTool,
-  createZodToolRegistrar,
-  mcpJsonResult as jsonResult,
-} from "../../../shared/mcp-tool-kit.ts";
-import { runCliOkThrowing } from "../../../shared/run-cli-json.ts";
+import { registerIacTools } from "./tools.ts";
 
 const mcp = new McpServer({ name: "nimbus-iac", version: "0.1.0" });
 
-import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
-
-const reg = createZodToolRegistrar(createRegisterSimpleTool(mcp));
-
-/**
- * Every MUTATING iac tool goes through here. Outside the gateway this adds the
- * consent gate, the write-scope allow-list, the mutation budget and the audit record; inside
- * the gateway it is a pass-through, because executor.ts (I2) is the gate there.
- */
-const registerWriteTool = createWriteToolRegistrar(mcp, {
-  connector: "iac",
-  scopeEnv: "NIMBUS_MCP_IAC_WRITE_SCOPE",
-  scopeKinds: ["dir", "stack"],
-});
-
-const processEnv = process.env as Record<string, string | undefined>;
-
-reg(
-  "iac_terraform_plan",
-  "Run terraform plan in a directory.",
-  z.object({ workingDirectory: z.string().min(1) }),
-  async (p) => {
-    await runCliOkThrowing(["terraform", "-chdir", p.workingDirectory, "plan", "-input=false"], {
-      ...processEnv,
-    });
-    return jsonResult({ ok: true });
-  },
-);
-
-registerWriteTool(
-  "iac_terraform_apply",
-  {
-    mutates: "iac.terraform.apply",
-    recoverable: true,
-    scopeTargetOf: (p) => ({ kind: "dir", value: p.workingDirectory }),
-  },
-  "Run terraform apply.",
-  z.object({ workingDirectory: z.string().min(1) }),
-  async (p) => {
-    await runCliOkThrowing(
-      ["terraform", "-chdir", p.workingDirectory, "apply", "-auto-approve", "-input=false"],
-      { ...processEnv },
-    );
-    return jsonResult({ ok: true });
-  },
-);
-
-registerWriteTool(
-  "iac_terraform_destroy",
-  {
-    mutates: "iac.terraform.destroy",
-    // Destroying infrastructure cannot be undone from its own result, and there is nothing
-    // queryable to snapshot, so the identifying parameters ARE the pre-state: a record naming
-    // WHICH directory was destroyed still beats silence.
-    recoverable: false,
-    capturePreState: (p) => Promise.resolve({ workingDirectory: p.workingDirectory }),
-    scopeTargetOf: (p) => ({ kind: "dir", value: p.workingDirectory }),
-  },
-  "Run terraform destroy.",
-  z.object({ workingDirectory: z.string().min(1) }),
-  async (p) => {
-    await runCliOkThrowing(
-      ["terraform", "-chdir", p.workingDirectory, "destroy", "-auto-approve", "-input=false"],
-      { ...processEnv },
-    );
-    return jsonResult({ ok: true });
-  },
-);
-
-registerWriteTool(
-  "iac_cloudformation_deploy",
-  {
-    mutates: "iac.cloudformation.deploy",
-    recoverable: true,
-    scopeTargetOf: (p) => ({ kind: "stack", value: p.stackName }),
-  },
-  "Deploy a CloudFormation stack via AWS CLI.",
-  z.object({
-    stackName: z.string().min(1),
-    templateBody: z.string().min(1),
-  }),
-  async (p) => {
-    await runCliOkThrowing(
-      [
-        "aws",
-        "cloudformation",
-        "deploy",
-        "--stack-name",
-        p.stackName,
-        "--template-body",
-        p.templateBody,
-        "--capabilities",
-        "CAPABILITY_IAM",
-      ],
-      { ...processEnv },
-    );
-    return jsonResult({ ok: true });
-  },
-);
-
-reg(
-  "iac_pulumi_preview",
-  "Run pulumi preview in a stack directory.",
-  z.object({ workingDirectory: z.string().min(1) }),
-  async (p) => {
-    await runCliOkThrowing(
-      ["pulumi", "preview", "--cwd", p.workingDirectory, "--non-interactive"],
-      { ...processEnv },
-    );
-    return jsonResult({ ok: true });
-  },
-);
-
-registerWriteTool(
-  "iac_pulumi_up",
-  {
-    mutates: "iac.pulumi.up",
-    recoverable: true,
-    scopeTargetOf: (p) => ({ kind: "dir", value: p.workingDirectory }),
-  },
-  "Run pulumi up.",
-  z.object({ workingDirectory: z.string().min(1) }),
-  async (p) => {
-    await runCliOkThrowing(
-      ["pulumi", "up", "--yes", "--cwd", p.workingDirectory, "--non-interactive"],
-      { ...processEnv },
-    );
-    return jsonResult({ ok: true });
-  },
-);
+registerIacTools(mcp);
 
 const transport = new StdioServerTransport();
 await mcp.connect(transport);

package/connectors/iac/src/tools.ts

@@ -0,0 +1,152 @@
+import { z } from "zod";
+import type { ConsentServer } from "../../../shared/consent-kit.ts";
+import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResult as jsonResult,
+} from "../../../shared/mcp-tool-kit.ts";
+import { runCliOkThrowing } from "../../../shared/run-cli-json.ts";
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const IAC_TOOL_NAMES = [
+  "iac_terraform_plan",
+  "iac_terraform_apply",
+  "iac_terraform_destroy",
+  "iac_cloudformation_deploy",
+  "iac_pulumi_preview",
+  "iac_pulumi_up",
+] as const;
+
+export function registerIacTools(
+  server: ConsentServer & { tool: (...args: never) => unknown },
+): void {
+  const reg = createZodToolRegistrar(createRegisterSimpleTool(server));
+
+  /**
+   * Every MUTATING iac tool goes through here. Outside the gateway this adds the
+   * consent gate, the write-scope allow-list, the mutation budget and the audit record; inside
+   * the gateway it is a pass-through, because executor.ts (I2) is the gate there.
+   */
+  const registerWriteTool = createWriteToolRegistrar(server, {
+    connector: "iac",
+    scopeEnv: "NIMBUS_MCP_IAC_WRITE_SCOPE",
+    scopeKinds: ["dir", "stack"],
+  });
+
+  const processEnv = process.env as Record<string, string | undefined>;
+
+  reg(
+    "iac_terraform_plan",
+    "Run terraform plan in a directory.",
+    z.object({ workingDirectory: z.string().min(1) }),
+    async (p) => {
+      await runCliOkThrowing(["terraform", "-chdir", p.workingDirectory, "plan", "-input=false"], {
+        ...processEnv,
+      });
+      return jsonResult({ ok: true });
+    },
+  );
+
+  registerWriteTool(
+    "iac_terraform_apply",
+    {
+      mutates: "iac.terraform.apply",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "dir", value: p.workingDirectory }),
+    },
+    "Run terraform apply.",
+    z.object({ workingDirectory: z.string().min(1) }),
+    async (p) => {
+      await runCliOkThrowing(
+        ["terraform", "-chdir", p.workingDirectory, "apply", "-auto-approve", "-input=false"],
+        { ...processEnv },
+      );
+      return jsonResult({ ok: true });
+    },
+  );
+
+  registerWriteTool(
+    "iac_terraform_destroy",
+    {
+      mutates: "iac.terraform.destroy",
+      // Destroying infrastructure cannot be undone from its own result, and there is nothing
+      // queryable to snapshot, so the identifying parameters ARE the pre-state: a record naming
+      // WHICH directory was destroyed still beats silence.
+      recoverable: false,
+      capturePreState: (p) => Promise.resolve({ workingDirectory: p.workingDirectory }),
+      scopeTargetOf: (p) => ({ kind: "dir", value: p.workingDirectory }),
+    },
+    "Run terraform destroy.",
+    z.object({ workingDirectory: z.string().min(1) }),
+    async (p) => {
+      await runCliOkThrowing(
+        ["terraform", "-chdir", p.workingDirectory, "destroy", "-auto-approve", "-input=false"],
+        { ...processEnv },
+      );
+      return jsonResult({ ok: true });
+    },
+  );
+
+  registerWriteTool(
+    "iac_cloudformation_deploy",
+    {
+      mutates: "iac.cloudformation.deploy",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "stack", value: p.stackName }),
+    },
+    "Deploy a CloudFormation stack via AWS CLI.",
+    z.object({
+      stackName: z.string().min(1),
+      templateBody: z.string().min(1),
+    }),
+    async (p) => {
+      await runCliOkThrowing(
+        [
+          "aws",
+          "cloudformation",
+          "deploy",
+          "--stack-name",
+          p.stackName,
+          "--template-body",
+          p.templateBody,
+          "--capabilities",
+          "CAPABILITY_IAM",
+        ],
+        { ...processEnv },
+      );
+      return jsonResult({ ok: true });
+    },
+  );
+
+  reg(
+    "iac_pulumi_preview",
+    "Run pulumi preview in a stack directory.",
+    z.object({ workingDirectory: z.string().min(1) }),
+    async (p) => {
+      await runCliOkThrowing(
+        ["pulumi", "preview", "--cwd", p.workingDirectory, "--non-interactive"],
+        { ...processEnv },
+      );
+      return jsonResult({ ok: true });
+    },
+  );
+
+  registerWriteTool(
+    "iac_pulumi_up",
+    {
+      mutates: "iac.pulumi.up",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "dir", value: p.workingDirectory }),
+    },
+    "Run pulumi up.",
+    z.object({ workingDirectory: z.string().min(1) }),
+    async (p) => {
+      await runCliOkThrowing(
+        ["pulumi", "up", "--yes", "--cwd", p.workingDirectory, "--non-interactive"],
+        { ...processEnv },
+      );
+      return jsonResult({ ok: true });
+    },
+  );
+}

package/connectors/imap/src/imap-core.ts

@@ -11,10 +11,28 @@
  * preview — there is no surface to request `BODY[]` or an attachment part.
  *
  * The IMAP client and SMTP mailer are injected so tests never open real sockets.
+ *
+ * The shapes themselves now live in `shared/imap-mail-core.ts`: this connector
+ * and protonmail declared them separately and identically, which is the same
+ * duplication the tool layer had already been through. The `Imap*` aliases stay
+ * so this connector's own callers read as before.
  */
 
-import type { MailAddress } from "../../../shared/imap-mail-core.ts";
+import type {
+  MailAddress,
+  MailAttachmentMeta,
+  MailClient,
+  MailEnvelope,
+  MailListOptions,
+  MailMessageMeta,
+  MailSearchOptions,
+} from "../../../shared/imap-mail-core.ts";
 
+export type {
+  SendMailInput,
+  SendMailResult,
+  SmtpMailer,
+} from "../../../shared/imap-mail-core.ts";
 export {
   capPreview,
   clampLimit,
@@ -25,86 +43,15 @@ export {
 
 /** One parsed address (name optional). */
 export type ImapAddress = MailAddress;
-
 /** Message ENVELOPE — RFC 2822 header fields only. */
-export interface ImapEnvelope {
-  readonly date?: Date | string | null;
-  readonly subject?: string | null;
-  readonly messageId?: string | null;
-  readonly from?: readonly ImapAddress[];
-  readonly to?: readonly ImapAddress[];
-  readonly cc?: readonly ImapAddress[];
-}
-
-/**
- * Attachment METADATA only — filename, size, mimetype. NEVER the bytes.
- * Derived from BODYSTRUCTURE.
- */
-export interface ImapAttachmentMeta {
-  readonly filename: string | null;
-  readonly sizeBytes: number | null;
-  readonly mimeType: string | null;
-}
-
-/**
- * A single mailbox message reduced to header + attachment-metadata + a capped
- * text preview. This is the ONLY shape the connector ever materializes; it has
- * no field that could carry attachment content or a full body.
- */
-export interface ImapMessageMeta {
-  readonly uid: number;
-  readonly mailbox: string;
-  readonly uidValidity: string | null;
-  readonly envelope: ImapEnvelope;
-  readonly attachments: readonly ImapAttachmentMeta[];
-  /** Plain-text body preview, already capped to {@link PREVIEW_MAX_CHARS}. */
-  readonly preview: string;
-}
-
+export type ImapEnvelope = MailEnvelope;
+/** Attachment METADATA only — filename, size, mimetype. NEVER the bytes. */
+export type ImapAttachmentMeta = MailAttachmentMeta;
+/** Header + attachment-metadata + capped preview: the only shape materialized. */
+export type ImapMessageMeta = MailMessageMeta;
 /** Listing options. */
-export interface ImapListOptions {
-  readonly mailbox?: string;
-  readonly limit?: number;
-}
-
-/** Search options — searches header/envelope fields, never document/body content scans. */
-export interface ImapSearchOptions {
-  readonly query: string;
-  readonly mailbox?: string;
-  readonly limit?: number;
-}
-
-/**
- * Minimal IMAP client surface the connector depends on. Implemented for real by
- * the imapflow adapter in `server.ts` and by a fake in tests. Deliberately
- * exposes ONLY header/attachment-metadata + capped-preview reads.
- */
-export interface ImapClient {
-  /** List the most recent messages (header + attachment metadata + preview). */
-  list(options: ImapListOptions): Promise<ImapMessageMeta[]>;
-  /** Fetch one message's header + attachment metadata + preview by uid. */
-  get(uid: number, mailbox?: string): Promise<ImapMessageMeta | null>;
-  /** Search by subject/from/to substring; returns matching message metas. */
-  search(options: ImapSearchOptions): Promise<ImapMessageMeta[]>;
-}
-
-/** Outgoing message for the SMTP send tool. */
-export interface SendMailInput {
-  readonly to: string;
-  readonly subject: string;
-  readonly body: string;
-  readonly cc?: string;
-  readonly bcc?: string;
-}
-
-/** Result of a send (message id assigned by the SMTP server, if any). */
-export interface SendMailResult {
-  readonly messageId: string | null;
-  readonly accepted: readonly string[];
-  readonly rejected: readonly string[];
-}
-
-/** Minimal SMTP mailer surface; implemented for real over nodemailer. */
-export interface SmtpMailer {
-  send(input: SendMailInput): Promise<SendMailResult>;
-}
+export type ImapListOptions = MailListOptions;
+/** Search options — header/envelope fields only, never body-content scans. */
+export type ImapSearchOptions = MailSearchOptions;
+/** Minimal IMAP client surface the connector depends on. */
+export type ImapClient = MailClient;