@builder.io/ai-utils 0.64.0 → 0.66.0

package/package.json

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

package/src/codegen.d.ts

@@ -2,7 +2,8 @@ import { z } from "zod";
 import type { Options as PrettierOptions } from "prettier";
 import type { Attachment, ContentMessageItemToolResult } from "./messages";
 import type { BuilderContent } from "./completion";
-import type { ForcedBackup, SetupDependency, GitDiagnostics } from "./projects";
+import { type EnvironmentVariable, type SetupDependency } from "./common-schemas";
+import type { ForcedBackup, GitDiagnostics } from "./projects";
 import type { Feature } from "./features";
 import type { CpuKind, BranchType } from "./projects";
 export declare const GitSnapshotSchema: z.ZodString;
@@ -816,14 +817,6 @@ export declare const ExitToolInputSchema: z.ZodObject<{
     projectDescription: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ExitToolInput = z.infer<typeof ExitToolInputSchema>;
-export declare const EnvironmentVariableSchema: z.ZodObject<{
-    key: z.ZodString;
-    value: z.ZodString;
-    isSecret: z.ZodBoolean;
-    placeholder: z.ZodOptional<z.ZodBoolean>;
-    explanation: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export type EnvironmentVariable = z.infer<typeof EnvironmentVariableSchema>;
 export declare const ProposedConfigSchema: z.ZodObject<{
     id: z.ZodString;
     projectId: z.ZodString;

package/src/codegen.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { AttachmentSchema, ContentMessageItemToolResultSchema, } from "./messages";
 import { UserContextSchema } from "./mapping";
-import { SetupDependencySchema } from "./projects";
+import { EnvironmentVariableSchema, SetupDependencySchema, } from "./common-schemas";
 export const GitSnapshotSchema = z.string().meta({
     title: "GitSnapshot",
     description: "Multi-repo git snapshot. Format: 'folder:hash,folder:hash' " +
@@ -906,19 +906,6 @@ const ProposedQuestionSchema = z.object({
         .meta({ description: "Placeholder text for text-type questions" }),
     options: z.array(LabelOptionSchema).optional(),
 });
-export const EnvironmentVariableSchema = z
-    .object({
-    key: z.string(),
-    value: z.string(),
-    isSecret: z.boolean(),
-    placeholder: z.boolean().optional().meta({
-        description: "If true, indicates this is a placeholder value that needs user replacement",
-    }),
-    explanation: z.string().optional().meta({
-        description: "Explanation of why this env var is needed and what value the user should provide",
-    }),
-})
-    .meta({ title: "EnvironmentVariable" });
 const ProposedConfigurationSchema = z.object({
     setupCommand: z.object({
         value: z.string().optional(),

package/src/common-schemas.d.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+export declare const EnvironmentVariableSchema: z.ZodObject<{
+    key: z.ZodString;
+    value: z.ZodString;
+    isSecret: z.ZodBoolean;
+    placeholder: z.ZodOptional<z.ZodBoolean>;
+    explanation: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type EnvironmentVariable = z.infer<typeof EnvironmentVariableSchema>;
+export declare const SetupMiseDependencySchema: z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodLiteral<"mise">;
+    tool: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SetupMiseDependency = z.infer<typeof SetupMiseDependencySchema>;
+export declare const SetupScriptDependencySchema: z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodLiteral<"script">;
+    name: z.ZodString;
+    script: z.ZodString;
+}, z.core.$strip>;
+export type SetupScriptDependency = z.infer<typeof SetupScriptDependencySchema>;
+export declare const SetupDependencySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodLiteral<"mise">;
+    tool: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodLiteral<"script">;
+    name: z.ZodString;
+    script: z.ZodString;
+}, z.core.$strip>], "type">;
+export type SetupDependency = z.infer<typeof SetupDependencySchema>;

package/src/common-schemas.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+// ============================================================================
+// Shared leaf schemas
+//
+// These schemas defined here to break runtime dependency cycle which would
+// surface as "Cannot access '<Schema>' before initialization" depending on
+// evaluation order. Keep this module dependency-free (zod only).
+// ============================================================================
+export const EnvironmentVariableSchema = z
+    .object({
+    key: z.string(),
+    value: z.string(),
+    isSecret: z.boolean(),
+    placeholder: z.boolean().optional().meta({
+        description: "If true, indicates this is a placeholder value that needs user replacement",
+    }),
+    explanation: z.string().optional().meta({
+        description: "Explanation of why this env var is needed and what value the user should provide",
+    }),
+})
+    .meta({ title: "EnvironmentVariable" });
+export const SetupMiseDependencySchema = z
+    .object({
+    key: z.string(),
+    type: z.literal("mise"),
+    tool: z.string(),
+    version: z.string().optional(),
+})
+    .meta({ title: "SetupMiseDependency" });
+export const SetupScriptDependencySchema = z
+    .object({
+    key: z.string(),
+    type: z.literal("script"),
+    name: z.string(),
+    script: z.string(),
+})
+    .meta({ title: "SetupScriptDependency" });
+export const SetupDependencySchema = z
+    .discriminatedUnion("type", [
+    SetupMiseDependencySchema,
+    SetupScriptDependencySchema,
+])
+    .meta({ title: "SetupDependency" });

package/src/design-systems.d.ts

@@ -6,6 +6,11 @@ export interface GenerateDesignSystemFormFields {
      * the uploaded `.fig` filenames.
      */
     projectName?: string;
+    /**
+     * Optional map of filename → page/frame GUIDs to restrict indexing.
+     * GUIDs are file-local, so they must be scoped per attachment.
+     */
+    selection?: Record<string, string[]>;
 }
 export interface GenerateDesignSystemRequest extends GenerateDesignSystemFormFields {
     /**
@@ -34,5 +39,6 @@ export declare const GENERATE_DESIGN_SYSTEM_MIN_ATTACHMENTS = 1;
  */
 export declare const generateDesignSystemBodySchema: z.ZodObject<{
     projectName: z.ZodOptional<z.ZodString>;
+    selection: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>>;
 }, z.core.$strip>;
 export type GenerateDesignSystemBody = z.infer<typeof generateDesignSystemBodySchema>;

package/src/design-systems.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-export const GENERATE_DESIGN_SYSTEM_MAX_FILE_BYTES = 100 * 1024 * 1024;
+export const GENERATE_DESIGN_SYSTEM_MAX_FILE_BYTES = 200 * 1024 * 1024;
 export const GENERATE_DESIGN_SYSTEM_MAX_ATTACHMENTS = 50;
 export const GENERATE_DESIGN_SYSTEM_MIN_ATTACHMENTS = 1;
 /**
@@ -11,4 +11,19 @@ export const GENERATE_DESIGN_SYSTEM_MIN_ATTACHMENTS = 1;
  */
 export const generateDesignSystemBodySchema = z.object({
     projectName: z.string().trim().min(1).max(200).optional(),
+    selection: z
+        .preprocess((v) => {
+        if (typeof v !== "string")
+            return v;
+        const trimmed = v.trim();
+        if (!trimmed)
+            return undefined;
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch (_a) {
+            return v;
+        }
+    }, z.record(z.string(), z.array(z.string().min(1)).max(10000)))
+        .optional(),
 });

package/src/events.d.ts

@@ -804,6 +804,52 @@ export declare const ProjectSnapshotFailedV1: {
     eventName: "project.snapshot.failed";
     version: "1";
 };
+/**
+ * Internal event used to poll whether a VolumeSnapshot has become ready
+ * without blocking a Pub/Sub handler for up to 10 minutes.
+ * The consumer (`handleSnapshotReadyCheckV1`) checks once, then either
+ * finalises (ready / timeout) or re-emits this event — each message
+ * completes in seconds.
+ */
+export type ProjectSnapshotReadyCheckV1 = FusionEventVariant<"project.snapshot.ready.check", {
+    projectId: string;
+    triggerEventId: string;
+    snapshotName: string;
+    gitSha: string;
+    /** Pod start time — used to compute durationMs in ProjectSnapshotCreatedV1. */
+    startedAtMs: number;
+    /** When the VolumeSnapshot was created — used to compute the readiness timeout. */
+    capturedAtMs: number;
+    timeoutMs: number;
+}, {
+    projectId: string;
+}, 1>;
+export declare const ProjectSnapshotReadyCheckV1: {
+    eventName: "project.snapshot.ready.check";
+    version: "1";
+};
+/**
+ * Internal event used to poll a snapshot pod's status without blocking a
+ * Pub/Sub handler for 45 minutes.  The consumer (`handleSnapshotPodWatchV1`)
+ * checks the pod once, then either finalises the snapshot (terminal state) or
+ * re-emits this event (still running) — each message completes in seconds.
+ */
+export type ProjectSnapshotPodWatchV1 = FusionEventVariant<"project.snapshot.pod.watch", {
+    projectId: string;
+    triggerEventId: string;
+    namespace: string;
+    podName: string;
+    source: "pr.merged" | "project.snapshot.refresh";
+    gitSha?: string;
+    startedAtMs: number;
+    timeoutMs: number;
+}, {
+    projectId: string;
+}, 1>;
+export declare const ProjectSnapshotPodWatchV1: {
+    eventName: "project.snapshot.pod.watch";
+    version: "1";
+};
 export type VideoRecordingCompletedV1 = FusionEventVariant<"video.recording.completed", {
     recordingId: string;
     videoUrl: string;
@@ -921,7 +967,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 | ProjectSnapshotRefreshV1 | ProjectSnapshotCapturedV1 | ProjectSnapshotCreatedV1 | ProjectSnapshotFailedV1;
+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 | ProjectSnapshotRefreshV1 | ProjectSnapshotCapturedV1 | ProjectSnapshotCreatedV1 | ProjectSnapshotFailedV1 | ProjectSnapshotReadyCheckV1 | ProjectSnapshotPodWatchV1;
 export interface ModelPermissionRequiredEvent {
     type: "assistant.model.permission.required";
     data: {

package/src/events.js

@@ -90,6 +90,14 @@ export const ProjectSnapshotFailedV1 = {
     eventName: "project.snapshot.failed",
     version: "1",
 };
+export const ProjectSnapshotReadyCheckV1 = {
+    eventName: "project.snapshot.ready.check",
+    version: "1",
+};
+export const ProjectSnapshotPodWatchV1 = {
+    eventName: "project.snapshot.pod.watch",
+    version: "1",
+};
 export const VideoRecordingCompletedV1 = {
     eventName: "video.recording.completed",
     version: "1",

package/src/index.d.ts

@@ -3,6 +3,7 @@ export * from "./events.js";
 export * from "./messages.js";
 export * from "./settings.js";
 export * from "./mapping.js";
+export * from "./common-schemas.js";
 export * from "./codegen.js";
 export * from "./diff-hunks.js";
 export * from "./projects.js";

package/src/index.js

@@ -3,6 +3,7 @@ export * from "./events.js";
 export * from "./messages.js";
 export * from "./settings.js";
 export * from "./mapping.js";
+export * from "./common-schemas.js";
 export * from "./codegen.js";
 export * from "./diff-hunks.js";
 export * from "./projects.js";

package/src/organization.d.ts

@@ -1,4 +1,5 @@
-import type { EnvironmentVariable, PrivacyMode, ReviewEffort } from "./codegen";
+import type { PrivacyMode, ReviewEffort } from "./codegen";
+import type { EnvironmentVariable } from "./common-schemas";
 export interface GithubEnterpriseSetupValue {
     host: string;
     clientId: string;

package/src/projects.d.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import type { ConnectivityErrorCode, CheckType, LikelyCause } from "./connectivity/types.js";
-import type { FileOverride, EnvironmentVariable, LaunchServerState, LaunchServerStatus, BranchBackup, CommitMode, CustomInstruction, CustomAgentDefinition, GitSnapshot, AutoPushMode, GenerateUserMessage, CodeGenToolMap, GenerateCompletionStep, ReviewEffort } from "./codegen";
+import { type EnvironmentVariable, type SetupDependency } from "./common-schemas";
+import type { FileOverride, LaunchServerState, LaunchServerStatus, BranchBackup, CommitMode, CustomInstruction, CustomAgentDefinition, GitSnapshot, AutoPushMode, GenerateUserMessage, CodeGenToolMap, GenerateCompletionStep, ReviewEffort } from "./codegen";
 import type { FallbackTokensPrivate } from "./organization";
 /**
  * Temporary type for date fields during migration.
@@ -328,32 +329,6 @@ export type ShutdownResponse = {
 export type ShutdownResponseSerialized = Omit<ShutdownResponse, "error"> & {
     error?: string;
 };
-export declare const SetupMiseDependencySchema: z.ZodObject<{
-    key: z.ZodString;
-    type: z.ZodLiteral<"mise">;
-    tool: z.ZodString;
-    version: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export type SetupMiseDependency = z.infer<typeof SetupMiseDependencySchema>;
-export declare const SetupScriptDependencySchema: z.ZodObject<{
-    key: z.ZodString;
-    type: z.ZodLiteral<"script">;
-    name: z.ZodString;
-    script: z.ZodString;
-}, z.core.$strip>;
-export type SetupScriptDependency = z.infer<typeof SetupScriptDependencySchema>;
-export declare const SetupDependencySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    key: z.ZodString;
-    type: z.ZodLiteral<"mise">;
-    tool: z.ZodString;
-    version: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
-    key: z.ZodString;
-    type: z.ZodLiteral<"script">;
-    name: z.ZodString;
-    script: z.ZodString;
-}, z.core.$strip>], "type">;
-export type SetupDependency = z.infer<typeof SetupDependencySchema>;
 export type FusionExecutionEnvironment = "containerized" | "container-less" | "cloud" | "cloud-v2";
 export type AgentType = "setup-project" | "project-configuration" | "org-agent" | "code-review-orchestrator" | "design-system-indexer" | "builder-publish-integration";
 export interface PartialBranchData {
@@ -889,6 +864,8 @@ 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 */
+    hosting?: ProjectHosting;
 }
 /**
  * Get the state of a branch, checking `state` first and falling back to `deleted` for backwards compatibility.
@@ -1235,4 +1212,106 @@ export interface ShouldDeletePodResponse {
     reason: "branch_inactive" | "force_delete_flag" | "project_not_found" | "branch_not_found" | "ok" | "error";
     error?: string;
 }
+/**
+ * Deploy lifecycle status:
+ * - queued     - inital state although we don't currently queue deploys per se
+ * - building   — deploy pod is running `npm run build`
+ * - uploading  — build succeeded; artifacts being uploaded to GCS (transient,
+ *                between `client.devtools.build.completed` and `client.devtools.build.uploaded`)
+ * - 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
+ */
+export declare const DeployStatusSchema: z.ZodEnum<{
+    building: "building";
+    deploying: "deploying";
+    failed: "failed";
+    live: "live";
+    queued: "queued";
+    uploading: "uploading";
+}>;
+export type DeployStatus = z.infer<typeof DeployStatusSchema>;
+export declare const ProjectHostingBuildConfigSchema: z.ZodObject<{
+    buildCommand: z.ZodOptional<z.ZodString>;
+    nodeVersion: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ProjectHostingBuildConfig = z.infer<typeof ProjectHostingBuildConfigSchema>;
+/**
+ * Hosting configuration for a project, stored at `projects/{projectId}.hosting`.
+ */
+export declare const ProjectHostingSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    slug: z.ZodOptional<z.ZodString>;
+    netlifySiteId: z.ZodOptional<z.ZodString>;
+    netlifySiteName: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    buildConfig: z.ZodOptional<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>>>;
+    lastDeployId: z.ZodOptional<z.ZodString>;
+    lastDeployAt: z.ZodOptional<z.ZodNumber>;
+    lastDeployStatus: z.ZodOptional<z.ZodEnum<{
+        building: "building";
+        deploying: "deploying";
+        failed: "failed";
+        live: "live";
+        queued: "queued";
+        uploading: "uploading";
+    }>>;
+    customDomain: z.ZodOptional<z.ZodString>;
+    customDomainVerified: z.ZodOptional<z.ZodBoolean>;
+    autoDeploy: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type ProjectHosting = z.infer<typeof ProjectHostingSchema>;
+/**
+ * A single deploy record, stored at `deploys/{deployId}`. The Deploy.id is the document key.
+ */
+export declare const DeploySchema: z.ZodObject<{
+    id: z.ZodString;
+    projectId: z.ZodString;
+    ownerId: z.ZodString;
+    checkoutBranch: z.ZodOptional<z.ZodString>;
+    deployBranchId: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        building: "building";
+        deploying: "deploying";
+        failed: "failed";
+        live: "live";
+        queued: "queued";
+        uploading: "uploading";
+    }>;
+    netlifyDeployId: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodNumber;
+    completedAt: z.ZodOptional<z.ZodNumber>;
+    triggeredBy: z.ZodString;
+}, z.core.$strip>;
+export type Deploy = z.infer<typeof DeploySchema>;
+/**
+ * Permanent slug reservation, stored at `hosting-slugs/{slug}` (slug is the document key).
+ *
+ * Created on first publish via the atomic Firestore transaction in
+ * `POST /projects/hosting/reserve-slug`. Never deleted (URL hijacking protection).
+ *
+ * "Is this URL currently live?" is NOT a property of this doc. It's answered by the
+ * presence of the per-slug `HTTPRoute` in Envoy Gateway (the source of truth for routing)
+ * and/or by `project.hosting.netlifySiteId` (set on publish, cleared on unpublish). The
+ * slug doc exists purely to enforce uniqueness and own the permanent reservation.
+ */
+export declare const HostingSlugSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    ownerId: z.ZodString;
+    createdAt: z.ZodNumber;
+    createdBy: z.ZodString;
+}, z.core.$strip>;
+export type HostingSlug = z.infer<typeof HostingSlugSchema>;
 export {};

package/src/projects.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { EnvironmentVariableSchema, } from "./common-schemas";
 /**
  * Detect git provider from a repository URL (HTTPS or SSH).
  * Used by both error diagnostics and connectivity checks for consistent provider labeling.
@@ -37,28 +38,6 @@ export const STARTER_REPO = "BuilderIO/fusion-starter";
 export const DSI_PREVIEW_REPO = "BuilderIO/dsi-starter";
 export const EXAMPLE_OR_STARTER_REPOS = [...EXAMPLE_REPOS, STARTER_REPO];
 export const EXAMPLE_OR_STARTER_REPOS_URLS = EXAMPLE_OR_STARTER_REPOS.map((repo) => `https://github.com/${repo}`);
-export const SetupMiseDependencySchema = z
-    .object({
-    key: z.string(),
-    type: z.literal("mise"),
-    tool: z.string(),
-    version: z.string().optional(),
-})
-    .meta({ title: "SetupMiseDependency" });
-export const SetupScriptDependencySchema = z
-    .object({
-    key: z.string(),
-    type: z.literal("script"),
-    name: z.string(),
-    script: z.string(),
-})
-    .meta({ title: "SetupScriptDependency" });
-export const SetupDependencySchema = z
-    .discriminatedUnion("type", [
-    SetupMiseDependencySchema,
-    SetupScriptDependencySchema,
-])
-    .meta({ title: "SetupDependency" });
 export const checkIsNewBranch = (branch) => {
     return "projectId" in branch;
 };
@@ -185,3 +164,124 @@ export function parseExitPlanMode(chunk) {
     }
     return null;
 }
+// ============================================================================
+// First-class Hosting
+// ============================================================================
+/**
+ * Deploy lifecycle status:
+ * - queued     - inital state although we don't currently queue deploys per se
+ * - building   — deploy pod is running `npm run build`
+ * - uploading  — build succeeded; artifacts being uploaded to GCS (transient,
+ *                between `client.devtools.build.completed` and `client.devtools.build.uploaded`)
+ * - 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
+ */
+export const DeployStatusSchema = z.enum([
+    "queued",
+    "building",
+    "uploading",
+    "deploying",
+    "live",
+    "failed",
+]);
+export const ProjectHostingBuildConfigSchema = z.object({
+    buildCommand: z.string().optional(),
+    nodeVersion: z.string().optional(),
+});
+/**
+ * Hosting configuration for a project, stored at `projects/{projectId}.hosting`.
+ */
+export const ProjectHostingSchema = z.object({
+    enabled: z.boolean().optional().meta({
+        description: "Whether hosting is enabled for this project or not.",
+    }),
+    slug: z.string().optional().meta({
+        description: 'e.g. "my-cool-app" — set once on first publish, immutable',
+    }),
+    netlifySiteId: z.string().optional().meta({
+        description: "Netlify site ID for management API calls; cleared on unpublish, set again on re-publish",
+    }),
+    netlifySiteName: z.string().optional().meta({
+        description: "<name> in <name>.netlify.app — the upstream the HTTPRoute filter rewrites Host to; cleared on unpublish",
+    }),
+    url: z.string().optional().meta({
+        description: '"https://my-cool-app.builder.cloud" — derived from slug',
+    }),
+    buildConfig: ProjectHostingBuildConfigSchema.optional(),
+    /**
+     * Hosting-build environment variables. Separate from `project.settings.environmentVariables`
+     * (which feeds the dev pod) so users can set different values for dev vs production —
+     * mirrors the Vercel/Netlify split between development and production env scopes.
+     *
+     * Reuses `EnvironmentVariableSchema`, including the `isSecret: boolean` flag. Stored in
+     * 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",
+    }),
+    lastDeployId: z.string().optional(),
+    lastDeployAt: z.number().optional(),
+    lastDeployStatus: DeployStatusSchema.optional(),
+    customDomain: z.string().optional(),
+    customDomainVerified: z.boolean().optional(),
+    autoDeploy: z
+        .boolean()
+        .optional()
+        .meta({ description: "auto-deploy on push/merge" }),
+});
+/**
+ * A single deploy record, stored at `deploys/{deployId}`. The Deploy.id is the document key.
+ */
+export const DeploySchema = z.object({
+    id: z.string(),
+    projectId: z.string(),
+    ownerId: z.string(),
+    checkoutBranch: z
+        .string()
+        .optional()
+        .meta({
+        description: 'The git ref that was deployed (always "main" in v0/v1; the feature branch ' +
+            "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.",
+    }),
+    status: DeployStatusSchema,
+    netlifyDeployId: z.string().optional(),
+    url: z.string().optional(),
+    error: z.string().optional().meta({
+        description: "Single human-readable line on failure; raw build logs not surfaced in v0",
+    }),
+    createdAt: z.number(),
+    completedAt: z.number().optional(),
+    triggeredBy: z.string().meta({
+        description: 'user ID for manual publish, or "auto-deploy" (v1)',
+    }),
+});
+/**
+ * Permanent slug reservation, stored at `hosting-slugs/{slug}` (slug is the document key).
+ *
+ * Created on first publish via the atomic Firestore transaction in
+ * `POST /projects/hosting/reserve-slug`. Never deleted (URL hijacking protection).
+ *
+ * "Is this URL currently live?" is NOT a property of this doc. It's answered by the
+ * presence of the per-slug `HTTPRoute` in Envoy Gateway (the source of truth for routing)
+ * and/or by `project.hosting.netlifySiteId` (set on publish, cleared on unpublish). The
+ * slug doc exists purely to enforce uniqueness and own the permanent reservation.
+ */
+export const HostingSlugSchema = z.object({
+    projectId: z.string(),
+    ownerId: z.string(),
+    createdAt: z.number(),
+    createdBy: z.string().meta({
+        description: "user ID of the user who first clicked Publish on the project",
+    }),
+});