@storyshelf/app 0.6.2 → 0.7.0

package/dist/routers/baselines.handlers.mjs

@@ -0,0 +1,64 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { DEFAULT_MAX_UPLOAD_BYTES } from "@storyshelf/core/config";
+import { BASELINE_ARCHIVE_LIMITS } from "@storyshelf/core/models";
+import { HTTPException } from "hono/http-exception";
+//#region src/routers/baselines.handlers.ts
+/** HTTP helpers for the baseline export/import router. */
+/** Ceiling for a buffered import archive, whatever `maxUploadBytes` allows. */
+const MAX_BASELINE_IMPORT_BYTES = BASELINE_ARCHIVE_LIMITS.maxArchiveBytes;
+/** Byte limit for an import body: `maxUploadBytes`, capped because the archive is buffered. */
+function importByteLimit(config) {
+	return Math.min(config.maxUploadBytes ?? DEFAULT_MAX_UPLOAD_BYTES, MAX_BASELINE_IMPORT_BYTES);
+}
+/**
+* Buffer a request body, failing fast with 413 once it passes `maxBytes`
+* (checked against `content-length` up front and while streaming).
+*/
+async function readCappedBody(request, maxBytes) {
+	if (Number(request.headers.get("content-length") ?? 0) > maxBytes) throw tooLarge(maxBytes);
+	if (!request.body) throw new HTTPException(400, { message: "Missing request body" });
+	return await collectCapped(request.body.getReader(), maxBytes);
+}
+async function collectCapped(reader, maxBytes) {
+	const chunks = [];
+	let seen = 0;
+	let next = await reader.read();
+	while (!next.done && seen <= maxBytes) {
+		seen += next.value.length;
+		chunks.push(next.value);
+		next = await reader.read();
+	}
+	if (seen > maxBytes) await abortTooLarge(reader, maxBytes);
+	return Buffer.concat(chunks);
+}
+async function abortTooLarge(reader, maxBytes) {
+	await reader.cancel();
+	throw tooLarge(maxBytes);
+}
+function tooLarge(maxBytes) {
+	return new HTTPException(413, { message: `Archive exceeds ${maxBytes} bytes` });
+}
+/** Adapt a lazily produced chunk sequence to a pull-based web stream. */
+function toWebStream(chunks) {
+	const iterator = chunks[Symbol.asyncIterator]();
+	return new ReadableStream({
+		async pull(controller) {
+			const next = await iterator.next();
+			if (next.done) controller.close();
+			else controller.enqueue(new Uint8Array(next.value));
+		},
+		async cancel() {
+			await iterator.return?.();
+		}
+	});
+}
+/** Download file name: `<slug>-baselines[-<branch>].zip`, header-safe. */
+function archiveFileName(slug, branch) {
+	return `${(branch ? `${slug}-baselines-${branch}` : `${slug}-baselines`).replaceAll(/[^\w.-]+/gu, "_")}.zip`;
+}
+//#endregion
+export { MAX_BASELINE_IMPORT_BYTES, archiveFileName, importByteLimit, readCappedBody, toWebStream };
+
+//# sourceMappingURL=baselines.handlers.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"baselines.handlers.mjs","names":[],"sources":["../../src/routers/baselines.handlers.ts"],"sourcesContent":["/** HTTP helpers for the baseline export/import router. */\nimport { DEFAULT_MAX_UPLOAD_BYTES, type ShelfConfig } from \"@storyshelf/core/config\";\nimport { BASELINE_ARCHIVE_LIMITS } from \"@storyshelf/core/models\";\nimport { HTTPException } from \"hono/http-exception\";\n\n/** Ceiling for a buffered import archive, whatever `maxUploadBytes` allows. */\nexport const MAX_BASELINE_IMPORT_BYTES = BASELINE_ARCHIVE_LIMITS.maxArchiveBytes;\n\n/** Byte limit for an import body: `maxUploadBytes`, capped because the archive is buffered. */\nexport function importByteLimit(config: Pick<ShelfConfig, \"maxUploadBytes\">): number {\n  return Math.min(config.maxUploadBytes ?? DEFAULT_MAX_UPLOAD_BYTES, MAX_BASELINE_IMPORT_BYTES);\n}\n\n/**\n * Buffer a request body, failing fast with 413 once it passes `maxBytes`\n * (checked against `content-length` up front and while streaming).\n */\nexport async function readCappedBody(request: Request, maxBytes: number): Promise<Buffer> {\n  if (Number(request.headers.get(\"content-length\") ?? 0) > maxBytes) {\n    throw tooLarge(maxBytes);\n  }\n  if (!request.body) {\n    throw new HTTPException(400, { message: \"Missing request body\" });\n  }\n  return await collectCapped(request.body.getReader(), maxBytes);\n}\n\nasync function collectCapped(\n  reader: ReadableStreamDefaultReader<Uint8Array>,\n  maxBytes: number,\n): Promise<Buffer> {\n  const chunks: Uint8Array[] = [];\n  let seen = 0;\n  let next = await reader.read();\n  while (!next.done && seen <= maxBytes) {\n    seen += next.value.length;\n    chunks.push(next.value);\n    // oxlint-disable-next-line eslint/no-await-in-loop -- reading a stream is inherently sequential\n    next = await reader.read();\n  }\n  if (seen > maxBytes) {\n    await abortTooLarge(reader, maxBytes);\n  }\n  return Buffer.concat(chunks);\n}\n\nasync function abortTooLarge(\n  reader: ReadableStreamDefaultReader<Uint8Array>,\n  maxBytes: number,\n): Promise<never> {\n  await reader.cancel();\n  throw tooLarge(maxBytes);\n}\n\nfunction tooLarge(maxBytes: number): HTTPException {\n  return new HTTPException(413, { message: `Archive exceeds ${maxBytes} bytes` });\n}\n\n/** Adapt a lazily produced chunk sequence to a pull-based web stream. */\nexport function toWebStream(chunks: AsyncIterable<Buffer>): ReadableStream<Uint8Array> {\n  const iterator = chunks[Symbol.asyncIterator]();\n  return new ReadableStream<Uint8Array>({\n    async pull(controller): Promise<void> {\n      const next = await iterator.next();\n      if (next.done) {\n        controller.close();\n      } else {\n        controller.enqueue(new Uint8Array(next.value));\n      }\n    },\n    async cancel(): Promise<void> {\n      await iterator.return?.();\n    },\n  });\n}\n\n/** Download file name: `<slug>-baselines[-<branch>].zip`, header-safe. */\nexport function archiveFileName(slug: string, branch?: string): string {\n  const base = branch ? `${slug}-baselines-${branch}` : `${slug}-baselines`;\n  return `${base.replaceAll(/[^\\w.-]+/gu, \"_\")}.zip`;\n}\n"],"mappings":";;;;;;;;;AAMA,MAAa,4BAA4B,wBAAwB;;AAGjE,SAAgB,gBAAgB,QAAqD;CACnF,OAAO,KAAK,IAAI,OAAO,kBAAkB,0BAA0B,yBAAyB;AAC9F;;;;;AAMA,eAAsB,eAAe,SAAkB,UAAmC;CACxF,IAAI,OAAO,QAAQ,QAAQ,IAAI,gBAAgB,KAAK,CAAC,IAAI,UACvD,MAAM,SAAS,QAAQ;CAEzB,IAAI,CAAC,QAAQ,MACX,MAAM,IAAI,cAAc,KAAK,EAAE,SAAS,uBAAuB,CAAC;CAElE,OAAO,MAAM,cAAc,QAAQ,KAAK,UAAU,GAAG,QAAQ;AAC/D;AAEA,eAAe,cACb,QACA,UACiB;CACjB,MAAM,SAAuB,CAAC;CAC9B,IAAI,OAAO;CACX,IAAI,OAAO,MAAM,OAAO,KAAK;CAC7B,OAAO,CAAC,KAAK,QAAQ,QAAQ,UAAU;EACrC,QAAQ,KAAK,MAAM;EACnB,OAAO,KAAK,KAAK,KAAK;EAEtB,OAAO,MAAM,OAAO,KAAK;CAC3B;CACA,IAAI,OAAO,UACT,MAAM,cAAc,QAAQ,QAAQ;CAEtC,OAAO,OAAO,OAAO,MAAM;AAC7B;AAEA,eAAe,cACb,QACA,UACgB;CAChB,MAAM,OAAO,OAAO;CACpB,MAAM,SAAS,QAAQ;AACzB;AAEA,SAAS,SAAS,UAAiC;CACjD,OAAO,IAAI,cAAc,KAAK,EAAE,SAAS,mBAAmB,SAAS,QAAQ,CAAC;AAChF;;AAGA,SAAgB,YAAY,QAA2D;CACrF,MAAM,WAAW,OAAO,OAAO,cAAc,CAAC;CAC9C,OAAO,IAAI,eAA2B;EACpC,MAAM,KAAK,YAA2B;GACpC,MAAM,OAAO,MAAM,SAAS,KAAK;GACjC,IAAI,KAAK,MACP,WAAW,MAAM;QAEjB,WAAW,QAAQ,IAAI,WAAW,KAAK,KAAK,CAAC;EAEjD;EACA,MAAM,SAAwB;GAC5B,MAAM,SAAS,SAAS;EAC1B;CACF,CAAC;AACH;;AAGA,SAAgB,gBAAgB,MAAc,QAAyB;CAErE,OAAO,IADM,SAAS,GAAG,KAAK,aAAa,WAAW,GAAG,KAAK,YAAA,CAC/C,WAAW,cAAc,GAAG,EAAE;AAC/C"}

