@storyshelf/app 0.6.2 → 0.8.0

package/dist/routers/build-reviews.mjs

@@ -0,0 +1,73 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { resolveAuthorizedProject, resolveReviewer } from "./helpers.mjs";
+import { hxRefresh } from "./htmx.mjs";
+import { flashHx } from "./flash.mjs";
+import { buildReviewCreateSchema, buildReviewSchema, buildReviewStateSchema, forbidden, notFound, unauthorized } from "./schemas.mjs";
+import { APPROVER_ROLES, VIEW_ROLES, buildForProject } from "./builds.handlers.mjs";
+import { giveVerdict, reviewStateOf } from "./build-reviews.handlers.mjs";
+import { createRoute, z } from "@hono/zod-openapi";
+// src/routers/build-reviews.ts
+const params = z.object({
+	slug: z.string(),
+	buildId: z.string()
+});
+const getReviewsRoute = createRoute({
+	method: "get",
+	tags: ["Review"],
+	summary: "Get a build's review state",
+	description: "The verdicts reviewers gave the build and what they make of it: each reviewer's latest verdict, the approvals against the project's requirement, and the full history. 404 when the project has review off.",
+	path: "/api/v1/projects/{slug}/builds/{buildId}/reviews",
+	request: { params },
+	responses: {
+		200: {
+			content: { "application/json": { schema: buildReviewStateSchema } },
+			description: "Review state of the build"
+		},
+		...notFound,
+		...unauthorized
+	}
+});
+const createReviewRoute = createRoute({
+	method: "post",
+	tags: ["Review"],
+	summary: "Approve or reject a build",
+	description: "Give the build a verdict (approver and admin). A reviewer rewrites their verdict by posting again; the newest counts. With `testing` off the verdicts decide the build: `approved` once the project's required approvals are present and no reviewer's latest verdict is `rejected`, `rejected` when any is. With `testing` on the verdict is a sign-off and the snapshot rollup keeps deciding. The verdict is attributed to the signed-in user, or to the user who owns the API token; a caller that is no user (the bootstrap admin token) gets 403, and only an instance with no authentication at all records an anonymous verdict, which counts when the project needs one approval (409 otherwise). 404 when the project has review off; 409 for a failed or cancelled build, while the build is still publishing, or for an anonymous verdict the project cannot count.",
+	path: "/api/v1/projects/{slug}/builds/{buildId}/reviews",
+	request: {
+		params,
+		body: { content: { "application/json": { schema: buildReviewCreateSchema } } }
+	},
+	responses: {
+		201: {
+			content: { "application/json": { schema: buildReviewSchema } },
+			description: "Verdict recorded"
+		},
+		...forbidden,
+		...notFound,
+		...unauthorized
+	}
+});
+/** Register the build-level verdict endpoints (`review` class). */
+function registerBuildReviews(app) {
+	app.openapi(getReviewsRoute, async (c) => {
+		const { slug, buildId } = c.req.valid("param");
+		const project = await resolveAuthorizedProject(c, slug, ...VIEW_ROLES);
+		const build = await buildForProject(project.id, buildId);
+		return c.json(await reviewStateOf(project, build));
+	});
+	app.openapi(createReviewRoute, async (c) => {
+		const { slug, buildId } = c.req.valid("param");
+		const project = await resolveAuthorizedProject(c, slug, ...APPROVER_ROLES);
+		const build = await buildForProject(project.id, buildId);
+		const userId = await resolveReviewer(c);
+		const review = await giveVerdict(project, build, userId, c.req.valid("json"));
+		hxRefresh(c);
+		flashHx(c, "Verdict recorded");
+		return c.json(review, 201);
+	});
+}
+export { registerBuildReviews };
+
+//# sourceMappingURL=build-reviews.mjs.map

package/dist/routers/build-reviews.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-reviews.mjs","names":["forbiddenResponse"],"sources":["../../src/routers/build-reviews.ts"],"sourcesContent":["import { createRoute, z } from \"@hono/zod-openapi\";\nimport type { ShelfRouter } from \"../app-types.ts\";\nimport { giveVerdict, reviewStateOf } from \"./build-reviews.handlers.ts\";\nimport { APPROVER_ROLES, VIEW_ROLES, buildForProject } from \"./builds.handlers.ts\";\nimport { flashHx } from \"./flash.ts\";\nimport { resolveAuthorizedProject, resolveReviewer } from \"./helpers.ts\";\nimport { hxRefresh } from \"./htmx.ts\";\nimport {\n  buildReviewCreateSchema,\n  buildReviewSchema,\n  buildReviewStateSchema,\n  forbidden as forbiddenResponse,\n  notFound,\n  unauthorized,\n} from \"./schemas.ts\";\n\nconst params = z.object({ slug: z.string(), buildId: z.string() });\n\nconst getReviewsRoute = createRoute({\n  method: \"get\",\n  tags: [\"Review\"],\n  summary: \"Get a build's review state\",\n  description:\n    \"The verdicts reviewers gave the build and what they make of it: each reviewer's latest verdict, the approvals against the project's requirement, and the full history. 404 when the project has review off.\",\n  path: \"/api/v1/projects/{slug}/builds/{buildId}/reviews\",\n  request: { params },\n  responses: {\n    200: {\n      content: { \"application/json\": { schema: buildReviewStateSchema } },\n      description: \"Review state of the build\",\n    },\n    ...notFound,\n    ...unauthorized,\n  },\n});\n\nconst createReviewRoute = createRoute({\n  method: \"post\",\n  tags: [\"Review\"],\n  summary: \"Approve or reject a build\",\n  description:\n    \"Give the build a verdict (approver and admin). A reviewer rewrites their verdict by posting again; the newest counts. With `testing` off the verdicts decide the build: `approved` once the project's required approvals are present and no reviewer's latest verdict is `rejected`, `rejected` when any is. With `testing` on the verdict is a sign-off and the snapshot rollup keeps deciding. The verdict is attributed to the signed-in user, or to the user who owns the API token; a caller that is no user (the bootstrap admin token) gets 403, and only an instance with no authentication at all records an anonymous verdict, which counts when the project needs one approval (409 otherwise). 404 when the project has review off; 409 for a failed or cancelled build, while the build is still publishing, or for an anonymous verdict the project cannot count.\",\n  path: \"/api/v1/projects/{slug}/builds/{buildId}/reviews\",\n  request: {\n    params,\n    body: { content: { \"application/json\": { schema: buildReviewCreateSchema } } },\n  },\n  responses: {\n    201: {\n      content: { \"application/json\": { schema: buildReviewSchema } },\n      description: \"Verdict recorded\",\n    },\n    ...forbiddenResponse,\n    ...notFound,\n    ...unauthorized,\n  },\n});\n\n/** Register the build-level verdict endpoints (`review` class). */\nexport function registerBuildReviews(app: ShelfRouter): void {\n  app.openapi(getReviewsRoute, async (c) => {\n    const { slug, buildId } = c.req.valid(\"param\");\n    const project = await resolveAuthorizedProject(c, slug, ...VIEW_ROLES);\n    const build = await buildForProject(project.id, buildId);\n    return c.json(await reviewStateOf(project, build));\n  });\n\n  app.openapi(createReviewRoute, async (c) => {\n    const { slug, buildId } = c.req.valid(\"param\");\n    const project = await resolveAuthorizedProject(c, slug, ...APPROVER_ROLES);\n    const build = await buildForProject(project.id, buildId);\n    const userId = await resolveReviewer(c);\n    const review = await giveVerdict(project, build, userId, c.req.valid(\"json\"));\n    hxRefresh(c);\n    flashHx(c, \"Verdict recorded\");\n    return c.json(review, 201);\n  });\n}\n"],"mappings":";;;;;;;;;;;AAgBA,MAAM,SAAS,EAAE,OAAO;CAAE,MAAM,EAAE,OAAO;CAAG,SAAS,EAAE,OAAO;AAAE,CAAC;AAEjE,MAAM,kBAAkB,YAAY;CAClC,QAAQ;CACR,MAAM,CAAC,QAAQ;CACf,SAAS;CACT,aACE;CACF,MAAM;CACN,SAAS,EAAE,OAAO;CAClB,WAAW;EACT,KAAK;GACH,SAAS,EAAE,oBAAoB,EAAE,QAAQ,uBAAuB,EAAE;GAClE,aAAa;EACf;EACA,GAAG;EACH,GAAG;CACL;AACF,CAAC;AAED,MAAM,oBAAoB,YAAY;CACpC,QAAQ;CACR,MAAM,CAAC,QAAQ;CACf,SAAS;CACT,aACE;CACF,MAAM;CACN,SAAS;EACP;EACA,MAAM,EAAE,SAAS,EAAE,oBAAoB,EAAE,QAAQ,wBAAwB,EAAE,EAAE;CAC/E;CACA,WAAW;EACT,KAAK;GACH,SAAS,EAAE,oBAAoB,EAAE,QAAQ,kBAAkB,EAAE;GAC7D,aAAa;EACf;EACA,GAAGA;EACH,GAAG;EACH,GAAG;CACL;AACF,CAAC;;AAGD,SAAgB,qBAAqB,KAAwB;CAC3D,IAAI,QAAQ,iBAAiB,OAAO,MAAM;EACxC,MAAM,EAAE,MAAM,YAAY,EAAE,IAAI,MAAM,OAAO;EAC7C,MAAM,UAAU,MAAM,yBAAyB,GAAG,MAAM,GAAG,UAAU;EACrE,MAAM,QAAQ,MAAM,gBAAgB,QAAQ,IAAI,OAAO;EACvD,OAAO,EAAE,KAAK,MAAM,cAAc,SAAS,KAAK,CAAC;CACnD,CAAC;CAED,IAAI,QAAQ,mBAAmB,OAAO,MAAM;EAC1C,MAAM,EAAE,MAAM,YAAY,EAAE,IAAI,MAAM,OAAO;EAC7C,MAAM,UAAU,MAAM,yBAAyB,GAAG,MAAM,GAAG,cAAc;EACzE,MAAM,QAAQ,MAAM,gBAAgB,QAAQ,IAAI,OAAO;EACvD,MAAM,SAAS,MAAM,gBAAgB,CAAC;EACtC,MAAM,SAAS,MAAM,YAAY,SAAS,OAAO,QAAQ,EAAE,IAAI,MAAM,MAAM,CAAC;EAC5E,UAAU,CAAC;EACX,QAAQ,GAAG,kBAAkB;EAC7B,OAAO,EAAE,KAAK,QAAQ,GAAG;CAC3B,CAAC;AACH"}

