@cursor/july 0.1.62 → 0.1.73

package/src/internal/deploy-manifest.ts

@@ -0,0 +1,161 @@
+/**
+ * Offline deploy manifest (workstream Wd of
+ * `docs/agent-serve/agent-sdk-event-ingress-plan.md`, Wd-0/Wd-1).
+ *
+ * The manifest is every piece of deployment metadata that is statically
+ * derivable from the agent project — extracted at build/deploy time, with no
+ * VM, no engine, and no network — so the control plane can store it before
+ * any pod starts and keep answering metadata questions while a deployment is
+ * offline or hibernated.
+ *
+ * Two layers with different stability contracts:
+ *
+ * - `declarations` is the **versioned wire contract** consumed by the
+ *   control plane (Wd-2): per-channel event capabilities, egress domains,
+ *   and public route paths. Validated by {@link agentDeployManifestV1Schema};
+ *   the CP stores these as columns / column views. Repos are deliberately
+ *   NOT here — which repos a deployment watches is per-instance deploy
+ *   configuration, not a property of the code.
+ * - `info` is the full static project description — the same payload the
+ *   engine serves at `GET /v1/info` (`projectInfo`). Stored opaquely by the
+ *   CP so `/v1/info`-class reads can be served for offline deployments
+ *   (Wd-5). Its shape evolves with the SDK and is intentionally not pinned
+ *   by the wire schema beyond "is an object".
+ *
+ * Event derivation note: each mounted channel publishes its event set in its
+ * own `channels[].eventTypes` declaration. A project with no GitHub channel
+ * subscribes to no GitHub events, regardless of configured repository scope.
+ * Keep that capability per-channel: do not reintroduce a provider-wide event
+ * union for control-plane consumers.
+ */
+
+import { z } from "zod";
+import { isPublicEndpointPolicy } from "../channels.js";
+import { isCursorHostedStorage } from "../storage-backends/cursor-hosted.js";
+import type { AgentProject, AgentProjectInfo } from "../types.js";
+import { projectInfo } from "./discovery.js";
+import { packageVersion } from "./distribution.js";
+
+export const DEPLOY_MANIFEST_VERSION: 1 = 1;
+
+/**
+ * Versioned wire contract for the CP-consumed declaration fields. Kept
+ * module-private (the package builds with isolated declarations); consumers
+ * use {@link parseAgentDeployManifest} and the explicit interfaces below.
+ */
+const agentDeployManifestV1Schema = z.object({
+  manifestVersion: z.literal(DEPLOY_MANIFEST_VERSION),
+  generatedAtMs: z.number().int().nonnegative(),
+  cliVersion: z.string().min(1),
+  declarations: z.object({
+    egressDomains: z.array(z.string().min(1)).max(64),
+    publicRoutePaths: z.array(z.string().min(1)).max(64),
+    frameworkStorage: z.enum(["cursor-hosted", "other", "none"]).optional(),
+    channels: z
+      .array(
+        z.object({
+          id: z.string().min(1).max(128),
+          kind: z.string().min(1).max(32).optional(),
+          eventTypes: z.array(z.string().min(1).max(64)).max(64).optional(),
+        })
+      )
+      .max(64),
+  }),
+  // Full `projectInfo` payload — opaque to the wire contract.
+  info: z.record(z.unknown()),
+});
+
+export interface AgentDeployManifestDeclarations {
+  egressDomains: string[];
+  publicRoutePaths: string[];
+  /** Where this runtime mirrors framework-owned sessions and event chunks. */
+  frameworkStorage?: "cursor-hosted" | "other" | "none";
+  /**
+   * Mounted channels with their kinds and per-channel event capability.
+   * Scope keys are installation config and are never extracted here.
+   * Continuation is opt-in: without a deterministic selector key, every
+   * inbound event starts a fresh session. Selector encoding remains open.
+   */
+  channels: Array<{ id: string; kind?: string; eventTypes?: string[] }>;
+}
+
+export interface AgentDeployManifestV1 {
+  manifestVersion: 1;
+  /** Unix ms at extraction. */
+  generatedAtMs: number;
+  /** `@cursor/july` version that produced the manifest. */
+  cliVersion: string;
+  declarations: AgentDeployManifestDeclarations;
+  /**
+   * Full `projectInfo` payload (see `GET /v1/info`). Opaque to the wire
+   * contract; the CP stores it verbatim.
+   */
+  info: AgentProjectInfo;
+}
+
+/**
+ * Extract the offline deploy manifest from a loaded project. Pure: no
+ * network, no filesystem beyond what `loadAgentProject` already read.
+ */
+export function buildAgentDeployManifest(
+  project: AgentProject,
+  options?: { nowMs?: number; cliVersion?: string }
+): AgentDeployManifestV1 {
+  const channels = project.channels.map((channel) => {
+    const kind = channel.definition.meta?.kind;
+    const githubEvents = channel.definition.meta?.githubWebhookEvents;
+    const originEvents = channel.definition.meta?.originWebhookEvents;
+    const eventTypes =
+      githubEvents !== undefined
+        ? [...githubEvents].sort()
+        : originEvents !== undefined
+          ? [...originEvents].sort()
+          : undefined;
+    return {
+      id: channel.id,
+      kind,
+      eventTypes,
+    };
+  });
+
+  // Same mapping as `july deploy` (cli-deploy.ts): channels declared public
+  // via `publicEndpoint()` become alias-token-free route prefixes.
+  const publicRoutePaths = project.channels
+    .filter((channel) =>
+      (channel.definition.auth ?? []).some(isPublicEndpointPolicy)
+    )
+    .map((channel) => `/v1/channels/${channel.id}`);
+
+  return {
+    manifestVersion: DEPLOY_MANIFEST_VERSION,
+    generatedAtMs: options?.nowMs ?? Date.now(),
+    cliVersion: options?.cliVersion ?? packageVersion(),
+    declarations: {
+      egressDomains: [...(project.agent.hosting?.egressDomains ?? [])],
+      publicRoutePaths,
+      frameworkStorage:
+        project.storage === undefined
+          ? "none"
+          : isCursorHostedStorage(project.storage)
+            ? "cursor-hosted"
+            : "other",
+      channels,
+    },
+    info: projectInfo(project),
+  };
+}
+
+/**
+ * Parse an untrusted manifest (round-trip check for the CLI's own output;
+ * the CP re-validates server-side with its own copy of the contract).
+ */
+export function parseAgentDeployManifest(
+  raw: unknown
+): AgentDeployManifestV1 | undefined {
+  const parsed = agentDeployManifestV1Schema.safeParse(raw);
+  // `info` is opaque to the wire schema (validated as a plain object) but
+  // typed as AgentProjectInfo for producers/consumers inside the SDK.
+  return parsed.success
+    ? (parsed.data as unknown as AgentDeployManifestV1)
+    : undefined;
+}