@spacefast/common 0.0.24 → 0.2.1

package/dist/contracts/bootstrap.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { CursorPaginationSchema, ProblemDetailsSchema } from "./common.js";
+import { meResponseSchema } from "./me.js";
+import { SpaceSchema } from "./resources.js";
+import { spaceRuntimeStatusSchema } from "./spaces.js";
+import { TeamDetailSchema, TeamSummarySchema } from "./teams.js";
+// `GET /v1/bootstrap`: the one-hop cold start. Every field here is an existing
+// contract referenced by name — `me` is what `GET /v1/me` returns, `teams` is
+// what `GET /v1/teams` returns, and so on — so a client can seed its per-resource
+// caches from this payload without a second definition of anything.
+export const bootstrapQuerySchema = z.object({
+    teamRef: z
+        .string()
+        .optional()
+        .describe("Team id or slug to resolve. It also scopes slug resolution for `spaceRef` and selects the team on the support boot payload. Present but blank is a request error, never `not_requested`."),
+    spaceRef: z
+        .string()
+        .optional()
+        .describe("Space reference: a `spc_` id, a hostname or URL, or a slug. Slugs resolve only within spaces you can already reach, so an unclaimed space is reachable by id or hostname only. Present but blank is a request error, never `not_requested`."),
+});
+// The per-slot problem: the RFC 9457 document minus `requestId` (the request has
+// exactly one, and repeating it in every slot of a 200 body is noise).
+// Everything else is byte-identical to the 4xx document, so the same error
+// renderer works on a slot problem unchanged — there is no second taxonomy.
+export const bootstrapProblemSchema = ProblemDetailsSchema.omit({ requestId: true }).describe("Why this slot did not resolve: the same problem document the dedicated endpoint would have returned, minus the request id carried by the response itself.");
+/**
+ * A resolution slot. A caller reaches a value ONLY through `status: "resolved"`.
+ * This is deliberate: the dashboard's space read is route admission, and a bare
+ * `null` invites reading "could not resolve" as "nothing was asked for".
+ */
+function bootstrapSlot(value, description) {
+    return z
+        .discriminatedUnion("status", [
+        z.object({ status: z.literal("resolved"), value }),
+        z.object({ status: z.literal("unresolved"), problem: bootstrapProblemSchema }),
+        z.object({ status: z.literal("not_requested") }),
+    ])
+        .describe(`${description}: the resolved value, the problem that stopped it, or not asked for.`);
+}
+export const bootstrapResponseSchema = z.object({
+    me: meResponseSchema
+        .nullable()
+        .describe("The authenticated identity, exactly as `GET /v1/me` returns it. Null only for a claim-token caller, which has no identity."),
+    teams: z
+        .array(TeamSummarySchema)
+        .describe("The teams this credential can act for, newest-first — the same set `GET /v1/teams` returns. Empty for a claim-token caller."),
+    teamsPagination: CursorPaginationSchema.describe("Paging for `teams`. `hasMore: true` means this credential reaches more teams than the boot payload carried; page the rest from `GET /v1/teams`."),
+    resolvedTeam: bootstrapSlot(TeamDetailSchema, "The team named by `teamRef`"),
+    resolvedSpace: bootstrapSlot(SpaceSchema, "The space named by `spaceRef`"),
+    spaceRuntime: bootstrapSlot(spaceRuntimeStatusSchema, "Serving status of the resolved space"),
+});

package/dist/contracts/builds.d.ts

@@ -1,4 +1,16 @@
 import { z } from "zod";
