@storyshelf/core 0.6.2 → 0.8.0

package/dist/capture/publish/handler.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.mjs","names":[],"sources":["../../../src/capture/publish/handler.ts"],"sourcesContent":["import type { DatabaseAdapter } from \"../../adapters/database.ts\";\n/** The `publish` job handler of the consumer (ADR 0006, decision 10): publish a stored zip, then complete the build. */\nimport type { StorageAdapter } from \"../../adapters/storage.ts\";\nimport type { Logger } from \"../../logger.ts\";\nimport { BuildModel } from \"../../models/build.ts\";\nimport type { ConsumerJob, KindHandler } from \"../consumer/types.ts\";\nimport type { PublishCompleter } from \"./complete.ts\";\nimport { ZipLimitError, type ExtractionLimits } from \"./limits.ts\";\nimport { publishStoredZip } from \"./run.ts\";\n\n/** What {@link createPublishHandler} needs. */\nexport interface PublishHandlerOptions {\n  db: DatabaseAdapter;\n  storage: StorageAdapter;\n  scratchDir: string;\n  limits: ExtractionLimits;\n  completer: PublishCompleter;\n  logger: Logger;\n}\n\n/** A `publish` job needs the build to publish. */\nfunction hasBuild(job: ConsumerJob): boolean {\n  return typeof job.buildId === \"string\" && job.buildId.length > 0;\n}\n\n/**\n * The handler. Resolving acks the job. A zip that breaks a cap is a final answer (retrying cannot\n * help): the build is failed and the job acked. Any other error is retried by the consumer, and\n * the build is failed on the last attempt. A redelivery after a lost lease repeats the extraction\n * (same keys) and leaves an already accepted build alone.\n */\nexport function createPublishHandler(options: PublishHandlerOptions): KindHandler {\n  return {\n    accepts: hasBuild,\n    run: async (job, context) => {\n      const build = await new BuildModel(options.db).get(job.buildId);\n      if (!build) {\n        context.logger.warn(\"build is gone; dropping publish job\");\n        return;\n      }\n      await publishOnce(options, job, context, build.projectId);\n    },\n  };\n}\n\nasync function publishOnce(\n  options: PublishHandlerOptions,\n  job: ConsumerJob,\n  context: { logger: Logger; touch: () => void },\n  projectId: string,\n): Promise<void> {\n  const { completer, storage, scratchDir, limits, db } = options;\n  try {\n    await publishStoredZip(\n      { storage, scratchDir, limits, db, logger: context.logger, touch: context.touch },\n      { projectId, buildId: job.buildId },\n    );\n  } catch (error) {\n    const permanent = error instanceof ZipLimitError;\n    if (permanent || (job.attempt ?? 1) >= (job.maxAttempts ?? 1)) {\n      await completer.complete(job.buildId, { ok: false, error: messageOf(error) });\n    }\n    if (permanent) {\n      return;\n    }\n    throw error;\n  }\n  await completer.complete(job.buildId, { ok: true });\n}\n\nfunction messageOf(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n"],"mappings":";;;;;;;;AAqBA,SAAS,SAAS,KAA2B;CAC3C,OAAO,OAAO,IAAI,YAAY,YAAY,IAAI,QAAQ,SAAS;AACjE;;;;;;;AAQA,SAAgB,qBAAqB,SAA6C;CAChF,OAAO;EACL,SAAS;EACT,KAAK,OAAO,KAAK,YAAY;GAC3B,MAAM,QAAQ,MAAM,IAAI,WAAW,QAAQ,EAAE,CAAC,CAAC,IAAI,IAAI,OAAO;GAC9D,IAAI,CAAC,OAAO;IACV,QAAQ,OAAO,KAAK,qCAAqC;IACzD;GACF;GACA,MAAM,YAAY,SAAS,KAAK,SAAS,MAAM,SAAS;EAC1D;CACF;AACF;AAEA,eAAe,YACb,SACA,KACA,SACA,WACe;CACf,MAAM,EAAE,WAAW,SAAS,YAAY,QAAQ,OAAO;CACvD,IAAI;EACF,MAAM,iBACJ;GAAE;GAAS;GAAY;GAAQ;GAAI,QAAQ,QAAQ;GAAQ,OAAO,QAAQ;EAAM,GAChF;GAAE;GAAW,SAAS,IAAI;EAAQ,CACpC;CACF,SAAS,OAAO;EACd,MAAM,YAAY,iBAAiB;EACnC,IAAI,cAAc,IAAI,WAAW,OAAO,IAAI,eAAe,IACzD,MAAM,UAAU,SAAS,IAAI,SAAS;GAAE,IAAI;GAAO,OAAO,UAAU,KAAK;EAAE,CAAC;EAE9E,IAAI,WACF;EAEF,MAAM;CACR;CACA,MAAM,UAAU,SAAS,IAAI,SAAS,EAAE,IAAI,KAAK,CAAC;AACpD;AAEA,SAAS,UAAU,OAAwB;CACzC,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAC9D"}

package/dist/capture/publish/index.d.mts

@@ -0,0 +1,11 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DEFAULT_MAX_INLINE_UNZIP_SIZE, DEFAULT_MAX_UNZIPPED_BYTES, DEFAULT_MAX_ZIP_ENTRIES, ExtractionLimits, FILE_BY_FILE_HINT, PublishLimits, ZipLimitError, extractionLimitsOf, publishRoute, resolvePublishLimits } from "./limits.mjs";
+import { AfterPublishContext, AfterPublishHook, PublishCompleter, PublishCompleterOptions, PublishOutcome, createPublishCompleter } from "./complete.mjs";
+import { PublishHandlerOptions, createPublishHandler } from "./handler.mjs";
+import { PublishFacts, publishVerdict } from "./accept.mjs";
+import { publishingOf } from "./published.mjs";
+import { ExtractionResult, extractZipStream } from "./extract.mjs";
+import { PUBLISH_SCRATCH_ID, PublishZipOptions, publishStoredZip } from "./run.mjs";
+import { ZipInvalidError } from "./invalid-zip.mjs";
+export { type AfterPublishContext, type AfterPublishHook, DEFAULT_MAX_INLINE_UNZIP_SIZE, DEFAULT_MAX_UNZIPPED_BYTES, DEFAULT_MAX_ZIP_ENTRIES, type ExtractionLimits, type ExtractionResult, FILE_BY_FILE_HINT, PUBLISH_SCRATCH_ID, type PublishCompleter, type PublishCompleterOptions, type PublishFacts, type PublishHandlerOptions, type PublishLimits, type PublishOutcome, type PublishZipOptions, ZipInvalidError, ZipLimitError, createPublishCompleter, createPublishHandler, extractZipStream, extractionLimitsOf, publishRoute, publishStoredZip, publishVerdict, publishingOf, resolvePublishLimits };

package/dist/capture/publish/invalid-zip.d.mts

@@ -0,0 +1,8 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+/** An archive that cannot be parsed; retrying the same bytes cannot help. */
+declare class ZipInvalidError extends Error {
+  readonly name = "ZipInvalidError";
+}
+export { ZipInvalidError };
+//# sourceMappingURL=invalid-zip.d.mts.map

package/dist/capture/publish/invalid-zip.mjs

@@ -0,0 +1,11 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// src/capture/publish/invalid-zip.ts
+/** An archive that cannot be parsed; retrying the same bytes cannot help. */
+var ZipInvalidError = class extends Error {
+	name = "ZipInvalidError";
+};
+export { ZipInvalidError };
+
+//# sourceMappingURL=invalid-zip.mjs.map

package/dist/capture/publish/invalid-zip.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalid-zip.mjs","names":[],"sources":["../../../src/capture/publish/invalid-zip.ts"],"sourcesContent":["/** An archive that cannot be parsed; retrying the same bytes cannot help. */\nexport class ZipInvalidError extends Error {\n  override readonly name = \"ZipInvalidError\";\n}\n"],"mappings":";;;;;AACA,IAAa,kBAAb,cAAqC,MAAM;CACzC,OAAyB;AAC3B"}

package/dist/capture/publish/limits.d.mts