package/dist/routers/baselines.mjs

@@ -0,0 +1,125 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { getStore } from "../store.mjs";
+import { resolveAuthorizedProject } from "./helpers.mjs";
+import { badRequest, errorSchema, forbidden, notFound, unauthorized } from "./schemas.mjs";
+import { archiveFileName, importByteLimit, readCappedBody, toWebStream } from "./baselines.handlers.mjs";
+import { createRoute, z } from "@hono/zod-openapi";
+import { BaselineArchiveError, BaselineTransferModel } from "@storyshelf/core/models";
+import { HTTPException } from "hono/http-exception";
+//#region src/routers/baselines.ts
+/**
+* Baseline portability endpoints: export a project's baselines as a zip
+* (`manifest.json` + PNGs, format v1) and import (upsert) the same format.
+* Format, limits, and validation live in `@storyshelf/core/models`
+* (`BaselineTransferModel`); this router owns HTTP concerns only.
+*/
+const VIEW_ROLES = [
+	"viewer",
+	"developer",
+	"approver",
+	"admin"
+];
+const APPROVER_ROLES = ["approver", "admin"];
+const zipSchema = z.string().openapi({
+	type: "string",
+	format: "binary"
+});
+const importResultSchema = z.object({
+	imported: z.number().int().openapi({ description: "Baselines in the archive (all applied)" }),
+	created: z.number().int().openapi({ description: "Baselines that did not exist before" }),
+	updated: z.number().int().openapi({ description: "Existing baselines overwritten" })
+}).openapi("BaselineImportResult");
+const exportRoute = createRoute({
+	method: "get",
+	tags: ["Baselines"],
+	summary: "Export baselines as a zip archive",
+	description: "Streams `manifest.json` (story/mode/browser/branch → file, SHA-256, timestamps) plus one PNG per baseline at `baselines/<branch>/<storyId>/<mode>.png`. Baselines whose image cannot be read are listed under `skipped`.",
+	path: "/api/v1/projects/{slug}/baselines/export",
+	request: {
+		params: z.object({ slug: z.string() }),
+		query: z.object({ branch: z.string().min(1).optional().openapi({ description: "Export only this branch" }) })
+	},
+	responses: {
+		200: {
+			content: { "application/zip": { schema: zipSchema } },
+			description: "Baseline archive"
+		},
+		...badRequest,
+		...unauthorized,
+		...forbidden,
+		...notFound
+	}
+});
+const importRoute = createRoute({
+	method: "post",
+	tags: ["Baselines"],
+	summary: "Import (upsert) baselines from a zip archive",
+	description: "Accepts an archive produced by the export endpoint. The whole archive is validated (manifest schema, path safety, PNG signature, SHA-256) before anything is written; baselines with the same story/mode/browser/branch are overwritten. Requires the approver role.",
+	path: "/api/v1/projects/{slug}/baselines/import",
+	request: {
+		params: z.object({ slug: z.string() }),
+		body: {
+			content: { "application/zip": { schema: zipSchema } },
+			required: true
+		}
+	},
+	responses: {
+		200: {
+			content: { "application/json": { schema: importResultSchema } },
+			description: "Baselines imported"
+		},
+		413: {
+			content: { "application/json": { schema: errorSchema } },
+			description: "Archive exceeds the size limit"
+		},
+		...badRequest,
+		...unauthorized,
+		...forbidden,
+		...notFound
+	}
+});
+/** Map archive validation failures to 400s; rethrow everything else. */
+function asBadRequest(error) {
+	if (error instanceof BaselineArchiveError) throw new HTTPException(400, { message: error.message });
+	throw error;
+}
+/** Register the baseline export/import endpoints. */
+function registerBaselines(app) {
+	app.openapi(exportRoute, async (c) => {
+		const project = await resolveAuthorizedProject(c, c.req.valid("param").slug, ...VIEW_ROLES);
+		const { branch } = c.req.valid("query");
+		const { db, storage, logger } = getStore();
+		const chunks = await new BaselineTransferModel(db, storage).export(project.id, {
+			branch,
+			project: project.slug,
+			onSkipped: (baseline) => {
+				logger.warn({
+					projectId: project.id,
+					...baseline
+				}, "baseline image skipped in export");
+			}
+		}).catch(asBadRequest);
+		return new Response(toWebStream(chunks), { headers: {
+			"content-type": "application/zip",
+			"content-disposition": `attachment; filename="${archiveFileName(project.slug, branch)}"`,
+			"cache-control": "no-store"
+		} });
+	});
+	app.openapi(importRoute, async (c) => {
+		const project = await resolveAuthorizedProject(c, c.req.valid("param").slug, ...APPROVER_ROLES);
+		const archive = await readCappedBody(c.req.raw, importByteLimit(getStore().config));
+		const { db, storage } = getStore();
+		const result = await new BaselineTransferModel(db, storage).import(project.id, archive).catch(asBadRequest);
+		getStore().logger.info({
+			projectId: project.id,
+			...result
+		}, "baselines imported");
+		return c.json(result, 200);
+	});
+}
+//#endregion
+export { registerBaselines };
+
+//# sourceMappingURL=baselines.mjs.map

