@storyshelf/core 0.1.2 → 0.3.1

package/dist/adapter/init.mjs

@@ -0,0 +1,93 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/adapters/init.ts
+/** Thrown when an `app.lifecycle.init()` or `close()` run has failures. */
+var AdapterLifecycleError = class extends Error {
+	phase;
+	failures;
+	constructor(phase, failures) {
+		super(`Adapter ${phase} failed: ${failures.map((f) => `${f.category}/${f.kind}`).join(", ")}`);
+		this.name = "AdapterLifecycleError";
+		this.phase = phase;
+		this.failures = failures;
+	}
+};
+function hookEntry(adapter, hook) {
+	const fn = adapter.lifecycle?.[hook];
+	if (!fn) return null;
+	const { category, kind, name } = adapter.metadata;
+	return {
+		category,
+		kind,
+		name,
+		run: async (ctx) => {
+			await fn(ctx);
+		}
+	};
+}
+function pushHook(entries, adapter, hook) {
+	if (!adapter) return;
+	const entry = hookEntry(adapter, hook);
+	if (entry) entries.push(entry);
+}
+function pushAll(entries, sources, hook) {
+	pushHook(entries, sources.database, hook);
+	pushHook(entries, sources.storage, hook);
+	pushHook(entries, sources.captureRunner, hook);
+	pushHook(entries, sources.captureQueue, hook);
+	pushHook(entries, sources.auth, hook);
+	for (const provider of sources.gitHosts ?? []) pushHook(entries, provider, hook);
+}
+/** Collect every available `init` hook in deterministic order. */
+function collectInits(sources) {
+	const entries = [];
+	pushAll(entries, sources, "init");
+	return entries;
+}
+/** Collect every available `close` hook in deterministic order. */
+function collectCloses(sources) {
+	const entries = [];
+	pushAll(entries, sources, "close");
+	return entries;
+}
+function messageOf(reason) {
+	return reason instanceof Error ? reason.message : String(reason);
+}
+function toFailure(entry, reason) {
+	return {
+		category: entry.category,
+		kind: entry.kind,
+		name: entry.name,
+		error: messageOf(reason)
+	};
+}
+function toResult(entries, outcomes, logger, verb) {
+	const failures = [];
+	for (const [index, entry] of entries.entries()) {
+		const outcome = outcomes[index];
+		if (outcome?.status === "rejected") failures.push(toFailure(entry, outcome.reason));
+	}
+	if (failures.length > 0) logger.error({ failures }, `adapter ${verb} failed`);
+	else logger.info({ count: entries.length }, `adapters ${verb}d`);
+	return {
+		ok: failures.length === 0,
+		failures
+	};
+}
+/** Run init hooks concurrently; failures are collected, never thrown. */
+async function runAdapterInits(entries, ctx, logger) {
+	return toResult(entries, await Promise.allSettled(entries.map(async (entry) => {
+		await entry.run(ctx);
+	})), logger, "init");
+}
+/** Run close hooks concurrently; failures are collected, never thrown. */
+async function runAdapterCloses(entries, ctx, logger) {
+	return toResult(entries, await Promise.allSettled(entries.map(async (entry) => {
+		await entry.run(ctx);
+	})), logger, "close");
+}
+//#endregion
+export { AdapterLifecycleError, collectCloses, collectInits, runAdapterCloses, runAdapterInits };
+
+//# sourceMappingURL=init.mjs.map