@@ -0,0 +1,35 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { ShelfConfig } from "../../config.mjs";
+/** Zip size (bytes) up to which a zip is extracted inline in the upload request: 50 MB. */
+declare const DEFAULT_MAX_INLINE_UNZIP_SIZE: number;
+/** Entries an uploaded Storybook zip may hold. A large Storybook has some thousands of files. */
+declare const DEFAULT_MAX_ZIP_ENTRIES = 50000;
+/** Total uncompressed bytes an uploaded Storybook zip may expand to: 2 GiB. */
+declare const DEFAULT_MAX_UNZIPPED_BYTES: number;
+/** Caps enforced while a zip is extracted; the compressed size alone is no bound. */
+interface ExtractionLimits {
+  /** Most entries (files and directories) the archive may hold. */
+  maxEntries: number;
+  /** Most uncompressed bytes all files together may expand to, counted while streaming. */
+  maxBytes: number;
+}
+/** Everything the publish pipeline reads from `ShelfConfig`, defaults applied. */
+interface PublishLimits extends ExtractionLimits {
+  /** Largest zip extracted inline in the upload request; `0` sends every zip to a `publish` job. */
+  inlineBytes: number;
+}
+/** The effective publish limits of a config. */
+declare function resolvePublishLimits(config?: Pick<ShelfConfig, "maxInlineUnzipSize" | "maxZipEntries" | "maxUnzippedBytes">): PublishLimits;
+/** The extraction caps alone. */
+declare function extractionLimitsOf(limits: PublishLimits | ExtractionLimits): ExtractionLimits;
+/** How an upload of `zipBytes` is published: inline in the request, or by a `publish` job. */
+declare function publishRoute(zipBytes: number, limits: Pick<PublishLimits, "inlineBytes">): "inline" | "job";
+/** An archive that breaks a cap or tries to write outside the target; retrying cannot help. */
+declare class ZipLimitError extends Error {
+  readonly name = "ZipLimitError";
+}
+/** Message of the 413 an over-limit zip gets on a host with no `publish` consumer. */
+declare const FILE_BY_FILE_HINT: string;
+export { DEFAULT_MAX_INLINE_UNZIP_SIZE, DEFAULT_MAX_UNZIPPED_BYTES, DEFAULT_MAX_ZIP_ENTRIES, ExtractionLimits, FILE_BY_FILE_HINT, PublishLimits, ZipLimitError, extractionLimitsOf, publishRoute, resolvePublishLimits };
+//# sourceMappingURL=limits.d.mts.map

package/dist/capture/publish/limits.mjs

@@ -0,0 +1,38 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// src/capture/publish/limits.ts
+/** Zip size (bytes) up to which a zip is extracted inline in the upload request: 50 MB. */
+const DEFAULT_MAX_INLINE_UNZIP_SIZE = 52428800;
+/** Entries an uploaded Storybook zip may hold. A large Storybook has some thousands of files. */
+const DEFAULT_MAX_ZIP_ENTRIES = 5e4;
+/** Total uncompressed bytes an uploaded Storybook zip may expand to: 2 GiB. */
+const DEFAULT_MAX_UNZIPPED_BYTES = 2147483648;
+/** The effective publish limits of a config. */
+function resolvePublishLimits(config) {
+	return {
+		inlineBytes: config?.maxInlineUnzipSize ?? 52428800,
+		maxEntries: config?.maxZipEntries ?? 5e4,
+		maxBytes: config?.maxUnzippedBytes ?? 2147483648
+	};
+}
+/** The extraction caps alone. */
+function extractionLimitsOf(limits) {
+	return {
+		maxEntries: limits.maxEntries,
+		maxBytes: limits.maxBytes
+	};
+}
+/** How an upload of `zipBytes` is published: inline in the request, or by a `publish` job. */
+function publishRoute(zipBytes, limits) {
+	return zipBytes <= limits.inlineBytes ? "inline" : "job";
+}
+/** An archive that breaks a cap or tries to write outside the target; retrying cannot help. */
+var ZipLimitError = class extends Error {
+	name = "ZipLimitError";
+};
+/** Message of the 413 an over-limit zip gets on a host with no `publish` consumer. */
+const FILE_BY_FILE_HINT = "Zip is larger than the inline publish limit and this host runs no publish consumer. Upload the Storybook file by file instead: POST /dedup, then PUT /content, then POST /manifest (the storyshelf CLI does this when it is given a directory).";
+export { DEFAULT_MAX_INLINE_UNZIP_SIZE, DEFAULT_MAX_UNZIPPED_BYTES, DEFAULT_MAX_ZIP_ENTRIES, FILE_BY_FILE_HINT, ZipLimitError, extractionLimitsOf, publishRoute, resolvePublishLimits };
+
+//# sourceMappingURL=limits.mjs.map

package/dist/capture/publish/limits.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.mjs","names":[],"sources":["../../../src/capture/publish/limits.ts"],"sourcesContent":["/** Publish limits (ADR 0006, decision 10): the inline threshold and the extraction caps, with defaults. */\nimport type { ShelfConfig } from \"../../config.ts\";\n\n/** Zip size (bytes) up to which a zip is extracted inline in the upload request: 50 MB. */\nexport const DEFAULT_MAX_INLINE_UNZIP_SIZE = 50 * 1024 * 1024;\n\n/** Entries an uploaded Storybook zip may hold. A large Storybook has some thousands of files. */\nexport const DEFAULT_MAX_ZIP_ENTRIES = 50_000;\n\n/** Total uncompressed bytes an uploaded Storybook zip may expand to: 2 GiB. */\nexport const DEFAULT_MAX_UNZIPPED_BYTES = 2 * 1024 * 1024 * 1024;\n\n/** Caps enforced while a zip is extracted; the compressed size alone is no bound. */\nexport interface ExtractionLimits {\n  /** Most entries (files and directories) the archive may hold. */\n  maxEntries: number;\n  /** Most uncompressed bytes all files together may expand to, counted while streaming. */\n  maxBytes: number;\n}\n\n/** Everything the publish pipeline reads from `ShelfConfig`, defaults applied. */\nexport interface PublishLimits extends ExtractionLimits {\n  /** Largest zip extracted inline in the upload request; `0` sends every zip to a `publish` job. */\n  inlineBytes: number;\n}\n\n/** The effective publish limits of a config. */\nexport function resolvePublishLimits(\n  config?: Pick<ShelfConfig, \"maxInlineUnzipSize\" | \"maxZipEntries\" | \"maxUnzippedBytes\">,\n): PublishLimits {\n  return {\n    inlineBytes: config?.maxInlineUnzipSize ?? DEFAULT_MAX_INLINE_UNZIP_SIZE,\n    maxEntries: config?.maxZipEntries ?? DEFAULT_MAX_ZIP_ENTRIES,\n    maxBytes: config?.maxUnzippedBytes ?? DEFAULT_MAX_UNZIPPED_BYTES,\n  };\n}\n\n/** The extraction caps alone. */\nexport function extractionLimitsOf(limits: PublishLimits | ExtractionLimits): ExtractionLimits {\n  return { maxEntries: limits.maxEntries, maxBytes: limits.maxBytes };\n}\n\n/** How an upload of `zipBytes` is published: inline in the request, or by a `publish` job. */\nexport function publishRoute(\n  zipBytes: number,\n  limits: Pick<PublishLimits, \"inlineBytes\">,\n): \"inline\" | \"job\" {\n  return zipBytes <= limits.inlineBytes ? \"inline\" : \"job\";\n}\n\n/** An archive that breaks a cap or tries to write outside the target; retrying cannot help. */\nexport class ZipLimitError extends Error {\n  override readonly name = \"ZipLimitError\";\n}\n\n/** Message of the 413 an over-limit zip gets on a host with no `publish` consumer. */\nexport const FILE_BY_FILE_HINT =\n  \"Zip is larger than the inline publish limit and this host runs no publish consumer. \" +\n  \"Upload the Storybook file by file instead: POST /dedup, then PUT /content, then POST /manifest \" +\n  \"(the storyshelf CLI does this when it is given a directory).\";\n"],"mappings":";;;;;AAIA,MAAa,gCAAgC;;AAG7C,MAAa,0BAA0B;;AAGvC,MAAa,6BAA6B;;AAiB1C,SAAgB,qBACd,QACe;CACf,OAAO;EACL,aAAa,QAAQ,sBAAA;EACrB,YAAY,QAAQ,iBAAA;EACpB,UAAU,QAAQ,oBAAA;CACpB;AACF;;AAGA,SAAgB,mBAAmB,QAA4D;CAC7F,OAAO;EAAE,YAAY,OAAO;EAAY,UAAU,OAAO;CAAS;AACpE;;AAGA,SAAgB,aACd,UACA,QACkB;CAClB,OAAO,YAAY,OAAO,cAAc,WAAW;AACrD;;AAGA,IAAa,gBAAb,cAAmC,MAAM;CACvC,OAAyB;AAC3B;;AAGA,MAAa,oBACX"}