package/dist/routers/baselines.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"baselines.mjs","names":[],"sources":["../../src/routers/baselines.ts"],"sourcesContent":["/**\n * Baseline portability endpoints: export a project's baselines as a zip\n * (`manifest.json` + PNGs, format v1) and import (upsert) the same format.\n * Format, limits, and validation live in `@storyshelf/core/models`\n * (`BaselineTransferModel`); this router owns HTTP concerns only.\n */\nimport { createRoute, z } from \"@hono/zod-openapi\";\nimport { BaselineArchiveError, BaselineTransferModel } from \"@storyshelf/core/models\";\nimport type { ProjectRole } from \"@storyshelf/core/types\";\nimport { HTTPException } from \"hono/http-exception\";\nimport type { ShelfRouter } from \"../app-types.ts\";\nimport { getStore } from \"../store.ts\";\nimport {\n  archiveFileName,\n  importByteLimit,\n  readCappedBody,\n  toWebStream,\n} from \"./baselines.handlers.ts\";\nimport { resolveAuthorizedProject } from \"./helpers.ts\";\nimport { badRequest, errorSchema, forbidden, notFound, unauthorized } from \"./schemas.ts\";\n\nconst VIEW_ROLES: readonly ProjectRole[] = [\"viewer\", \"developer\", \"approver\", \"admin\"];\nconst APPROVER_ROLES: readonly ProjectRole[] = [\"approver\", \"admin\"];\n\nconst zipSchema = z.string().openapi({ type: \"string\", format: \"binary\" });\nconst importResultSchema = z\n  .object({\n    imported: z.number().int().openapi({ description: \"Baselines in the archive (all applied)\" }),\n    created: z.number().int().openapi({ description: \"Baselines that did not exist before\" }),\n    updated: z.number().int().openapi({ description: \"Existing baselines overwritten\" }),\n  })\n  .openapi(\"BaselineImportResult\");\n\nconst exportRoute = createRoute({\n  method: \"get\",\n  tags: [\"Baselines\"],\n  summary: \"Export baselines as a zip archive\",\n  description:\n    \"Streams `manifest.json` (story/mode/browser/branch → file, SHA-256, timestamps) plus one PNG per baseline at `baselines/<branch>/<storyId>/<mode>.png`. Baselines whose image cannot be read are listed under `skipped`.\",\n  path: \"/api/v1/projects/{slug}/baselines/export\",\n  request: {\n    params: z.object({ slug: z.string() }),\n    query: z.object({\n      branch: z.string().min(1).optional().openapi({ description: \"Export only this branch\" }),\n    }),\n  },\n  responses: {\n    200: { content: { \"application/zip\": { schema: zipSchema } }, description: \"Baseline archive\" },\n    ...badRequest,\n    ...unauthorized,\n    ...forbidden,\n    ...notFound,\n  },\n});\n\nconst importRoute = createRoute({\n  method: \"post\",\n  tags: [\"Baselines\"],\n  summary: \"Import (upsert) baselines from a zip archive\",\n  description:\n    \"Accepts an archive produced by the export endpoint. The whole archive is validated (manifest schema, path safety, PNG signature, SHA-256) before anything is written; baselines with the same story/mode/browser/branch are overwritten. Requires the approver role.\",\n  path: \"/api/v1/projects/{slug}/baselines/import\",\n  request: {\n    params: z.object({ slug: z.string() }),\n    body: { content: { \"application/zip\": { schema: zipSchema } }, required: true },\n  },\n  responses: {\n    200: {\n      content: { \"application/json\": { schema: importResultSchema } },\n      description: \"Baselines imported\",\n    },\n    413: {\n      content: { \"application/json\": { schema: errorSchema } },\n      description: \"Archive exceeds the size limit\",\n    },\n    ...badRequest,\n    ...unauthorized,\n    ...forbidden,\n    ...notFound,\n  },\n});\n\n/** Map archive validation failures to 400s; rethrow everything else. */\nfunction asBadRequest(error: unknown): never {\n  if (error instanceof BaselineArchiveError) {\n    throw new HTTPException(400, { message: error.message });\n  }\n  throw error;\n}\n\n/** Register the baseline export/import endpoints. */\nexport function registerBaselines(app: ShelfRouter): void {\n  app.openapi(exportRoute, async (c) => {\n    const project = await resolveAuthorizedProject(c, c.req.valid(\"param\").slug, ...VIEW_ROLES);\n    const { branch } = c.req.valid(\"query\");\n    const { db, storage, logger } = getStore();\n    const chunks = await new BaselineTransferModel(db, storage)\n      .export(project.id, {\n        branch,\n        project: project.slug,\n        onSkipped: (baseline): void => {\n          logger.warn({ projectId: project.id, ...baseline }, \"baseline image skipped in export\");\n        },\n      })\n      .catch(asBadRequest);\n    return new Response(toWebStream(chunks), {\n      headers: {\n        \"content-type\": \"application/zip\",\n        \"content-disposition\": `attachment; filename=\"${archiveFileName(project.slug, branch)}\"`,\n        \"cache-control\": \"no-store\",\n      },\n    });\n  });\n\n  app.openapi(importRoute, async (c) => {\n    const project = await resolveAuthorizedProject(c, c.req.valid(\"param\").slug, ...APPROVER_ROLES);\n    const archive = await readCappedBody(c.req.raw, importByteLimit(getStore().config));\n    const { db, storage } = getStore();\n    const result = await new BaselineTransferModel(db, storage)\n      .import(project.id, archive)\n      .catch(asBadRequest);\n    getStore().logger.info({ projectId: project.id, ...result }, \"baselines imported\");\n    return c.json(result, 200);\n  });\n}\n"],"mappings":"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"}