package/dist/routers/builds.handlers.mjs

@@ -5,15 +5,16 @@ import { credentialKeys } from "../credential-keys.mjs";
 import { getStore } from "../store.mjs";
 import { notifyProject } from "../notify.mjs";
 import { notFound } from "./helpers.mjs";
-import { assertBaselineCurrent } from "./baseline-guard.mjs";
+import { requestBuildState } from "../git-status.mjs";
+import { assertBaselineCurrent, baselineChanged } from "./baseline-guard.mjs";
 import { z } from "@hono/zod-openapi";
-import { extractStorybookToScratch, persistStorybookStatics } from "@storyshelf/core/capture";
-import { BaselineModel, BuildModel, LabelModel, ProjectModel, SnapshotModel } from "@storyshelf/core/models";
-import { BUILD_STATUSES } from "@storyshelf/core/types";
+import { BaselineApprovalConflict, BaselineModel, BaselineWriteConflict, BuildModel, LabelModel, ProjectModel, SnapshotModel } from "@storyshelf/core/models";
 import { HTTPException } from "hono/http-exception";
 import { emitWebhookEvent } from "@storyshelf/core/adapter/webhook-events";
+import { BUILD_STATUSES } from "@storyshelf/core/types";
+import { ReferenceGenerationConflict } from "@storyshelf/core/adapter/database";
 import { Readable, Transform } from "node:stream";
