@nimbus-dev/connectors 0.7.0 → 0.8.0

package/connectors/apple/src/adapters.ts

@@ -190,7 +190,8 @@ export interface DavClientLike {
     calendar: DAVCalendar;
     timeRange?: { start: string; end: string };
     expand?: boolean;
-  }): Promise<{ url: string; data?: unknown }[]>;
+    objectUrls?: string[];
+  }): Promise<{ url: string; etag?: string | undefined; data?: unknown }[]>;
   createCalendarObject(params: {
     calendar: DAVCalendar;
     iCalString: string;
@@ -204,6 +205,8 @@ export interface LoggingInCalDavClient extends CalDavClient {
   login(): Promise<void>;
 }
 
+const NOT_IN_YOUR_CALENDARS = "href is not in one of your calendars";
+
 class TsdavCalDavClient implements LoggingInCalDavClient {
   /**
    * Discovered DAVCalendar objects keyed by their url. Populated after the
@@ -282,7 +285,59 @@ class TsdavCalDavClient implements LoggingInCalDavClient {
     return { href };
   }
 
+  /**
+   * The discovered calendar whose URL contains `href`, or undefined. Both are compared as normalised
+   * absolute URLs (dot segments resolved), the calendar's with a trailing slash, so `.../home/` does
+   * not own `.../home-evil/x.ics` or `.../home/../other/x.ics`, and another host owns nothing. The
+   * calendars are discovered first when none has been.
+   */
+  private async calendarOwning(href: string): Promise<DAVCalendar | undefined> {
+    if (this.discovered.size === 0) await this.listCalendars();
+    let target: string;
+    try {
+      target = new URL(href).toString();
+    } catch {
+      return undefined;
+    }
+    for (const [url, cal] of this.discovered) {
+      let base: string;
+      try {
+        base = new URL(url).toString();
+      } catch {
+        continue;
+      }
+      if (!base.endsWith("/")) base = `${base}/`;
+      if (target.startsWith(base) && target.length > base.length) return cal;
+    }
+    return undefined;
+  }
+
+  async getEvent(
+    href: string,
+  ): Promise<{ calendar: string; etag: string | null; event: ParsedEvent }> {
+    const cal = await this.calendarOwning(href);
+    if (cal === undefined) throw new Error(NOT_IN_YOUR_CALENDARS);
+    const objects = await this.davClient.fetchCalendarObjects({
+      calendar: cal,
+      objectUrls: [href],
+    });
+    for (const obj of objects) {
+      if (typeof obj.data !== "string" || obj.data === "") continue;
+      const event = parseICalendar(obj.data)[0];
+      if (event === undefined) continue;
+      const name =
+        typeof cal.displayName === "string" && cal.displayName !== "" ? cal.displayName : cal.url;
+      return { calendar: name, etag: typeof obj.etag === "string" ? obj.etag : null, event };
+    }
+    throw new Error("event not found");
+  }
+
   async deleteEvent(href: string): Promise<void> {
+    // The credential goes to whatever host the href names, and the href is the model's: refuse one
+    // that is not under a calendar this account discovered, before any request.
+    if ((await this.calendarOwning(href)) === undefined) {
+      throw new Error(NOT_IN_YOUR_CALENDARS);
+    }
     // etag: "" means "unconditional delete" — acceptable because we don't track
     // etags in the CalendarRef/EventWindow flow.
     await this.davClient.deleteCalendarObject({

package/connectors/apple/src/caldav-core.ts

@@ -38,6 +38,13 @@ export interface CalDavClient {
     window: EventWindow,
   ): Promise<{ href: string; event: ParsedEvent }[]>;
   putEvent(cal: CalendarRef, uid: string, ics: string): Promise<{ href: string }>;
+  /**
+   * One event by its object URL, with the entity tag the server holds for it (RFC 4791 5.3.4: a GET on
+   * a calendar object resource MUST return an ETag). `href` must lie under one of the account's own
+   * calendars; any other is refused BEFORE a request is made.
+   */
+  getEvent(href: string): Promise<{ calendar: string; etag: string | null; event: ParsedEvent }>;
+  /** Delete by object URL; `href` must lie under one of the account's own calendars. */
   deleteEvent(href: string): Promise<void>;
 }
 

package/connectors/apple/src/calendar-tools.ts

@@ -229,6 +229,40 @@ export function registerAppleCalendarTools(
     },
   );
 
+  // -------------------------------------------------------------------------
+  // apple_calendar_event_get
+  // -------------------------------------------------------------------------
+
+  registerSimpleTool(
+    "apple_calendar_event_get",
+    "Get one iCloud Calendar event by its object href (as apple_calendar_list returns it), with its ETag. The href must be under one of your calendars. The before-state of apple_calendar_event_delete; same href.",
+    deleteArgs.shape,
+    async (args: unknown) => {
+      const parsed = deleteArgs.safeParse(args);
+      if (!parsed.success) {
+        throw new Error(parsed.error.message);
+      }
+      const { calendar: calendarName, etag, event } = await calendar.getEvent(parsed.data.href);
+      const view: ViewEvent & { etag: string | null } = {
+        href: parsed.data.href,
+        uid: event.uid,
+        summary: event.summary,
+        start: event.start,
+        end: event.end,
+        allDay: event.allDay,
+        location: event.location,
+        organizer: event.organizer,
+        status: event.status,
+        attendees: event.attendees,
+        rrule: event.rrule,
+        notes: capPreview(event.description ?? ""),
+        calendar: calendarName,
+        etag,
+      };
+      return mcpJsonResult(view);
+    },
+  );
+
   // -------------------------------------------------------------------------
   // apple_calendar_event_create
   // -------------------------------------------------------------------------

package/connectors/apple/src/tools.ts

@@ -90,7 +90,7 @@ export function registerAppleTools(
     },
   );
 
-  // apple_calendar_list, apple_calendar_event_create, apple_calendar_event_delete
+  // apple_calendar_list, apple_calendar_event_get, apple_calendar_event_create, apple_calendar_event_delete
   registerAppleCalendarTools(server, {
     calendar,
     now,
@@ -107,6 +107,7 @@ export const APPLE_TOOL_NAMES = [
   "apple_mail_send",
   "apple_mail_draft_create",
   "apple_calendar_list",
+  "apple_calendar_event_get",
   "apple_calendar_event_create",
   "apple_calendar_event_delete",
 ] as const;

package/connectors/aws/src/tools.ts

@@ -38,10 +38,79 @@ async function awsJson(args: string[]): Promise<unknown> {
   return (await runCliJsonThrowing(cmd, awsEnv())) ?? {};
 }
 
+/** One EC2 instance id: `i-` and 8 to 17 lowercase hex digits (the long and the legacy short form). */
+const ec2InstanceId = awsCliArg.regex(/^i-[0-9a-f]{8,17}$/, "not an EC2 instance id (i-...)");
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * The projection of `aws ec2 describe-instances --instance-ids <id>`. Field names are those on
+ * https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html:
+ * `Reservations[].Instances[]` with `InstanceId`, `InstanceType`, `LaunchTime`, `State{Code,Name}`,
+ * `IamInstanceProfile{Arn,Id}` and `Tags[]{Key,Value}`. No instance in the reply (AWS omits one you
+ * do not own) throws "instance not found".
+ */
+function projectInstance(raw: unknown): Record<string, unknown> {
+  const reservations =
+    isRecord(raw) && Array.isArray(raw["Reservations"]) ? raw["Reservations"] : [];
+  for (const r of reservations) {
+    const instances = isRecord(r) && Array.isArray(r["Instances"]) ? r["Instances"] : [];
+    for (const i of instances) {
+      if (!isRecord(i) || typeof i["InstanceId"] !== "string") continue;
+      const state = isRecord(i["State"]) ? i["State"]["Name"] : undefined;
+      const profile = isRecord(i["IamInstanceProfile"])
+        ? i["IamInstanceProfile"]["Arn"]
+        : undefined;
+      const tags = (Array.isArray(i["Tags"]) ? i["Tags"] : [])
+        .filter(isRecord)
+        .map((t) => ({ key: t["Key"], value: t["Value"] }));
+      return {
+        instanceId: i["InstanceId"],
+        state: typeof state === "string" ? state : undefined,
+        instanceType: i["InstanceType"],
+        launchTime: i["LaunchTime"],
+        tags,
+        iamProfileArn: typeof profile === "string" ? profile : undefined,
+      };
+    }
+  }
+  throw new Error("instance not found");
+}
+
+/**
+ * The projection of `aws ecs describe-services --cluster X --services Y`
+ * (https://docs.aws.amazon.com/cli/latest/reference/ecs/describe-services.html): `services[]` with
+ * `serviceName, status, desiredCount, runningCount, taskDefinition, launchType`, and `failures[]`
+ * for a service it could not describe (a missing one comes back there, with exit code 0). A service
+ * in `failures` with none in `services`, or no entry in `services` at all, is "service not found".
+ * An INACTIVE service is still listed by the API and is reported with its status.
+ */
+function projectEcsService(raw: unknown): Record<string, unknown> {
+  const services = isRecord(raw) && Array.isArray(raw["services"]) ? raw["services"] : [];
+  const service = services.find((s) => isRecord(s) && typeof s["serviceName"] === "string");
+  if (!isRecord(service)) throw new Error("service not found");
+  const out: Record<string, unknown> = {};
+  for (const k of [
+    "serviceName",
+    "status",
+    "desiredCount",
+    "runningCount",
+    "taskDefinition",
+    "launchType",
+  ] as const) {
+    if (service[k] !== undefined && service[k] !== null) out[k] = service[k];
+  }
+  return out;
+}
+
 /** Tool names exposed by this connector — for contract/introspection tests. */
 export const AWS_TOOL_NAMES = [
   "aws_ecs_service_list",
+  "aws_ecs_service_get",
   "aws_lambda_list",
+  "aws_ec2_instance_get",
   "aws_ecs_service_update",
   "aws_lambda_invoke",
   "aws_ec2_instance_stop",
@@ -71,10 +140,51 @@ export function registerAwsTools(
     async (p) => jsonResult(await awsJson(["ecs", "list-services", "--cluster", p.cluster])),
   );
 
+  reg(
+    "aws_ecs_service_get",
+    "Get one ECS service's state: {serviceName, status, desiredCount, runningCount, taskDefinition, launchType}. The before-state of aws_ecs_service_update; same cluster and service. A service the API reports as a failure, or does not return, is 'service not found'.",
+    z.object({ cluster: awsCliArg, service: awsCliArg }),
+    async (p) =>
+      jsonResult(
+        projectEcsService(
+          await awsJson([
+            "ecs",
+            "describe-services",
+            "--cluster",
+            p.cluster,
+            "--services",
+            p.service,
+          ]),
+        ),
+      ),
+  );
+
   reg("aws_lambda_list", "List Lambda functions (first page).", z.object({}), async () =>
     jsonResult(await awsJson(["lambda", "list-functions"])),
   );
 
+  reg(
+    "aws_ec2_instance_get",
+    "Get one EC2 instance's state: {instanceId, state, instanceType, launchTime, tags, iamProfileArn}. The before-state of a start or a stop.",
+    z.object({ instanceId: ec2InstanceId }),
+    async (p) => {
+      try {
+        return jsonResult(
+          projectInstance(
+            await awsJson(["ec2", "describe-instances", "--instance-ids", p.instanceId]),
+          ),
+        );
+      } catch (e) {
+        // The error code for a well-formed id that does not exist is InvalidInstanceID.NotFound
+        // (EC2 error codes); the describe-instances page names none, so the code is matched here.
+        if (e instanceof Error && /InvalidInstanceID.NotFound/.test(e.message)) {
+          throw new Error("instance not found", { cause: e });
+        }
+        throw e;
+      }
+    },
+  );
+
   registerWriteTool(
     "aws_ecs_service_update",
     {

package/connectors/azure/src/tools.ts

@@ -18,9 +18,50 @@ async function azJson(args: string[]): Promise<unknown> {
   return (await runCliJsonThrowing(cmd, azEnv())) ?? {};
 }
 
+/**
+ * The node-pool keys `az aks nodepool show` is projected to. The page
+ * (https://learn.microsoft.com/en-us/cli/azure/aks/nodepool) does not list the output fields, so
+ * only the keys PRESENT in the reply are kept and an absent one stays absent.
+ */
+const NODE_POOL_KEYS = [
+  "count",
+  "vmSize",
+  "mode",
+  "powerState",
+  "provisioningState",
+  "orchestratorVersion",
+  "enableAutoScaling",
+  "minCount",
+  "maxCount",
+] as const;
+
+function projectNodePool(raw: unknown): Record<string, unknown> {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error("node pool not found");
+  }
+  const rec = raw as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  for (const k of NODE_POOL_KEYS) {
+    if (rec[k] !== undefined && rec[k] !== null) out[k] = rec[k];
+  }
+  // None of the keys present: not a node pool reply, so the owner is not shown an empty before-state.
+  if (Object.keys(out).length === 0) throw new Error("node pool not found");
+  // powerState is an object ({code}) in az's output; report its code as the plain string it is.
+  const ps = out["powerState"];
+  if (
+    typeof ps === "object" &&
+    ps !== null &&
+    typeof (ps as { code?: unknown }).code === "string"
+  ) {
+    out["powerState"] = (ps as { code: string }).code;
+  }
+  return out;
+}
+
 /** Tool names exposed by this connector — for contract/introspection tests. */
 export const AZURE_TOOL_NAMES = [
   "azure_app_service_list",
+  "azure_aks_node_pool_get",
   "azure_app_service_restart",
   "azure_aks_node_pool_scale",
 ] as const;
@@ -61,6 +102,35 @@ export function registerAzureTools(
       ),
   );
 
+  reg(
+    "azure_aks_node_pool_get",
+    "Get one AKS node pool's state (count, vmSize, mode, powerState, provisioningState, orchestratorVersion, autoscaler bounds; absent keys omitted). The before-state of azure_aks_node_pool_scale; same keys.",
+    z.object({
+      subscriptionId: azCliArg,
+      resourceGroup: azCliArg,
+      clusterName: azCliArg,
+      poolName: azCliArg,
+    }),
+    async (p) =>
+      jsonResult(
+        projectNodePool(
+          await azJson([
+            "aks",
+            "nodepool",
+            "show",
+            "--subscription",
+            p.subscriptionId,
+            "--resource-group",
+            p.resourceGroup,
+            "--cluster-name",
+            p.clusterName,
+            "--name",
+            p.poolName,
+          ]),
+        ),
+      ),
+  );
+
   registerWriteTool(
     "azure_app_service_restart",
     {

package/connectors/circleci/src/tools.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import type { ConsentServer } from "../../../shared/consent-kit.ts";
 import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import { guardedFetch } from "../../../shared/guarded-fetch.ts";
 import {
   createRegisterSimpleTool,
   createZodToolRegistrar,
@@ -30,7 +31,9 @@ async function circleciFetch(
   init?: RequestInit,
 ): Promise<RestFetchResult> {
   const url = path.startsWith("http") ? path : `${CCI_API}${path}`;
-  const res = await fetch(url, {
+  // guardedFetch: the Circle-Token header must never follow a redirect to another origin, and a
+  // redirect on a write is refused rather than replayed.
+  const res = await guardedFetch("CircleCI", url, {
     ...init,
     headers: {
       Accept: "application/json",
@@ -41,6 +44,47 @@ async function circleciFetch(
   return toRestFetchResult(res);
 }
 
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v !== "" ? v : undefined;
+}
+
+/**
+ * The job fields a cancel preview needs, read defensively: `GET /project/{slug}/job/{n}` is not on
+ * the CircleCI v2 reference page (only `GET /jobs/{job_id}`, whose fields are `name, job_number,
+ * status, pipeline_id, started_at, stopped_at`), so each field is taken under both spellings when
+ * one is plausible and an absent one is left out. Live check item.
+ */
+export function projectJob(raw: unknown): Record<string, unknown> {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error("CircleCI returned no job");
+  }
+  const r = raw as Record<string, unknown>;
+  const pipeline =
+    typeof r["pipeline"] === "object" && r["pipeline"] !== null
+      ? (r["pipeline"] as Record<string, unknown>)
+      : {};
+  const out: Record<string, unknown> = {};
+  const set = (k: string, v: unknown): void => {
+    if (v !== undefined) out[k] = v;
+  };
+  set("name", str(r["name"]));
+  set(
+    "number",
+    typeof r["number"] === "number"
+      ? r["number"]
+      : typeof r["job_number"] === "number"
+        ? r["job_number"]
+        : undefined,
+  );
+  set("status", str(r["status"]));
+  set("startedAt", str(r["started_at"]));
+  set("stoppedAt", str(r["stopped_at"]));
+  set("webUrl", str(r["web_url"]));
+  set("pipelineId", str(r["pipeline_id"]) ?? str(pipeline["id"]));
+  if (Object.keys(out).length === 0) throw new Error("CircleCI returned no job");
+  return out;
+}
+
 /** Tool names exposed by this connector — for contract/introspection tests. */
 export const CIRCLECI_TOOL_NAMES = [
   "circleci_pipeline_list",
@@ -48,6 +92,7 @@ export const CIRCLECI_TOOL_NAMES = [
   "circleci_workflow_list",
   "circleci_job_list",
   "circleci_job_artifacts",
+  "circleci_job_get",
   "circleci_pipeline_trigger",
   "circleci_job_cancel",
 ] as const;
@@ -132,6 +177,23 @@ export function registerCircleciTools(
       `/project/${projectPathSegments(parsed.projectSlug)}/job/${String(parsed.jobNumber)}/artifacts`,
   );
 
+  reg(
+    "circleci_job_get",
+    "Get one job under a project by job number: {name, number, status, startedAt, stoppedAt, webUrl, pipelineId}. The before-state of circleci_job_cancel; same arguments.",
+    projectSlugSchema.extend({ jobNumber: z.number().int().min(1) }),
+    async (parsed) => {
+      const token = requireProcessEnv("CIRCLECI_API_TOKEN");
+      const res = await circleciFetch(
+        token,
+        `/project/${projectPathSegments(parsed.projectSlug)}/job/${String(parsed.jobNumber)}`,
+      );
+      if (!res.ok) {
+        throw new Error(`CircleCI ${String(res.status)}: ${res.text.slice(0, 400)}`);
+      }
+      return jsonResult(projectJob(res.json));
+    },
+  );
+
   registerWriteTool(
     "circleci_pipeline_trigger",
     {

package/connectors/gcp/src/tools.ts

@@ -2,11 +2,13 @@ import { z } from "zod";
 import { cliArg, gcloudEnv } from "../../../shared/cli-json-kit.ts";
 import type { ConsentServer } from "../../../shared/consent-kit.ts";
 import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import { isKubectlNotFound, projectDeployment } from "../../../shared/k8s-deployment-view.ts";
 import {
   createRegisterSimpleTool,
   createZodToolRegistrar,
   mcpJsonResult as jsonResult,
 } from "../../../shared/mcp-tool-kit.ts";
+import { withPrivateKubeconfig } from "../../../shared/private-kubeconfig.ts";
 import { runCliJsonThrowing, runCliOkThrowing } from "../../../shared/run-cli-json.ts";
 
 async function gcloudJson(args: string[]): Promise<unknown> {
@@ -14,11 +16,47 @@ async function gcloudJson(args: string[]): Promise<unknown> {
   return (await runCliJsonThrowing(cmd, gcloudEnv())) ?? {};
 }
 
+type GkeTarget = {
+  readonly projectId: string;
+  readonly location: string;
+  readonly cluster: string;
+};
+
+/**
+ * Run `body` with credentials for one GKE cluster in a PRIVATE kubeconfig: a fresh empty file,
+ * which `get-credentials` fills (it writes `$HOME/.kube/config` only when `KUBECONFIG` is unset,
+ * so the owner's file is never touched). `--location` is gcloud's own preferred flag and, unlike
+ * `--zone`, also names a regional cluster.
+ * https://docs.cloud.google.com/sdk/gcloud/reference/container/clusters/get-credentials
+ */
+function withGkeCredentials<T>(
+  t: GkeTarget,
+  body: (env: Record<string, string | undefined>) => Promise<T>,
+): Promise<T> {
+  return withPrivateKubeconfig({}, async (kube) => {
+    const env = { ...gcloudEnv(), ...kube };
+    await runCliOkThrowing(
+      [
+        "gcloud",
+        "container",
+        "clusters",
+        "get-credentials",
+        t.cluster,
+        `--project=${t.projectId}`,
+        `--location=${t.location}`,
+      ],
+      env,
+    );
+    return body(env);
+  });
+}
+
 /** Tool names exposed by this connector — for contract/introspection tests. */
 export const GCP_TOOL_NAMES = [
   "gcp_cloud_run_service_list",
   "gcp_cloud_run_deploy",
   "gcp_gke_workload_restart",
+  "gcp_gke_workload_get",
 ] as const;
 
 export function registerGcpTools(
@@ -92,7 +130,7 @@ export function registerGcpTools(
       recoverable: true,
       scopeTargetOf: (p) => ({ kind: "project", value: p.projectId }),
     },
-    "Restart a GKE deployment rollout via kubectl (uses current cluster credentials).",
+    "Restart a GKE deployment rollout via kubectl, with cluster credentials fetched into a private kubeconfig (the owner's kubeconfig is never read or changed).",
     z.object({
       projectId: cliArg,
       location: cliArg,
@@ -101,23 +139,43 @@ export function registerGcpTools(
       deployment: cliArg,
     }),
     async (p) => {
-      await runCliOkThrowing(
-        [
-          "gcloud",
-          "container",
-          "clusters",
-          "get-credentials",
-          p.cluster,
-          `--project=${p.projectId}`,
-          `--zone=${p.location}`,
-        ],
-        gcloudEnv(),
-      );
-      await runCliOkThrowing(
-        ["kubectl", "rollout", "restart", "deployment", p.deployment, "-n", p.namespace],
-        gcloudEnv(),
+      await withGkeCredentials(p, (env) =>
+        runCliOkThrowing(
+          ["kubectl", "rollout", "restart", "deployment", p.deployment, "-n", p.namespace],
+          env,
+        ),
       );
       return jsonResult({ ok: true });
     },
   );
+
+  reg(
+    "gcp_gke_workload_get",
+    "Get one GKE deployment's state: {name, namespace, replicas, readyReplicas, generation, observedGeneration, restartedAt, images}. The before-state of gcp_gke_workload_restart; it takes the same arguments.",
+    z.object({
+      projectId: cliArg,
+      location: cliArg,
+      cluster: cliArg,
+      namespace: cliArg,
+      deployment: cliArg,
+    }),
+    async (p) => {
+      // NotFound is read from the kubectl step ONLY: a get-credentials failure ("cluster not found")
+      // is a different problem and must reach the caller as itself.
+      const data = await withGkeCredentials(p, async (env) => {
+        try {
+          return await runCliJsonThrowing(
+            ["kubectl", "get", "deployment", p.deployment, "-n", p.namespace, "-o", "json"],
+            env,
+          );
+        } catch (e) {
+          if (e instanceof Error && isKubectlNotFound(e.message)) {
+            throw new Error("deployment not found", { cause: e });
+          }
+          throw e;
+        }
+      });
+      return jsonResult(projectDeployment(data));
+    },
+  );
 }