package/dist/routers/build-cancel.mjs

@@ -0,0 +1,68 @@
+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 { buildSchema, errorSchema, notFound, unauthorized } from "./schemas.mjs";
+import { DEVELOPER_ROLES, announceBuildStatus, buildForProject } from "./builds.handlers.mjs";
+import { createRoute, z } from "@hono/zod-openapi";
+import { BuildModel, CaptureAttemptModel } from "@storyshelf/core/models";
+import { HTTPException } from "hono/http-exception";
+import { CANCELLABLE_BUILD_STATUSES } from "@storyshelf/core/types";
+//#region src/routers/build-cancel.ts
+const cancelBuildRoute = createRoute({
+	method: "post",
+	tags: ["Builds"],
+	summary: "Cancel a build",
+	description: "Stops the work of a build that has not finished capturing: its queued jobs (capture, publish and notification jobs alike) end cancelled, running ones are signalled and stop within seconds, and the build ends `cancelled`, a terminal status that a capture finishing late cannot move (retry resets it like a failed build). It raises `build:cancelled` (webhook and notification topic), never `build:failed` or a capture-failed alert. `testing` class. 409 when the build is not pending, capturing or comparing.",
+	path: "/api/v1/projects/{slug}/builds/{buildId}/cancel",
+	request: { params: z.object({
+		slug: z.string(),
+		buildId: z.string()
+	}) },
+	responses: {
+		200: {
+			content: { "application/json": { schema: buildSchema } },
+			description: "The build's jobs were cancelled and the build marked cancelled"
+		},
+		409: {
+			content: { "application/json": { schema: errorSchema } },
+			description: "The build is not in a cancellable state"
+		},
+		...notFound,
+		...unauthorized
+	}
+});
+/** Register `POST …/builds/:buildId/cancel` (`testing` class). */
+function registerBuildCancel(app) {
+	app.openapi(cancelBuildRoute, async (c) => {
+		const { slug, buildId } = c.req.valid("param");
+		const project = await resolveAuthorizedProject(c, slug, ...DEVELOPER_ROLES);
+		const build = await buildForProject(project.id, buildId);
+		if (!CANCELLABLE_BUILD_STATUSES.includes(build.status)) throw new HTTPException(409, { message: `A ${build.status} build cannot be cancelled` });
+		const updated = await cancelBuild(build.id);
+		hxRefresh(c);
+		flashHx(c, "Build cancelled");
+		return c.json(updated, 200);
+	});
+}
+/**
+* Cancel the build's jobs of every kind, close its open attempts, then end the build `cancelled` and
+* announce it. A capture still running notices the cancel on its next check (within seconds) and
+* stops; whatever it still writes cannot move the build off `cancelled`. The jobs end first so the
+* cancel's own notification job is not cancelled.
+*/
+async function cancelBuild(buildId) {
+	const { db, cancelBuildJobs } = getStore();
+	await cancelBuildJobs?.(buildId);
+	await new CaptureAttemptModel(db).closeOthers(buildId, null, "Cancelled by a user");
+	const updated = await new BuildModel(db).setStatus(buildId, "cancelled");
+	await announceBuildStatus(buildId, "cancelled");
+	return updated;
+}
+//#endregion
+export { registerBuildCancel };
+
+//# sourceMappingURL=build-cancel.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build-cancel.mjs","names":[],"sources":["../../src/routers/build-cancel.ts"],"sourcesContent":["import { createRoute, z } from \"@hono/zod-openapi\";\nimport { BuildModel, CaptureAttemptModel } from \"@storyshelf/core/models\";\nimport type { Build } from \"@storyshelf/core/schema\";\nimport { CANCELLABLE_BUILD_STATUSES } from \"@storyshelf/core/types\";\nimport { HTTPException } from \"hono/http-exception\";\nimport type { ShelfRouter } from \"../app-types.ts\";\nimport { getStore } from \"../store.ts\";\nimport { DEVELOPER_ROLES, announceBuildStatus, buildForProject } from \"./builds.handlers.ts\";\nimport { flashHx } from \"./flash.ts\";\nimport { resolveAuthorizedProject } from \"./helpers.ts\";\nimport { hxRefresh } from \"./htmx.ts\";\nimport { buildSchema, errorSchema, notFound, unauthorized } from \"./schemas.ts\";\n\nconst cancelBuildRoute = createRoute({\n  method: \"post\",\n  tags: [\"Builds\"],\n  summary: \"Cancel a build\",\n  description:\n    \"Stops the work of a build that has not finished capturing: its queued jobs (capture, publish and notification jobs alike) end cancelled, running ones are signalled and stop within seconds, and the build ends `cancelled`, a terminal status that a capture finishing late cannot move (retry resets it like a failed build). It raises `build:cancelled` (webhook and notification topic), never `build:failed` or a capture-failed alert. `testing` class. 409 when the build is not pending, capturing or comparing.\",\n  path: \"/api/v1/projects/{slug}/builds/{buildId}/cancel\",\n  request: { params: z.object({ slug: z.string(), buildId: z.string() }) },\n  responses: {\n    200: {\n      content: { \"application/json\": { schema: buildSchema } },\n      description: \"The build's jobs were cancelled and the build marked cancelled\",\n    },\n    409: {\n      content: { \"application/json\": { schema: errorSchema } },\n      description: \"The build is not in a cancellable state\",\n    },\n    ...notFound,\n    ...unauthorized,\n  },\n});\n\n/** Register `POST …/builds/:buildId/cancel` (`testing` class). */\nexport function registerBuildCancel(app: ShelfRouter): void {\n  app.openapi(cancelBuildRoute, async (c) => {\n    const { slug, buildId } = c.req.valid(\"param\");\n    const project = await resolveAuthorizedProject(c, slug, ...DEVELOPER_ROLES);\n    const build = await buildForProject(project.id, buildId);\n    if (!CANCELLABLE_BUILD_STATUSES.includes(build.status)) {\n      throw new HTTPException(409, { message: `A ${build.status} build cannot be cancelled` });\n    }\n    const updated = await cancelBuild(build.id);\n    hxRefresh(c);\n    flashHx(c, \"Build cancelled\");\n    return c.json(updated, 200);\n  });\n}\n\n/**\n * Cancel the build's jobs of every kind, close its open attempts, then end the build `cancelled` and\n * announce it. A capture still running notices the cancel on its next check (within seconds) and\n * stops; whatever it still writes cannot move the build off `cancelled`. The jobs end first so the\n * cancel's own notification job is not cancelled.\n */\nasync function cancelBuild(buildId: string): Promise<Build> {\n  const { db, cancelBuildJobs } = getStore();\n  await cancelBuildJobs?.(buildId);\n  await new CaptureAttemptModel(db).closeOthers(buildId, null, \"Cancelled by a user\");\n  const updated = await new BuildModel(db).setStatus(buildId, \"cancelled\");\n  await announceBuildStatus(buildId, \"cancelled\");\n  return updated;\n}\n"],"mappings":";;;;;;;;;;;;;;AAaA,MAAM,mBAAmB,YAAY;CACnC,QAAQ;CACR,MAAM,CAAC,QAAQ;CACf,SAAS;CACT,aACE;CACF,MAAM;CACN,SAAS,EAAE,QAAQ,EAAE,OAAO;EAAE,MAAM,EAAE,OAAO;EAAG,SAAS,EAAE,OAAO;CAAE,CAAC,EAAE;CACvE,WAAW;EACT,KAAK;GACH,SAAS,EAAE,oBAAoB,EAAE,QAAQ,YAAY,EAAE;GACvD,aAAa;EACf;EACA,KAAK;GACH,SAAS,EAAE,oBAAoB,EAAE,QAAQ,YAAY,EAAE;GACvD,aAAa;EACf;EACA,GAAG;EACH,GAAG;CACL;AACF,CAAC;;AAGD,SAAgB,oBAAoB,KAAwB;CAC1D,IAAI,QAAQ,kBAAkB,OAAO,MAAM;EACzC,MAAM,EAAE,MAAM,YAAY,EAAE,IAAI,MAAM,OAAO;EAC7C,MAAM,UAAU,MAAM,yBAAyB,GAAG,MAAM,GAAG,eAAe;EAC1E,MAAM,QAAQ,MAAM,gBAAgB,QAAQ,IAAI,OAAO;EACvD,IAAI,CAAC,2BAA2B,SAAS,MAAM,MAAM,GACnD,MAAM,IAAI,cAAc,KAAK,EAAE,SAAS,KAAK,MAAM,OAAO,4BAA4B,CAAC;EAEzF,MAAM,UAAU,MAAM,YAAY,MAAM,EAAE;EAC1C,UAAU,CAAC;EACX,QAAQ,GAAG,iBAAiB;EAC5B,OAAO,EAAE,KAAK,SAAS,GAAG;CAC5B,CAAC;AACH;;;;;;;AAQA,eAAe,YAAY,SAAiC;CAC1D,MAAM,EAAE,IAAI,oBAAoB,SAAS;CACzC,MAAM,kBAAkB,OAAO;CAC/B,MAAM,IAAI,oBAAoB,EAAE,CAAC,CAAC,YAAY,SAAS,MAAM,qBAAqB;CAClF,MAAM,UAAU,MAAM,IAAI,WAAW,EAAE,CAAC,CAAC,UAAU,SAAS,WAAW;CACvE,MAAM,oBAAoB,SAAS,WAAW;CAC9C,OAAO;AACT"}