-//#region src/routers/builds.handlers.ts
+// src/routers/builds.handlers.ts
 /**
 * Create a build record with labels and the `build:created` webhook.
 * Shared by the build-creation route.
@@ -48,10 +49,12 @@ async function createBuildRecord(project, meta) {
 		authorName: meta.authorName,
 		message: meta.message
 	}, `/builds/${build.id}`);
+	await requestBuildState(build.id);
 	return build;
 }
 /**
-* Stream a raw request body into storage with a byte cap.
+* Stream a raw request body into storage with a byte cap, counting the bytes as they pass (a
+* chunked upload has no `Content-Length`). Resolves to the bytes stored.
 * Throws 400 for a missing body, 413 once `maxBytes` is exceeded.
 */
 async function storeUploadStream(storage, path, body, maxBytes) {
@@ -65,34 +68,12 @@ async function storeUploadStream(storage, path, body, maxBytes) {
 	try {
 		const nodeBody = Readable.fromWeb(body);
 		await storage.writeStream(path, nodeBody.pipe(limiter));
+		return seen;
 	} catch (error) {
 		if (seen > maxBytes) throw new HTTPException(413, { message: "Upload exceeds size limit" });
 		throw error;
 	}
 }
-/**
-* Best-effort inline statics extraction for small uploads (see
-* `maxInlineUnzipSize`). Never throws: failures are logged and the capture
-* job backfills the same keys idempotently.
-*/
-async function persistInlineStatics(storage, scratchDir, maxInlineBytes, contentLength, projectId, buildId, logger) {
-	if (!scratchDir || !maxInlineBytes) return;
-	const size = parseContentLength(contentLength);
-	if (size === void 0 || size > maxInlineBytes) return;
-	try {
-		const extractedDir = await extractStorybookToScratch(storage, scratchDir, projectId, buildId);
-		await persistStorybookStatics(storage, extractedDir, projectId, buildId);
-		logger.info({
-			buildId,
-			size
-		}, "upload statics persisted inline");
-	} catch (error) {
-		logger.error({
-			err: error,
-			buildId
-		}, "inline statics persist failed; capture will backfill");
-	}
-}
 /** Query filters accepted by the build list endpoint. */
 const buildListQuery = z.object({
 	status: z.enum(BUILD_STATUSES).optional(),
@@ -112,34 +93,46 @@ async function snapshotForBuild(build, snapshotId) {
 	if (!snapshot || snapshot.buildId !== build.id) notFound("Snapshot not found");
 	return snapshot;
 }
+/** Roll snapshot statuses up into the build's review status. */
+function rollupStatus(snapshots) {
+	if (snapshots.some((s) => s.status === "new" || s.status === "changed")) return "reviewing";
+	return snapshots.some((s) => s.status === "rejected") ? "rejected" : "approved";
+}
 /** Recompute a build's counts and roll its status up from its snapshots. */
 async function refreshBuild(buildId) {
-	const { db, config } = getStore();
+	const { db } = getStore();
 	await new BuildModel(db).updateCounts(buildId);
 	const snapshots = await new SnapshotModel(db).listByBuild(buildId);
-	const unresolved = snapshots.some((s) => s.status === "new" || s.status === "changed");
-	let status;
-	if (unresolved) status = "reviewing";
-	else status = snapshots.some((s) => s.status === "rejected") ? "rejected" : "approved";
+	const status = rollupStatus(snapshots);
 	const build = await new BuildModel(db).get(buildId);
-	if (build) {
-		await new BuildModel(db).setStatus(buildId, status);
-		await emitWebhookEvent(db, { webhooks: getStore().db.tables.webhooks }, build.projectId, `build:${status}`, {
-			buildId,
-			status,
-			snapshotCount: snapshots.length
-		}, credentialKeys(config));
-		const project = await new ProjectModel(db).get(build.projectId);
-		if (project) await notifyProject(project, `build:${status}`, {
-			buildId,
-			status,
-			snapshotCount: snapshots.length
-		}, `/builds/${buildId}`);
-	}
+	if (!build || build.status === "cancelled") return;
+	await new BuildModel(db).setStatus(buildId, status);
+	await announceBuildStatus(buildId, status, { snapshotCount: snapshots.length });
+}
+/**
+* Tell the world a build reached `status`: its git channels, the `build:<status>` webhook and the
+* project's notification channels. Every route that moves a build to a decided status ends here.
+*/
+async function announceBuildStatus(buildId, status, extra = {}) {
+	const { db, config } = getStore();
+	const build = await new BuildModel(db).get(buildId);
+	if (!build) return;
+	await requestBuildState(buildId);
+	const payload = {
+		buildId,
+		status,
+		...extra
+	};
+	await emitWebhookEvent(db, { webhooks: getStore().db.tables.webhooks }, build.projectId, `build:${status}`, payload, credentialKeys(config));
+	const project = await new ProjectModel(db).get(build.projectId);
+	if (!project) return;
+	await notifyProject(project, `build:${status}`, payload, `/builds/${buildId}`);
 }
 /**
 * Approve a snapshot, promote its screenshot to baseline, and refresh the build.
 * Refuses with 409 when the baseline changed since the diff, unless `force` is set.
+* Bulk callers pass `deferRefresh` and call {@link refreshBuild} once, so the build's
+* outcome (and its git status) is announced a single time.
 */
 async function approveSnapshot(snapshotId, userId, options = {}) {
 	const { db, config } = getStore();
@@ -149,19 +142,38 @@ async function approveSnapshot(snapshotId, userId, options = {}) {
 	const project = await new ProjectModel(db).get(snapshot.projectId);
 	const build = await new BuildModel(db).get(snapshot.buildId);
 	if (!project || !build) notFound("Project or build not found");
+	if (build.status === "cancelled") throw new HTTPException(409, { message: "The build was cancelled; retry it to review it" });
 	await assertBaselineCurrent(project, build, snapshot, options.force ?? false);
-	await snapshots.review(snapshotId, "approved", userId);
+	if (!db.buildReferenceLifecycle) await snapshots.review(snapshotId, "approved", userId);
 	const baselines = new BaselineModel(db, void 0, getStore().storage, credentialKeys(config));
-	const prior = await baselines.getFor(project.id, snapshot.storyId, snapshot.viewportName, build.gitBranch);
-	await baselines.upsert(project.id, snapshot.storyId, snapshot.viewportName, build.gitBranch, snapshot.id, snapshot.screenshotPath);
+	const prior = await baselines.getFor(project.id, snapshot.storyId, snapshot.viewportName, build.gitBranch, snapshot.browser);
+	try {
+		await baselines.upsert(project.id, snapshot.storyId, snapshot.viewportName, build.gitBranch, snapshot.id, snapshot.screenshotPath, void 0, {
+			browser: snapshot.browser,
+			mode: snapshot.mode,
+			approval: db.buildReferenceLifecycle ? {
+				snapshot,
+				reviewedBy: userId,
+				force: options.force ?? false,
+				branch: build.gitBranch
+			} : void 0
+		});
+	} catch (error) {
+		if (error instanceof BaselineWriteConflict || error instanceof ReferenceGenerationConflict) {
+			if (error instanceof BaselineApprovalConflict && error.driftStatus) throw baselineChanged(snapshot.id, error.driftStatus);
+			throw new HTTPException(409, { message: error.message });
+		}
+		throw error;
+	}
 	await notifyProject(project, prior ? "baseline:updated" : "baseline:created", {
 		storyId: snapshot.storyId,
 		viewport: snapshot.viewportName,
+		browser: snapshot.browser ?? "chromium",
 		branch: build.gitBranch,
 		snapshotId: snapshot.id,
 		buildId: build.id
 	}, `/builds/${build.id}`);
-	await refreshBuild(build.id);
+	if (!options.deferRefresh) await refreshBuild(build.id);
 }
 /** Roles permitted to view builds, snapshots, and comments. */
 const VIEW_ROLES = [
@@ -205,13 +217,6 @@ async function attachLabels(db, projectId, buildId, labels) {
 		await models.attach(projectId, buildId, key, value);
 	}
 }
-/** Parse a Content-Length header value into bytes, or undefined when unknown. */
-function parseContentLength(value) {
-	if (!value) return;
-	const parsed = Math.trunc(Number(value));
-	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : void 0;
-}
-//#endregion
-export { APPROVER_ROLES, DEVELOPER_ROLES, VIEW_ROLES, approveSnapshot, buildCreateJsonSchema, buildForProject, buildListQuery, createBuildRecord, persistInlineStatics, refreshBuild, snapshotForBuild, storeUploadStream };
+export { APPROVER_ROLES, DEVELOPER_ROLES, VIEW_ROLES, announceBuildStatus, approveSnapshot, buildCreateJsonSchema, buildForProject, buildListQuery, createBuildRecord, refreshBuild, snapshotForBuild, storeUploadStream };
 
 //# sourceMappingURL=builds.handlers.mjs.map

package/dist/routers/builds.handlers.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"builds.handlers.mjs","names":[],"sources":["../../src/routers/builds.handlers.ts"],"sourcesContent":["import { z } from \"@hono/zod-openapi\";\nimport type { DatabaseAdapter } from \"@storyshelf/core/adapter/database\";\nimport type { StorageAdapter } from \"@storyshelf/core/adapter/storage\";\nimport { emitWebhookEvent } from \"@storyshelf/core/adapter/webhook-events\";\nimport { extractStorybookToScratch, persistStorybookStatics } from \"@storyshelf/core/capture\";\nimport type { Logger } from \"@storyshelf/core/logger\";\nimport { BaselineModel } from \"@storyshelf/core/models\";\nimport { BuildModel } from \"@storyshelf/core/models\";\nimport { LabelModel } from \"@storyshelf/core/models\";\nimport { ProjectModel } from \"@storyshelf/core/models\";\nimport { SnapshotModel } from \"@storyshelf/core/models\";\nimport type { Project } from \"@storyshelf/core/schema\";\nimport type { Build, Snapshot } from \"@storyshelf/core/schema\";\nimport { type ProjectRole, BUILD_STATUSES } from \"@storyshelf/core/types\";\nimport { HTTPException } from \"hono/http-exception\";\nimport { Readable, Transform } from \"node:stream\";\nimport type { ReadableStream as NodeWebStream } from \"node:stream/web\";\nimport { credentialKeys } from \"../credential-keys.ts\";\nimport { notifyProject } from \"../notify.ts\";\nimport { getStore } from \"../store.ts\";\nimport { assertBaselineCurrent } from \"./baseline-guard.ts\";\nimport { notFound } from \"./helpers.ts\";\n/**\n * Create a build record with labels and the `build:created` webhook.\n * Shared by the build-creation route.\n */\nexport async function createBuildRecord(\n  project: Project,\n  meta: BuildCreateMetadata,\n): Promise<Build> {\n  const { db, config } = getStore();\n  if (!meta.gitSha || !meta.gitBranch) {\n    throw new HTTPException(400, {\n      message: \"gitSha and gitBranch are required (revision SHA and baseline namespace)\",\n    });\n  }\n  const build = await new BuildModel(db).create(project.id, {\n    gitSha: meta.gitSha,\n    gitBranch: meta.gitBranch,\n    isDefault: meta.gitBranch === project.gitDefaultBranch,\n    authorEmail: meta.authorEmail,\n    authorName: meta.authorName,\n    message: meta.message,\n    affectedOnly: meta.affectedOnly,\n    baselineSha: await resolveBaselineSha(db, project.id, meta.gitBranch, meta.gitSha),\n  });\n  if (meta.labels && meta.labels.length > 0) {\n    await attachLabels(db, project.id, build.id, meta.labels);\n  }\n  await emitWebhookEvent(\n    db,\n    { webhooks: getStore().db.tables.webhooks },\n    project.id,\n    \"build:created\",\n    {\n      buildId: build.id,\n      gitSha: meta.gitSha,\n      gitBranch: meta.gitBranch,\n      authorEmail: meta.authorEmail,\n      authorName: meta.authorName,\n      message: meta.message,\n    },\n    credentialKeys(config),\n  );\n  await notifyProject(\n    project,\n    \"build:created\",\n    {\n      buildId: build.id,\n      gitSha: meta.gitSha,\n      gitBranch: meta.gitBranch,\n      authorEmail: meta.authorEmail,\n      authorName: meta.authorName,\n      message: meta.message,\n    },\n    `/builds/${build.id}`,\n  );\n  return build;\n}\n\n/**\n * Stream a raw request body into storage with a byte cap.\n * Throws 400 for a missing body, 413 once `maxBytes` is exceeded.\n */\nexport async function storeUploadStream(\n  storage: StorageAdapter,\n  path: string,\n  body: ReadableStream<Uint8Array> | null,\n  maxBytes: number,\n): Promise<void> {\n  if (!body) {\n    throw new HTTPException(400, { message: \"Missing request body\" });\n  }\n  let seen = 0;\n  const limiter = new Transform({\n    transform(\n      chunk: Buffer,\n      _encoding: string,\n      callback: (error?: Error | null, data?: Buffer) => void,\n    ): void {\n      seen += chunk.length;\n      if (seen > maxBytes) {\n        callback(new Error(`Upload exceeds ${maxBytes} byte limit`));\n      } else {\n        callback(null, chunk);\n      }\n    },\n  });\n  try {\n    const nodeBody = Readable.fromWeb(body as unknown as NodeWebStream);\n    await storage.writeStream(path, nodeBody.pipe(limiter));\n  } catch (error) {\n    if (seen > maxBytes) {\n      throw new HTTPException(413, { message: \"Upload exceeds size limit\" });\n    }\n    throw error;\n  }\n}\n\n/**\n * Best-effort inline statics extraction for small uploads (see\n * `maxInlineUnzipSize`). Never throws: failures are logged and the capture\n * job backfills the same keys idempotently.\n */\nexport async function persistInlineStatics(\n  storage: StorageAdapter,\n  scratchDir: string | undefined,\n  maxInlineBytes: number | undefined,\n  contentLength: string | undefined,\n  projectId: string,\n  buildId: string,\n  logger: Logger,\n): Promise<void> {\n  if (!scratchDir || !maxInlineBytes) {\n    return;\n  }\n  const size = parseContentLength(contentLength);\n  if (size === undefined || size > maxInlineBytes) {\n    return;\n  }\n  try {\n    const extractedDir = await extractStorybookToScratch(storage, scratchDir, projectId, buildId);\n    await persistStorybookStatics(storage, extractedDir, projectId, buildId);\n    logger.info({ buildId, size }, \"upload statics persisted inline\");\n  } catch (error) {\n    logger.error({ err: error, buildId }, \"inline statics persist failed; capture will backfill\");\n  }\n}\n\n/** Query filters accepted by the build list endpoint. */\nexport const buildListQuery = z.object({\n  status: z.enum(BUILD_STATUSES).optional(),\n  branch: z.string().optional(),\n  labelKey: z.string().optional(),\n  labelValue: z.string().optional(),\n});\n\n/** Fetch a build scoped to its project, throwing 404 when it does not belong. */\nexport async function buildForProject(projectId: string, buildId: string): Promise<Build> {\n  const build = await new BuildModel(getStore().db).get(buildId);\n  if (!build || build.projectId !== projectId) {\n    notFound(\"Build not found\");\n  }\n  return build;\n}\n\n/** Fetch a snapshot scoped to its build, throwing 404 when it does not belong. */\nexport async function snapshotForBuild(\n  build: { id: string },\n  snapshotId: string,\n): Promise<Snapshot> {\n  const snapshot = await new SnapshotModel(getStore().db).get(snapshotId);\n  if (!snapshot || snapshot.buildId !== build.id) {\n    notFound(\"Snapshot not found\");\n  }\n  return snapshot;\n}\n\n/** Recompute a build's counts and roll its status up from its snapshots. */\nexport async function refreshBuild(buildId: string): Promise<void> {\n  const { db, config } = getStore();\n  await new BuildModel(db).updateCounts(buildId);\n  const snapshots = await new SnapshotModel(db).listByBuild(buildId);\n  const unresolved = snapshots.some((s) => s.status === \"new\" || s.status === \"changed\");\n  let status: \"reviewing\" | \"rejected\" | \"approved\";\n  if (unresolved) {\n    status = \"reviewing\";\n  } else {\n    const rejected = snapshots.some((s) => s.status === \"rejected\");\n    status = rejected ? \"rejected\" : \"approved\";\n  }\n  const build = await new BuildModel(db).get(buildId);\n  if (build) {\n    await new BuildModel(db).setStatus(buildId, status);\n    await emitWebhookEvent(\n      db,\n      { webhooks: getStore().db.tables.webhooks },\n      build.projectId,\n      `build:${status}`,\n      {\n        buildId,\n        status,\n        snapshotCount: snapshots.length,\n      },\n      credentialKeys(config),\n    );\n    const project = await new ProjectModel(db).get(build.projectId);\n    if (project) {\n      await notifyProject(\n        project,\n        `build:${status}`,\n        { buildId, status, snapshotCount: snapshots.length },\n        `/builds/${buildId}`,\n      );\n    }\n  }\n}\n\n/**\n * Approve a snapshot, promote its screenshot to baseline, and refresh the build.\n * Refuses with 409 when the baseline changed since the diff, unless `force` is set.\n */\nexport async function approveSnapshot(\n  snapshotId: string,\n  userId: string | null,\n  options: { force?: boolean } = {},\n): Promise<void> {\n  const { db, config } = getStore();\n  const snapshots = new SnapshotModel(db);\n  const snapshot = await snapshots.get(snapshotId);\n  if (!snapshot) {\n    notFound(\"Snapshot not found\");\n  }\n  const project = await new ProjectModel(db).get(snapshot.projectId);\n  const build = await new BuildModel(db).get(snapshot.buildId);\n  if (!project || !build) {\n    notFound(\"Project or build not found\");\n  }\n  await assertBaselineCurrent(project, build, snapshot, options.force ?? false);\n  await snapshots.review(snapshotId, \"approved\", userId);\n  const baselines = new BaselineModel(db, undefined, getStore().storage, credentialKeys(config));\n  const prior = await baselines.getFor(\n    project.id,\n    snapshot.storyId,\n    snapshot.viewportName,\n    build.gitBranch,\n  );\n  await baselines.upsert(\n    project.id,\n    snapshot.storyId,\n    snapshot.viewportName,\n    build.gitBranch,\n    snapshot.id,\n    snapshot.screenshotPath,\n  );\n  await notifyProject(\n    project,\n    prior ? \"baseline:updated\" : \"baseline:created\",\n    {\n      storyId: snapshot.storyId,\n      viewport: snapshot.viewportName,\n      branch: build.gitBranch,\n      snapshotId: snapshot.id,\n      buildId: build.id,\n    },\n    `/builds/${build.id}`,\n  );\n  await refreshBuild(build.id);\n}\n\n/** Roles permitted to view builds, snapshots, and comments. */\nexport const VIEW_ROLES: readonly ProjectRole[] = [\"viewer\", \"developer\", \"approver\", \"admin\"];\n/** Roles permitted to upload builds and write comments. */\nexport const DEVELOPER_ROLES: readonly ProjectRole[] = [\"developer\", \"approver\", \"admin\"];\n/** Roles permitted to approve or reject snapshots and delete builds. */\nexport const APPROVER_ROLES: readonly ProjectRole[] = [\"approver\", \"admin\"];\n\n/** JSON input schema for creating a build before streaming its bundle. */\nexport const buildCreateJsonSchema = z\n  .object({\n    gitSha: z.string().min(1),\n    gitBranch: z.string().min(1),\n    authorEmail: z.string().optional(),\n    authorName: z.string().optional(),\n    message: z.string().optional(),\n    affectedOnly: z.boolean().optional(),\n    labels: z.array(z.object({ key: z.string().min(1), value: z.string() })).optional(),\n  })\n  .openapi(\"BuildCreate\");\n\n/** Metadata accepted by either build-creation route. */\nexport interface BuildCreateMetadata {\n  gitSha: string;\n  gitBranch: string;\n  authorEmail?: string;\n  authorName?: string;\n  message?: string;\n  affectedOnly?: boolean;\n  labels?: { key: string; value: string }[];\n}\n\n/** Latest prior revision on a branch with a build, or null for first builds. */\nasync function resolveBaselineSha(\n  db: DatabaseAdapter,\n  projectId: string,\n  branch: string,\n  sha: string,\n): Promise<string | null> {\n  const builds = await new BuildModel(db).list(projectId, { branch });\n  return builds.find((build) => build.gitSha !== sha)?.gitSha ?? null;\n}\n\n/* oxlint-disable eslint/no-await-in-loop -- label attach is intentionally sequential */\nasync function attachLabels(\n  db: DatabaseAdapter,\n  projectId: string,\n  buildId: string,\n  labels: { key: string; value: string }[],\n): Promise<void> {\n  const models = new LabelModel(db);\n  for (const { key, value } of labels) {\n    const existing = await models.getType(projectId, key);\n    if (!existing) {\n      await models.createType(projectId, { key, name: key });\n    }\n    await models.attach(projectId, buildId, key, value);\n  }\n}\n/* oxlint-enable eslint/no-await-in-loop */\n\n/** Parse a Content-Length header value into bytes, or undefined when unknown. */\nfunction parseContentLength(value: string | undefined): number | undefined {\n  if (!value) {\n    return undefined;\n  }\n  const parsed = Math.trunc(Number(value));\n  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;\n}\n"],"mappings":"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"}
+{"version":3,"file":"builds.handlers.mjs","names":[],"sources":["../../src/routers/builds.handlers.ts"],"sourcesContent":["import { z } from \"@hono/zod-openapi\";\nimport {\n  ReferenceGenerationConflict,\n  type DatabaseAdapter,\n} from \"@storyshelf/core/adapter/database\";\nimport type { StorageAdapter } from \"@storyshelf/core/adapter/storage\";\nimport { emitWebhookEvent } from \"@storyshelf/core/adapter/webhook-events\";\nimport {\n  BaselineApprovalConflict,\n  BaselineModel,\n  BaselineWriteConflict,\n} from \"@storyshelf/core/models\";\nimport { BuildModel } from \"@storyshelf/core/models\";\nimport { LabelModel } from \"@storyshelf/core/models\";\nimport { ProjectModel } from \"@storyshelf/core/models\";\nimport { SnapshotModel } from \"@storyshelf/core/models\";\nimport type { Project } from \"@storyshelf/core/schema\";\nimport type { Build, Snapshot } from \"@storyshelf/core/schema\";\nimport { type BuildStatus, type ProjectRole, BUILD_STATUSES } from \"@storyshelf/core/types\";\nimport { HTTPException } from \"hono/http-exception\";\nimport { Readable, Transform } from \"node:stream\";\nimport type { ReadableStream as NodeWebStream } from \"node:stream/web\";\nimport { credentialKeys } from \"../credential-keys.ts\";\nimport { requestBuildState } from \"../git-status.ts\";\nimport { notifyProject } from \"../notify.ts\";\nimport { getStore } from \"../store.ts\";\nimport { assertBaselineCurrent, baselineChanged } from \"./baseline-guard.ts\";\nimport { notFound } from \"./helpers.ts\";\n/**\n * Create a build record with labels and the `build:created` webhook.\n * Shared by the build-creation route.\n */\nexport async function createBuildRecord(\n  project: Project,\n  meta: BuildCreateMetadata,\n): Promise<Build> {\n  const { db, config } = getStore();\n  if (!meta.gitSha || !meta.gitBranch) {\n    throw new HTTPException(400, {\n      message: \"gitSha and gitBranch are required (revision SHA and baseline namespace)\",\n    });\n  }\n  const build = await new BuildModel(db).create(project.id, {\n    gitSha: meta.gitSha,\n    gitBranch: meta.gitBranch,\n    isDefault: meta.gitBranch === project.gitDefaultBranch,\n    authorEmail: meta.authorEmail,\n    authorName: meta.authorName,\n    message: meta.message,\n    affectedOnly: meta.affectedOnly,\n    baselineSha: await resolveBaselineSha(db, project.id, meta.gitBranch, meta.gitSha),\n  });\n  if (meta.labels && meta.labels.length > 0) {\n    await attachLabels(db, project.id, build.id, meta.labels);\n  }\n  await emitWebhookEvent(\n    db,\n    { webhooks: getStore().db.tables.webhooks },\n    project.id,\n    \"build:created\",\n    {\n      buildId: build.id,\n      gitSha: meta.gitSha,\n      gitBranch: meta.gitBranch,\n      authorEmail: meta.authorEmail,\n      authorName: meta.authorName,\n      message: meta.message,\n    },\n    credentialKeys(config),\n  );\n  await notifyProject(\n    project,\n    \"build:created\",\n    {\n      buildId: build.id,\n      gitSha: meta.gitSha,\n      gitBranch: meta.gitBranch,\n      authorEmail: meta.authorEmail,\n      authorName: meta.authorName,\n      message: meta.message,\n    },\n    `/builds/${build.id}`,\n  );\n  await requestBuildState(build.id);\n  return build;\n}\n\n/**\n * Stream a raw request body into storage with a byte cap, counting the bytes as they pass (a\n * chunked upload has no `Content-Length`). Resolves to the bytes stored.\n * Throws 400 for a missing body, 413 once `maxBytes` is exceeded.\n */\nexport async function storeUploadStream(\n  storage: StorageAdapter,\n  path: string,\n  body: ReadableStream<Uint8Array> | null,\n  maxBytes: number,\n): Promise<number> {\n  if (!body) {\n    throw new HTTPException(400, { message: \"Missing request body\" });\n  }\n  let seen = 0;\n  const limiter = new Transform({\n    transform(\n      chunk: Buffer,\n      _encoding: string,\n      callback: (error?: Error | null, data?: Buffer) => void,\n    ): void {\n      seen += chunk.length;\n      if (seen > maxBytes) {\n        callback(new Error(`Upload exceeds ${maxBytes} byte limit`));\n      } else {\n        callback(null, chunk);\n      }\n    },\n  });\n  try {\n    const nodeBody = Readable.fromWeb(body as unknown as NodeWebStream);\n    await storage.writeStream(path, nodeBody.pipe(limiter));\n    return seen;\n  } catch (error) {\n    if (seen > maxBytes) {\n      throw new HTTPException(413, { message: \"Upload exceeds size limit\" });\n    }\n    throw error;\n  }\n}\n\n/** Query filters accepted by the build list endpoint. */\nexport const buildListQuery = z.object({\n  status: z.enum(BUILD_STATUSES).optional(),\n  branch: z.string().optional(),\n  labelKey: z.string().optional(),\n  labelValue: z.string().optional(),\n});\n\n/** Fetch a build scoped to its project, throwing 404 when it does not belong. */\nexport async function buildForProject(projectId: string, buildId: string): Promise<Build> {\n  const build = await new BuildModel(getStore().db).get(buildId);\n  if (!build || build.projectId !== projectId) {\n    notFound(\"Build not found\");\n  }\n  return build;\n}\n\n/** Fetch a snapshot scoped to its build, throwing 404 when it does not belong. */\nexport async function snapshotForBuild(\n  build: { id: string },\n  snapshotId: string,\n): Promise<Snapshot> {\n  const snapshot = await new SnapshotModel(getStore().db).get(snapshotId);\n  if (!snapshot || snapshot.buildId !== build.id) {\n    notFound(\"Snapshot not found\");\n  }\n  return snapshot;\n}\n\n/** Roll snapshot statuses up into the build's review status. */\nfunction rollupStatus(snapshots: Snapshot[]): \"reviewing\" | \"rejected\" | \"approved\" {\n  if (snapshots.some((s) => s.status === \"new\" || s.status === \"changed\")) {\n    return \"reviewing\";\n  }\n  return snapshots.some((s) => s.status === \"rejected\") ? \"rejected\" : \"approved\";\n}\n\n/** Recompute a build's counts and roll its status up from its snapshots. */\nexport async function refreshBuild(buildId: string): Promise<void> {\n  const { db } = getStore();\n  await new BuildModel(db).updateCounts(buildId);\n  const snapshots = await new SnapshotModel(db).listByBuild(buildId);\n  const status = rollupStatus(snapshots);\n  const build = await new BuildModel(db).get(buildId);\n  // A cancelled build is terminal: its snapshots may still be touched, but no verdict is announced.\n  if (!build || build.status === \"cancelled\") return;\n  await new BuildModel(db).setStatus(buildId, status);\n  await announceBuildStatus(buildId, status, { snapshotCount: snapshots.length });\n}\n\n/**\n * Tell the world a build reached `status`: its git channels, the `build:<status>` webhook and the\n * project's notification channels. Every route that moves a build to a decided status ends here.\n */\nexport async function announceBuildStatus(\n  buildId: string,\n  status: BuildStatus,\n  extra: { snapshotCount?: number } = {},\n): Promise<void> {\n  const { db, config } = getStore();\n  const build = await new BuildModel(db).get(buildId);\n  if (!build) return;\n  await requestBuildState(buildId);\n  const payload = { buildId, status, ...extra };\n  await emitWebhookEvent(\n    db,\n    { webhooks: getStore().db.tables.webhooks },\n    build.projectId,\n    `build:${status}`,\n    payload,\n    credentialKeys(config),\n  );\n  const project = await new ProjectModel(db).get(build.projectId);\n  if (!project) return;\n  await notifyProject(project, `build:${status}`, payload, `/builds/${buildId}`);\n}\n\n/**\n * Approve a snapshot, promote its screenshot to baseline, and refresh the build.\n * Refuses with 409 when the baseline changed since the diff, unless `force` is set.\n * Bulk callers pass `deferRefresh` and call {@link refreshBuild} once, so the build's\n * outcome (and its git status) is announced a single time.\n */\nexport async function approveSnapshot(\n  snapshotId: string,\n  userId: string | null,\n  options: { force?: boolean; deferRefresh?: boolean } = {},\n): Promise<void> {\n  const { db, config } = getStore();\n  const snapshots = new SnapshotModel(db);\n  const snapshot = await snapshots.get(snapshotId);\n  if (!snapshot) {\n    notFound(\"Snapshot not found\");\n  }\n  const project = await new ProjectModel(db).get(snapshot.projectId);\n  const build = await new BuildModel(db).get(snapshot.buildId);\n  if (!project || !build) {\n    notFound(\"Project or build not found\");\n  }\n  if (build.status === \"cancelled\") {\n    throw new HTTPException(409, { message: \"The build was cancelled; retry it to review it\" });\n  }\n  await assertBaselineCurrent(project, build, snapshot, options.force ?? false);\n  if (!db.buildReferenceLifecycle) await snapshots.review(snapshotId, \"approved\", userId);\n  const baselines = new BaselineModel(db, undefined, getStore().storage, credentialKeys(config));\n  const prior = await baselines.getFor(\n    project.id,\n    snapshot.storyId,\n    snapshot.viewportName,\n    build.gitBranch,\n    snapshot.browser,\n  );\n  try {\n    await baselines.upsert(\n      project.id,\n      snapshot.storyId,\n      snapshot.viewportName,\n      build.gitBranch,\n      snapshot.id,\n      snapshot.screenshotPath,\n      undefined,\n      {\n        browser: snapshot.browser,\n        mode: snapshot.mode,\n        approval: db.buildReferenceLifecycle\n          ? { snapshot, reviewedBy: userId, force: options.force ?? false, branch: build.gitBranch }\n          : undefined,\n      },\n    );\n  } catch (error) {\n    if (error instanceof BaselineWriteConflict || error instanceof ReferenceGenerationConflict) {\n      if (error instanceof BaselineApprovalConflict && error.driftStatus)\n        throw baselineChanged(snapshot.id, error.driftStatus);\n      throw new HTTPException(409, { message: error.message });\n    }\n    throw error;\n  }\n  await notifyProject(\n    project,\n    prior ? \"baseline:updated\" : \"baseline:created\",\n    {\n      storyId: snapshot.storyId,\n      viewport: snapshot.viewportName,\n      browser: snapshot.browser ?? \"chromium\",\n      branch: build.gitBranch,\n      snapshotId: snapshot.id,\n      buildId: build.id,\n    },\n    `/builds/${build.id}`,\n  );\n  if (!options.deferRefresh) {\n    await refreshBuild(build.id);\n  }\n}\n\n/** Roles permitted to view builds, snapshots, and comments. */\nexport const VIEW_ROLES: readonly ProjectRole[] = [\"viewer\", \"developer\", \"approver\", \"admin\"];\n/** Roles permitted to upload builds and write comments. */\nexport const DEVELOPER_ROLES: readonly ProjectRole[] = [\"developer\", \"approver\", \"admin\"];\n/** Roles permitted to approve or reject snapshots and delete builds. */\nexport const APPROVER_ROLES: readonly ProjectRole[] = [\"approver\", \"admin\"];\n\n/** JSON input schema for creating a build before streaming its bundle. */\nexport const buildCreateJsonSchema = z\n  .object({\n    gitSha: z.string().min(1),\n    gitBranch: z.string().min(1),\n    authorEmail: z.string().optional(),\n    authorName: z.string().optional(),\n    message: z.string().optional(),\n    affectedOnly: z.boolean().optional(),\n    labels: z.array(z.object({ key: z.string().min(1), value: z.string() })).optional(),\n  })\n  .openapi(\"BuildCreate\");\n\n/** Metadata accepted by either build-creation route. */\nexport interface BuildCreateMetadata {\n  gitSha: string;\n  gitBranch: string;\n  authorEmail?: string;\n  authorName?: string;\n  message?: string;\n  affectedOnly?: boolean;\n  labels?: { key: string; value: string }[];\n}\n\n/** Latest prior revision on a branch with a build, or null for first builds. */\nasync function resolveBaselineSha(\n  db: DatabaseAdapter,\n  projectId: string,\n  branch: string,\n  sha: string,\n): Promise<string | null> {\n  const builds = await new BuildModel(db).list(projectId, { branch });\n  return builds.find((build) => build.gitSha !== sha)?.gitSha ?? null;\n}\n\n/* oxlint-disable eslint/no-await-in-loop -- label attach is intentionally sequential */\nasync function attachLabels(\n  db: DatabaseAdapter,\n  projectId: string,\n  buildId: string,\n  labels: { key: string; value: string }[],\n): Promise<void> {\n  const models = new LabelModel(db);\n  for (const { key, value } of labels) {\n    const existing = await models.getType(projectId, key);\n    if (!existing) {\n      await models.createType(projectId, { key, name: key });\n    }\n    await models.attach(projectId, buildId, key, value);\n  }\n}\n/* oxlint-enable eslint/no-await-in-loop */\n"],"mappings":"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"}

package/dist/routers/builds.mjs

@@ -2,20 +2,33 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { getStore } from "../store.mjs";
+import { resolveAuthorizedProject } from "./helpers.mjs";
 import { hxRefresh } from "./htmx.mjs";
 import { flashHx } from "./flash.mjs";
-import { resolveAuthorizedProject } from "./helpers.mjs";
 import { badRequest, buildSchema, forbidden, notFound, unauthorized } from "./schemas.mjs";
-import { APPROVER_ROLES, DEVELOPER_ROLES, VIEW_ROLES, buildCreateJsonSchema, buildForProject, buildListQuery, createBuildRecord, persistInlineStatics, storeUploadStream } from "./builds.handlers.mjs";
+import { APPROVER_ROLES, DEVELOPER_ROLES, VIEW_ROLES, buildCreateJsonSchema, buildForProject, buildListQuery, createBuildRecord, storeUploadStream } from "./builds.handlers.mjs";
 import { registerAttempts } from "./attempts.mjs";
+import { discardZip, planUpload, publishUpload } from "./publish-upload.mjs";
+import { registerBuildCancel } from "./build-cancel.mjs";
+import { registerBuildChangeset } from "./build-changeset.mjs";
+import { registerBuildReviews } from "./build-reviews.mjs";
 import { registerComments } from "./comments.mjs";
 import { registerSnapshots } from "./snapshots.mjs";
 import { createRoute, z } from "@hono/zod-openapi";
-import { BuildModel } from "@storyshelf/core/models";
+import { DEFAULT_MAX_UPLOAD_BYTES } from "@storyshelf/core/config";
 import { storybookZipPath } from "@storyshelf/core/utils";
+import { BuildModel, PackageUsageModel } from "@storyshelf/core/models";
 import { HTTPException } from "hono/http-exception";
-import { DEFAULT_MAX_UPLOAD_BYTES } from "@storyshelf/core/config";
-//#region src/routers/builds.ts
+// src/routers/builds.ts
+/** Decide how the stored zip is published; a zip this host cannot publish is removed and refused. */
+async function planOrDiscard(zipBytes, projectId, buildId) {
+	try {
+		return planUpload(zipBytes);
+	} catch (error) {
+		await discardZip(projectId, buildId);
+		throw error;
+	}
+}
 async function upsertContentRef(hash) {
 	try {
 		const contentRefs = getStore().db.tables.contentRefs;
@@ -48,14 +61,13 @@ function registerBuilds(app) {
 	});
 	app.openapi(createBuildRoute, async (c) => {
 		const project = await resolveAuthorizedProject(c, c.req.valid("param").slug, ...DEVELOPER_ROLES);
-		const parsed = buildCreateJsonSchema.safeParse(await c.req.json());
-		if (!parsed.success) throw new HTTPException(400, { message: parsed.error.message });
-		const build = await createBuildRecord(project, parsed.data);
+		const build = await createBuildRecord(project, c.req.valid("json"));
 		const uploadUrl = `/api/v1/projects/${project.slug}/builds/${build.id}/zip`;
 		return c.json({
 			build,
 			uploadUrl,
-			baselineSha: build.baselineSha
+			baselineSha: build.baselineSha,
+			testing: getStore().testing
 		}, 202);
 	});
 	app.openapi(affectedRoute, async (c) => {
@@ -70,17 +82,24 @@ function registerBuilds(app) {
 		});
 		return c.json(updated);
 	});
+	app.openapi(usageRoute, async (c) => {
+		const { slug, buildId } = c.req.valid("param");
+		const project = await resolveAuthorizedProject(c, slug, ...DEVELOPER_ROLES);
+		const build = await buildForProject(project.id, buildId);
+		const { usage } = c.req.valid("json");
+		const stored = await new PackageUsageModel(getStore().db).replaceForBuild(project.id, build.id, usage);
+		return c.json({ stored });
+	});
 	app.openapi(uploadZipRoute, async (c) => {
 		const { slug, buildId } = c.req.valid("param");
 		const project = await resolveAuthorizedProject(c, slug, ...DEVELOPER_ROLES);
 		const build = await buildForProject(project.id, buildId);
 		const maxBytes = getStore().config.maxUploadBytes ?? DEFAULT_MAX_UPLOAD_BYTES;
-		await storeUploadStream(getStore().storage, storybookZipPath(project.id, build.id), c.req.raw.body, maxBytes);
+		const route = await planOrDiscard(await storeUploadStream(getStore().storage, storybookZipPath(project.id, build.id), c.req.raw.body, maxBytes), project.id, build.id);
 		const reqId = c.get("requestId");
+		const published = await publishUpload(route, build, reqId);
 		await getStore().enqueueCapture?.(build.id, reqId);
-		const { storage, config, logger } = getStore();
-		await persistInlineStatics(storage, config.scratchDir, config.maxInlineUnzipSize, c.req.header("content-length"), project.id, build.id, logger);
-		return c.json(build, 202);
+		return c.json(published, 202);
 	});
 	app.openapi(dedupRoute, async (c) => {
 		const { slug, buildId } = c.req.valid("param");
@@ -130,6 +149,7 @@ function registerBuilds(app) {
 			});
 			else await getStore().db.update(contentRefs, f.hash, { lastSeenAt: now });
 		} catch {}
+		await getStore().publish?.completer.complete(build.id, { ok: true });
 		const reqId = c.get("requestId");
 		await getStore().enqueueCapture?.(build.id, reqId);
 		return c.json({ ok: true });
@@ -144,7 +164,7 @@ function registerBuilds(app) {
 		const { slug, buildId } = c.req.valid("param");
 		const project = await resolveAuthorizedProject(c, slug, ...DEVELOPER_ROLES);
 		const build = await buildForProject(project.id, buildId);
-		const updated = await new BuildModel(getStore().db).setStatus(build.id, "pending");
+		const updated = await new BuildModel(getStore().db).resetStatus(build.id, "pending");
 		await getStore().enqueueCapture?.(build.id, c.get("requestId"));
 		hxRefresh(c);
 		flashHx(c, "Capture queued");
@@ -159,6 +179,9 @@ function registerBuilds(app) {
 	});
 	registerSnapshots(app);
 	registerComments(app);
+	registerBuildReviews(app);
+	registerBuildChangeset(app);
+	registerBuildCancel(app);
 	registerAttempts(app);
 }
 const listBuildsRoute = createRoute({
@@ -182,7 +205,8 @@ const listBuildsRoute = createRoute({
 const buildCreatedSchema = z.object({
 	build: buildSchema,
 	uploadUrl: z.string(),
-	baselineSha: z.string().nullable()
+	baselineSha: z.string().nullable(),
+	testing: z.boolean().openapi({ description: "False when the server has no `testing` option: the build is published but never captured or compared." })
 }).openapi("BuildCreated");
 const createBuildRoute = createRoute({
 	method: "post",
@@ -196,7 +220,7 @@ const createBuildRoute = createRoute({
 	responses: {
 		202: {
 			content: { "application/json": { schema: buildCreatedSchema } },
-			description: "Build created. PUT the Storybook zip to uploadUrl to queue capture."
+			description: "Build created. PUT the Storybook zip to uploadUrl to publish it (and queue capture when testing is on)."
 		},
 		...badRequest,
 		...forbidden,
@@ -221,11 +245,15 @@ const uploadZipRoute = createRoute({
 	responses: {
 		202: {
 			content: { "application/json": { schema: buildSchema } },
-			description: "Zip stored and capture queued"
+			description: "Zip stored. A zip up to maxInlineUnzipSize (default 50 MB) is extracted inline in this request; a larger one is published by a background job. With testing off, the build becomes approved when publishing finishes on the project's default branch (failed if it cannot be published) and stays pending on other branches; with testing on, capture sets the status."
+		},
+		422: {
+			content: { "text/plain": { schema: z.string() } },
+			description: "The inline zip is invalid, unsafe, or exceeds the extraction limits"
 		},
 		413: {
 			content: { "application/json": { schema: z.object({ message: z.string() }).openapi("Error") } },
-			description: "Upload exceeds the configured size limit"
+			description: "Upload exceeds the configured size limit, or the zip is over the inline limit and this host (serverless) runs no publish consumer: upload file by file instead (POST /dedup, PUT /content, POST /manifest)"
 		},
 		...badRequest,
 		...forbidden,
@@ -238,6 +266,7 @@ const dedupRoute = createRoute({
 	method: "post",
 	tags: ["Builds"],
 	summary: "Check which files need uploading",
+	description: "File-by-file upload, step 1 (dedup, content, manifest): needs no zip extraction and works on any host, serverless included. Send the content hashes; the response lists those the server does not hold yet.",
 	path: "/api/v1/projects/{slug}/builds/{buildId}/dedup",
 	request: {
 		params: z.object({
@@ -258,6 +287,7 @@ const contentUploadRoute = createRoute({
 	method: "post",
 	tags: ["Builds"],
 	summary: "Upload build content",
+	description: "File-by-file upload, step 2: store the missing files content-addressed (multipart, or one file with an X-Content-Hash header).",
 	path: "/api/v1/projects/{slug}/builds/{buildId}/content",
 	request: {
 		params: z.object({
@@ -283,6 +313,7 @@ const manifestRoute = createRoute({
 	method: "post",
 	tags: ["Builds"],
 	summary: "Store the build manifest",
+	description: "File-by-file upload, step 3: store the path-to-hash manifest. This completes publishing. With testing off the build becomes approved when it is on the project's default branch and stays pending on other branches; with testing on, a capture is queued and sets the status.",
 	path: "/api/v1/projects/{slug}/builds/{buildId}/manifest",
 	request: {
 		params: z.object({
@@ -326,6 +357,34 @@ const affectedRoute = createRoute({
 		...notFound
 	}
 });
+const usagePayloadSchema = z.object({ usage: z.array(z.object({
+	storyImportPath: z.string().min(1).max(1024),
+	packageName: z.string().min(1).max(214),
+	modulePath: z.string().min(1).max(2048),
+	version: z.string().max(128).nullable().optional()
+})).max(2e4) });
+const usageRoute = createRoute({
+	method: "post",
+	tags: ["Builds"],
+	summary: "Record the dependency packages each story uses",
+	path: "/api/v1/projects/{slug}/builds/{buildId}/usage",
+	request: {
+		params: z.object({
+			slug: z.string(),
+			buildId: z.string()
+		}),
+		body: { content: { "application/json": { schema: usagePayloadSchema } } }
+	},
+	responses: {
+		200: {
+			content: { "application/json": { schema: z.object({ stored: z.number() }) } },
+			description: "Usage recorded (replaces any earlier report for the build)"
+		},
+		...badRequest,
+		...forbidden,
+		...notFound
+	}
+});
 const getBuildRoute = createRoute({
 	method: "get",
 	tags: ["Builds"],
@@ -375,7 +434,6 @@ const deleteBuildRoute = createRoute({
 		...notFound
 	}
 });
-//#endregion
 export { registerBuilds };
 
 //# sourceMappingURL=builds.mjs.map