package/dist/capture/publish/published.d.mts

@@ -0,0 +1,13 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { StorageAdapter } from "../../adapter/storage.mjs";
+import { PublishingState } from "../../adapters/notifier/build-state.mjs";
+import { Build } from "../../schema/build.mjs";
+/**
+ * How publishing the build stands. The manifest is written last, so its presence means done. A
+ * `failed` or `cancelled` build without one did not publish (or never uploaded); any other build waits. Without
+ * a storage adapter nothing can be read, so publishing reads as pending.
+ */
+declare function publishingOf(storage: StorageAdapter | undefined, build: Pick<Build, "id" | "projectId" | "status">): Promise<PublishingState>;
+export { publishingOf };
+//# sourceMappingURL=published.d.mts.map

package/dist/capture/publish/published.mjs

@@ -0,0 +1,17 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { storybookDir } from "../../paths.mjs";
+// src/capture/publish/published.ts
+/**
+* How publishing the build stands. The manifest is written last, so its presence means done. A
+* `failed` or `cancelled` build without one did not publish (or never uploaded); any other build waits. Without
+* a storage adapter nothing can be read, so publishing reads as pending.
+*/
+async function publishingOf(storage, build) {
+	if (storage !== void 0 && await storage.exists(`${storybookDir(build.projectId, build.id)}/manifest.json`)) return "success";
+	return build.status === "failed" || build.status === "cancelled" ? "failure" : "pending";
+}
+export { publishingOf };
+
+//# sourceMappingURL=published.mjs.map

package/dist/capture/publish/published.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"published.mjs","names":[],"sources":["../../../src/capture/publish/published.ts"],"sourcesContent":["/**\n * Whether a build's Storybook is published: the one probe behind the `<prefix>/storybook` status\n * (ADR 0014) and the rule that a verdict waits for publishing to end (ADR 0013, decision 3).\n */\nimport type { PublishingState } from \"../../adapters/notifier/build-state.ts\";\nimport type { StorageAdapter } from \"../../adapters/storage.ts\";\nimport type { Build } from \"../../schema/build.ts\";\nimport { storybookDir } from \"../../utils/paths.ts\";\n\n/**\n * How publishing the build stands. The manifest is written last, so its presence means done. A\n * `failed` or `cancelled` build without one did not publish (or never uploaded); any other build waits. Without\n * a storage adapter nothing can be read, so publishing reads as pending.\n */\nexport async function publishingOf(\n  storage: StorageAdapter | undefined,\n  build: Pick<Build, \"id\" | \"projectId\" | \"status\">,\n): Promise<PublishingState> {\n  const published =\n    storage !== undefined &&\n    (await storage.exists(`${storybookDir(build.projectId, build.id)}/manifest.json`));\n  if (published) {\n    return \"success\";\n  }\n  return build.status === \"failed\" || build.status === \"cancelled\" ? \"failure\" : \"pending\";\n}\n"],"mappings":";;;;;;;;;;AAcA,eAAsB,aACpB,SACA,OAC0B;CAI1B,IAFE,YAAY,KAAA,KACX,MAAM,QAAQ,OAAO,GAAG,aAAa,MAAM,WAAW,MAAM,EAAE,EAAE,eAAe,GAEhF,OAAO;CAET,OAAO,MAAM,WAAW,YAAY,MAAM,WAAW,cAAc,YAAY;AACjF"}

package/dist/capture/publish/run.d.mts

@@ -0,0 +1,31 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Logger } from "../../logger.mjs";
+import { DatabaseAdapter } from "../../adapter/database.mjs";
+import { StorageAdapter } from "../../adapter/storage.mjs";
+import { ExtractionLimits } from "./limits.mjs";
+/** Scratch id publishing uses, so it never shares a directory with the build's capture. */
+declare const PUBLISH_SCRATCH_ID = "publish";
+/** What {@link publishStoredZip} works with. */
+interface PublishZipOptions {
+  storage: StorageAdapter;
+  scratchDir: string;
+  limits: ExtractionLimits;
+  /** Records the persisted content in `content_refs`, so retention knows who still uses it. */
+  db?: DatabaseAdapter | undefined;
+  logger: Logger;
+  /** Called between stages (renews a job's lease). */
+  touch?: () => void;
+}
+/**
+ * Extract `storybook.zip` of a build and persist its statics. The manifest is written last, so a
+ * build serves only once complete and a repeat run rewrites the same keys.
+ *
+ * @throws {ZipLimitError} When the zip breaks a cap or tries to escape the target.
+ */
+declare function publishStoredZip(options: PublishZipOptions, target: {
+  projectId: string;
+  buildId: string;
+}): Promise<void>;
+export { PUBLISH_SCRATCH_ID, PublishZipOptions, publishStoredZip };
+//# sourceMappingURL=run.d.mts.map

package/dist/capture/publish/run.mjs

@@ -0,0 +1,29 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { removeShardScratch } from "../scratch.mjs";
+import { extractStorybookToScratch, persistStorybookStatics } from "../statics.mjs";
+// src/capture/publish/run.ts
+/** Scratch id publishing uses, so it never shares a directory with the build's capture. */
+const PUBLISH_SCRATCH_ID = "publish";
+/**
+* Extract `storybook.zip` of a build and persist its statics. The manifest is written last, so a
+* build serves only once complete and a repeat run rewrites the same keys.
+*
+* @throws {ZipLimitError} When the zip breaks a cap or tries to escape the target.
+*/
+async function publishStoredZip(options, target) {
+	const { storage, scratchDir, logger } = options;
+	const { projectId, buildId } = target;
+	try {
+		const dir = await extractStorybookToScratch(storage, scratchDir, projectId, buildId, PUBLISH_SCRATCH_ID, options.limits);
+		options.touch?.();
+		await persistStorybookStatics(storage, dir, projectId, buildId, options.db);
+		options.touch?.();
+	} finally {
+		await removeShardScratch(scratchDir, projectId, buildId, PUBLISH_SCRATCH_ID, logger);
+	}
+}
+export { PUBLISH_SCRATCH_ID, publishStoredZip };
+
+//# sourceMappingURL=run.mjs.map

package/dist/capture/publish/run.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.mjs","names":[],"sources":["../../../src/capture/publish/run.ts"],"sourcesContent":["/** Publish a build's stored zip: extract with the caps, persist statics and manifest, clean the scratch. */\nimport type { DatabaseAdapter } from \"../../adapters/database.ts\";\nimport type { StorageAdapter } from \"../../adapters/storage.ts\";\nimport type { Logger } from \"../../logger.ts\";\nimport { removeShardScratch } from \"../scratch.ts\";\nimport { extractStorybookToScratch, persistStorybookStatics } from \"../statics.ts\";\nimport type { ExtractionLimits } from \"./limits.ts\";\n\n/** Scratch id publishing uses, so it never shares a directory with the build's capture. */\nexport const PUBLISH_SCRATCH_ID = \"publish\";\n\n/** What {@link publishStoredZip} works with. */\nexport interface PublishZipOptions {\n  storage: StorageAdapter;\n  scratchDir: string;\n  limits: ExtractionLimits;\n  /** Records the persisted content in `content_refs`, so retention knows who still uses it. */\n  db?: DatabaseAdapter | undefined;\n  logger: Logger;\n  /** Called between stages (renews a job's lease). */\n  touch?: () => void;\n}\n\n/**\n * Extract `storybook.zip` of a build and persist its statics. The manifest is written last, so a\n * build serves only once complete and a repeat run rewrites the same keys.\n *\n * @throws {ZipLimitError} When the zip breaks a cap or tries to escape the target.\n */\nexport async function publishStoredZip(\n  options: PublishZipOptions,\n  target: { projectId: string; buildId: string },\n): Promise<void> {\n  const { storage, scratchDir, logger } = options;\n  const { projectId, buildId } = target;\n  try {\n    const dir = await extractStorybookToScratch(\n      storage,\n      scratchDir,\n      projectId,\n      buildId,\n      PUBLISH_SCRATCH_ID,\n      options.limits,\n    );\n    options.touch?.();\n    await persistStorybookStatics(storage, dir, projectId, buildId, options.db);\n    options.touch?.();\n  } finally {\n    await removeShardScratch(scratchDir, projectId, buildId, PUBLISH_SCRATCH_ID, logger);\n  }\n}\n"],"mappings":";;;;;;;AASA,MAAa,qBAAqB;;;;;;;AAoBlC,eAAsB,iBACpB,SACA,QACe;CACf,MAAM,EAAE,SAAS,YAAY,WAAW;CACxC,MAAM,EAAE,WAAW,YAAY;CAC/B,IAAI;EACF,MAAM,MAAM,MAAM,0BAChB,SACA,YACA,WACA,SACA,oBACA,QAAQ,MACV;EACA,QAAQ,QAAQ;EAChB,MAAM,wBAAwB,SAAS,KAAK,WAAW,SAAS,QAAQ,EAAE;EAC1E,QAAQ,QAAQ;CAClB,UAAU;EACR,MAAM,mBAAmB,YAAY,WAAW,SAAS,oBAAoB,MAAM;CACrF;AACF"}