package/dist/routers/build-changeset.mjs

@@ -0,0 +1,70 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { getStore } from "../store.mjs";
+import { resolveAuthorizedProject } from "./helpers.mjs";
+import { notFound, unauthorized } from "./schemas.mjs";
+import { VIEW_ROLES, buildForProject } from "./builds.handlers.mjs";
+import { createRoute, z } from "@hono/zod-openapi";
+import { changesetOf } from "@storyshelf/core/models";
+//#region src/routers/build-changeset.ts
+const component = z.object({
+	importPath: z.string(),
+	title: z.string(),
+	storyCount: z.number()
+});
+const changesetSchema = z.object({
+	baseline: z.object({
+		id: z.string(),
+		gitBranch: z.string(),
+		gitSha: z.string()
+	}).nullable().describe("The build compared with; null for the first build"),
+	added: component.array(),
+	removed: component.array(),
+	changed: component.extend({ previousStoryCount: z.number() }).array(),
+	unchanged: z.number().describe("Components with the same hash in both builds")
+}).openapi("BuildChangeset");
+const getChangesetRoute = createRoute({
+	method: "get",
+	tags: ["Review"],
+	summary: "Get a build's changeset",
+	description: "Components the build added, removed or changed against its baseline build (the latest accepted build of its branch, else of the default branch), from the Storybook catalog. A changed hash means the component's stories changed, not that anything looks different. 404 when the project has review off.",
+	path: "/api/v1/projects/{slug}/builds/{buildId}/changeset",
+	request: { params: z.object({
+		slug: z.string(),
+		buildId: z.string()
+	}) },
+	responses: {
+		200: {
+			content: { "application/json": { schema: changesetSchema } },
+			description: "The build's changeset"
+		},
+		...notFound,
+		...unauthorized
+	}
+});
+/** Register the changeset endpoint (`review` class). */
+function registerBuildChangeset(app) {
+	app.openapi(getChangesetRoute, async (c) => {
+		const { slug, buildId } = c.req.valid("param");
+		const project = await resolveAuthorizedProject(c, slug, ...VIEW_ROLES);
+		const build = await buildForProject(project.id, buildId);
+		const { baseline, changeset } = await changesetOf(getStore().db, project, build);
+		const { added, removed, changed, unchanged } = changeset;
+		return c.json({
+			baseline: baseline ? {
+				id: baseline.id,
+				gitBranch: baseline.gitBranch,
+				gitSha: baseline.gitSha
+			} : null,
+			added,
+			removed,
+			changed,
+			unchanged
+		});
+	});
+}
+//#endregion
+export { registerBuildChangeset };
+
+//# sourceMappingURL=build-changeset.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build-changeset.mjs","names":[],"sources":["../../src/routers/build-changeset.ts"],"sourcesContent":["import { createRoute, z } from \"@hono/zod-openapi\";\nimport { changesetOf } from \"@storyshelf/core/models\";\nimport type { ShelfRouter } from \"../app-types.ts\";\nimport { getStore } from \"../store.ts\";\nimport { VIEW_ROLES, buildForProject } from \"./builds.handlers.ts\";\nimport { resolveAuthorizedProject } from \"./helpers.ts\";\nimport { notFound, unauthorized } from \"./schemas.ts\";\n\nconst component = z.object({\n  importPath: z.string(),\n  title: z.string(),\n  storyCount: z.number(),\n});\n\nconst changesetSchema = z\n  .object({\n    baseline: z\n      .object({ id: z.string(), gitBranch: z.string(), gitSha: z.string() })\n      .nullable()\n      .describe(\"The build compared with; null for the first build\"),\n    added: component.array(),\n    removed: component.array(),\n    changed: component.extend({ previousStoryCount: z.number() }).array(),\n    unchanged: z.number().describe(\"Components with the same hash in both builds\"),\n  })\n  .openapi(\"BuildChangeset\");\n\nconst getChangesetRoute = createRoute({\n  method: \"get\",\n  tags: [\"Review\"],\n  summary: \"Get a build's changeset\",\n  description:\n    \"Components the build added, removed or changed against its baseline build (the latest accepted build of its branch, else of the default branch), from the Storybook catalog. A changed hash means the component's stories changed, not that anything looks different. 404 when the project has review off.\",\n  path: \"/api/v1/projects/{slug}/builds/{buildId}/changeset\",\n  request: { params: z.object({ slug: z.string(), buildId: z.string() }) },\n  responses: {\n    200: {\n      content: { \"application/json\": { schema: changesetSchema } },\n      description: \"The build's changeset\",\n    },\n    ...notFound,\n    ...unauthorized,\n  },\n});\n\n/** Register the changeset endpoint (`review` class). */\nexport function registerBuildChangeset(app: ShelfRouter): void {\n  app.openapi(getChangesetRoute, 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    const { baseline, changeset } = await changesetOf(getStore().db, project, build);\n    const { added, removed, changed, unchanged } = changeset;\n    return c.json({\n      baseline: baseline\n        ? { id: baseline.id, gitBranch: baseline.gitBranch, gitSha: baseline.gitSha }\n        : null,\n      added,\n      removed,\n      changed,\n      unchanged,\n    });\n  });\n}\n"],"mappings":";;;;;;;;;;AAQA,MAAM,YAAY,EAAE,OAAO;CACzB,YAAY,EAAE,OAAO;CACrB,OAAO,EAAE,OAAO;CAChB,YAAY,EAAE,OAAO;AACvB,CAAC;AAED,MAAM,kBAAkB,EACrB,OAAO;CACN,UAAU,EACP,OAAO;EAAE,IAAI,EAAE,OAAO;EAAG,WAAW,EAAE,OAAO;EAAG,QAAQ,EAAE,OAAO;CAAE,CAAC,CAAC,CACrE,SAAS,CAAC,CACV,SAAS,mDAAmD;CAC/D,OAAO,UAAU,MAAM;CACvB,SAAS,UAAU,MAAM;CACzB,SAAS,UAAU,OAAO,EAAE,oBAAoB,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,MAAM;CACpE,WAAW,EAAE,OAAO,CAAC,CAAC,SAAS,8CAA8C;AAC/E,CAAC,CAAC,CACD,QAAQ,gBAAgB;AAE3B,MAAM,oBAAoB,YAAY;CACpC,QAAQ;CACR,MAAM,CAAC,QAAQ;CACf,SAAS;CACT,aACE;CACF,MAAM;CACN,SAAS,EAAE,QAAQ,EAAE,OAAO;EAAE,MAAM,EAAE,OAAO;EAAG,SAAS,EAAE,OAAO;CAAE,CAAC,EAAE;CACvE,WAAW;EACT,KAAK;GACH,SAAS,EAAE,oBAAoB,EAAE,QAAQ,gBAAgB,EAAE;GAC3D,aAAa;EACf;EACA,GAAG;EACH,GAAG;CACL;AACF,CAAC;;AAGD,SAAgB,uBAAuB,KAAwB;CAC7D,IAAI,QAAQ,mBAAmB,OAAO,MAAM;EAC1C,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,MAAM,EAAE,UAAU,cAAc,MAAM,YAAY,SAAS,CAAC,CAAC,IAAI,SAAS,KAAK;EAC/E,MAAM,EAAE,OAAO,SAAS,SAAS,cAAc;EAC/C,OAAO,EAAE,KAAK;GACZ,UAAU,WACN;IAAE,IAAI,SAAS;IAAI,WAAW,SAAS;IAAW,QAAQ,SAAS;GAAO,IAC1E;GACJ;GACA;GACA;GACA;EACF,CAAC;CACH,CAAC;AACH"}

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

