@spacefast/common 0.0.26 → 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

@@ -170,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>>;
@@ -193,8 +224,8 @@ export declare const BuildSchema: z.ZodObject<{
         code: z.ZodString;
         severity: z.ZodEnum<{
             info: "info";
-            error: "error";
             warning: "warning";
+            error: "error";
         }>;
         message: z.ZodString;
         path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -244,8 +275,77 @@ export declare const buildCreateRequestSchema: 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>>>;
+        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>>;
@@ -260,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;
@@ -291,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<{
@@ -307,8 +420,8 @@ export declare const buildSourceArchiveUploadSchema: z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
                 info: "info";
-                error: "error";
                 warning: "warning";
+                error: "error";
             }>;
             message: z.ZodString;
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -348,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>>;
@@ -371,8 +515,8 @@ export declare const buildCreateResponseSchema: z.ZodObject<{
                 code: z.ZodString;
                 severity: z.ZodEnum<{
                     info: "info";
-                    error: "error";
                     warning: "warning";
+                    error: "error";
                 }>;
                 message: z.ZodString;
                 path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -420,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<{
@@ -436,8 +581,8 @@ export declare const buildCreateResponseSchema: z.ZodObject<{
                     code: z.ZodString;
                     severity: z.ZodEnum<{
                         info: "info";
-                        error: "error";
                         warning: "warning";
+                        error: "error";
                     }>;
                     message: z.ZodString;
                     path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -482,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>>;
@@ -505,8 +681,8 @@ export declare const buildListResponseSchema: z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
                 info: "info";
-                error: "error";
                 warning: "warning";
+                error: "error";
             }>;
             message: z.ZodString;
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -558,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,6 +2,8 @@ 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);
@@ -54,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."),
@@ -81,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", [
@@ -156,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({
@@ -169,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(),
@@ -211,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
@@ -238,16 +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: 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,
@@ -264,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;

package/dist/contracts/channels.d.ts

@@ -1,10 +1,33 @@
 import { z } from "zod";
+export declare const channelChangeKindSchema: z.ZodEnum<{
+    publish: "publish";
+    rollback: "rollback";
+    promote: "promote";
+}>;
+export type ChannelChangeKind = z.infer<typeof channelChangeKindSchema>;
+export declare const channelLastChangeSchema: z.ZodObject<{
+    kind: z.ZodNullable<z.ZodEnum<{
+        publish: "publish";
+        rollback: "rollback";
+        promote: "promote";
+    }>>;
+    at: z.ZodString;
+}, z.core.$strip>;
+export type ChannelLastChange = z.infer<typeof channelLastChangeSchema>;
 export declare const channelListItemSchema: z.ZodObject<{
     name: z.ZodString;
     currentVersionId: z.ZodNullable<z.ZodString>;
     currentDeploymentUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     previousVersionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     updatedAt: z.ZodString;
+    lastChange: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        kind: z.ZodNullable<z.ZodEnum<{
+            publish: "publish";
+            rollback: "rollback";
+            promote: "promote";
+        }>>;
+        at: z.ZodString;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type ChannelListItem = z.infer<typeof channelListItemSchema>;
 export declare const channelHistoryEntrySchema: z.ZodObject<{
@@ -15,10 +38,16 @@ export declare const channelHistoryEntrySchema: z.ZodObject<{
         system: "system";
         user: "user";
         api_key: "api_key";
+        partner_token: "partner_token";
         oauth_client: "oauth_client";
         anonymous_claim: "anonymous_claim";
     }>>>;
     actorId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    kind: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        publish: "publish";
+        rollback: "rollback";
+        promote: "promote";
+    }>>>;
     at: z.ZodString;
 }, z.core.$strip>;
 export type ChannelHistoryEntry = z.infer<typeof channelHistoryEntrySchema>;
@@ -29,6 +58,14 @@ export declare const channelListResponseSchema: z.ZodObject<{
         currentDeploymentUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         previousVersionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         updatedAt: z.ZodString;
+        lastChange: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            kind: z.ZodNullable<z.ZodEnum<{
+                publish: "publish";
+                rollback: "rollback";
+                promote: "promote";
+            }>>;
+            at: z.ZodString;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const channelHistoryResponseSchema: z.ZodObject<{
@@ -40,10 +77,16 @@ export declare const channelHistoryResponseSchema: z.ZodObject<{
             system: "system";
             user: "user";
             api_key: "api_key";
+            partner_token: "partner_token";
             oauth_client: "oauth_client";
             anonymous_claim: "anonymous_claim";
         }>>>;
         actorId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        kind: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            publish: "publish";
+            rollback: "rollback";
+            promote: "promote";
+        }>>>;
         at: z.ZodString;
     }, z.core.$strip>>;
 }, z.core.$strip>;

package/dist/contracts/channels.js

@@ -1,12 +1,21 @@
 import { z } from "zod";
-// Channels READ surface (the platform spec "Channels"): a read-only
-// projection over the existing `channels` table and the `channel.promoted`
-// activity log. No writes, no new storage — promotion stays owned by the
-// publish/version lifecycle. Additive only.
-// One row of the channel list: where each named channel points right now.
+// Channels READ surface (the platform spec "Channels"): a projection over the
+// `channels` table and the `channel.promoted` activity log. No writes:
+// promotion stays owned by the publish/version lifecycle.
+// How a channel pointer moved: a fresh publish going live, a forward promote,
+// or a rollback to an older version. Recorded on the `channel.promoted` event
+// at write time; null on events that predate kind recording.
+export const channelChangeKindSchema = z.enum(["publish", "promote", "rollback"]);
+// The channel's most recent pointer move, straight from the promotion log.
+export const channelLastChangeSchema = z.object({
+    kind: channelChangeKindSchema
+        .nullable()
+        .describe("How the pointer moved, or null when the log entry predates kind recording."),
+    at: z.string().datetime().describe("Instant the pointer moved, from the promotion log."),
+});
 // `currentVersionId` is the channel's version pointer (`channels.versionId`).
 export const channelListItemSchema = z.object({
-    name: z.string().describe("Channel name; `live` is the default channel."),
+    name: z.string().describe("Channel name; `live` is the default."),
     currentVersionId: z
         .string()
         .nullable()
@@ -22,10 +31,13 @@ export const channelListItemSchema = z.object({
         .optional()
         .describe("Last version this channel served before the current pointer (rollback target)."),
     updatedAt: z.string().datetime().describe("Instant when this channel pointer last moved."),
+    lastChange: channelLastChangeSchema
+        .nullable()
+        .optional()
+        .describe("The most recent pointer move from the promotion log, or null when none exists."),
 });
 // One entry of a channel's promotion history (the deploy log): a single
-// `channel.promoted` event, newest first. This is the audit trail of every
-// pointer move on the channel.
+// `channel.promoted` event, newest first.
 export const channelHistoryEntrySchema = z.object({
     versionId: z.string().describe("Version the channel was promoted to."),
     channel: z.string().describe("Channel that moved."),
@@ -35,11 +47,15 @@ export const channelHistoryEntrySchema = z.object({
         .optional()
         .describe("Version the channel served immediately before this promotion."),
     actorType: z
-        .enum(["user", "api_key", "oauth_client", "anonymous_claim", "system"])
+        .enum(["user", "api_key", "partner_token", "oauth_client", "anonymous_claim", "system"])
         .nullable()
         .optional()
         .describe("Kind of actor that performed the promotion."),
     actorId: z.string().nullable().optional().describe("Identifier of the promoting actor."),
+    kind: channelChangeKindSchema
+        .nullable()
+        .optional()
+        .describe("How the pointer moved, or null when the entry predates kind recording."),
     at: z.string().datetime().describe("Instant when the promotion happened."),
 });
 export const channelListResponseSchema = z.object({

package/dist/contracts/cli.d.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 export declare const CLI_EXIT_CODES: {
     readonly ok: 0;
     readonly validation: 2;
@@ -8,3 +9,9 @@ export declare const CLI_EXIT_CODES: {
     readonly timeout: 50;
     readonly unknown: 1;
 };
+export declare const cliWarningSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+    hint: z.ZodString;
+}, z.core.$strip>;
+export type CliWarning = z.infer<typeof cliWarningSchema>;