package/dist/capture/rediff.d.mts

@@ -1,11 +1,10 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
+import { Logger } from "../logger.mjs";
 import { DatabaseAdapter } from "../adapter/database.mjs";
 import { StorageAdapter } from "../adapter/storage.mjs";
-import { Logger } from "../logger.mjs";
 import { Build } from "../schema/build.mjs";
 import { Project } from "../schema/project.mjs";
-//#region src/capture/rediff.d.ts
 /** Dependencies for {@link rediffBuild}. */
 interface RediffDeps {
   db: DatabaseAdapter;
@@ -30,6 +29,5 @@ declare const REDIFFABLE_BUILD_STATUSES: ReadonlySet<string>;
  * rendered. The caller refreshes the build rollup afterwards.
  */
 declare function rediffBuild(deps: RediffDeps, project: Project, build: Build): Promise<RediffResult>;
-//#endregion
 export { REDIFFABLE_BUILD_STATUSES, RediffDeps, RediffResult, rediffBuild };
 //# sourceMappingURL=rediff.d.mts.map

package/dist/capture/rediff.mjs

@@ -2,12 +2,14 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { diffPath } from "../paths.mjs";
-import { BaselineModel } from "../models/baseline.mjs";
 import { NO_BASELINE } from "../models/baseline-status.mjs";
+import { BaselineModel } from "../models/baseline.mjs";
 import { SnapshotModel } from "../models/snapshot.mjs";
+import { mapLimit } from "../utils/map-limit.mjs";
+import { freezeComparison, isComparisonImagePath, parseComparisonReference, sourceSnapshotId } from "./comparison-reference.mjs";
 import { diffStoredScreenshots, writeDiffOverlay } from "./diff-record.mjs";
 import { diffStatus } from "./pipeline.mjs";
-//#region src/capture/rediff.ts
+// src/capture/rediff.ts
 /** Build statuses a re-diff may run in; earlier or failed builds have no complete snapshot set. */
 const REDIFFABLE_BUILD_STATUSES = /* @__PURE__ */ new Set([
 	"reviewing",
@@ -27,7 +29,7 @@ const REDIFFABLE_SNAPSHOT_STATUSES = /* @__PURE__ */ new Set([
 */
 async function rediffBuild(deps, project, build) {
 	const rows = (await new SnapshotModel(deps.db).listByBuild(build.id)).filter((row) => !row.inherited && REDIFFABLE_SNAPSHOT_STATUSES.has(row.status));
-	const outcomes = await Promise.all(rows.map(async (row) => await rediffSnapshot(deps, project, build, row)));
+	const outcomes = await mapLimit(rows, 4, async (row) => await rediffSnapshot(deps, project, build, row));
 	const result = {
 		rediffed: outcomes.filter((outcome) => outcome !== "missing").length,
 		statusChanged: outcomes.filter((outcome) => outcome === "changed").length,
@@ -41,9 +43,10 @@ async function rediffBuild(deps, project, build) {
 }
 async function rediffSnapshot(deps, project, build, row) {
 	if (!await deps.storage.exists(row.screenshotPath)) return "missing";
-	const baseline = await new BaselineModel(deps.db).resolve(project.id, row.storyId, row.viewportName, build.gitBranch, project.gitDefaultBranch);
+	const baseline = await new BaselineModel(deps.db).resolve(project.id, row.storyId, row.viewportName, build.gitBranch, project.gitDefaultBranch, row.browser);
 	const patch = baseline ? await diffPatch(deps, project, build, row, baseline) : noBaselinePatch();
 	await new SnapshotModel(deps.db).update(row.id, patch);
+	if (row.comparisonImagePath && row.comparisonImagePath !== patch.comparisonImagePath && isComparisonImagePath(row.comparisonImagePath, project.id, build.id)) await deps.storage.delete(row.comparisonImagePath).catch(() => {});
 	return patch.status === row.status ? "same" : "changed";
 }
 function noBaselinePatch() {
@@ -54,12 +57,23 @@ function noBaselinePatch() {
 		diffRatio: null,
 		diffPassed: null,
 		baselineId: null,
-		baselineVersion: NO_BASELINE
+		baselineVersion: NO_BASELINE,
+		comparisonImagePath: null,
+		comparisonMetadata: null
 	};
 }
 async function diffPatch(deps, project, build, row, baseline) {
-	const result = await diffStoredScreenshots(deps.storage, project, baseline.screenshotPath, row.screenshotPath);
-	const target = diffPath(project.id, build.id, row.storyId, row.viewportName);
+	const comparison = await freezeComparison(deps.storage, project.id, build.id, baseline, {
+		defaultBranch: project.gitDefaultBranch,
+		mode: row.mode ?? null,
+		target: row.browser ?? "chromium",
+		width: row.viewportWidth ?? null,
+		height: row.viewportHeight ?? null,
+		captureFingerprint: parseComparisonReference(row.comparisonMetadata)?.captureFingerprint ?? null,
+		sourceSnapshotId: await sourceSnapshotId(deps.db, baseline)
+	});
+	const result = await diffStoredScreenshots(deps.storage, project, baseline.screenshotPath === row.screenshotPath ? row.screenshotPath : comparison.comparisonImagePath, row.screenshotPath);
+	const target = diffPath(project.id, build.id, row.storyId, row.viewportName, row.browser);
 	const overlay = await writeDiffOverlay(deps.storage, target, result, result.passed);
 	return {
 		status: diffStatus(result.passed, false),
@@ -68,10 +82,10 @@ async function diffPatch(deps, project, build, row, baseline) {
 		diffRatio: result.diffRatio,
 		diffPassed: result.passed,
 		baselineId: baseline.id,
-		baselineVersion: baseline.updatedAt
+		baselineVersion: baseline.updatedAt,
+		...comparison
 	};
 }
-//#endregion
 export { REDIFFABLE_BUILD_STATUSES, rediffBuild };
 
 //# sourceMappingURL=rediff.mjs.map

package/dist/capture/rediff.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"rediff.mjs","names":[],"sources":["../../src/capture/rediff.ts"],"sourcesContent":["/** Recompute a build's diffs against the baselines that apply now, without re-rendering. */\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport type { StorageAdapter } from \"../adapters/storage.ts\";\nimport type { Logger } from \"../logger.ts\";\nimport { NO_BASELINE } from \"../models/baseline-status.ts\";\nimport { BaselineModel } from \"../models/baseline.ts\";\nimport { SnapshotModel } from \"../models/snapshot.ts\";\nimport type { Baseline } from \"../schema/baseline.ts\";\nimport type { Build } from \"../schema/build.ts\";\nimport type { Project } from \"../schema/project.ts\";\nimport type { Snapshot } from \"../schema/snapshot.ts\";\nimport { diffPath } from \"../utils/paths.ts\";\nimport { diffStoredScreenshots, writeDiffOverlay } from \"./diff-record.ts\";\nimport { diffStatus } from \"./pipeline.ts\";\n\n/** Dependencies for {@link rediffBuild}. */\nexport interface RediffDeps {\n  db: DatabaseAdapter;\n  storage: StorageAdapter;\n  logger?: Logger;\n}\n\n/** Outcome of a re-diff run. */\nexport interface RediffResult {\n  /** Snapshots diffed against their current baseline. */\n  rediffed: number;\n  /** Snapshots whose status changed (for example `changed` to `unchanged`). */\n  statusChanged: number;\n  /** Snapshot ids skipped because their stored screenshot is gone. */\n  missingScreenshots: string[];\n}\n\n/** Build statuses a re-diff may run in; earlier or failed builds have no complete snapshot set. */\nexport const REDIFFABLE_BUILD_STATUSES: ReadonlySet<string> = new Set([\n  \"reviewing\",\n  \"approved\",\n  \"rejected\",\n]);\n\nconst REDIFFABLE_SNAPSHOT_STATUSES: ReadonlySet<string> = new Set([\"new\", \"changed\", \"unchanged\"]);\n\n/**\n * Re-diff the build's undecided snapshots against the baselines that apply today.\n *\n * Approved and rejected snapshots are decisions and stay untouched; inherited snapshots were never\n * rendered. The caller refreshes the build rollup afterwards.\n */\nexport async function rediffBuild(\n  deps: RediffDeps,\n  project: Project,\n  build: Build,\n): Promise<RediffResult> {\n  const snapshots = new SnapshotModel(deps.db);\n  const rows = (await snapshots.listByBuild(build.id)).filter(\n    (row) => !row.inherited && REDIFFABLE_SNAPSHOT_STATUSES.has(row.status),\n  );\n  const outcomes = await Promise.all(\n    rows.map(async (row) => await rediffSnapshot(deps, project, build, row)),\n  );\n  const result: RediffResult = {\n    rediffed: outcomes.filter((outcome) => outcome !== \"missing\").length,\n    statusChanged: outcomes.filter((outcome) => outcome === \"changed\").length,\n    missingScreenshots: rows\n      .filter((_row, index) => outcomes[index] === \"missing\")\n      .map((row) => row.id),\n  };\n  deps.logger?.info({ buildId: build.id, ...result }, \"build re-diffed against current baselines\");\n  return result;\n}\n\ntype Outcome = \"same\" | \"changed\" | \"missing\";\n\nasync function rediffSnapshot(\n  deps: RediffDeps,\n  project: Project,\n  build: Build,\n  row: Snapshot,\n): Promise<Outcome> {\n  if (!(await deps.storage.exists(row.screenshotPath))) {\n    return \"missing\";\n  }\n  const baseline = await new BaselineModel(deps.db).resolve(\n    project.id,\n    row.storyId,\n    row.viewportName,\n    build.gitBranch,\n    project.gitDefaultBranch,\n  );\n  const patch = baseline ? await diffPatch(deps, project, build, row, baseline) : noBaselinePatch();\n  await new SnapshotModel(deps.db).update(row.id, patch);\n  return patch.status === row.status ? \"same\" : \"changed\";\n}\n\nfunction noBaselinePatch(): Partial<Snapshot> {\n  return {\n    status: \"new\",\n    diffPath: null,\n    diffPixels: null,\n    diffRatio: null,\n    diffPassed: null,\n    baselineId: null,\n    baselineVersion: NO_BASELINE,\n  };\n}\n\nasync function diffPatch(\n  deps: RediffDeps,\n  project: Project,\n  build: Build,\n  row: Snapshot,\n  baseline: Baseline,\n): Promise<Partial<Snapshot>> {\n  const result = await diffStoredScreenshots(\n    deps.storage,\n    project,\n    baseline.screenshotPath,\n    row.screenshotPath,\n  );\n  const target = diffPath(project.id, build.id, row.storyId, row.viewportName);\n  const overlay = await writeDiffOverlay(deps.storage, target, result, result.passed);\n  return {\n    status: diffStatus(result.passed, false),\n    diffPath: overlay,\n    diffPixels: result.diffPixels,\n    diffRatio: result.diffRatio,\n    diffPassed: result.passed,\n    baselineId: baseline.id,\n    baselineVersion: baseline.updatedAt,\n  };\n}\n"],"mappings":";;;;;;;;;;;AAiCA,MAAa,4CAAiD,IAAI,IAAI;CACpE;CACA;CACA;AACF,CAAC;AAED,MAAM,+CAAoD,IAAI,IAAI;CAAC;CAAO;CAAW;AAAW,CAAC;;;;;;;AAQjG,eAAsB,YACpB,MACA,SACA,OACuB;CAEvB,MAAM,QAAQ,MAAM,IADE,cAAc,KAAK,EACb,CAAC,CAAC,YAAY,MAAM,EAAE,EAAA,CAAG,QAClD,QAAQ,CAAC,IAAI,aAAa,6BAA6B,IAAI,IAAI,MAAM,CACxE;CACA,MAAM,WAAW,MAAM,QAAQ,IAC7B,KAAK,IAAI,OAAO,QAAQ,MAAM,eAAe,MAAM,SAAS,OAAO,GAAG,CAAC,CACzE;CACA,MAAM,SAAuB;EAC3B,UAAU,SAAS,QAAQ,YAAY,YAAY,SAAS,CAAC,CAAC;EAC9D,eAAe,SAAS,QAAQ,YAAY,YAAY,SAAS,CAAC,CAAC;EACnE,oBAAoB,KACjB,QAAQ,MAAM,UAAU,SAAS,WAAW,SAAS,CAAC,CACtD,KAAK,QAAQ,IAAI,EAAE;CACxB;CACA,KAAK,QAAQ,KAAK;EAAE,SAAS,MAAM;EAAI,GAAG;CAAO,GAAG,2CAA2C;CAC/F,OAAO;AACT;AAIA,eAAe,eACb,MACA,SACA,OACA,KACkB;CAClB,IAAI,CAAE,MAAM,KAAK,QAAQ,OAAO,IAAI,cAAc,GAChD,OAAO;CAET,MAAM,WAAW,MAAM,IAAI,cAAc,KAAK,EAAE,CAAC,CAAC,QAChD,QAAQ,IACR,IAAI,SACJ,IAAI,cACJ,MAAM,WACN,QAAQ,gBACV;CACA,MAAM,QAAQ,WAAW,MAAM,UAAU,MAAM,SAAS,OAAO,KAAK,QAAQ,IAAI,gBAAgB;CAChG,MAAM,IAAI,cAAc,KAAK,EAAE,CAAC,CAAC,OAAO,IAAI,IAAI,KAAK;CACrD,OAAO,MAAM,WAAW,IAAI,SAAS,SAAS;AAChD;AAEA,SAAS,kBAAqC;CAC5C,OAAO;EACL,QAAQ;EACR,UAAU;EACV,YAAY;EACZ,WAAW;EACX,YAAY;EACZ,YAAY;EACZ,iBAAiB;CACnB;AACF;AAEA,eAAe,UACb,MACA,SACA,OACA,KACA,UAC4B;CAC5B,MAAM,SAAS,MAAM,sBACnB,KAAK,SACL,SACA,SAAS,gBACT,IAAI,cACN;CACA,MAAM,SAAS,SAAS,QAAQ,IAAI,MAAM,IAAI,IAAI,SAAS,IAAI,YAAY;CAC3E,MAAM,UAAU,MAAM,iBAAiB,KAAK,SAAS,QAAQ,QAAQ,OAAO,MAAM;CAClF,OAAO;EACL,QAAQ,WAAW,OAAO,QAAQ,KAAK;EACvC,UAAU;EACV,YAAY,OAAO;EACnB,WAAW,OAAO;EAClB,YAAY,OAAO;EACnB,YAAY,SAAS;EACrB,iBAAiB,SAAS;CAC5B;AACF"}
+{"version":3,"file":"rediff.mjs","names":[],"sources":["../../src/capture/rediff.ts"],"sourcesContent":["/** Recompute a build's diffs against the baselines that apply now, without re-rendering. */\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport type { StorageAdapter } from \"../adapters/storage.ts\";\nimport type { Logger } from \"../logger.ts\";\nimport { NO_BASELINE } from \"../models/baseline-status.ts\";\nimport { BaselineModel } from \"../models/baseline.ts\";\nimport { SnapshotModel } from \"../models/snapshot.ts\";\nimport type { Baseline } from \"../schema/baseline.ts\";\nimport type { Build } from \"../schema/build.ts\";\nimport type { Project } from \"../schema/project.ts\";\nimport type { Snapshot } from \"../schema/snapshot.ts\";\nimport { mapLimit } from \"../utils/map-limit.ts\";\nimport { diffPath } from \"../utils/paths.ts\";\nimport {\n  freezeComparison,\n  isComparisonImagePath,\n  parseComparisonReference,\n  sourceSnapshotId,\n} from \"./comparison-reference.ts\";\nimport { diffStoredScreenshots, writeDiffOverlay } from \"./diff-record.ts\";\nimport { diffStatus, PERSIST_CONCURRENCY } from \"./pipeline.ts\";\n\n/** Dependencies for {@link rediffBuild}. */\nexport interface RediffDeps {\n  db: DatabaseAdapter;\n  storage: StorageAdapter;\n  logger?: Logger;\n}\n\n/** Outcome of a re-diff run. */\nexport interface RediffResult {\n  /** Snapshots diffed against their current baseline. */\n  rediffed: number;\n  /** Snapshots whose status changed (for example `changed` to `unchanged`). */\n  statusChanged: number;\n  /** Snapshot ids skipped because their stored screenshot is gone. */\n  missingScreenshots: string[];\n}\n\n/** Build statuses a re-diff may run in; earlier or failed builds have no complete snapshot set. */\nexport const REDIFFABLE_BUILD_STATUSES: ReadonlySet<string> = new Set([\n  \"reviewing\",\n  \"approved\",\n  \"rejected\",\n]);\n\nconst REDIFFABLE_SNAPSHOT_STATUSES: ReadonlySet<string> = new Set([\"new\", \"changed\", \"unchanged\"]);\n\n/**\n * Re-diff the build's undecided snapshots against the baselines that apply today.\n *\n * Approved and rejected snapshots are decisions and stay untouched; inherited snapshots were never\n * rendered. The caller refreshes the build rollup afterwards.\n */\nexport async function rediffBuild(\n  deps: RediffDeps,\n  project: Project,\n  build: Build,\n): Promise<RediffResult> {\n  const snapshots = new SnapshotModel(deps.db);\n  const rows = (await snapshots.listByBuild(build.id)).filter(\n    (row) => !row.inherited && REDIFFABLE_SNAPSHOT_STATUSES.has(row.status),\n  );\n  const outcomes = await mapLimit(\n    rows,\n    PERSIST_CONCURRENCY,\n    async (row) => await rediffSnapshot(deps, project, build, row),\n  );\n  const result: RediffResult = {\n    rediffed: outcomes.filter((outcome) => outcome !== \"missing\").length,\n    statusChanged: outcomes.filter((outcome) => outcome === \"changed\").length,\n    missingScreenshots: rows\n      .filter((_row, index) => outcomes[index] === \"missing\")\n      .map((row) => row.id),\n  };\n  deps.logger?.info({ buildId: build.id, ...result }, \"build re-diffed against current baselines\");\n  return result;\n}\n\ntype Outcome = \"same\" | \"changed\" | \"missing\";\n\nasync function rediffSnapshot(\n  deps: RediffDeps,\n  project: Project,\n  build: Build,\n  row: Snapshot,\n): Promise<Outcome> {\n  if (!(await deps.storage.exists(row.screenshotPath))) {\n    return \"missing\";\n  }\n  const baseline = await new BaselineModel(deps.db).resolve(\n    project.id,\n    row.storyId,\n    row.viewportName,\n    build.gitBranch,\n    project.gitDefaultBranch,\n    row.browser,\n  );\n  const patch = baseline ? await diffPatch(deps, project, build, row, baseline) : noBaselinePatch();\n  await new SnapshotModel(deps.db).update(row.id, patch);\n  if (\n    row.comparisonImagePath &&\n    row.comparisonImagePath !== patch.comparisonImagePath &&\n    isComparisonImagePath(row.comparisonImagePath, project.id, build.id)\n  ) {\n    await deps.storage.delete(row.comparisonImagePath).catch(() => {});\n  }\n  return patch.status === row.status ? \"same\" : \"changed\";\n}\n\nfunction noBaselinePatch(): Partial<Snapshot> {\n  return {\n    status: \"new\",\n    diffPath: null,\n    diffPixels: null,\n    diffRatio: null,\n    diffPassed: null,\n    baselineId: null,\n    baselineVersion: NO_BASELINE,\n    comparisonImagePath: null,\n    comparisonMetadata: null,\n  };\n}\n\nasync function diffPatch(\n  deps: RediffDeps,\n  project: Project,\n  build: Build,\n  row: Snapshot,\n  baseline: Baseline,\n): Promise<Partial<Snapshot>> {\n  const comparison = await freezeComparison(deps.storage, project.id, build.id, baseline, {\n    defaultBranch: project.gitDefaultBranch,\n    mode: row.mode ?? null,\n    target: row.browser ?? \"chromium\",\n    width: row.viewportWidth ?? null,\n    height: row.viewportHeight ?? null,\n    captureFingerprint:\n      parseComparisonReference(row.comparisonMetadata)?.captureFingerprint ?? null,\n    sourceSnapshotId: await sourceSnapshotId(deps.db, baseline),\n  });\n  const result = await diffStoredScreenshots(\n    deps.storage,\n    project,\n    baseline.screenshotPath === row.screenshotPath\n      ? row.screenshotPath\n      : comparison.comparisonImagePath,\n    row.screenshotPath,\n  );\n  const target = diffPath(project.id, build.id, row.storyId, row.viewportName, row.browser);\n  const overlay = await writeDiffOverlay(deps.storage, target, result, result.passed);\n  return {\n    status: diffStatus(result.passed, false),\n    diffPath: overlay,\n    diffPixels: result.diffPixels,\n    diffRatio: result.diffRatio,\n    diffPassed: result.passed,\n    baselineId: baseline.id,\n    baselineVersion: baseline.updatedAt,\n    ...comparison,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;AAwCA,MAAa,4CAAiD,IAAI,IAAI;CACpE;CACA;CACA;AACF,CAAC;AAED,MAAM,+CAAoD,IAAI,IAAI;CAAC;CAAO;CAAW;AAAW,CAAC;;;;;;;AAQjG,eAAsB,YACpB,MACA,SACA,OACuB;CAEvB,MAAM,QAAQ,MAAM,IADE,cAAc,KAAK,EACb,CAAC,CAAC,YAAY,MAAM,EAAE,EAAA,CAAG,QAClD,QAAQ,CAAC,IAAI,aAAa,6BAA6B,IAAI,IAAI,MAAM,CACxE;CACA,MAAM,WAAW,MAAM,SACrB,MAAA,GAEA,OAAO,QAAQ,MAAM,eAAe,MAAM,SAAS,OAAO,GAAG,CAC/D;CACA,MAAM,SAAuB;EAC3B,UAAU,SAAS,QAAQ,YAAY,YAAY,SAAS,CAAC,CAAC;EAC9D,eAAe,SAAS,QAAQ,YAAY,YAAY,SAAS,CAAC,CAAC;EACnE,oBAAoB,KACjB,QAAQ,MAAM,UAAU,SAAS,WAAW,SAAS,CAAC,CACtD,KAAK,QAAQ,IAAI,EAAE;CACxB;CACA,KAAK,QAAQ,KAAK;EAAE,SAAS,MAAM;EAAI,GAAG;CAAO,GAAG,2CAA2C;CAC/F,OAAO;AACT;AAIA,eAAe,eACb,MACA,SACA,OACA,KACkB;CAClB,IAAI,CAAE,MAAM,KAAK,QAAQ,OAAO,IAAI,cAAc,GAChD,OAAO;CAET,MAAM,WAAW,MAAM,IAAI,cAAc,KAAK,EAAE,CAAC,CAAC,QAChD,QAAQ,IACR,IAAI,SACJ,IAAI,cACJ,MAAM,WACN,QAAQ,kBACR,IAAI,OACN;CACA,MAAM,QAAQ,WAAW,MAAM,UAAU,MAAM,SAAS,OAAO,KAAK,QAAQ,IAAI,gBAAgB;CAChG,MAAM,IAAI,cAAc,KAAK,EAAE,CAAC,CAAC,OAAO,IAAI,IAAI,KAAK;CACrD,IACE,IAAI,uBACJ,IAAI,wBAAwB,MAAM,uBAClC,sBAAsB,IAAI,qBAAqB,QAAQ,IAAI,MAAM,EAAE,GAEnE,MAAM,KAAK,QAAQ,OAAO,IAAI,mBAAmB,CAAC,CAAC,YAAY,CAAC,CAAC;CAEnE,OAAO,MAAM,WAAW,IAAI,SAAS,SAAS;AAChD;AAEA,SAAS,kBAAqC;CAC5C,OAAO;EACL,QAAQ;EACR,UAAU;EACV,YAAY;EACZ,WAAW;EACX,YAAY;EACZ,YAAY;EACZ,iBAAiB;EACjB,qBAAqB;EACrB,oBAAoB;CACtB;AACF;AAEA,eAAe,UACb,MACA,SACA,OACA,KACA,UAC4B;CAC5B,MAAM,aAAa,MAAM,iBAAiB,KAAK,SAAS,QAAQ,IAAI,MAAM,IAAI,UAAU;EACtF,eAAe,QAAQ;EACvB,MAAM,IAAI,QAAQ;EAClB,QAAQ,IAAI,WAAW;EACvB,OAAO,IAAI,iBAAiB;EAC5B,QAAQ,IAAI,kBAAkB;EAC9B,oBACE,yBAAyB,IAAI,kBAAkB,CAAC,EAAE,sBAAsB;EAC1E,kBAAkB,MAAM,iBAAiB,KAAK,IAAI,QAAQ;CAC5D,CAAC;CACD,MAAM,SAAS,MAAM,sBACnB,KAAK,SACL,SACA,SAAS,mBAAmB,IAAI,iBAC5B,IAAI,iBACJ,WAAW,qBACf,IAAI,cACN;CACA,MAAM,SAAS,SAAS,QAAQ,IAAI,MAAM,IAAI,IAAI,SAAS,IAAI,cAAc,IAAI,OAAO;CACxF,MAAM,UAAU,MAAM,iBAAiB,KAAK,SAAS,QAAQ,QAAQ,OAAO,MAAM;CAClF,OAAO;EACL,QAAQ,WAAW,OAAO,QAAQ,KAAK;EACvC,UAAU;EACV,YAAY,OAAO;EACnB,WAAW,OAAO;EAClB,YAAY,OAAO;EACnB,YAAY,SAAS;EACrB,iBAAiB,SAAS;EAC1B,GAAG;CACL;AACF"}

package/dist/capture/render.mjs

@@ -0,0 +1,52 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import "../utils/storybook-token.mjs";
+import { redactSecrets } from "../utils/redact.mjs";
+// src/capture/render.ts
+/** Default budget for one render call before the orchestrator cancels it. */
+const RENDER_TIMEOUT_MS = 9e5;
+/**
+* Budget for one render call: an explicit setting wins; otherwise the default
+* floor, raised to a per-capture allowance for large matrices. Bounded page
+* concurrency on small hosts makes big builds legitimately take longer than 15 minutes.
+*/
+function renderBudgetMs(captureCount, explicitMs) {
+	return explicitMs ?? Math.max(9e5, captureCount * 15e3);
+}
+/** Failure error text cap (persisted rows and logs stay bounded). */
+const FAILURE_ERROR_MAX = 500;
+/** Cap failure error text so one chatty runner cannot flood rows and logs. */
+function capFailures(result) {
+	return {
+		...result,
+		captures: result.captures,
+		failures: result.failures.map((failure) => ({
+			...failure,
+			error: redactSecrets(failure.error).slice(0, FAILURE_ERROR_MAX)
+		}))
+	};
+}
+/** Render with a timeout; cancels the runner when the budget expires. */
+async function renderWithTimeout(runner, request, timeoutMs) {
+	let timedOut = false;
+	let timer;
+	const timeout = new Promise((_, reject) => {
+		timer = setTimeout(() => {
+			timedOut = true;
+			reject(/* @__PURE__ */ new Error(`Render timed out after ${timeoutMs}ms`));
+		}, timeoutMs);
+	});
+	timer?.unref?.();
+	try {
+		return capFailures(await Promise.race([runner.render(request), timeout]));
+	} catch (error) {
+		if (timedOut) await runner.cancel(request.buildId, request.runId).catch(() => {});
+		throw error;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+export { RENDER_TIMEOUT_MS, renderBudgetMs, renderWithTimeout };
+
+//# sourceMappingURL=render.mjs.map

package/dist/capture/render.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.mjs","names":[],"sources":["../../src/capture/render.ts"],"sourcesContent":["/** Render one engine's pass with a budget; shared by the orchestrator's browser loop. */\nimport type { Logger } from \"pino\";\nimport type {\n  CaptureTarget,\n  CaptureRunner,\n  RenderResult,\n  RenderedSnapshot,\n} from \"../adapters/capture-runner.ts\";\nimport { redactSecrets } from \"../utils/redact.ts\";\nimport { PER_CAPTURE_BUDGET_MS } from \"../utils/storybook-token.ts\";\n\n/** Default budget for one render call before the orchestrator cancels it. */\nexport const RENDER_TIMEOUT_MS = 15 * 60_000;\n\n/**\n * Budget for one render call: an explicit setting wins; otherwise the default\n * floor, raised to a per-capture allowance for large matrices. Bounded page\n * concurrency on small hosts makes big builds legitimately take longer than 15 minutes.\n */\nexport function renderBudgetMs(captureCount: number, explicitMs?: number): number {\n  return explicitMs ?? Math.max(RENDER_TIMEOUT_MS, captureCount * PER_CAPTURE_BUDGET_MS);\n}\n\n/** Failure error text cap (persisted rows and logs stay bounded). */\nconst FAILURE_ERROR_MAX = 500;\n\n/** Render input assembled by the orchestrator for one build. */\nexport interface RenderRequest {\n  buildId: string;\n  /** This render's cancel handle within the build (see `CaptureRunner.render`). */\n  runId?: string | undefined;\n  /** The shard's 1-based position in the build's plan (see `CaptureRunner.render`). */\n  shardIndex?: number | undefined;\n  storybookDir: string;\n  stories: Parameters<CaptureRunner[\"render\"]>[0][\"stories\"];\n  viewports: Parameters<CaptureRunner[\"render\"]>[0][\"viewports\"];\n  logger: Logger | undefined;\n  executePlay: boolean;\n  playTimeoutMs: number;\n  runA11y: boolean;\n  target: CaptureTarget;\n  /** The signed URL a `reach: \"url\"` target opens (never logged); absent for every other target. */\n  storybookUrl?: string | undefined;\n  onCapture?: (capture: RenderedSnapshot) => Promise<void>;\n}\n\n/** Cap failure error text so one chatty runner cannot flood rows and logs. */\nfunction capFailures(result: RenderResult): RenderResult {\n  return {\n    ...result,\n    captures: result.captures,\n    failures: result.failures.map((failure) => ({\n      ...failure,\n      // A runner's error can quote the URL it failed to open, which carries a signed token.\n      error: redactSecrets(failure.error).slice(0, FAILURE_ERROR_MAX),\n    })),\n  };\n}\n\n/** Render with a timeout; cancels the runner when the budget expires. */\nexport async function renderWithTimeout(\n  runner: CaptureRunner,\n  request: RenderRequest,\n  timeoutMs: number,\n): Promise<RenderResult> {\n  let timedOut = false;\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  const timeout = new Promise<never>((_, reject) => {\n    timer = setTimeout(() => {\n      timedOut = true;\n      reject(new Error(`Render timed out after ${timeoutMs}ms`));\n    }, timeoutMs);\n  });\n  timer?.unref?.();\n  try {\n    return capFailures(await Promise.race([runner.render(request), timeout]));\n  } catch (error) {\n    if (timedOut) {\n      // Only this render: a sibling shard of the same build may be rendering in this process.\n      await runner.cancel(request.buildId, request.runId).catch(() => {});\n    }\n    throw error;\n  } finally {\n    clearTimeout(timer);\n  }\n}\n"],"mappings":";;;;;;;AAYA,MAAa,oBAAoB;;;;;;AAOjC,SAAgB,eAAe,cAAsB,YAA6B;CAChF,OAAO,cAAc,KAAK,IAAA,KAAuB,eAAA,IAAoC;AACvF;;AAGA,MAAM,oBAAoB;;AAuB1B,SAAS,YAAY,QAAoC;CACvD,OAAO;EACL,GAAG;EACH,UAAU,OAAO;EACjB,UAAU,OAAO,SAAS,KAAK,aAAa;GAC1C,GAAG;GAEH,OAAO,cAAc,QAAQ,KAAK,CAAC,CAAC,MAAM,GAAG,iBAAiB;EAChE,EAAE;CACJ;AACF;;AAGA,eAAsB,kBACpB,QACA,SACA,WACuB;CACvB,IAAI,WAAW;CACf,IAAI;CACJ,MAAM,UAAU,IAAI,SAAgB,GAAG,WAAW;EAChD,QAAQ,iBAAiB;GACvB,WAAW;GACX,uBAAO,IAAI,MAAM,0BAA0B,UAAU,GAAG,CAAC;EAC3D,GAAG,SAAS;CACd,CAAC;CACD,OAAO,QAAQ;CACf,IAAI;EACF,OAAO,YAAY,MAAM,QAAQ,KAAK,CAAC,OAAO,OAAO,OAAO,GAAG,OAAO,CAAC,CAAC;CAC1E,SAAS,OAAO;EACd,IAAI,UAEF,MAAM,OAAO,OAAO,QAAQ,SAAS,QAAQ,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC;EAEpE,MAAM;CACR,UAAU;EACR,aAAa,KAAK;CACpB;AACF"}

package/dist/capture/scratch.d.mts

@@ -0,0 +1,42 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Logger } from "../logger.mjs";
+/**
+ * Subtree of `scratchDir` that holds extracted Storybooks.
+ *
+ * `scratchDir` is often also the local storage root (dev server, generated servers), where
+ * `<project>/builds/<build>/...` holds screenshots and published statics. Keeping scratch in its
+ * own subtree means removing it can never touch a storage key.
+ */
+declare const SCRATCH_DIRNAME = ".storyshelf-scratch";
+/** Scratch dirs untouched for this long are assumed orphaned by a crash (no capture runs this long). */
+declare const SCRATCH_MAX_AGE_MS: number;
+/** Scratch directory owned by one build: `<scratchDir>/.storyshelf-scratch/<projectId>/<buildId>`. */
+declare function buildScratchDir(scratchDir: string, projectId: string, buildId: string): string;
+/**
+ * Remove the scratch of the build's own job (the plan, or the whole build when it is not sharded)
+ * and the build directory too if nothing else is left in it.
+ *
+ * Shards live in their own `shards/` directory beside `job/`, so this can never reach one: the plan
+ * hands its shards to the queue before it cleans up, and a worker may already be extracting.
+ */
+declare function removeJobScratch(scratchDir: string, projectId: string, buildId: string, logger?: Logger): Promise<void>;
+/** Remove a build's scratch directory. Best effort: a failure is logged, never thrown. */
+declare function removeBuildScratch(scratchDir: string, projectId: string, buildId: string, logger?: Logger): Promise<void>;
+/** Options for {@link sweepOrphanedScratch}. */
+interface ScratchSweepOptions {
+  /** Remove build scratch dirs not modified for this long (default {@link SCRATCH_MAX_AGE_MS}). */
+  maxAgeMs?: number;
+  /** Clock override for tests. */
+  now?: number;
+  logger?: Logger;
+}
+/**
+ * Boot-time sweep for scratch dirs a crash left behind. Age-gated rather than wholesale so a
+ * second process sharing the same `scratchDir` (server plus worker) keeps its live captures.
+ *
+ * @returns How many build scratch directories were removed.
+ */
+declare function sweepOrphanedScratch(scratchDir: string, options?: ScratchSweepOptions): Promise<number>;
+export { SCRATCH_DIRNAME, SCRATCH_MAX_AGE_MS, ScratchSweepOptions, buildScratchDir, removeBuildScratch, removeJobScratch, sweepOrphanedScratch };
+//# sourceMappingURL=scratch.d.mts.map

package/dist/capture/scratch.mjs

@@ -0,0 +1,136 @@
+import { join } from "node:path";
+import "node:url";
+import.meta.url;
+import { readdir, rm, rmdir, stat } from "node:fs/promises";
+// src/capture/scratch.ts
+/** Per-build scratch directories: where they live, removing them, and sweeping crash leftovers. */
+/**
+* Subtree of `scratchDir` that holds extracted Storybooks.
+*
+* `scratchDir` is often also the local storage root (dev server, generated servers), where
+* `<project>/builds/<build>/...` holds screenshots and published statics. Keeping scratch in its
+* own subtree means removing it can never touch a storage key.
+*/
+const SCRATCH_DIRNAME = ".storyshelf-scratch";
+/** Scratch dirs untouched for this long are assumed orphaned by a crash (no capture runs this long). */
+const SCRATCH_MAX_AGE_MS = 216e5;
+/** Directory inside a build's scratch directory that holds one subdirectory per shard. */
+const SHARDS_DIRNAME = "shards";
+/** Directory inside a build's scratch directory for the build's own job, apart from its shards. */
+const JOB_DIRNAME = "job";
+/** Scratch directory owned by one build: `<scratchDir>/.storyshelf-scratch/<projectId>/<buildId>`. */
+function buildScratchDir(scratchDir, projectId, buildId) {
+	return join(scratchDir, SCRATCH_DIRNAME, projectId, buildId);
+}
+/** Scratch directory of the build's own job (plan or whole build): `<build>/job`, beside `shards/`. */
+function jobScratchDir(scratchDir, projectId, buildId) {
+	return join(buildScratchDir(scratchDir, projectId, buildId), JOB_DIRNAME);
+}
+/** Scratch directory of one shard of a build, inside the build's: shards of a build can share a host. */
+function shardScratchDir(scratchDir, projectId, buildId, shardId) {
+	return join(buildScratchDir(scratchDir, projectId, buildId), SHARDS_DIRNAME, shardId);
+}
+/**
+* Remove one shard's scratch directory, leaving the build's other shards alone, then the build's
+* directories if that left them empty: whichever shard finishes last tidies up. Best effort.
+*/
+async function removeShardScratch(scratchDir, projectId, buildId, shardId, logger) {
+	try {
+		await rm(shardScratchDir(scratchDir, projectId, buildId, shardId), {
+			recursive: true,
+			force: true
+		});
+		await pruneBuildScratch(scratchDir, projectId, buildId);
+	} catch (error) {
+		logger?.warn({
+			err: error,
+			buildId,
+			shardId
+		}, "failed to remove shard scratch directory");
+	}
+}
+/**
+* Remove the scratch of the build's own job (the plan, or the whole build when it is not sharded)
+* and the build directory too if nothing else is left in it.
+*
+* Shards live in their own `shards/` directory beside `job/`, so this can never reach one: the plan
+* hands its shards to the queue before it cleans up, and a worker may already be extracting.
+*/
+async function removeJobScratch(scratchDir, projectId, buildId, logger) {
+	try {
+		await rm(jobScratchDir(scratchDir, projectId, buildId), {
+			recursive: true,
+			force: true
+		});
+		await pruneBuildScratch(scratchDir, projectId, buildId);
+	} catch (error) {
+		logger?.warn({
+			err: error,
+			buildId
+		}, "failed to remove job scratch directory");
+	}
+}
+/**
+* Remove the build's scratch directories that are empty, and nothing that is not. A shard that is
+* still running (a redelivered duplicate of one that already finished) keeps its directory; its own
+* cleanup, or the boot sweep, removes it later. `rmdir` fails on a non-empty directory, which is
+* the point.
+*/
+async function pruneBuildScratch(scratchDir, projectId, buildId) {
+	const buildDir = buildScratchDir(scratchDir, projectId, buildId);
+	await rmdir(join(buildDir, SHARDS_DIRNAME)).catch(ignore);
+	await rmdir(buildDir).catch(ignore);
+}
+/** Remove a build's scratch directory. Best effort: a failure is logged, never thrown. */
+async function removeBuildScratch(scratchDir, projectId, buildId, logger) {
+	try {
+		await rm(buildScratchDir(scratchDir, projectId, buildId), {
+			recursive: true,
+			force: true
+		});
+	} catch (error) {
+		logger?.warn({
+			err: error,
+			buildId
+		}, "failed to remove build scratch directory");
+	}
+}
+/**
+* Boot-time sweep for scratch dirs a crash left behind. Age-gated rather than wholesale so a
+* second process sharing the same `scratchDir` (server plus worker) keeps its live captures.
+*
+* @returns How many build scratch directories were removed.
+*/
+async function sweepOrphanedScratch(scratchDir, options = {}) {
+	const root = join(scratchDir, SCRATCH_DIRNAME);
+	const cutoff = (options.now ?? Date.now()) - (options.maxAgeMs ?? 216e5);
+	const projects = await readdir(root).catch(() => []);
+	const total = (await Promise.all(projects.map(async (projectId) => await sweepProject(join(root, projectId), cutoff)))).reduce((sum, count) => sum + count, 0);
+	if (total > 0) options.logger?.info({ removed: total }, "removed orphaned capture scratch directories");
+	return total;
+}
+async function sweepProject(projectDir, cutoff) {
+	const builds = await readdir(projectDir).catch(() => []);
+	const results = await Promise.all(builds.map(async (buildId) => await sweepBuild(join(projectDir, buildId), cutoff)));
+	if ((await readdir(projectDir).catch(() => ["x"])).length === 0) await rm(projectDir, {
+		recursive: true,
+		force: true
+	}).catch(ignore);
+	return results.filter(Boolean).length;
+}
+async function sweepBuild(buildDir, cutoff) {
+	try {
+		if ((await stat(buildDir)).mtimeMs >= cutoff) return false;
+		await rm(buildDir, {
+			recursive: true,
+			force: true
+		});
+		return true;
+	} catch {
+		return false;
+	}
+}
+function ignore() {}
+export { SCRATCH_DIRNAME, SCRATCH_MAX_AGE_MS, buildScratchDir, jobScratchDir, pruneBuildScratch, removeBuildScratch, removeJobScratch, removeShardScratch, shardScratchDir, sweepOrphanedScratch };
+
+//# sourceMappingURL=scratch.mjs.map