package/dist/adapter/init.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.mjs","names":[],"sources":["../../src/adapters/init.ts"],"sourcesContent":["/**\n * Adapter lifecycle runner: collect and execute `init`/`close` hooks.\n *\n * `createShelfRouter` kicks `init` eagerly via `Promise.allSettled` (so one\n * slow adapter never starves the others) and gates the first request on the\n * shared result. `app.lifecycle.init()` re-runs for fail-fast startup;\n * `app.lifecycle.close()` fans out teardown. All hooks must be idempotent.\n */\nimport type { Logger } from \"pino\";\nimport type { AuthAdapter } from \"./auth.ts\";\nimport type { CaptureQueue } from \"./capture-queue.ts\";\nimport type { CaptureRunner } from \"./capture-runner.ts\";\nimport type { DatabaseAdapter } from \"./database.ts\";\nimport type { GitHostProvider } from \"./git-host/index.ts\";\nimport type { AdapterInitContext, AdapterLifecycle, AdapterMetadata } from \"./metadata.ts\";\nimport type { StorageAdapter } from \"./storage.ts\";\n\n/** Adapters that can take part in lifecycle runs. */\nexport interface AdapterInitSources {\n  database: DatabaseAdapter;\n  storage: StorageAdapter;\n  captureRunner?: CaptureRunner;\n  captureQueue?: CaptureQueue;\n  auth?: AuthAdapter;\n  gitHosts?: GitHostProvider[];\n}\n\ninterface LifecycleCarrier {\n  readonly metadata: AdapterMetadata;\n  readonly lifecycle?: AdapterLifecycle;\n}\n\n/** One collected hook bound to its adapter identity. */\nexport interface HookEntry {\n  readonly category: string;\n  readonly kind: string;\n  readonly name: string;\n  readonly run: (ctx: AdapterInitContext) => Promise<void>;\n}\n\n/** One failed hook, with its adapter identity attached. */\nexport interface AdapterInitFailure {\n  readonly category: string;\n  readonly kind: string;\n  readonly name: string;\n  readonly error: string;\n}\n\n/** Settled outcome of a lifecycle run (never rejects — use `ok`). */\nexport interface AdapterInitResult {\n  readonly ok: boolean;\n  readonly failures: AdapterInitFailure[];\n}\n\n/** Lifecycle phase a run covers. */\nexport type LifecyclePhase = \"init\" | \"close\";\n\n/** Thrown when an `app.lifecycle.init()` or `close()` run has failures. */\nexport class AdapterLifecycleError extends Error {\n  readonly phase: LifecyclePhase;\n  readonly failures: AdapterInitFailure[];\n  constructor(phase: LifecyclePhase, failures: AdapterInitFailure[]) {\n    super(`Adapter ${phase} failed: ${failures.map((f) => `${f.category}/${f.kind}`).join(\", \")}`);\n    this.name = \"AdapterLifecycleError\";\n    this.phase = phase;\n    this.failures = failures;\n  }\n}\n\nfunction hookEntry(adapter: LifecycleCarrier, hook: \"init\" | \"close\"): HookEntry | null {\n  const fn = adapter.lifecycle?.[hook];\n  if (!fn) {\n    return null;\n  }\n  const { category, kind, name } = adapter.metadata;\n  return {\n    category,\n    kind,\n    name,\n    run: async (ctx) => {\n      await fn(ctx);\n    },\n  };\n}\n\nfunction pushHook(\n  entries: HookEntry[],\n  adapter: LifecycleCarrier | undefined,\n  hook: \"init\" | \"close\",\n): void {\n  if (!adapter) {\n    return;\n  }\n  const entry = hookEntry(adapter, hook);\n  if (entry) {\n    entries.push(entry);\n  }\n}\n\nfunction pushAll(entries: HookEntry[], sources: AdapterInitSources, hook: \"init\" | \"close\"): void {\n  pushHook(entries, sources.database, hook);\n  pushHook(entries, sources.storage, hook);\n  pushHook(entries, sources.captureRunner, hook);\n  pushHook(entries, sources.captureQueue, hook);\n  pushHook(entries, sources.auth, hook);\n  for (const provider of sources.gitHosts ?? []) {\n    pushHook(entries, provider, hook);\n  }\n}\n\n/** Collect every available `init` hook in deterministic order. */\nexport function collectInits(sources: AdapterInitSources): HookEntry[] {\n  const entries: HookEntry[] = [];\n  pushAll(entries, sources, \"init\");\n  return entries;\n}\n\n/** Collect every available `close` hook in deterministic order. */\nexport function collectCloses(sources: AdapterInitSources): HookEntry[] {\n  const entries: HookEntry[] = [];\n  pushAll(entries, sources, \"close\");\n  return entries;\n}\n\nfunction messageOf(reason: unknown): string {\n  return reason instanceof Error ? reason.message : String(reason);\n}\n\nfunction toFailure(entry: HookEntry, reason: unknown): AdapterInitFailure {\n  return { category: entry.category, kind: entry.kind, name: entry.name, error: messageOf(reason) };\n}\n\nfunction toResult(\n  entries: HookEntry[],\n  outcomes: PromiseSettledResult<void>[],\n  logger: Logger,\n  verb: string,\n): AdapterInitResult {\n  const failures: AdapterInitFailure[] = [];\n  for (const [index, entry] of entries.entries()) {\n    const outcome: PromiseSettledResult<void> | undefined = outcomes[index];\n    if (outcome?.status === \"rejected\") {\n      failures.push(toFailure(entry, outcome.reason));\n    }\n  }\n  if (failures.length > 0) {\n    logger.error({ failures }, `adapter ${verb} failed`);\n  } else {\n    logger.info({ count: entries.length }, `adapters ${verb}d`);\n  }\n  return { ok: failures.length === 0, failures };\n}\n\n/** Run init hooks concurrently; failures are collected, never thrown. */\nexport async function runAdapterInits(\n  entries: HookEntry[],\n  ctx: AdapterInitContext,\n  logger: Logger,\n): Promise<AdapterInitResult> {\n  const outcomes = await Promise.allSettled(\n    entries.map(async (entry) => {\n      await entry.run(ctx);\n    }),\n  );\n  return toResult(entries, outcomes, logger, \"init\");\n}\n\n/** Run close hooks concurrently; failures are collected, never thrown. */\nexport async function runAdapterCloses(\n  entries: HookEntry[],\n  ctx: AdapterInitContext,\n  logger: Logger,\n): Promise<AdapterInitResult> {\n  const outcomes = await Promise.allSettled(\n    entries.map(async (entry) => {\n      await entry.run(ctx);\n    }),\n  );\n  return toResult(entries, outcomes, logger, \"close\");\n}\n"],"mappings":";;;;;AA0DA,IAAa,wBAAb,cAA2C,MAAM;CAC/C;CACA;CACA,YAAY,OAAuB,UAAgC;EACjE,MAAM,WAAW,MAAM,WAAW,SAAS,KAAK,MAAM,GAAG,EAAE,SAAS,GAAG,EAAE,MAAM,CAAC,CAAC,KAAK,IAAI,GAAG;EAC7F,KAAK,OAAO;EACZ,KAAK,QAAQ;EACb,KAAK,WAAW;CAClB;AACF;AAEA,SAAS,UAAU,SAA2B,MAA0C;CACtF,MAAM,KAAK,QAAQ,YAAY;CAC/B,IAAI,CAAC,IACH,OAAO;CAET,MAAM,EAAE,UAAU,MAAM,SAAS,QAAQ;CACzC,OAAO;EACL;EACA;EACA;EACA,KAAK,OAAO,QAAQ;GAClB,MAAM,GAAG,GAAG;EACd;CACF;AACF;AAEA,SAAS,SACP,SACA,SACA,MACM;CACN,IAAI,CAAC,SACH;CAEF,MAAM,QAAQ,UAAU,SAAS,IAAI;CACrC,IAAI,OACF,QAAQ,KAAK,KAAK;AAEtB;AAEA,SAAS,QAAQ,SAAsB,SAA6B,MAA8B;CAChG,SAAS,SAAS,QAAQ,UAAU,IAAI;CACxC,SAAS,SAAS,QAAQ,SAAS,IAAI;CACvC,SAAS,SAAS,QAAQ,eAAe,IAAI;CAC7C,SAAS,SAAS,QAAQ,cAAc,IAAI;CAC5C,SAAS,SAAS,QAAQ,MAAM,IAAI;CACpC,KAAK,MAAM,YAAY,QAAQ,YAAY,CAAC,GAC1C,SAAS,SAAS,UAAU,IAAI;AAEpC;;AAGA,SAAgB,aAAa,SAA0C;CACrE,MAAM,UAAuB,CAAC;CAC9B,QAAQ,SAAS,SAAS,MAAM;CAChC,OAAO;AACT;;AAGA,SAAgB,cAAc,SAA0C;CACtE,MAAM,UAAuB,CAAC;CAC9B,QAAQ,SAAS,SAAS,OAAO;CACjC,OAAO;AACT;AAEA,SAAS,UAAU,QAAyB;CAC1C,OAAO,kBAAkB,QAAQ,OAAO,UAAU,OAAO,MAAM;AACjE;AAEA,SAAS,UAAU,OAAkB,QAAqC;CACxE,OAAO;EAAE,UAAU,MAAM;EAAU,MAAM,MAAM;EAAM,MAAM,MAAM;EAAM,OAAO,UAAU,MAAM;CAAE;AAClG;AAEA,SAAS,SACP,SACA,UACA,QACA,MACmB;CACnB,MAAM,WAAiC,CAAC;CACxC,KAAK,MAAM,CAAC,OAAO,UAAU,QAAQ,QAAQ,GAAG;EAC9C,MAAM,UAAkD,SAAS;EACjE,IAAI,SAAS,WAAW,YACtB,SAAS,KAAK,UAAU,OAAO,QAAQ,MAAM,CAAC;CAElD;CACA,IAAI,SAAS,SAAS,GACpB,OAAO,MAAM,EAAE,SAAS,GAAG,WAAW,KAAK,QAAQ;MAEnD,OAAO,KAAK,EAAE,OAAO,QAAQ,OAAO,GAAG,YAAY,KAAK,EAAE;CAE5D,OAAO;EAAE,IAAI,SAAS,WAAW;EAAG;CAAS;AAC/C;;AAGA,eAAsB,gBACpB,SACA,KACA,QAC4B;CAM5B,OAAO,SAAS,SAAS,MALF,QAAQ,WAC7B,QAAQ,IAAI,OAAO,UAAU;EAC3B,MAAM,MAAM,IAAI,GAAG;CACrB,CAAC,CACH,GACmC,QAAQ,MAAM;AACnD;;AAGA,eAAsB,iBACpB,SACA,KACA,QAC4B;CAM5B,OAAO,SAAS,SAAS,MALF,QAAQ,WAC7B,QAAQ,IAAI,OAAO,UAAU;EAC3B,MAAM,MAAM,IAAI,GAAG;CACrB,CAAC,CACH,GACmC,QAAQ,OAAO;AACpD"}

