@builder.io/ai-utils 0.68.0 → 0.69.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder.io/ai-utils",
-  "version": "0.68.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

@@ -1052,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";
@@ -1086,9 +1100,25 @@ 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;
@@ -1096,6 +1126,10 @@ export interface FigmaFrameManifest {
     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;

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",
+    }),
+});