+export declare const BuildSettingsOverrideSchema: z.ZodObject<{
+    rootDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    installDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    installCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    buildCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    outputDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    ignoredBuildCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    frameworkPreset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    platformPreset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    allowUnsupportedPlatformFeatures: z.ZodOptional<z.ZodBoolean>;
+    timeoutSeconds: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 export declare const BuildSettingsSchema: z.ZodObject<{
     rootDirectory: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     installDirectory: z.ZodDefault<z.ZodNullable<z.ZodString>>;
@@ -158,6 +170,37 @@ export declare const BuildSchema: z.ZodObject<{
         branch: z.ZodOptional<z.ZodString>;
         pullRequestNumber: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>], "kind">;
+    source: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        kind: z.ZodEnum<{
+            build: "build";
+            agent: "agent";
+            api: "api";
+            dashboard: "dashboard";
+            cli: "cli";
+            git: "git";
+            direct_upload: "direct_upload";
+            import: "import";
+            variable_update: "variable_update";
+            config_update: "config_update";
+        }>;
+        client: z.ZodOptional<z.ZodString>;
+        branch: z.ZodOptional<z.ZodString>;
+        commit: z.ZodOptional<z.ZodString>;
+        message: z.ZodOptional<z.ZodString>;
+        dirty: z.ZodOptional<z.ZodBoolean>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        git: z.ZodOptional<z.ZodObject<{
+            repository: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            repositoryFullName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            repositoryUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            ref: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            branch: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            branchAliasUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            commit: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            commitSha: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            pullRequestNumber: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$catchall<z.ZodUnknown>>>;
+    }, z.core.$strip>>>;
     settingsSnapshot: z.ZodObject<{
         rootDirectory: z.ZodDefault<z.ZodNullable<z.ZodString>>;
         installDirectory: z.ZodDefault<z.ZodNullable<z.ZodString>>;
@@ -188,7 +231,7 @@ export declare const BuildSchema: z.ZodObject<{
         path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
             registrar: "registrar";
-            wpcloud: "wpcloud";
+            infra: "infra";
             dns: "dns";
             runtime: "runtime";
         }>>>;
@@ -213,16 +256,85 @@ export declare const buildCreateRequestSchema: z.ZodObject<{
         pullRequestNumber: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>], "kind">;
     settings: z.ZodOptional<z.ZodObject<{
-        rootDirectory: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        installDirectory: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        installCommand: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        buildCommand: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        outputDirectory: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        ignoredBuildCommand: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        frameworkPreset: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        platformPreset: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
-        allowUnsupportedPlatformFeatures: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
-        timeoutSeconds: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        rootDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        installDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        installCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        buildCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        outputDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        ignoredBuildCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        frameworkPreset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        platformPreset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        allowUnsupportedPlatformFeatures: z.ZodOptional<z.ZodBoolean>;
+        timeoutSeconds: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    target: z.ZodOptional<z.ZodObject<{
+        channel: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
+        preview: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    }, z.core.$strip>>;
+    diagnostics: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        severity: z.ZodEnum<{
+            info: "info";
+            warning: "warning";
+            error: "error";
+        }>;
+        message: z.ZodString;
+        path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            registrar: "registrar";
+            infra: "infra";
+            dns: "dns";
+            runtime: "runtime";
+        }>>>;
+        details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        fix: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        retryable: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    }, z.core.$strip>>>;
+    wait: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const buildSourceSchema: z.ZodEnum<{
+    wordpress: "wordpress";
+}>;
+export declare const wordpressBuildTriggerRequestSchema: z.ZodObject<{
+    source: z.ZodLiteral<"wordpress">;
+    sourceUrl: z.ZodString;
+}, z.core.$strict>;
+/**
+ * `POST /v1/spaces/{spaceId}/builds` takes either a caller-described build or a
+ * named managed source. `source` is a real discriminator, not a plain union
+ * arm: zod routes the body to exactly one variant and reports the failure
+ * inside it, so a validation problem keeps its RFC 6901 pointer
+ * (`/input/kind`, `/sourceUrl`) instead of collapsing to a top-level
+ * `invalid_union` with nowhere to point. Both variants are strict, so a body
+ * carrying `source` alongside `input` is rejected rather than quietly read as
+ * a caller-described build.
+ */
+export declare const spaceBuildCreateRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    source: z.ZodLiteral<"wordpress">;
+    sourceUrl: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    input: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"archive">;
+        sourceMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"repository">;
+        repositoryConnectionId: z.ZodString;
+        ref: z.ZodOptional<z.ZodString>;
+        commit: z.ZodOptional<z.ZodString>;
+        branch: z.ZodOptional<z.ZodString>;
+        pullRequestNumber: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>], "kind">;
+    settings: z.ZodOptional<z.ZodObject<{
+        rootDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        installDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        installCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        buildCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        outputDirectory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        ignoredBuildCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        frameworkPreset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        platformPreset: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        allowUnsupportedPlatformFeatures: z.ZodOptional<z.ZodBoolean>;
+        timeoutSeconds: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
     target: z.ZodOptional<z.ZodObject<{
         channel: z.ZodOptional<z.ZodDefault<z.ZodNullable<z.ZodString>>>;
@@ -239,7 +351,7 @@ export declare const buildCreateRequestSchema: z.ZodObject<{
         path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
             registrar: "registrar";
-            wpcloud: "wpcloud";
+            infra: "infra";
             dns: "dns";
             runtime: "runtime";
         }>>>;
@@ -248,6 +360,18 @@ export declare const buildCreateRequestSchema: z.ZodObject<{
         retryable: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
     }, z.core.$strip>>>;
     wait: z.ZodDefault<z.ZodBoolean>;
+    source: z.ZodOptional<z.ZodUndefined>;
+}, z.core.$strict>], "source">;
+export declare const buildPreflightQuerySchema: z.ZodObject<{
+    source: z.ZodEnum<{
+        wordpress: "wordpress";
+    }>;
+    sourceUrl: z.ZodString;
+}, z.core.$strict>;
+export declare const buildPreflightResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        ready: z.ZodLiteral<true>;
+    }, z.core.$strict>;
 }, z.core.$strip>;
 export declare const buildSourceArchiveUploadSchema: z.ZodObject<{
     id: z.ZodString;
@@ -279,7 +403,8 @@ export declare const buildSourceArchiveUploadSchema: z.ZodObject<{
         contentType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     links: z.ZodObject<{
-        resume: z.ZodString;
+        refresh: z.ZodString;
+        resume: z.ZodOptional<z.ZodString>;
         finalize: z.ZodString;
     }, z.core.$strip>;
     details: z.ZodOptional<z.ZodObject<{
@@ -302,7 +427,7 @@ export declare const buildSourceArchiveUploadSchema: z.ZodObject<{
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
                 registrar: "registrar";
-                wpcloud: "wpcloud";
+                infra: "infra";
                 dns: "dns";
                 runtime: "runtime";
             }>>>;
@@ -336,6 +461,37 @@ export declare const buildCreateResponseSchema: z.ZodObject<{
                 branch: z.ZodOptional<z.ZodString>;
                 pullRequestNumber: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strict>], "kind">;
+            source: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    build: "build";
+                    agent: "agent";
+                    api: "api";
+                    dashboard: "dashboard";
+                    cli: "cli";
+                    git: "git";
+                    direct_upload: "direct_upload";
+                    import: "import";
+                    variable_update: "variable_update";
+                    config_update: "config_update";
+                }>;
+                client: z.ZodOptional<z.ZodString>;
+                branch: z.ZodOptional<z.ZodString>;
+                commit: z.ZodOptional<z.ZodString>;
+                message: z.ZodOptional<z.ZodString>;
+                dirty: z.ZodOptional<z.ZodBoolean>;
+                metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                git: z.ZodOptional<z.ZodObject<{
+                    repository: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                    repositoryFullName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                    repositoryUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                    ref: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                    branch: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                    branchAliasUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                    commit: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                    commitSha: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                    pullRequestNumber: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+                }, z.core.$catchall<z.ZodUnknown>>>;
+            }, z.core.$strip>>>;
             settingsSnapshot: z.ZodObject<{
                 rootDirectory: z.ZodDefault<z.ZodNullable<z.ZodString>>;
                 installDirectory: z.ZodDefault<z.ZodNullable<z.ZodString>>;
@@ -366,7 +522,7 @@ export declare const buildCreateResponseSchema: z.ZodObject<{
                 path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
                     registrar: "registrar";
-                    wpcloud: "wpcloud";
+                    infra: "infra";
                     dns: "dns";
                     runtime: "runtime";
                 }>>>;
@@ -408,7 +564,8 @@ export declare const buildCreateResponseSchema: z.ZodObject<{
                 contentType: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>>;
             links: z.ZodObject<{
-                resume: z.ZodString;
+                refresh: z.ZodString;
+                resume: z.ZodOptional<z.ZodString>;
                 finalize: z.ZodString;
             }, z.core.$strip>;
             details: z.ZodOptional<z.ZodObject<{
@@ -431,7 +588,7 @@ export declare const buildCreateResponseSchema: z.ZodObject<{
                     path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                     provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
                         registrar: "registrar";
-                        wpcloud: "wpcloud";
+                        infra: "infra";
                         dns: "dns";
                         runtime: "runtime";
                     }>>>;
@@ -470,6 +627,37 @@ export declare const buildListResponseSchema: z.ZodObject<{
             branch: z.ZodOptional<z.ZodString>;
             pullRequestNumber: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>], "kind">;
+        source: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+            kind: z.ZodEnum<{
+                build: "build";
+                agent: "agent";
+                api: "api";
+                dashboard: "dashboard";
+                cli: "cli";
+                git: "git";
+                direct_upload: "direct_upload";
+                import: "import";
+                variable_update: "variable_update";
+                config_update: "config_update";
+            }>;
+            client: z.ZodOptional<z.ZodString>;
+            branch: z.ZodOptional<z.ZodString>;
+            commit: z.ZodOptional<z.ZodString>;
+            message: z.ZodOptional<z.ZodString>;
+            dirty: z.ZodOptional<z.ZodBoolean>;
+            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            git: z.ZodOptional<z.ZodObject<{
+                repository: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                repositoryFullName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                repositoryUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                ref: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                branch: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                branchAliasUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                commit: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                commitSha: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                pullRequestNumber: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            }, z.core.$catchall<z.ZodUnknown>>>;
+        }, z.core.$strip>>>;
         settingsSnapshot: z.ZodObject<{
             rootDirectory: z.ZodDefault<z.ZodNullable<z.ZodString>>;
             installDirectory: z.ZodDefault<z.ZodNullable<z.ZodString>>;
@@ -500,7 +688,7 @@ export declare const buildListResponseSchema: z.ZodObject<{
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
                 registrar: "registrar";
-                wpcloud: "wpcloud";
+                infra: "infra";
                 dns: "dns";
                 runtime: "runtime";
             }>>>;
@@ -546,4 +734,7 @@ export type InternalBuildExecutionLaunch = z.infer<typeof buildExecutionLaunchSc
 export type InternalBuildExecutionSupervision = z.infer<typeof buildExecutionSupervisionSchema>;
 export type BuildCreateRequest = z.infer<typeof buildCreateRequestSchema>;
 export type BuildCreateResponse = z.infer<typeof buildCreateResponseSchema>;
+export type WordPressBuildTriggerRequest = z.infer<typeof wordpressBuildTriggerRequestSchema>;
+export type SpaceBuildCreateRequest = z.infer<typeof spaceBuildCreateRequestSchema>;
+export type BuildPreflightQuery = z.infer<typeof buildPreflightQuerySchema>;
 export {};

package/dist/contracts/builds.js

@@ -2,18 +2,34 @@ import { z } from "zod";
 import { CursorPaginationSchema, baseDiagnosticSchema, cursorListQuerySchema, dataEnvelope, } from "./common.js";
 import { buildStatus } from "./enums.js";
 import { uploadInstructionsSchema } from "./internal.js";
+import { PublishSourceSchema } from "./resources.js";
+import { wordpressDataSourceUrlSchema } from "./space-config.js";
 import { versionLogEntrySchema } from "./spaces.js";
 const nullableCommandSchema = z.string().trim().min(1).nullable();
-const buildTimeoutSecondsSchema = z.number().int().min(60).max(7200).default(900);
+const buildTimeoutSecondsSchema = z.number().int().min(60).max(7200);
 const scpStyleGitRemotePattern = /^[^@\s/:]+@[^:\s]+:[^\s]+$/;
 const gitCloneUrlSchema = z
     .string()
     .trim()
     .min(1)
     .refine((value) => scpStyleGitRemotePattern.test(value) || z.string().url().safeParse(value).success, "Clone URL must be a URL or scp-style Git remote.");
-// Build (`bld_`, internal-docs/platform.md "Build"): a first-class resource with
+// Build (`bld_`, the platform spec "Build"): a first-class resource with
 // its own table; ids are opaque and NEVER derived from version ids. The runner
 // mints the produced version through the normal finalize path.
+export const BuildSettingsOverrideSchema = z
+    .object({
+    rootDirectory: nullableCommandSchema.optional(),
+    installDirectory: nullableCommandSchema.optional(),
+    installCommand: nullableCommandSchema.optional(),
+    buildCommand: nullableCommandSchema.optional(),
+    outputDirectory: nullableCommandSchema.optional(),
+    ignoredBuildCommand: nullableCommandSchema.optional(),
+    frameworkPreset: nullableCommandSchema.optional(),
+    platformPreset: nullableCommandSchema.optional(),
+    allowUnsupportedPlatformFeatures: z.boolean().optional(),
+    timeoutSeconds: buildTimeoutSecondsSchema.optional(),
+})
+    .describe("Sparse per-request build setting overrides applied over saved settings.");
 export const BuildSettingsSchema = z
     .object({
     rootDirectory: nullableCommandSchema.default(null),
@@ -25,7 +41,7 @@ export const BuildSettingsSchema = z
     frameworkPreset: nullableCommandSchema.default(null),
     platformPreset: nullableCommandSchema.default(null),
     allowUnsupportedPlatformFeatures: z.boolean().default(false),
-    timeoutSeconds: buildTimeoutSecondsSchema,
+    timeoutSeconds: buildTimeoutSecondsSchema.default(900),
 })
     .describe("Resolved build settings. Builds persist this as an immutable `settingsSnapshot`.");
 export const BuildTargetSchema = z
@@ -40,8 +56,6 @@ export const BuildTargetSchema = z
     preview: z.boolean().default(false).describe("Whether the build targets preview behavior."),
 })
     .describe("Where a successful build should publish or run in preview mode.");
-// Shared by InternalBuildSourceSchema and InternalBuildInputSchema: both carry
-// this exact archive-source member in their `kind` discriminated union.
 const internalArchiveBuildSourceSchema = z.object({
     kind: z.literal("archive").describe("Build from an uploaded source archive."),
     uploadId: z.string().optional().describe("Upload session (`upl_`) carrying the archive."),
@@ -67,11 +81,7 @@ const internalArchiveBuildSourceSchema = z.object({
     compressedBytes: z.number().int().nonnegative().optional(),
     expandedBytes: z.number().int().nonnegative().optional(),
     fileCount: z.number().int().nonnegative().optional(),
-    expiresAt: z
-        .string()
-        .datetime()
-        .optional()
-        .describe("Server-enforced upload expiry while the archive is waiting for upload."),
+    expiresAt: z.string().datetime().optional().describe("Server-enforced upload expiry."),
 });
 const InternalBuildSourceSchema = z
     .discriminatedUnion("kind", [
@@ -142,7 +152,7 @@ export const BuildCreateInputSchema = z
         sourceMetadata: z
             .record(z.string(), z.unknown())
             .optional()
-            .describe("Optional source provenance for the produced version."),
+            .describe("Source provenance for the produced version."),
     })
         .strict(),
     z.object({
@@ -155,10 +165,9 @@ export const BuildCreateInputSchema = z
     }),
 ])
     .describe("What a new build should run against.");
-// One phase-timeline entry the build runner appends via recordBuildPhase
-// (apps/control-plane/src/builds/runner.ts BUILD_PHASES); `phase` stays a
-// plain string here since the runner's specific phase vocabulary is an
-// app-level concern, not a shared contract.
+// One phase-timeline entry the runner appends via recordBuildPhase
+// (apps/control-plane/src/builds/runner.ts BUILD_PHASES). `phase` stays a plain
+// string: the runner's phase vocabulary is app-level, not a shared contract.
 const buildExecutionPhaseSchema = z.object({
     phase: z.string().min(1).describe("Build phase name. See `BUILD_PHASES` in `builds/runner.ts`."),
     at: z.string().datetime(),
@@ -197,12 +206,15 @@ const InternalBuildExecutionSchema = z
         .optional()
         .describe("Phase timeline that the runner appends to with `recordBuildPhase`."),
 })
-    .describe("Internal runner execution metadata surfaced only where appropriate.");
+    .describe("Internal runner execution metadata. Not part of the public Build resource.");
 export const BuildSchema = z.object({
     id: z.string().describe("Build id (`bld_`); opaque and never derived from a version id."),
     spaceId: z.string().describe("Space (`spc_`) the build produces a version for."),
     status: buildStatus.describe("Build lifecycle status."),
     input: PublicBuildInputSchema,
+    source: PublishSourceSchema.nullable()
+        .default(null)
+        .describe("Publish provenance as declared at build start (client, git ref data, publish message). Present on failed and running builds too; the produced version's `source` is the authoritative copy once one exists. Null when nothing was declared."),
     settingsSnapshot: BuildSettingsSchema,
     target: BuildTargetSchema,
     retryOfBuildId: z
@@ -224,18 +236,73 @@ export const BuildSchema = z.object({
     startedAt: z.string().datetime().nullable().describe("When the runner picked the build up."),
     finishedAt: z.string().datetime().nullable().describe("When the build reached a terminal state."),
 });
-export const buildCreateRequestSchema = z.object({
+export const buildCreateRequestSchema = z
+    .object({
     input: BuildCreateInputSchema,
-    settings: BuildSettingsSchema.partial()
-        .optional()
-        .describe("Per-run settings overrides, persisted as `settingsSnapshot` after resolution."),
+    settings: BuildSettingsOverrideSchema.optional().describe("Per-run settings overrides, persisted as `settingsSnapshot` after resolution."),
     target: BuildTargetSchema.partial().optional(),
     diagnostics: z
         .array(baseDiagnosticSchema)
         .optional()
-        .describe("Optional diagnostics already known before the build is queued."),
+        .describe("Diagnostics already known before the build is queued."),
     wait: z.boolean().default(false),
-});
+})
+    // Strict so a typo is a validation failure instead of a silently dropped
+    // field, and so a body that names a managed `source` can never be read as a
+    // caller-described build.
+    .strict();
+// A build source is a named way of deciding what to build. `wordpress` reads
+// the Space's configured WordPress source and its connected production
+// repository, so the caller names the source and nothing else — no input,
+// commands, settings, refs, or targets.
+//
+// It is an enum of one, and adding a second value is not a one-line edit: each
+// source owns a request variant in the create union, a resolver that finds its
+// repository, and its own preflight branch. The enum is how a caller names a
+// source, not an extension point.
+export const buildSourceSchema = z
+    .enum(["wordpress"])
+    .describe("Managed build source that decides what to build on the caller's behalf. `wordpress` is the only one.");
+export const wordpressBuildTriggerRequestSchema = z
+    .object({
+    source: z.literal("wordpress").describe("Build the Space's configured WordPress source."),
+    sourceUrl: wordpressDataSourceUrlSchema.describe("Configured WordPress URL that changed, as stored in the Space's data sources."),
+})
+    .strict()
+    .describe("Trigger a production build for a Space's configured WordPress source.");
+/**
+ * `POST /v1/spaces/{spaceId}/builds` takes either a caller-described build or a
+ * named managed source. `source` is a real discriminator, not a plain union
+ * arm: zod routes the body to exactly one variant and reports the failure
+ * inside it, so a validation problem keeps its RFC 6901 pointer
+ * (`/input/kind`, `/sourceUrl`) instead of collapsing to a top-level
+ * `invalid_union` with nowhere to point. Both variants are strict, so a body
+ * carrying `source` alongside `input` is rejected rather than quietly read as
+ * a caller-described build.
+ */
+export const spaceBuildCreateRequestSchema = z
+    .discriminatedUnion("source", [
+    wordpressBuildTriggerRequestSchema,
+    buildCreateRequestSchema.extend({
+        source: z
+            .undefined()
+            .optional()
+            .meta({ description: "Omit `source` to describe the build yourself." }),
+    }),
+])
+    .describe("A caller-described build, or a build triggered from a managed source.");
+export const buildPreflightQuerySchema = z
+    .object({
+    source: buildSourceSchema,
+    sourceUrl: wordpressDataSourceUrlSchema.describe("Configured WordPress URL to check, as stored in the Space's data sources."),
+})
+    .strict()
+    .describe("Which managed source to check before triggering builds from it.");
+export const buildPreflightResponseSchema = dataEnvelope(z
+    .object({
+    ready: z.literal(true).describe("The source can trigger production builds right now."),
+})
+    .strict());
 export const buildSourceArchiveUploadSchema = uploadInstructionsSchema;
 export const buildCreateResponseSchema = dataEnvelope(z.object({
     build: BuildSchema,
@@ -252,17 +319,16 @@ export const buildLogListResponseSchema = z.object({
     data: z.array(versionLogEntrySchema),
     pagination: CursorPaginationSchema,
 });
-// Branch-to-channel integration config (spec "Lifecycle model": "branch-to-
-// channel mapping rules live on the Space as integration config"). Launch only
-// supports `live`; keep the stored config aligned with publish/finalize until
-// named channels ship.
+// Branch-to-channel integration config (spec "Lifecycle model": mapping rules
+// live on the Space as integration config). Launch only supports `live`; keep
+// the stored config aligned with publish/finalize until named channels ship.
 export const spaceBuildIntegrationSchema = z
     .object({
     branchChannels: z
         .record(z.string().min(1).describe("Git branch or ref name."), z.literal("live").describe("Channel the branch's builds promote to."))
         .describe("Exact branch or ref name to channel name, for example `{ main: 'live' }`."),
 })
-    .describe("Per-space build integration config that defines where repository builds promote.");
+    .describe("Per-space build integration config: where repository builds promote.");
 /** Channel a repository build promotes to, or null when the ref is unmapped (default channel applies). */
 export function resolveBuildChannel(integration, ref) {
     return integration?.branchChannels[ref] ?? null;