@@ -0,0 +1,86 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { getStore } from "../store.mjs";
+import { REVIEW_EVENTS, announceReview } from "../review-events.mjs";
+import { requestBuildState } from "../git-status.mjs";
+import { announceBuildStatus } from "./builds.handlers.mjs";
+import { publishingOf } from "@storyshelf/core/capture";
+import { BuildModel, BuildReviewModel, deriveReviewStatus, latestVerdicts } from "@storyshelf/core/models";
+import { HTTPException } from "hono/http-exception";
+//#region src/routers/build-reviews.handlers.ts
+/**
+* Build-level verdicts (ADR 0013, decision 3): giving one and reading where a build stands. The
+* routes are classed `review`, so `requireReview` answers 404 for a project with review off.
+*/
+/** Statuses the verdicts may move a build between; a failed, cancelled or capturing build is not theirs to decide. */
+const VERDICT_STATUSES = /* @__PURE__ */ new Set([
+	"pending",
+	"approved",
+	"rejected"
+]);
+/** The verdicts of a build and what they make of it. */
+async function reviewStateOf(project, build) {
+	const history = await new BuildReviewModel(getStore().db).listByBuild(build.id);
+	const latest = latestVerdicts(history);
+	return {
+		status: build.status,
+		approvalsRequired: approvalsRequired(project),
+		approvals: latest.filter((review) => review.verdict === "approved").length,
+		latest,
+		history
+	};
+}
+/**
+* Record `userId`'s verdict and let the verdicts decide the build. With `testing` on the verdict is
+* stored as a sign-off and the snapshot rollup keeps deciding. Every write asks for the build's
+* state to be shown on its git channels; a status the verdicts moved to `approved` or `rejected`
+* is announced like any other (webhook and notifications). Every verdict raises `review:verdict`.
+*/
+async function giveVerdict(project, build, userId, input) {
+	await assertReviewable(project, build, userId);
+	const review = await new BuildReviewModel(getStore().db).add(build.id, userId, input.verdict, input.body);
+	const status = await decideBuild(project, build);
+	await announceReview(project, REVIEW_EVENTS.verdict, {
+		buildId: build.id,
+		gitBranch: build.gitBranch,
+		verdict: review.verdict,
+		userId,
+		body: review.body?.slice(0, 500) ?? null,
+		status: status ?? build.status
+	}, build.id);
+	if (status === null) await requestBuildState(build.id);
+	else await announceBuildStatus(build.id, status);
+	return review;
+}
+/**
+* A verdict needs a build that is neither `failed` nor `cancelled`, whose publishing has ended (a publish that later
+* failed would otherwise leave an approved build without statics), and, when it has no user (an
+* instance without authentication), a project that needs one approval: the anonymous reviewer is
+* one person, however many verdicts they give.
+*/
+async function assertReviewable(project, build, userId) {
+	if (build.status === "failed" || build.status === "cancelled") throw new HTTPException(409, { message: `The build ${build.status === "failed" ? "failed" : "was cancelled"}; there is nothing to review` });
+	if (await publishingOf(getStore().storage, build) !== "success") throw new HTTPException(409, { message: "The build is still publishing; give a verdict once its Storybook is published" });
+	if (userId === null && approvalsRequired(project) > 1) throw new HTTPException(409, { message: `Verdicts without authentication count as one reviewer, but this project needs ${String(approvalsRequired(project))} approvals; enable authentication to review` });
+}
+/** Move the build to the status its verdicts give it; the new status, or null when it did not move. */
+async function decideBuild(project, build) {
+	const { db, testing } = getStore();
+	const status = deriveReviewStatus({
+		testing,
+		review: true,
+		approvalsRequired: approvalsRequired(project),
+		reviews: await new BuildReviewModel(db).listByBuild(build.id)
+	});
+	if (status === null || !VERDICT_STATUSES.has(build.status) || status === build.status) return null;
+	await new BuildModel(db).setStatus(build.id, status);
+	return status;
+}
+function approvalsRequired(project) {
+	return Math.max(1, project.reviewApprovals ?? 1);
+}
+//#endregion
+export { giveVerdict, reviewStateOf };
+
+//# sourceMappingURL=build-reviews.handlers.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build-reviews.handlers.mjs","names":[],"sources":["../../src/routers/build-reviews.handlers.ts"],"sourcesContent":["/**\n * Build-level verdicts (ADR 0013, decision 3): giving one and reading where a build stands. The\n * routes are classed `review`, so `requireReview` answers 404 for a project with review off.\n */\nimport { publishingOf } from \"@storyshelf/core/capture\";\nimport {\n  BuildModel,\n  BuildReviewModel,\n  deriveReviewStatus,\n  latestVerdicts,\n} from \"@storyshelf/core/models\";\nimport type { Build, BuildReview, Project } from \"@storyshelf/core/schema\";\nimport type { BuildStatus, ReviewVerdict } from \"@storyshelf/core/types\";\nimport { HTTPException } from \"hono/http-exception\";\nimport { requestBuildState } from \"../git-status.ts\";\nimport { REVIEW_EVENTS, announceReview } from \"../review-events.ts\";\nimport { getStore } from \"../store.ts\";\nimport { announceBuildStatus } from \"./builds.handlers.ts\";\n\n/** Statuses the verdicts may move a build between; a failed, cancelled or capturing build is not theirs to decide. */\nconst VERDICT_STATUSES: ReadonlySet<BuildStatus> = new Set([\"pending\", \"approved\", \"rejected\"]);\n\n/** Where a build stands in review. */\nexport interface ReviewState {\n  status: BuildStatus;\n  approvalsRequired: number;\n  approvals: number;\n  latest: BuildReview[];\n  history: BuildReview[];\n}\n\n/** The verdicts of a build and what they make of it. */\nexport async function reviewStateOf(project: Project, build: Build): Promise<ReviewState> {\n  const history = await new BuildReviewModel(getStore().db).listByBuild(build.id);\n  const latest = latestVerdicts(history);\n  return {\n    status: build.status,\n    approvalsRequired: approvalsRequired(project),\n    approvals: latest.filter((review) => review.verdict === \"approved\").length,\n    latest,\n    history,\n  };\n}\n\n/**\n * Record `userId`'s verdict and let the verdicts decide the build. With `testing` on the verdict is\n * stored as a sign-off and the snapshot rollup keeps deciding. Every write asks for the build's\n * state to be shown on its git channels; a status the verdicts moved to `approved` or `rejected`\n * is announced like any other (webhook and notifications). Every verdict raises `review:verdict`.\n */\nexport async function giveVerdict(\n  project: Project,\n  build: Build,\n  userId: string | null,\n  input: { verdict: ReviewVerdict; body?: string | undefined },\n): Promise<BuildReview> {\n  await assertReviewable(project, build, userId);\n  const review = await new BuildReviewModel(getStore().db).add(\n    build.id,\n    userId,\n    input.verdict,\n    input.body,\n  );\n  const status = await decideBuild(project, build);\n  await announceReview(\n    project,\n    REVIEW_EVENTS.verdict,\n    {\n      buildId: build.id,\n      gitBranch: build.gitBranch,\n      verdict: review.verdict,\n      userId,\n      body: review.body?.slice(0, 500) ?? null,\n      status: status ?? build.status,\n    },\n    build.id,\n  );\n  // Every move is news: `approved` and `rejected` as ever, and `pending` when a rewritten verdict\n  // sends the build back; a verdict that moves nothing only refreshes the git channels.\n  if (status === null) {\n    await requestBuildState(build.id);\n  } else {\n    await announceBuildStatus(build.id, status);\n  }\n  return review;\n}\n\n/**\n * A verdict needs a build that is neither `failed` nor `cancelled`, whose publishing has ended (a publish that later\n * failed would otherwise leave an approved build without statics), and, when it has no user (an\n * instance without authentication), a project that needs one approval: the anonymous reviewer is\n * one person, however many verdicts they give.\n */\nasync function assertReviewable(\n  project: Project,\n  build: Build,\n  userId: string | null,\n): Promise<void> {\n  if (build.status === \"failed\" || build.status === \"cancelled\") {\n    throw new HTTPException(409, {\n      message: `The build ${build.status === \"failed\" ? \"failed\" : \"was cancelled\"}; there is nothing to review`,\n    });\n  }\n  if ((await publishingOf(getStore().storage, build)) !== \"success\") {\n    throw new HTTPException(409, {\n      message: \"The build is still publishing; give a verdict once its Storybook is published\",\n    });\n  }\n  if (userId === null && approvalsRequired(project) > 1) {\n    throw new HTTPException(409, {\n      message: `Verdicts without authentication count as one reviewer, but this project needs ${String(approvalsRequired(project))} approvals; enable authentication to review`,\n    });\n  }\n}\n\n/** Move the build to the status its verdicts give it; the new status, or null when it did not move. */\nasync function decideBuild(\n  project: Project,\n  build: Build,\n): Promise<\"approved\" | \"rejected\" | \"pending\" | null> {\n  const { db, testing } = getStore();\n  const status = deriveReviewStatus({\n    testing,\n    review: true,\n    approvalsRequired: approvalsRequired(project),\n    reviews: await new BuildReviewModel(db).listByBuild(build.id),\n  });\n  if (status === null || !VERDICT_STATUSES.has(build.status) || status === build.status) {\n    return null;\n  }\n  await new BuildModel(db).setStatus(build.id, status);\n  return status;\n}\n\nfunction approvalsRequired(project: Project): number {\n  return Math.max(1, project.reviewApprovals ?? 1);\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAoBA,MAAM,mCAA6C,IAAI,IAAI;CAAC;CAAW;CAAY;AAAU,CAAC;;AAY9F,eAAsB,cAAc,SAAkB,OAAoC;CACxF,MAAM,UAAU,MAAM,IAAI,iBAAiB,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,YAAY,MAAM,EAAE;CAC9E,MAAM,SAAS,eAAe,OAAO;CACrC,OAAO;EACL,QAAQ,MAAM;EACd,mBAAmB,kBAAkB,OAAO;EAC5C,WAAW,OAAO,QAAQ,WAAW,OAAO,YAAY,UAAU,CAAC,CAAC;EACpE;EACA;CACF;AACF;;;;;;;AAQA,eAAsB,YACpB,SACA,OACA,QACA,OACsB;CACtB,MAAM,iBAAiB,SAAS,OAAO,MAAM;CAC7C,MAAM,SAAS,MAAM,IAAI,iBAAiB,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,IACvD,MAAM,IACN,QACA,MAAM,SACN,MAAM,IACR;CACA,MAAM,SAAS,MAAM,YAAY,SAAS,KAAK;CAC/C,MAAM,eACJ,SACA,cAAc,SACd;EACE,SAAS,MAAM;EACf,WAAW,MAAM;EACjB,SAAS,OAAO;EAChB;EACA,MAAM,OAAO,MAAM,MAAM,GAAG,GAAG,KAAK;EACpC,QAAQ,UAAU,MAAM;CAC1B,GACA,MAAM,EACR;CAGA,IAAI,WAAW,MACb,MAAM,kBAAkB,MAAM,EAAE;MAEhC,MAAM,oBAAoB,MAAM,IAAI,MAAM;CAE5C,OAAO;AACT;;;;;;;AAQA,eAAe,iBACb,SACA,OACA,QACe;CACf,IAAI,MAAM,WAAW,YAAY,MAAM,WAAW,aAChD,MAAM,IAAI,cAAc,KAAK,EAC3B,SAAS,aAAa,MAAM,WAAW,WAAW,WAAW,gBAAgB,8BAC/E,CAAC;CAEH,IAAK,MAAM,aAAa,SAAS,CAAC,CAAC,SAAS,KAAK,MAAO,WACtD,MAAM,IAAI,cAAc,KAAK,EAC3B,SAAS,gFACX,CAAC;CAEH,IAAI,WAAW,QAAQ,kBAAkB,OAAO,IAAI,GAClD,MAAM,IAAI,cAAc,KAAK,EAC3B,SAAS,iFAAiF,OAAO,kBAAkB,OAAO,CAAC,EAAE,6CAC/H,CAAC;AAEL;;AAGA,eAAe,YACb,SACA,OACqD;CACrD,MAAM,EAAE,IAAI,YAAY,SAAS;CACjC,MAAM,SAAS,mBAAmB;EAChC;EACA,QAAQ;EACR,mBAAmB,kBAAkB,OAAO;EAC5C,SAAS,MAAM,IAAI,iBAAiB,EAAE,CAAC,CAAC,YAAY,MAAM,EAAE;CAC9D,CAAC;CACD,IAAI,WAAW,QAAQ,CAAC,iBAAiB,IAAI,MAAM,MAAM,KAAK,WAAW,MAAM,QAC7E,OAAO;CAET,MAAM,IAAI,WAAW,EAAE,CAAC,CAAC,UAAU,MAAM,IAAI,MAAM;CACnD,OAAO;AACT;AAEA,SAAS,kBAAkB,SAA0B;CACnD,OAAO,KAAK,IAAI,GAAG,QAAQ,mBAAmB,CAAC;AACjD"}

package/dist/routers/build-reviews.mjs

@@ -0,0 +1,74 @@
+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";
+//#region 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);
+	});
+}
+//#endregion
+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"}