@builder.io/ai-utils 0.67.0 → 0.69.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder.io/ai-utils",
-  "version": "0.67.0",
+  "version": "0.69.0",
   "description": "Builder.io AI utils",
   "files": [
     "src"

package/src/builder-config.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+/**
+ * Server-side view of the on-disk `builder.config.json` file, scoped to the
+ * fields the backend provisioning read path cares about (currently just
+ * `database`).
+ *
+ * This is intentionally a separate, parallel model from {@link FusionConfig}
+ * (codegen.ts), which is the dev-tools CLI's full view of the same file
+ * (parsed there as `Partial<FusionConfig>`). The two are different consumers:
+ * dev-tools owns launch/runtime config; this schema owns the server's
+ * database-provisioning read. `FusionConfig` has no `database` field, so this
+ * is additive rather than duplicative — keep new server-only config fields
+ * here and dev-tools/runtime fields on `FusionConfig`.
+ */
+export declare const BuilderConfigDatabaseSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"postgres">;
+    migrations: z.ZodLiteral<"drizzle">;
+    schemaDir: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export type BuilderConfigDatabase = z.infer<typeof BuilderConfigDatabaseSchema>;
+export declare const BuilderConfigSchema: z.ZodObject<{
+    database: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"postgres">;
+        migrations: z.ZodLiteral<"drizzle">;
+        schemaDir: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type BuilderConfig = z.infer<typeof BuilderConfigSchema>;

package/src/builder-config.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+/**
+ * Server-side view of the on-disk `builder.config.json` file, scoped to the
+ * fields the backend provisioning read path cares about (currently just
+ * `database`).
+ *
+ * This is intentionally a separate, parallel model from {@link FusionConfig}
+ * (codegen.ts), which is the dev-tools CLI's full view of the same file
+ * (parsed there as `Partial<FusionConfig>`). The two are different consumers:
+ * dev-tools owns launch/runtime config; this schema owns the server's
+ * database-provisioning read. `FusionConfig` has no `database` field, so this
+ * is additive rather than duplicative — keep new server-only config fields
+ * here and dev-tools/runtime fields on `FusionConfig`.
+ */
+export const BuilderConfigDatabaseSchema = z.object({
+    kind: z.literal("postgres"),
+    migrations: z.literal("drizzle"),
+    schemaDir: z.string().default("drizzle"),
+});
+export const BuilderConfigSchema = z.object({
+    database: BuilderConfigDatabaseSchema.optional(),
+});

package/src/codegen.d.ts

@@ -3993,7 +3993,7 @@ export interface FusionConfig {
     /** Whether this branch is for a code review - affects enabled agents and tools */
     branchType?: BranchType;
     /**
-     * When set, launch.ts hydrates `.builder/figma/<...>` from the corresponding
+     * When set, launch.ts hydrates `.builder/sources/<...>` from the corresponding
      * GCS frame manifest before the agent starts. Only used on
      * `branchType === "design-system-indexing"` branches.
      */

package/src/design-systems.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 export interface FigmaHydrationFile {
-    /** Relative path to write under `.builder/figma/`. */
+    /** Relative path to write under `.builder/sources/`. */
     localPath: string;
     downloadUrl: string;
     contentType: string;
@@ -24,7 +24,14 @@ export interface GenerateDesignSystemFormFields {
      * GUIDs are file-local, so they must be scoped per attachment.
      */
     selection?: Record<string, string[]>;
+    githubRepoUrl?: string;
 }
+/**
+ * Accepts `https://github.com/<owner>/<repo>` (optionally with a trailing
+ * `.git` or path segments). Used to gate the public-repo input on the
+ * `/design-systems/v1/generate` endpoint.
+ */
+export declare const GITHUB_REPO_URL_REGEX: RegExp;
 export interface GenerateDesignSystemRequest extends GenerateDesignSystemFormFields {
     /**
      * Mixed list of uploaded files in any order. Sent as repeated
@@ -41,6 +48,7 @@ export interface GenerateDesignSystemResponse {
      * resolved `branchName` / `branchUrl`.
      */
     jobId: string;
+    designSystemId: string;
 }
 export interface GenerateDesignSystemErrorResponse {
     error: string | Record<string, unknown>;
@@ -59,5 +67,6 @@ export declare const generateDesignSystemBodySchema: z.ZodObject<{
     projectName: z.ZodOptional<z.ZodString>;
     devToolsVersion: z.ZodOptional<z.ZodString>;
     selection: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>>;
+    githubRepoUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type GenerateDesignSystemBody = z.infer<typeof generateDesignSystemBodySchema>;

package/src/design-systems.js

@@ -1,4 +1,10 @@
 import { z } from "zod";
+/**
+ * Accepts `https://github.com/<owner>/<repo>` (optionally with a trailing
+ * `.git` or path segments). Used to gate the public-repo input on the
+ * `/design-systems/v1/generate` endpoint.
+ */
+export const GITHUB_REPO_URL_REGEX = /^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+(?:\.git)?\/?$/;
 export const GENERATE_DESIGN_SYSTEM_MAX_FILE_BYTES = 2 * 1024 * 1024 * 1024;
 export const GENERATE_DESIGN_SYSTEM_MAX_ATTACHMENTS = 50;
 export const GENERATE_DESIGN_SYSTEM_MIN_ATTACHMENTS = 1;
@@ -27,4 +33,9 @@ export const generateDesignSystemBodySchema = z.object({
         }
     }, z.record(z.string(), z.array(z.string().min(1)).max(10000)))
         .optional(),
+    githubRepoUrl: z
+        .string()
+        .trim()
+        .regex(GITHUB_REPO_URL_REGEX, "must be a public github.com repo URL")
+        .optional(),
 });

package/src/events.d.ts

@@ -528,7 +528,7 @@ export declare const ReviewSubmittedV1: {
     eventName: "review.submitted";
     version: "1";
 };
-export type BotMentionExternalPrV1 = FusionEventVariant<"bot.mention.external-pr", {
+export type BotMentionGitHubExternalPrV1 = FusionEventVariant<"bot.mention.external-pr", {
     projectId: string;
     repoFullName: string;
     prNumber: number;
@@ -554,10 +554,148 @@ export type BotMentionExternalPrV1 = FusionEventVariant<"bot.mention.external-pr
 }, {
     projectId: string;
 }, 1>;
-export declare const BotMentionExternalPrV1: {
+export declare const BotMentionGitHubExternalPrV1: {
     eventName: "bot.mention.external-pr";
     version: "1";
 };
+/**
+ * Common fields shared by all four bot-mention PR events.
+ *
+ * Extracting this base makes the future consolidation into a single
+ * `bot.mention.pr` event straightforward: the unified type will be
+ * `BaseBotMentionEventData & { provider: ..., ...providerSpecificOptionals }`.
+ */
+export type BaseBotMentionEventData = {
+    /** Fusion project ID resolved from PR metadata */
+    projectId: string;
+    /** Fusion branch name resolved from PR metadata */
+    branchName: string;
+    /** Raw comment body that triggered the bot mention */
+    comment: string;
+    commentLink?: string;
+    /** Dedup lock key — composite of comment ID and delivery ID */
+    commentIdStr: string;
+    userName?: string;
+    /** Provider-specific user ID as string (for credits / analytics) */
+    gitUserId?: string;
+    /** Commenter email when available from the provider (preferred for user resolution) */
+    userEmail?: string;
+    /** Original webhook delivery ID — passed through for logging */
+    webhookEventId: string;
+};
+/**
+ * Emitted when @builderio-bot is mentioned on a Fusion (internal) GitHub PR comment.
+ * Pre-flight checks (project existence, installation token, GitHub App rights) have
+ * already passed before this event is published. The heavy work — container
+ * provisioning and AI processing — is handled asynchronously by the subscriber.
+ */
+export type BotMentionGitHubInternalPrV1 = FusionEventVariant<"bot.mention.github-internal-pr", BaseBotMentionEventData & {
+    provider: "github";
+    repoFullName: string;
+    prNumber: number;
+    /** Numeric GitHub comment ID (for reaction / reply threading) */
+    commentNumericId?: number;
+    commentType: "issue" | "pr";
+    /** GitHub Enterprise hostname, if applicable */
+    hostname?: string;
+    /** For review comments: the comment being replied to */
+    inReplyToCommentId?: number;
+    /** For review comments: unified diff context */
+    diffHunk?: string;
+    /** For review comments: file path */
+    filePath?: string;
+    /** For review comments: first line of the comment range */
+    startLine?: number;
+    /** For review comments: last line of the comment range */
+    endLine?: number;
+    /** For review comments: reply target comment ID */
+    replyToCommentId?: number;
+}, {
+    projectId: string;
+}, 1>;
+export declare const BotMentionGitHubInternalPrV1: {
+    eventName: "bot.mention.github-internal-pr";
+    version: "1";
+};
+/**
+ * Emitted when @builderio-bot is mentioned on a GitLab MR comment.
+ * Pre-flight checks have already passed before this event is published.
+ * Container provisioning and AI processing happen asynchronously in the subscriber.
+ */
+export type BotMentionGitLabPrV1 = FusionEventVariant<"bot.mention.gitlab-pr", BaseBotMentionEventData & {
+    provider: "gitlab";
+    /** GitLab numeric project ID (needed to re-fetch token and post comments) */
+    gitlabProjectId: number;
+    /** GitLab MR IID */
+    mrId: number;
+    /**
+     * Thread discussion ID for threaded replies.
+     * GitLab sends this as a hex SHA string (e.g. "6a9c1750b37d..."),
+     * not a number — used only in URL interpolation.
+     */
+    discussionId?: string;
+    /** GitLab Enterprise hostname, if applicable */
+    hostname?: string;
+}, {
+    projectId: string;
+}, 1>;
+export declare const BotMentionGitLabPrV1: {
+    eventName: "bot.mention.gitlab-pr";
+    version: "1";
+};
+/**
+ * Emitted when @builderio-bot is mentioned on a Bitbucket PR comment.
+ * Pre-flight checks have already passed before this event is published.
+ */
+export type BotMentionBitbucketPrV1 = FusionEventVariant<"bot.mention.bitbucket-pr", BaseBotMentionEventData & {
+    provider: "bitbucket";
+    /** e.g. "workspace/repo" */
+    repositorySlug: string;
+    workspace?: string;
+    pullRequestId: number;
+    /** Numeric Bitbucket comment ID — used as parentCommentId for reply threading */
+    parentCommentId?: number;
+    /** PR browser URL (links.html.href from the pullrequest payload) */
+    pullRequestUrl?: string;
+    /** PR title from the pullrequest payload */
+    pullRequestTitle?: string;
+    /** PR description from the pullrequest payload */
+    pullRequestDescription?: string;
+}, {
+    projectId: string;
+}, 1>;
+export declare const BotMentionBitbucketPrV1: {
+    eventName: "bot.mention.bitbucket-pr";
+    version: "1";
+};
+/**
+ * Emitted when @builderio-bot is mentioned on an Azure DevOps PR comment.
+ * Pre-flight checks have already passed before this event is published.
+ */
+export type BotMentionAzurePrV1 = FusionEventVariant<"bot.mention.azure-pr", BaseBotMentionEventData & {
+    provider: "azure";
+    azureOrg: string;
+    azureProject: string;
+    pullRequestId: number;
+    /** Repository ID extracted from comment links */
+    repositoryId: string;
+    /** Thread link URL — used for reply threading and thread context */
+    threadLink: string;
+    /**
+     * The actual Azure DevOps REST URL of the pull request
+     * (event.resource.url or pullRequest.url from the webhook payload).
+     * Distinct from commentLink which is the comment resource URL.
+     */
+    pullRequestUrl?: string;
+    /** PR description from the pullrequest payload */
+    pullRequestDescription?: string;
+}, {
+    projectId: string;
+}, 1>;
+export declare const BotMentionAzurePrV1: {
+    eventName: "bot.mention.azure-pr";
+    version: "1";
+};
 export type ClientDevtoolsSessionStartedEvent = FusionEventVariant<"client.devtools.session.started", {
     sessionId?: string;
     sessionType?: string;
@@ -914,7 +1052,21 @@ export type FigmaDecodeJobV1 = FusionEventVariant<"figma.decode.job", {
         mimetype: string;
         size: number;
     }>;
+    /**
+     * Optional public GitHub repo URL to include as supplementary context.
+     * Recorded in the frame manifest; the container shallow-clones it into
+     * `.builder/sources/<repo>/` at hydration time.
+     */
+    githubRepoUrl?: string;
     devToolsVersion?: string;
+    /**
+     * Optional map of `.fig` filename → page/frame GUID keys
+     * (`"sessionID:localID"`) to restrict extraction to. When a filename is
+     * present, only the listed pages/frames are decoded into the manifest;
+     * filenames absent from the map are processed in full. GUIDs are
+     * file-local, so they must be scoped per attachment.
+     */
+    selection?: Record<string, string[]>;
 }, {}, 1>;
 export declare const FigmaDecodeJobV1: {
     eventName: "figma.decode.job";
@@ -948,16 +1100,36 @@ export interface FigmaFrameManifestEntry {
 export interface FigmaFrameAsset {
     /** Bucket-relative GCS path. */
     gcsPath: string;
-    /** Relative path under `.builder/figma/` (e.g. `images/abc123.png`). */
+    /** Relative path under `.builder/sources/figma/` (e.g. `images/abc123.png`). */
     localPath: string;
     contentType: string;
 }
+/**
+ * A plain-text / markdown attachment uploaded alongside the `.fig` files.
+ */
+export interface FigmaTextSource {
+    /** Relative path under `.builder/sources/` (e.g. `brand-guidelines.md`). */
+    localPath: string;
+    gcsPath: string;
+    originalName: string;
+    contentType: string;
+    sizeBytes: number;
+}
+export interface FigmaGithubRepoSource {
+    url: string;
+    /** Directory name under `.builder/sources/` to clone into. */
+    localDir: string;
+}
 export interface FigmaFrameManifest {
     jobId: string;
     figmaName: string;
     frames: FigmaFrameManifestEntry[];
     /** Raster assets referenced by frame HTML via relative `images/…` URLs. */
     assets?: FigmaFrameAsset[];
+    /** Uploaded plain-text / markdown supplementary sources. */
+    textSources?: FigmaTextSource[];
+    /** Optional public GitHub repo to clone as supplementary context. */
+    githubRepo?: FigmaGithubRepoSource;
 }
 export type PrReviewRequestedV1 = FusionEventVariant<"pr.review.requested", {
     repoFullName: string;
@@ -1030,7 +1202,7 @@ export declare const ClientDevtoolsToolResultV1: {
     eventName: "client.devtools.tool.result";
     version: "1";
 };
-export type FusionEvent = ClientDevtoolsSessionStartedEvent | ClientDevtoolsSessionIdleEventV1 | ClientDevtoolsToolCallRequestV1 | ClientDevtoolsToolCallV1 | ClientDevtoolsToolResultV1 | FusionProjectCreatedV1 | SetupAgentCompletedV1 | GitPrMergedV1 | GitPrCreatedV1 | GitPrClosedV1 | ForceSetupAgentV1 | ClawMessageSentV1 | CodegenCompletionV1 | CodegenUserPromptV1 | GitWebhooksRegisterV1 | FusionProjectSettingsUpdatedV1 | VideoRecordingCompletedV1 | TimelineRecordingReadyV1 | FusionBranchCreatedV1 | FusionContainerStartedV1 | FusionContainerFailedV1 | FusionBranchFailedV1 | BotMentionExternalPrV1 | ReviewSubmittedV1 | PrReviewRequestedV1 | FigmaDecodeJobV1 | ProjectSnapshotRefreshV1 | ProjectSnapshotCapturedV1 | ProjectSnapshotCreatedV1 | ProjectSnapshotFailedV1 | ProjectSnapshotReadyCheckV1 | ProjectSnapshotPodWatchV1;
+export type FusionEvent = ClientDevtoolsSessionStartedEvent | ClientDevtoolsSessionIdleEventV1 | ClientDevtoolsToolCallRequestV1 | ClientDevtoolsToolCallV1 | ClientDevtoolsToolResultV1 | FusionProjectCreatedV1 | SetupAgentCompletedV1 | GitPrMergedV1 | GitPrCreatedV1 | GitPrClosedV1 | ForceSetupAgentV1 | ClawMessageSentV1 | CodegenCompletionV1 | CodegenUserPromptV1 | GitWebhooksRegisterV1 | FusionProjectSettingsUpdatedV1 | VideoRecordingCompletedV1 | TimelineRecordingReadyV1 | FusionBranchCreatedV1 | FusionContainerStartedV1 | FusionContainerFailedV1 | FusionBranchFailedV1 | BotMentionGitHubExternalPrV1 | BotMentionGitHubInternalPrV1 | BotMentionGitLabPrV1 | BotMentionBitbucketPrV1 | BotMentionAzurePrV1 | ReviewSubmittedV1 | PrReviewRequestedV1 | FigmaDecodeJobV1 | ProjectSnapshotRefreshV1 | ProjectSnapshotCapturedV1 | ProjectSnapshotCreatedV1 | ProjectSnapshotFailedV1 | ProjectSnapshotReadyCheckV1 | ProjectSnapshotPodWatchV1;
 export interface ModelPermissionRequiredEvent {
     type: "assistant.model.permission.required";
     data: {

package/src/events.js

@@ -14,10 +14,26 @@ export const ReviewSubmittedV1 = {
     eventName: "review.submitted",
     version: "1",
 };
-export const BotMentionExternalPrV1 = {
+export const BotMentionGitHubExternalPrV1 = {
     eventName: "bot.mention.external-pr",
     version: "1",
 };
+export const BotMentionGitHubInternalPrV1 = {
+    eventName: "bot.mention.github-internal-pr",
+    version: "1",
+};
+export const BotMentionGitLabPrV1 = {
+    eventName: "bot.mention.gitlab-pr",
+    version: "1",
+};
+export const BotMentionBitbucketPrV1 = {
+    eventName: "bot.mention.bitbucket-pr",
+    version: "1",
+};
+export const BotMentionAzurePrV1 = {
+    eventName: "bot.mention.azure-pr",
+    version: "1",
+};
 export const ClientDevtoolsSessionStartedEvent = {
     eventName: "client.devtools.session.started",
     version: "1",

package/src/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./builder-config.js";
 export * from "./completion.js";
 export * from "./events.js";
 export * from "./messages.js";

package/src/index.js

@@ -1,3 +1,4 @@
+export * from "./builder-config.js";
 export * from "./completion.js";
 export * from "./events.js";
 export * from "./messages.js";

package/src/organization.d.ts

@@ -70,6 +70,7 @@ interface OrganizationSettings {
     enableModelValidationHooks?: boolean;
     enableOrgInsights?: boolean;
     enableBuilderHosting?: boolean;
+    enableFusionHosting?: boolean;
     allowLegacyPlanSubscriptions?: boolean;
     enforceMaxUsers?: boolean;
     ssoRestrictedMode?: boolean;

package/src/projects.d.ts

@@ -435,7 +435,7 @@ export interface OrgAgentConfig {
     enabledTools: string[];
     longLived: boolean;
 }
-export type BranchType = "code-review" | "setup-project" | "org-agent" | "snapshot-build" | "design-system-indexing" | "default";
+export type BranchType = "code-review" | "setup-project" | "org-agent" | "snapshot-build" | "design-system-indexing" | "deploy" | "default";
 /** Category of work a branch represents, auto-assigned during prompt analysis. */
 export type BranchCategory = "feature" | "fix" | "research" | "other";
 export interface BranchSharedData {
@@ -526,6 +526,7 @@ export interface BranchSharedData {
     lastReviewId?: string | null;
     /** Timestamp of the last PR review */
     lastReviewAt?: number | null;
+    database?: BranchDatabase;
 }
 /**
  * fields that are required in the new branch format, but optional in the legacy branch format.
@@ -864,9 +865,53 @@ export interface Project {
     userInitiatedAutoSetup?: boolean;
     /** When true, automatically apply verified setup configuration when the setup agent completes */
     autoApplySetup?: boolean;
-    /** Settings related to Fusion fist class hosting */
+    /** Settings related to Fusion first class hosting */
     hosting?: ProjectHosting;
+    database?: ProjectDatabase;
 }
+export interface ProjectDatabase {
+    ownerId: string;
+    neonOrgId: string;
+    neonOrgTier: "free" | "paid";
+    neonProjectId: string;
+    mainBranchId: string;
+    mainEndpointHost: string;
+    mainEndpointPoolerHost: string;
+    role: string;
+    /** @internal Plaintext credential — Firestore IAM enforces access. Never serialize to client responses. */
+    password: string;
+    region: string;
+    createdAt: number;
+    createdBy: string;
+    lastActivityAt: number;
+}
+export interface BranchDatabase {
+    ownerId: string;
+    projectId: string;
+    neonProjectId: string;
+    neonBranchId: string;
+    endpointHost: string;
+    endpointPoolerHost: string;
+    createdAt: number;
+    createdBy: string;
+}
+interface DatabaseDeletionBase {
+    id: string;
+    ownerId: string;
+    projectId: string;
+    neonProjectId: string;
+    pendingDeleteAt: number;
+    createdAt: number;
+    createdBy: string;
+    reason?: string;
+}
+export type DatabaseDeletion = (DatabaseDeletionBase & {
+    neonBranchId: string;
+    neonProjectAllBranches?: never;
+}) | (DatabaseDeletionBase & {
+    neonBranchId?: never;
+    neonProjectAllBranches: true;
+});
 /**
  * Get the state of a branch, checking `state` first and falling back to `deleted` for backwards compatibility.
  */
@@ -1221,9 +1266,13 @@ export interface ShouldDeletePodResponse {
  * - deploying  — queue handler is pushing artifacts to Netlify + updating Envoy HTTPRoute
  * - live       — terminal: site is serving traffic
  * - failed     — terminal: see `error` for the one-line reason
+ * - canceled   — terminal: a concurrent unpublish (or an expired-lock takeover by a
+ *                newer deploy) stole the lock, and this deploy aborted at a fencing
+ *                gate before going live — see "Concurrency & Locking" in the spec
  */
 export declare const DeployStatusSchema: z.ZodEnum<{
     building: "building";
+    canceled: "canceled";
     deploying: "deploying";
     failed: "failed";
     live: "live";
@@ -1249,17 +1298,27 @@ export declare const ProjectHostingSchema: z.ZodObject<{
         buildCommand: z.ZodOptional<z.ZodString>;
         nodeVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
-    environment: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        key: z.ZodString;
-        value: z.ZodString;
-        isSecret: z.ZodBoolean;
-        placeholder: z.ZodOptional<z.ZodBoolean>;
-        explanation: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>>;
+    environment: z.ZodOptional<z.ZodObject<{
+        build: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            value: z.ZodString;
+            isSecret: z.ZodBoolean;
+            placeholder: z.ZodOptional<z.ZodBoolean>;
+            explanation: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        prod: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            value: z.ZodString;
+            isSecret: z.ZodBoolean;
+            placeholder: z.ZodOptional<z.ZodBoolean>;
+            explanation: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
     lastDeployId: z.ZodOptional<z.ZodString>;
     lastDeployAt: z.ZodOptional<z.ZodNumber>;
     lastDeployStatus: z.ZodOptional<z.ZodEnum<{
         building: "building";
+        canceled: "canceled";
         deploying: "deploying";
         failed: "failed";
         live: "live";
@@ -1280,8 +1339,10 @@ export declare const DeploySchema: z.ZodObject<{
     ownerId: z.ZodString;
     checkoutBranch: z.ZodOptional<z.ZodString>;
     deployBranchId: z.ZodOptional<z.ZodString>;
+    devBranchId: z.ZodOptional<z.ZodString>;
     status: z.ZodEnum<{
         building: "building";
+        canceled: "canceled";
         deploying: "deploying";
         failed: "failed";
         live: "live";
@@ -1314,4 +1375,60 @@ export declare const HostingSlugSchema: z.ZodObject<{
     createdBy: z.ZodString;
 }, z.core.$strip>;
 export type HostingSlug = z.infer<typeof HostingSlugSchema>;
+/**
+ * Deploy lease lock with fencing token, stored at
+ * `hosting-locks/{projectId}__{checkoutBranch}` (the key uses the resolved ref
+ * string, not a branchId, because `main` has no backing fusion-branch doc in PRs
+ * mode).
+ *
+ * Serializes deploys per `(projectId, checkoutBranch)` and lets unpublish preempt an
+ * in-flight deploy. Created by the `POST /projects/deploy` acquire transaction,
+ * force-stolen by `DELETE /projects/hosting`, and deleted on any terminal deploy
+ * state (`live` / `failed` / `canceled`) or after unpublish teardown. A crashed
+ * holder's lock is reclaimed lazily via `expiresAt` rather than auto-released.
+ */
+export declare const HostingLockSchema: z.ZodObject<{
+    ownerId: z.ZodString;
+    holderId: z.ZodString;
+    holderKind: z.ZodEnum<{
+        deploy: "deploy";
+        unpublish: "unpublish";
+    }>;
+    deployId: z.ZodOptional<z.ZodString>;
+    acquiredAt: z.ZodNumber;
+    expiresAt: z.ZodNumber;
+}, z.core.$strip>;
+export type HostingLock = z.infer<typeof HostingLockSchema>;
+/**
+ * Response item for `GET /projects/deploys`. The same shape backs both the deploy
+ * history list and the single-deploy poll, so the frontend can render both with one
+ * renderer.
+ */
+export declare const DeployListItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodEnum<{
+        building: "building";
+        canceled: "canceled";
+        deploying: "deploying";
+        failed: "failed";
+        live: "live";
+        queued: "queued";
+        uploading: "uploading";
+    }>;
+    url: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodNumber;
+    completedAt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type DeployListItem = z.infer<typeof DeployListItemSchema>;
+/**
+ * Shape of the `manifest.json` the deploy pod uploads to GCS alongside
+ * `artifact.tar.gz`. Modeled on Netlify's deploy file map: static files are hashed
+ * with sha1, serverless functions with sha256 (per Netlify's contract).
+ */
+export declare const DeployArtifactManifestSchema: z.ZodObject<{
+    files: z.ZodRecord<z.ZodString, z.ZodString>;
+    functions: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strip>;
+export type DeployArtifactManifest = z.infer<typeof DeployArtifactManifestSchema>;
 export {};

package/src/projects.js

@@ -180,6 +180,9 @@ export function parseExitPlanMode(chunk) {
  * - deploying  — queue handler is pushing artifacts to Netlify + updating Envoy HTTPRoute
  * - live       — terminal: site is serving traffic
  * - failed     — terminal: see `error` for the one-line reason
+ * - canceled   — terminal: a concurrent unpublish (or an expired-lock takeover by a
+ *                newer deploy) stole the lock, and this deploy aborted at a fencing
+ *                gate before going live — see "Concurrency & Locking" in the spec
  */
 export const DeployStatusSchema = z.enum([
     "queued",
@@ -188,6 +191,7 @@ export const DeployStatusSchema = z.enum([
     "deploying",
     "live",
     "failed",
+    "canceled",
 ]);
 export const ProjectHostingBuildConfigSchema = z.object({
     buildCommand: z.string().optional(),
@@ -222,9 +226,16 @@ export const ProjectHostingSchema = z.object({
      * plaintext in Firestore, masked on the read path before responses leave ai-services
      * (see "Secret handling" in the hosting spec).
      */
-    environment: z.array(EnvironmentVariableSchema).optional().meta({
-        description: "Production environment variables set when we deploy",
-    }),
+    environment: z
+        .object({
+        build: z.array(EnvironmentVariableSchema).optional().meta({
+            description: "Env vars available to the build itself",
+        }),
+        prod: z.array(EnvironmentVariableSchema).optional().meta({
+            description: "Env vars for the production deploy served via Netlify",
+        }),
+    })
+        .optional(),
     lastDeployId: z.string().optional(),
     lastDeployAt: z.number().optional(),
     lastDeployStatus: DeployStatusSchema.optional(),
@@ -250,13 +261,11 @@ export const DeploySchema = z.object({
             "for row 2 in v2). This is the value passed as `checkoutBranch` when the " +
             "deploy pod was created.",
     }),
-    deployBranchId: z
-        .string()
-        .optional()
-        .meta({
-        description: 'ID of the ephemeral hidden deploy branch (`type: "deploy"`) that ran the ' +
-            "build. Cleared after the pod terminates so historical Deploy docs don't " +
-            "hold references to garbage-collected branch state.",
+    deployBranchId: z.string().optional().meta({
+        description: 'Fusion branch id of the ephemeral hidden deploy branch (`type: "deploy"`) that ran the build.',
+    }),
+    devBranchId: z.string().optional().meta({
+        description: "Fusion dev branch's id (unset if we are deploying project default branch)",
     }),
     status: DeployStatusSchema,
     netlifyDeployId: z.string().optional(),
@@ -289,3 +298,55 @@ export const HostingSlugSchema = z.object({
         description: "user ID of the user who first clicked Publish on the project",
     }),
 });
+/**
+ * Deploy lease lock with fencing token, stored at
+ * `hosting-locks/{projectId}__{checkoutBranch}` (the key uses the resolved ref
+ * string, not a branchId, because `main` has no backing fusion-branch doc in PRs
+ * mode).
+ *
+ * Serializes deploys per `(projectId, checkoutBranch)` and lets unpublish preempt an
+ * in-flight deploy. Created by the `POST /projects/deploy` acquire transaction,
+ * force-stolen by `DELETE /projects/hosting`, and deleted on any terminal deploy
+ * state (`live` / `failed` / `canceled`) or after unpublish teardown. A crashed
+ * holder's lock is reclaimed lazily via `expiresAt` rather than auto-released.
+ */
+export const HostingLockSchema = z.object({
+    ownerId: z.string(),
+    holderId: z.string().meta({
+        description: "unique per acquisition (the fencing token); == deployId for a deploy holder",
+    }),
+    holderKind: z.enum(["deploy", "unpublish"]),
+    deployId: z.string().optional().meta({
+        description: 'set when holderKind === "deploy"',
+    }),
+    acquiredAt: z.number().meta({ description: "unix time (ms)" }),
+    expiresAt: z.number().meta({
+        description: "acquiredAt + 15min (same ceiling as the deploy lazy-timeout)",
+    }),
+});
+/**
+ * Response item for `GET /projects/deploys`. The same shape backs both the deploy
+ * history list and the single-deploy poll, so the frontend can render both with one
+ * renderer.
+ */
+export const DeployListItemSchema = DeploySchema.pick({
+    id: true,
+    status: true,
+    url: true,
+    createdAt: true,
+    completedAt: true,
+    error: true,
+}).meta({ title: "DeployListItem" });
+/**
+ * Shape of the `manifest.json` the deploy pod uploads to GCS alongside
+ * `artifact.tar.gz`. Modeled on Netlify's deploy file map: static files are hashed
+ * with sha1, serverless functions with sha256 (per Netlify's contract).
+ */
+export const DeployArtifactManifestSchema = z.object({
+    files: z.record(z.string(), z.string()).meta({
+        description: "static file path → sha1 hash",
+    }),
+    functions: z.record(z.string(), z.string()).meta({
+        description: "serverless function name → sha256 hash",
+    }),
+});