package/dist/adapter/metadata.d.mts

@@ -0,0 +1,83 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { ShelfConfig } from "../config.mjs";
+import { Logger } from "../logger.mjs";
+import { z } from "zod";
+//#region src/adapters/metadata.d.ts
+/**
+ * Adapter family — which concern an adapter supplies.
+ *
+ * Distinct from `kind` (the implementation, e.g. "sqlite" vs "turso"):
+ * `category` tells a reader which slot the adapter fills without knowing
+ * which adapter instance supplied the metadata.
+ */
+type AdapterCategory = "database" | "storage" | "auth" | "capture-runner" | "capture-queue" | "git-host";
+/** Common adapter identity — every adapter instance exposes this. */
+interface AdapterMetadata {
+  /** Human label for UI/logs. */
+  readonly name: string;
+  /** Package version injected at build via __PKG_VERSION__. */
+  readonly version: string;
+  /** Optional short description. */
+  readonly description?: string;
+  /** Machine key for the implementation (e.g. "sqlite", "local", "s3", "oauth", "playwright"). */
+  readonly kind: string;
+  /** Adapter family — which concern this adapter supplies. */
+  readonly category: AdapterCategory;
+}
+/** Git-specific metadata extension (adds logo + validation schema). */
+interface GitAdapterMetadata extends AdapterMetadata {
+  readonly category: "git-host";
+  readonly logo?: string;
+  readonly schema: z.ZodType;
+}
+/** Context passed to an adapter's `init` on server startup. */
+interface AdapterInitContext {
+  /** Resolved shelf configuration (scratchDir, secret, …). Never log the secret. */
+  readonly config: ShelfConfig;
+  /** Scoped logger for init-time diagnostics. */
+  readonly logger: Logger;
+}
+/** Result of an adapter's ongoing health probe. */
+interface AdapterHealth {
+  /** Whether the adapter is currently usable. */
+  readonly ok: boolean;
+  /** Probe latency in milliseconds, when measured. */
+  readonly latencyMs?: number;
+  /** Short human-readable detail (must not contain secrets). */
+  readonly detail?: string;
+}
+/**
+ * Optional lifecycle every adapter can expose.
+ *
+ * Grouped in a sub-object (rather than flattened onto each adapter) so
+ * future hooks (`drain?`, `reinit?`, …) land in one place. All hooks must
+ * be idempotent — the router may run them more than once per process.
+ */
+interface AdapterLifecycle {
+  /**
+   * One-shot setup: migrations, directory creation, credential validation.
+   * Throw when something required is missing.
+   */
+  init?: (ctx: AdapterInitContext) => Promise<void>;
+  /** Teardown: close clients and handles. Must tolerate repeated calls. */
+  close?: () => Promise<void>;
+  /** Ongoing liveness probe (cheap: SELECT 1, access(), head-bucket). */
+  health?: () => Promise<AdapterHealth>;
+}
+/**
+ * Shared adapter base.
+ *
+ * Every adapter interface extends this (narrowing `category` via `Extra`)
+ * instead of redeclaring `metadata`. `kind` stays an open string so
+ * third-party implementations are never blocked by a closed union.
+ */
+interface Adapter<Extra extends object = Record<string, unknown>> {
+  /** Adapter identity (mandatory). */
+  readonly metadata: AdapterMetadata & Extra;
+  /** Optional lifecycle hooks. */
+  readonly lifecycle?: AdapterLifecycle;
+}
+//#endregion
+export { Adapter, AdapterCategory, AdapterHealth, AdapterInitContext, AdapterLifecycle, AdapterMetadata, GitAdapterMetadata };
+//# sourceMappingURL=metadata.d.mts.map

package/dist/adapter/metadata.mjs

@@ -0,0 +1,4 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+export {};

package/dist/adapter/storage.d.mts

@@ -1,12 +1,13 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { AdapterMetadata } from "../adapters/metadata.mjs";
+import { Adapter } from "./metadata.mjs";
+import { Readable } from "node:stream";
 import { Buffer } from "node:buffer";
 //#region src/adapters/storage.d.ts
 /** Blob storage abstraction for screenshots, diffs and Storybook archives. */
-interface StorageAdapter {
-  /** Adapter identity. */
-  readonly metadata?: AdapterMetadata;
+interface StorageAdapter extends Adapter<{
+  readonly category: "storage";
+}> {
   /** Read the bytes stored at `path`. */
   read(path: string): Promise<Buffer>;
   /** Write `data` to `path`, creating parent directories as needed. */
@@ -17,6 +18,16 @@ interface StorageAdapter {
   exists(path: string): Promise<boolean>;
   /** List object paths under the given key prefix. */
   list(prefix: string): Promise<string[]>;
+  /**
+   * Stream `stream` to `path`, creating parent directories as needed.
+   * Resolves when the stream is fully consumed and persisted.
+   */
+  writeStream(path: string, stream: Readable): Promise<void>;
+  /**
+   * Open a stream for the bytes stored at `path`.
+   * Rejects when no object exists at `path`.
+   */
+  readStream(path: string): Promise<Readable>;
 }
 //#endregion
 export { StorageAdapter };

package/dist/adapters/webhook-events.mjs

@@ -1,8 +1,8 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-import { hmacSha256 } from "../utils/hash.mjs";
 import { WebhookModel } from "../models/webhook.mjs";
+import { hmacSha256 } from "../utils/hash.mjs";
 //#region src/adapters/webhook-events.ts
 async function sendWebhook(url, secret, event) {
 	const body = JSON.stringify(event);
@@ -17,8 +17,18 @@ async function sendWebhook(url, secret, event) {
 		body
 	});
 }
-async function emitWebhookEvent(db, projectId, event, data) {
-	const webhooks = await new WebhookModel(db).list(projectId);
+/**
+* Deliver an event to every subscribed webhook of a project.
+*
+* @param db - Database adapter for loading subscriptions.
+* @param projectId - Project whose webhooks receive the event.
+* @param event - Event name (e.g. "baseline:created").
+* @param data - Event payload.
+* @param secret - Server secret for decrypting webhook secrets (in memory only).
+*/
+async function emitWebhookEvent(db, projectId, event, data, secret) {
+	const webhookModel = new WebhookModel(db, secret);
+	const webhooks = await webhookModel.list(projectId);
 	const eventPayload = {
 		event,
 		projectId,
@@ -28,8 +38,14 @@ async function emitWebhookEvent(db, projectId, event, data) {
 	await Promise.allSettled(webhooks.map(async (webhook) => {
 		const events = WebhookModel.eventsOf(webhook);
 		if (events.length > 0 && !events.includes(event)) return;
+		let plaintext;
+		try {
+			plaintext = webhookModel.decryptSecret(webhook);
+		} catch {
+			return;
+		}
 		try {
-			await sendWebhook(webhook.url, webhook.secret, eventPayload);
+			await sendWebhook(webhook.url, plaintext, eventPayload);
 		} catch {}
 	}));
 }

package/dist/adapters/webhook-events.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"webhook-events.mjs","names":[],"sources":["../../src/adapters/webhook-events.ts"],"sourcesContent":["import type { DatabaseAdapter } from \"./database.ts\";\nimport { WebhookModel } from \"../models/webhook.ts\";\nimport { hmacSha256 } from \"../utils/hash.ts\";\n\nexport interface WebhookEvent {\n  event: string;\n  projectId: string;\n  data: Record<string, unknown>;\n  timestamp: string;\n}\n\nasync function sendWebhook(url: string, secret: string, event: WebhookEvent): Promise<void> {\n  const body = JSON.stringify(event);\n  const signature = hmacSha256(secret, body);\n  await fetch(url, {\n    method: \"POST\",\n    headers: {\n      \"Content-Type\": \"application/json\",\n      \"X-StoryShelf-Event\": event.event,\n      \"X-StoryShelf-Signature\": signature,\n    },\n    body,\n  });\n}\n\nexport async function emitWebhookEvent(\n  db: DatabaseAdapter,\n  projectId: string,\n  event: string,\n  data: Record<string, unknown>,\n): Promise<void> {\n  const webhookModel = new WebhookModel(db);\n  const webhooks = await webhookModel.list(projectId);\n  const eventPayload: WebhookEvent = {\n    event,\n    projectId,\n    data,\n    timestamp: new Date().toISOString(),\n  };\n\n  await Promise.allSettled(\n    webhooks.map(async (webhook) => {\n      const events = WebhookModel.eventsOf(webhook);\n      if (events.length > 0 && !events.includes(event)) {\n        return;\n      }\n      try {\n        await sendWebhook(webhook.url, webhook.secret, eventPayload);\n      } catch {\n        // Webhook delivery failures are non-fatal\n      }\n    }),\n  );\n}\n"],"mappings":";;;;;;AAWA,eAAe,YAAY,KAAa,QAAgB,OAAoC;CAC1F,MAAM,OAAO,KAAK,UAAU,KAAK;CACjC,MAAM,YAAY,WAAW,QAAQ,IAAI;CACzC,MAAM,MAAM,KAAK;EACf,QAAQ;EACR,SAAS;GACP,gBAAgB;GAChB,sBAAsB,MAAM;GAC5B,0BAA0B;EAC5B;EACA;CACF,CAAC;AACH;AAEA,eAAsB,iBACpB,IACA,WACA,OACA,MACe;CAEf,MAAM,WAAW,MAAM,IADE,aAAa,EACJ,CAAC,CAAC,KAAK,SAAS;CAClD,MAAM,eAA6B;EACjC;EACA;EACA;EACA,4BAAW,IAAI,KAAK,EAAA,CAAE,YAAY;CACpC;CAEA,MAAM,QAAQ,WACZ,SAAS,IAAI,OAAO,YAAY;EAC9B,MAAM,SAAS,aAAa,SAAS,OAAO;EAC5C,IAAI,OAAO,SAAS,KAAK,CAAC,OAAO,SAAS,KAAK,GAC7C;EAEF,IAAI;GACF,MAAM,YAAY,QAAQ,KAAK,QAAQ,QAAQ,YAAY;EAC7D,QAAQ,CAER;CACF,CAAC,CACH;AACF"}
+{"version":3,"file":"webhook-events.mjs","names":[],"sources":["../../src/adapters/webhook-events.ts"],"sourcesContent":["import { WebhookModel } from \"../models/webhook.ts\";\nimport { hmacSha256 } from \"../utils/hash.ts\";\nimport type { DatabaseAdapter } from \"./database.ts\";\n\n/** Outbound webhook payload delivered to subscribers. */\nexport interface WebhookEvent {\n  event: string;\n  projectId: string;\n  data: Record<string, unknown>;\n  timestamp: string;\n}\n\nasync function sendWebhook(url: string, secret: string, event: WebhookEvent): Promise<void> {\n  const body = JSON.stringify(event);\n  const signature = hmacSha256(secret, body);\n  await fetch(url, {\n    method: \"POST\",\n    headers: {\n      \"Content-Type\": \"application/json\",\n      \"X-StoryShelf-Event\": event.event,\n      \"X-StoryShelf-Signature\": signature,\n    },\n    body,\n  });\n}\n\n/**\n * Deliver an event to every subscribed webhook of a project.\n *\n * @param db - Database adapter for loading subscriptions.\n * @param projectId - Project whose webhooks receive the event.\n * @param event - Event name (e.g. \"baseline:created\").\n * @param data - Event payload.\n * @param secret - Server secret for decrypting webhook secrets (in memory only).\n */\nexport async function emitWebhookEvent(\n  db: DatabaseAdapter,\n  projectId: string,\n  event: string,\n  data: Record<string, unknown>,\n  secret: string | undefined,\n): Promise<void> {\n  const webhookModel = new WebhookModel(db, secret);\n  const webhooks = await webhookModel.list(projectId);\n  const eventPayload: WebhookEvent = {\n    event,\n    projectId,\n    data,\n    timestamp: new Date().toISOString(),\n  };\n\n  await Promise.allSettled(\n    webhooks.map(async (webhook) => {\n      const events = WebhookModel.eventsOf(webhook);\n      if (events.length > 0 && !events.includes(event)) {\n        return;\n      }\n      let plaintext: string;\n      try {\n        plaintext = webhookModel.decryptSecret(webhook);\n      } catch {\n        // Undecryptable secret (e.g. rotated server SECRET) — skip, don't leak\n        return;\n      }\n      try {\n        await sendWebhook(webhook.url, plaintext, eventPayload);\n      } catch {\n        // Webhook delivery failures are non-fatal\n      }\n    }),\n  );\n}\n"],"mappings":";;;;;;AAYA,eAAe,YAAY,KAAa,QAAgB,OAAoC;CAC1F,MAAM,OAAO,KAAK,UAAU,KAAK;CACjC,MAAM,YAAY,WAAW,QAAQ,IAAI;CACzC,MAAM,MAAM,KAAK;EACf,QAAQ;EACR,SAAS;GACP,gBAAgB;GAChB,sBAAsB,MAAM;GAC5B,0BAA0B;EAC5B;EACA;CACF,CAAC;AACH;;;;;;;;;;AAWA,eAAsB,iBACpB,IACA,WACA,OACA,MACA,QACe;CACf,MAAM,eAAe,IAAI,aAAa,IAAI,MAAM;CAChD,MAAM,WAAW,MAAM,aAAa,KAAK,SAAS;CAClD,MAAM,eAA6B;EACjC;EACA;EACA;EACA,4BAAW,IAAI,KAAK,EAAA,CAAE,YAAY;CACpC;CAEA,MAAM,QAAQ,WACZ,SAAS,IAAI,OAAO,YAAY;EAC9B,MAAM,SAAS,aAAa,SAAS,OAAO;EAC5C,IAAI,OAAO,SAAS,KAAK,CAAC,OAAO,SAAS,KAAK,GAC7C;EAEF,IAAI;EACJ,IAAI;GACF,YAAY,aAAa,cAAc,OAAO;EAChD,QAAQ;GAEN;EACF;EACA,IAAI;GACF,MAAM,YAAY,QAAQ,KAAK,WAAW,YAAY;EACxD,QAAQ,CAER;CACF,CAAC,CACH;AACF"}

package/dist/capture/adapter.d.mts

@@ -1,6 +1,7 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 //#region src/capture/adapter.d.ts
+/** Per-story capture parameters from the Storybook index. */
 interface StoryParameters {
   disableSnapshot?: boolean;
   delay?: number;
@@ -8,6 +9,10 @@ interface StoryParameters {
   pauseAnimationAtEnd?: boolean;
   flakyTest?: boolean;
 }
+/** Return whether a story is marked flaky (failures stay non-blocking). */
+declare function isFlakyStory(entry: Pick<StoryEntry, "tags" | "parameters">): boolean;
+/** Return whether a story is excluded from snapshot capture. */
+declare function isDisabledStory(entry: Pick<StoryEntry, "tags" | "parameters">): boolean;
 /** A single discoverable story or docs entry within a Storybook. */
 interface StoryEntry {
   id: string;
@@ -31,7 +36,8 @@ interface Viewport {
   width: number;
   height: number;
 }
+/** Default viewport used when none is configured. */
 declare const DEFAULT_VIEWPORTS: Viewport[];
 //#endregion
-export { DEFAULT_VIEWPORTS, StoryEntry, StoryParameters, StorySourceAdapter, Viewport };
+export { DEFAULT_VIEWPORTS, StoryEntry, StoryParameters, StorySourceAdapter, Viewport, isDisabledStory, isFlakyStory };
 //# sourceMappingURL=adapter.d.mts.map

package/dist/capture/adapter.mjs

@@ -2,12 +2,14 @@ import "node:path";
 import "node:url";
 import.meta.url;
 //#region src/capture/adapter.ts
+/** Return whether a story is marked flaky (failures stay non-blocking). */
 function isFlakyStory(entry) {
 	if (entry.parameters?.flakyTest) return true;
 	const tags = entry.tags ?? [];
 	for (const t of tags) if (t.toLowerCase() === "flaky-test") return true;
 	return false;
 }
+/** Return whether a story is excluded from snapshot capture. */
 function isDisabledStory(entry) {
 	if (entry.parameters?.disableSnapshot) return true;
 	const tags = entry.tags ?? [];
@@ -17,6 +19,7 @@ function isDisabledStory(entry) {
 	}
 	return false;
 }
+/** Default viewport used when none is configured. */
 const DEFAULT_VIEWPORTS = [{
 	name: "desktop",
 	width: 1280,

package/dist/capture/adapter.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.mjs","names":[],"sources":["../../src/capture/adapter.ts"],"sourcesContent":["export interface StoryParameters {\n  disableSnapshot?: boolean;\n  delay?: number;\n  diffThreshold?: number;\n  pauseAnimationAtEnd?: boolean;\n  flakyTest?: boolean;\n}\n\nexport function isFlakyStory(entry: Pick<StoryEntry, \"tags\" | \"parameters\">): boolean {\n  if (entry.parameters?.flakyTest) return true;\n  const tags = entry.tags ?? [];\n  for (const t of tags) {\n    if (t.toLowerCase() === \"flaky-test\") return true;\n  }\n  return false;\n}\n\nexport function isDisabledStory(entry: Pick<StoryEntry, \"tags\" | \"parameters\">): boolean {\n  if (entry.parameters?.disableSnapshot) return true;\n  const tags = entry.tags ?? [];\n  for (const t of tags) {\n    const lower = t.toLowerCase();\n    if (lower === \"skip\" || lower === \"disable\" || lower === \"disable-snapshot\") return true;\n  }\n  return false;\n}\n\n/** A single discoverable story or docs entry within a Storybook. */\nexport interface StoryEntry {\n  id: string;\n  title: string;\n  name: string;\n  importPath?: string;\n  tags?: string[];\n  type: \"story\" | \"docs\";\n  parameters?: StoryParameters;\n}\n\n/** Adapter that discovers and renders stories from a Storybook build. */\nexport interface StorySourceAdapter {\n  name: string;\n  discover(source: string): Promise<StoryEntry[]>;\n  buildUrl(baseUrl: string, storyId: string): string;\n  screenshotSelector?: string;\n}\n\n/** A viewport size at which stories are captured. */\nexport interface Viewport {\n  name: string;\n  width: number;\n  height: number;\n}\n\nexport const DEFAULT_VIEWPORTS: Viewport[] = [{ name: \"desktop\", width: 1280, height: 720 }];\n"],"mappings":";;;;AAQA,SAAgB,aAAa,OAAyD;CACpF,IAAI,MAAM,YAAY,WAAW,OAAO;CACxC,MAAM,OAAO,MAAM,QAAQ,CAAC;CAC5B,KAAK,MAAM,KAAK,MACd,IAAI,EAAE,YAAY,MAAM,cAAc,OAAO;CAE/C,OAAO;AACT;AAEA,SAAgB,gBAAgB,OAAyD;CACvF,IAAI,MAAM,YAAY,iBAAiB,OAAO;CAC9C,MAAM,OAAO,MAAM,QAAQ,CAAC;CAC5B,KAAK,MAAM,KAAK,MAAM;EACpB,MAAM,QAAQ,EAAE,YAAY;EAC5B,IAAI,UAAU,UAAU,UAAU,aAAa,UAAU,oBAAoB,OAAO;CACtF;CACA,OAAO;AACT;AA4BA,MAAa,oBAAgC,CAAC;CAAE,MAAM;CAAW,OAAO;CAAM,QAAQ;AAAI,CAAC"}
+{"version":3,"file":"adapter.mjs","names":[],"sources":["../../src/capture/adapter.ts"],"sourcesContent":["/** Per-story capture parameters from the Storybook index. */\nexport interface StoryParameters {\n  disableSnapshot?: boolean;\n  delay?: number;\n  diffThreshold?: number;\n  pauseAnimationAtEnd?: boolean;\n  flakyTest?: boolean;\n}\n\n/** Return whether a story is marked flaky (failures stay non-blocking). */\nexport function isFlakyStory(entry: Pick<StoryEntry, \"tags\" | \"parameters\">): boolean {\n  if (entry.parameters?.flakyTest) return true;\n  const tags = entry.tags ?? [];\n  for (const t of tags) {\n    if (t.toLowerCase() === \"flaky-test\") return true;\n  }\n  return false;\n}\n\n/** Return whether a story is excluded from snapshot capture. */\nexport function isDisabledStory(entry: Pick<StoryEntry, \"tags\" | \"parameters\">): boolean {\n  if (entry.parameters?.disableSnapshot) return true;\n  const tags = entry.tags ?? [];\n  for (const t of tags) {\n    const lower = t.toLowerCase();\n    if (lower === \"skip\" || lower === \"disable\" || lower === \"disable-snapshot\") return true;\n  }\n  return false;\n}\n\n/** A single discoverable story or docs entry within a Storybook. */\nexport interface StoryEntry {\n  id: string;\n  title: string;\n  name: string;\n  importPath?: string;\n  tags?: string[];\n  type: \"story\" | \"docs\";\n  parameters?: StoryParameters;\n}\n\n/** Adapter that discovers and renders stories from a Storybook build. */\nexport interface StorySourceAdapter {\n  name: string;\n  discover(source: string): Promise<StoryEntry[]>;\n  buildUrl(baseUrl: string, storyId: string): string;\n  screenshotSelector?: string;\n}\n\n/** A viewport size at which stories are captured. */\nexport interface Viewport {\n  name: string;\n  width: number;\n  height: number;\n}\n\n/** Default viewport used when none is configured. */\nexport const DEFAULT_VIEWPORTS: Viewport[] = [{ name: \"desktop\", width: 1280, height: 720 }];\n"],"mappings":";;;;;AAUA,SAAgB,aAAa,OAAyD;CACpF,IAAI,MAAM,YAAY,WAAW,OAAO;CACxC,MAAM,OAAO,MAAM,QAAQ,CAAC;CAC5B,KAAK,MAAM,KAAK,MACd,IAAI,EAAE,YAAY,MAAM,cAAc,OAAO;CAE/C,OAAO;AACT;;AAGA,SAAgB,gBAAgB,OAAyD;CACvF,IAAI,MAAM,YAAY,iBAAiB,OAAO;CAC9C,MAAM,OAAO,MAAM,QAAQ,CAAC;CAC5B,KAAK,MAAM,KAAK,MAAM;EACpB,MAAM,QAAQ,EAAE,YAAY;EAC5B,IAAI,UAAU,UAAU,UAAU,aAAa,UAAU,oBAAoB,OAAO;CACtF;CACA,OAAO;AACT;;AA6BA,MAAa,oBAAgC,CAAC;CAAE,MAAM;CAAW,OAAO;CAAM,QAAQ;AAAI,CAAC"}

package/dist/capture/dispatch.mjs

@@ -0,0 +1,150 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { BuildModel } from "../models/build.mjs";
+import { ProjectModel } from "../models/project.mjs";
+import { executeCaptureJob } from "./orchestrator.mjs";
+import { hasApprovedBuildForSha, isAlreadyMerged } from "./skip-checks.mjs";
+import { postStatusesForBuild } from "./status-fanout.mjs";
+//#region src/capture/dispatch.ts
+async function postPending(deps, project, url, sha) {
+	await postStatusesForBuild({
+		db: deps.db,
+		project,
+		sha,
+		status: "pending",
+		url,
+		providers: deps.gitHosts,
+		secret: deps.secret,
+		logger: deps.logger
+	}).catch((error) => {
+		deps.logger.error({ err: error }, "failed to post pending status");
+	});
+}
+async function postTerminal(deps, project, url, sha, status) {
+	await postStatusesForBuild({
+		db: deps.db,
+		project,
+		sha,
+		status,
+		url,
+		providers: deps.gitHosts,
+		secret: deps.secret,
+		logger: deps.logger
+	}).catch((error) => {
+		deps.logger.error({ err: error }, "failed to post terminal status");
+	});
+}
+async function approveWithoutCapture(ctx, reason) {
+	const { deps, build, project, pendingUrl } = ctx;
+	deps.logger.info({
+		buildId: build.id,
+		sha: build.gitSha,
+		branch: build.gitBranch
+	}, reason);
+	await new BuildModel(deps.db).setStatus(build.id, "approved").catch(() => {});
+	await postTerminal(deps, project, pendingUrl, build.gitSha, "success").catch(() => {});
+}
+async function maybeSkipMerged(ctx) {
+	const { deps, build, project } = ctx;
+	if (build.isDefault) return false;
+	if (await isAlreadyMerged({
+		providers: deps.gitHosts,
+		sha: build.gitSha,
+		branch: build.gitBranch,
+		secret: deps.secret,
+		db: deps.db,
+		projectId: project.id,
+		logger: deps.logger
+	}).catch(() => false)) {
+		await approveWithoutCapture(ctx, "skipping capture — already merged");
+		return true;
+	}
+	return false;
+}
+async function maybeSkipDuplicate(ctx) {
+	const { deps, build, project } = ctx;
+	if (await hasApprovedBuildForSha(deps.db, project.id, build.gitSha, build.id)) {
+		await approveWithoutCapture(ctx, "skipping capture — duplicate sha already approved");
+		return true;
+	}
+	return false;
+}
+/** Map a terminal build status to its check-run state. */
+function terminalState(status) {
+	if (status === "approved") return "success";
+	if (status === "rejected" || status === "failed") return "failure";
+	return null;
+}
+/** Post the terminal status for a finished capture. */
+async function reportTerminalStatus(ctx, buildId) {
+	const { deps, build, project, pendingUrl } = ctx;
+	const terminal = terminalState((await new BuildModel(deps.db).get(buildId))?.status);
+	if (terminal) await postTerminal(deps, project, pendingUrl, build.gitSha, terminal);
+}
+async function runAndReport(ctx, job) {
+	const { deps, build, project, pendingUrl } = ctx;
+	try {
+		await executeCaptureJob({
+			buildId: job.buildId,
+			reqId: job.reqId
+		}, deps.jobOptions);
+		await reportTerminalStatus(ctx, job.buildId);
+	} catch (error) {
+		await postStatusesForBuild({
+			db: deps.db,
+			project,
+			sha: build.gitSha,
+			status: "failure",
+			url: pendingUrl,
+			providers: deps.gitHosts,
+			secret: deps.secret,
+			logger: deps.logger
+		}).catch(() => {});
+		throw error;
+	}
+}
+/** Load the build + project for a job, running orphan jobs directly. */
+async function loadJobTarget(deps, job) {
+	const build = await new BuildModel(deps.db).get(job.buildId);
+	if (!build) {
+		await executeCaptureJob({
+			buildId: job.buildId,
+			reqId: job.reqId
+		}, deps.jobOptions);
+		return null;
+	}
+	const project = await new ProjectModel(deps.db).get(build.projectId);
+	if (!project) {
+		await executeCaptureJob({
+			buildId: job.buildId,
+			reqId: job.reqId
+		}, deps.jobOptions);
+		return null;
+	}
+	return {
+		build,
+		project
+	};
+}
+/** Build the queue's job runner: post pending, apply skip rules, capture, report. */
+function createDispatchJob(deps) {
+	return async (job) => {
+		const target = await loadJobTarget(deps, job);
+		if (!target) return;
+		const pendingUrl = `/projects/${target.project.slug}/builds/${job.buildId}`;
+		await postPending(deps, target.project, pendingUrl, target.build.gitSha);
+		const ctx = {
+			deps,
+			build: target.build,
+			project: target.project,
+			pendingUrl
+		};
+		if (await maybeSkipMerged(ctx) || await maybeSkipDuplicate(ctx)) return;
+		await runAndReport(ctx, job);
+	};
+}
+//#endregion
+export { createDispatchJob };
+
+//# sourceMappingURL=dispatch.mjs.map

package/dist/capture/dispatch.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.mjs","names":[],"sources":["../../src/capture/dispatch.ts"],"sourcesContent":["import type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport type { GitHostProvider } from \"../adapters/git-host/index.ts\";\nimport type { Logger } from \"../logger.ts\";\nimport { BuildModel } from \"../models/build.ts\";\nimport { ProjectModel } from \"../models/project.ts\";\nimport type { Build } from \"../schema/build.ts\";\nimport type { Project } from \"../schema/project.ts\";\nimport { executeCaptureJob, type CaptureJobOptions } from \"./orchestrator.ts\";\nimport { hasApprovedBuildForSha, isAlreadyMerged } from \"./skip-checks.ts\";\nimport { postStatusesForBuild } from \"./status-fanout.ts\";\n\n/** Dependencies for building the capture queue's job runner. */\nexport interface DispatchDeps {\n  db: DatabaseAdapter;\n  jobOptions: CaptureJobOptions;\n  gitHosts: GitHostProvider[];\n  secret: string | undefined;\n  logger: Logger;\n}\n\n/** A queued capture job. */\nexport interface CaptureDispatchJob {\n  buildId: string;\n  reqId?: string;\n}\n\ninterface JobContext {\n  deps: DispatchDeps;\n  build: Build;\n  project: Project;\n  pendingUrl: string;\n}\n\nasync function postPending(\n  deps: DispatchDeps,\n  project: Project,\n  url: string,\n  sha: string,\n): Promise<void> {\n  await postStatusesForBuild({\n    db: deps.db,\n    project,\n    sha,\n    status: \"pending\",\n    url,\n    providers: deps.gitHosts,\n    secret: deps.secret,\n    logger: deps.logger,\n  }).catch((error: unknown) => {\n    deps.logger.error({ err: error }, \"failed to post pending status\");\n  });\n}\n\nasync function postTerminal(\n  deps: DispatchDeps,\n  project: Project,\n  url: string,\n  sha: string,\n  status: \"success\" | \"failure\",\n): Promise<void> {\n  await postStatusesForBuild({\n    db: deps.db,\n    project,\n    sha,\n    status,\n    url,\n    providers: deps.gitHosts,\n    secret: deps.secret,\n    logger: deps.logger,\n  }).catch((error: unknown) => {\n    deps.logger.error({ err: error }, \"failed to post terminal status\");\n  });\n}\n\nasync function approveWithoutCapture(ctx: JobContext, reason: string): Promise<void> {\n  const { deps, build, project, pendingUrl } = ctx;\n  deps.logger.info({ buildId: build.id, sha: build.gitSha, branch: build.gitBranch }, reason);\n  await new BuildModel(deps.db).setStatus(build.id, \"approved\").catch(() => {}); // Intentionally empty — fire-and-forget\n  await postTerminal(deps, project, pendingUrl, build.gitSha, \"success\").catch(() => {}); // Intentionally empty — fire-and-forget\n}\n\nasync function maybeSkipMerged(ctx: JobContext): Promise<boolean> {\n  const { deps, build, project } = ctx;\n  if (build.isDefault) {\n    return false;\n  }\n  const merged = await isAlreadyMerged({\n    providers: deps.gitHosts,\n    sha: build.gitSha,\n    branch: build.gitBranch,\n    secret: deps.secret,\n    db: deps.db,\n    projectId: project.id,\n    logger: deps.logger,\n  }).catch(() => false);\n  if (merged) {\n    await approveWithoutCapture(ctx, \"skipping capture — already merged\");\n    return true;\n  }\n  return false;\n}\n\nasync function maybeSkipDuplicate(ctx: JobContext): Promise<boolean> {\n  const { deps, build, project } = ctx;\n  const dup = await hasApprovedBuildForSha(deps.db, project.id, build.gitSha, build.id);\n  if (dup) {\n    await approveWithoutCapture(ctx, \"skipping capture — duplicate sha already approved\");\n    return true;\n  }\n  return false;\n}\n\n/** Map a terminal build status to its check-run state. */\nfunction terminalState(status: string | undefined): \"success\" | \"failure\" | null {\n  if (status === \"approved\") {\n    return \"success\";\n  }\n  if (status === \"rejected\" || status === \"failed\") {\n    return \"failure\";\n  }\n  return null;\n}\n\n/** Post the terminal status for a finished capture. */\nasync function reportTerminalStatus(ctx: JobContext, buildId: string): Promise<void> {\n  const { deps, build, project, pendingUrl } = ctx;\n  const updated = await new BuildModel(deps.db).get(buildId);\n  const terminal = terminalState(updated?.status);\n  if (terminal) {\n    await postTerminal(deps, project, pendingUrl, build.gitSha, terminal);\n  }\n}\n\nasync function runAndReport(ctx: JobContext, job: CaptureDispatchJob): Promise<void> {\n  const { deps, build, project, pendingUrl } = ctx;\n  try {\n    await executeCaptureJob({ buildId: job.buildId, reqId: job.reqId }, deps.jobOptions);\n    await reportTerminalStatus(ctx, job.buildId);\n  } catch (error: unknown) {\n    await postStatusesForBuild({\n      db: deps.db,\n      project,\n      sha: build.gitSha,\n      status: \"failure\",\n      url: pendingUrl,\n      providers: deps.gitHosts,\n      secret: deps.secret,\n      logger: deps.logger,\n    }).catch(() => {\n      // Ignore: status post failure already logged\n    });\n    throw error;\n  }\n}\n\n/** Load the build + project for a job, running orphan jobs directly. */\nasync function loadJobTarget(\n  deps: DispatchDeps,\n  job: CaptureDispatchJob,\n): Promise<{ build: Build; project: Project } | null> {\n  const builds = new BuildModel(deps.db);\n  const build = await builds.get(job.buildId);\n  if (!build) {\n    await executeCaptureJob({ buildId: job.buildId, reqId: job.reqId }, deps.jobOptions);\n    return null;\n  }\n  const project = await new ProjectModel(deps.db).get(build.projectId);\n  if (!project) {\n    await executeCaptureJob({ buildId: job.buildId, reqId: job.reqId }, deps.jobOptions);\n    return null;\n  }\n  return { build, project };\n}\n\n/** Build the queue's job runner: post pending, apply skip rules, capture, report. */\nexport function createDispatchJob(deps: DispatchDeps): (job: CaptureDispatchJob) => Promise<void> {\n  return async (job: CaptureDispatchJob): Promise<void> => {\n    const target = await loadJobTarget(deps, job);\n    if (!target) {\n      return;\n    }\n    const pendingUrl = `/projects/${target.project.slug}/builds/${job.buildId}`;\n    await postPending(deps, target.project, pendingUrl, target.build.gitSha);\n    const ctx: JobContext = { deps, build: target.build, project: target.project, pendingUrl };\n    if ((await maybeSkipMerged(ctx)) || (await maybeSkipDuplicate(ctx))) {\n      return;\n    }\n    await runAndReport(ctx, job);\n  };\n}\n"],"mappings":"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"}

package/dist/capture/orchestrator.d.mts

@@ -6,6 +6,7 @@ import { DatabaseAdapter } from "../adapter/database.mjs";
 import { StorageAdapter } from "../adapter/storage.mjs";
 import { Logger } from "pino";
 //#region src/capture/orchestrator.d.ts
+/** Inputs for running a capture job against a Storybook build. */
 interface CaptureJobOptions {
   db: DatabaseAdapter;
   storage: StorageAdapter;
@@ -13,7 +14,15 @@ interface CaptureJobOptions {
   scratchDir: string;
   viewports?: Viewport[];
   logger?: Logger;
+  /** Server secret for decrypting webhook secrets at send time. */
+  secret?: string | undefined;
 }
+/**
+ * Run the full capture for a build: extract, render, persist, and finalize.
+ *
+ * @param input - Build id plus the originating request id.
+ * @param options - Adapters, scratch dir, viewports, and logger.
+ */
 declare function executeCaptureJob(input: {
   buildId: string;
   reqId?: string;

package/dist/capture/orchestrator.mjs

@@ -3,14 +3,17 @@ import "node:url";
 import.meta.url;
 import { BuildModel } from "../models/build.mjs";
 import { ProjectModel } from "../models/project.mjs";
-import { storybookDir, storybookZipPath } from "../utils/paths.mjs";
+import { DEFAULT_VIEWPORTS, isDisabledStory, isFlakyStory } from "./adapter.mjs";
 import { persistCapture } from "./pipeline.mjs";
+import { extractStorybookToScratch, persistStorybookStatics } from "./statics.mjs";
 import { StorybookAdapter } from "./storybook.mjs";
-import { DEFAULT_VIEWPORTS, isDisabledStory, isFlakyStory } from "./adapter.mjs";
-import { mkdir, readFile, readdir, rm } from "node:fs/promises";
-import { join, relative, resolve, sep } from "node:path";
-import AdmZip from "adm-zip";
 //#region src/capture/orchestrator.ts
+/**
+* Run the full capture for a build: extract, render, persist, and finalize.
+*
+* @param input - Build id plus the originating request id.
+* @param options - Adapters, scratch dir, viewports, and logger.
+*/
 async function executeCaptureJob(input, options) {
 	const builds = new BuildModel(options.db);
 	const { build, project } = await loadTarget(options, input.buildId);
@@ -23,7 +26,7 @@ async function executeCaptureJob(input, options) {
 	let extractedDir;
 	try {
 		const extractStart = performance.now();
-		extractedDir = await extractStorybook(options, project.id, build.id);
+		extractedDir = await extractStorybookToScratch(options.storage, options.scratchDir, project.id, build.id);
 		const extractDuration = performance.now() - extractStart;
 		logger?.info({ durationMs: Math.round(extractDuration) }, "storybook extracted");
 		const staticsStart = performance.now();
@@ -59,7 +62,8 @@ async function executeCaptureJob(input, options) {
 			build,
 			viewports,
 			captures: result.captures,
-			logger
+			logger,
+			secret: options.secret
 		}, blockingFailed, flakyFailed);
 		const persistDuration = performance.now() - persistStart;
 		logger?.info({ durationMs: Math.round(persistDuration) }, "capture persisted");
@@ -87,43 +91,6 @@ async function loadTarget(options, buildId) {
 		project
 	};
 }
-function blockedTarget(root, entryName) {
-	const candidate = resolve(join(root, entryName));
-	return candidate !== root && !candidate.startsWith(root + sep);
-}
-function assertNoTraversal(zip, root) {
-	for (const entry of zip.getEntries()) if (blockedTarget(root, entry.entryName)) throw new Error(`Blocked path traversal in uploaded Storybook: ${entry.entryName}`);
-}
-async function extractStorybook(options, projectId, buildId) {
-	const targetDir = join(options.scratchDir, projectId, "builds", buildId, "storybook");
-	const root = resolve(targetDir);
-	const zip = new AdmZip(await options.storage.read(storybookZipPath(projectId, buildId)));
-	assertNoTraversal(zip, root);
-	await rm(targetDir, {
-		recursive: true,
-		force: true
-	});
-	await mkdir(targetDir, { recursive: true });
-	zip.extractAllTo(targetDir, true);
-	return targetDir;
-}
-async function walkFiles(dir) {
-	const entries = await readdir(dir, { withFileTypes: true });
-	return (await Promise.all(entries.map(async (entry) => {
-		const full = join(dir, entry.name);
-		if (entry.isDirectory()) return await walkFiles(full);
-		return [full];
-	}))).flat();
-}
-async function persistStorybookStatics(storage, sourceDir, projectId, buildId) {
-	const root = resolve(sourceDir);
-	const destinationPrefix = storybookDir(projectId, buildId);
-	const files = await walkFiles(root);
-	await Promise.all(files.map(async (file) => {
-		const rel = relative(root, file);
-		await storage.write(`${destinationPrefix}/${rel}`, await readFile(file));
-	}));
-}
 //#endregion
 export { executeCaptureJob };