@storyshelf/core 0.7.0 → 0.9.0-next-d2cc082

package/dist/adapter/capture-queue.d.mts

@@ -1,7 +1,6 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { Adapter } from "./metadata.mjs";
-//#region src/adapters/capture-queue.d.ts
 /** Lifecycle status of a queued capture job. */
 type JobStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
 /** Observable state of a single capture queue entry. */
@@ -116,6 +115,5 @@ interface PollableCaptureQueue extends CaptureQueue {
    */
   inspect?(job: PollableJob): Promise<LeaseRenewal>;
 }
-//#endregion
 export { CaptureJob, CaptureQueue, JobStatus, LeaseRenewal, PollableCaptureQueue, PollableJob, QueueEntry };
 //# sourceMappingURL=capture-queue.d.mts.map

package/dist/adapter/capture-runner.d.mts

@@ -3,12 +3,17 @@ import __tsdown_shims_url from 'node:url';
 import { StoryEntry, StoryParameters, StorySourceAdapter, Viewport } from "../capture/adapter.mjs";
 import { BROWSER_NAMES, BrowserName, CaptureTarget, DEFAULT_BROWSER, ParsedTarget, RunnerTarget, TARGET_NAME_PATTERN, TargetLaunchError, TargetReach, TargetStatus, engineOf, isBrowserName, isCaptureTarget, parseTarget, tryParseTarget, unavailableReason } from "../adapters/capture-target.mjs";
 import { TargetOffers, createTargetOffers } from "../adapters/capture-target-offers.mjs";
-import { RemoteBrowser, RemoteConnection, RemoteOptions, RemoteProtocol, RemoteSupport, RemoteTarget, defineRemote, isRemoteBrowser, reachOf, remoteTargetsOf, scrubConnection } from "../adapters/remote-browser.mjs";
+import { RemoteBrowser, RemoteConnectContext, RemoteConnection, RemoteLeaseOutcome, RemoteLeasedConnection, RemoteOptions, RemoteProtocol, RemotePurpose, RemoteReleaseInfo, RemoteSupport, RemoteTarget, defineRemote, hasSchemeFor, isRemoteBrowser, remoteTargetsOf, scrubConnection } from "../adapters/remote-browser.mjs";
+import { HeldConnection } from "../adapters/remote-lease-held.mjs";
+import { RemoteConnectError, RemoteConnectErrorOptions } from "../adapters/remote-lease-error.mjs";
+import { onRemoteShutdown, shutdownRemote } from "../adapters/remote-lease-shutdown.mjs";
+import { ConnectLeasedContext, ConnectLeasedOptions, connectLeased } from "../adapters/remote-lease.mjs";
+import { RemoteSizing, UNVERIFIED_NOTE, logRemoteSizing, remoteSizingOf } from "../adapters/remote-sizing.mjs";
+import { PoolLease, RefCounted, RefCountedOptions, refCounted } from "../adapters/remote-pool.mjs";
 import { RenderRuns } from "../adapters/render-runs.mjs";
 import { Adapter } from "./metadata.mjs";
 import { JobStatus } from "./capture-queue.mjs";
 import { Logger } from "pino";
-//#region src/adapters/capture-runner.d.ts
 /**
  * The rendering environment a runner captured in. Two captures with the same environment (and
  * engine and viewport) should produce identical pixels; a different one explains a visual diff
@@ -119,6 +124,8 @@ interface CaptureRunner extends Adapter<{
      * build (its shards) can be in flight in one process. Absent, the build id is used.
      */
     runId?: string | undefined;
+    /** The shard's 1-based position in the build's plan, for a remote service that routes per shard. */
+    shardIndex?: number | undefined;
     /** Root of the already-extracted Storybook build. */
     storybookDir: string;
     /** Stories to render. */
@@ -202,6 +209,5 @@ interface CaptureRunner extends Adapter<{
    */
   cancel(buildId: string, runId?: string): Promise<void>;
 }
-//#endregion
-export { BROWSER_NAMES, type BrowserName, CaptureEnvironment, CaptureRunner, type CaptureTarget, DEFAULT_BROWSER, type JobStatus, type ParsedTarget, type RemoteBrowser, type RemoteConnection, type RemoteOptions, type RemoteProtocol, type RemoteSupport, type RemoteTarget, RenderFailure, RenderResult, RenderRuns, RenderedSnapshot, type RunnerTarget, type StoryEntry, type StorySourceAdapter, TARGET_NAME_PATTERN, TargetLaunchError, type TargetOffers, type TargetReach, type TargetStatus, TestOutcome, type Viewport, createTargetOffers, defineRemote, engineOf, isBrowserName, isCaptureTarget, isRemoteBrowser, parseTarget, reachOf, remoteTargetsOf, scrubConnection, tryParseTarget, unavailableReason };
+export { BROWSER_NAMES, type BrowserName, CaptureEnvironment, CaptureRunner, type CaptureTarget, type ConnectLeasedContext, type ConnectLeasedOptions, DEFAULT_BROWSER, type HeldConnection, type JobStatus, type ParsedTarget, type PoolLease, type RefCounted, type RefCountedOptions, type RemoteBrowser, type RemoteConnectContext, RemoteConnectError, type RemoteConnectErrorOptions, type RemoteConnection, type RemoteLeaseOutcome, type RemoteLeasedConnection, type RemoteOptions, type RemoteProtocol, type RemotePurpose, type RemoteReleaseInfo, type RemoteSizing, type RemoteSupport, type RemoteTarget, RenderFailure, RenderResult, RenderRuns, RenderedSnapshot, type RunnerTarget, type StoryEntry, type StorySourceAdapter, TARGET_NAME_PATTERN, TargetLaunchError, type TargetOffers, type TargetReach, type TargetStatus, TestOutcome, UNVERIFIED_NOTE, type Viewport, connectLeased, createTargetOffers, defineRemote, engineOf, hasSchemeFor, isBrowserName, isCaptureTarget, isRemoteBrowser, logRemoteSizing, onRemoteShutdown, parseTarget, refCounted, remoteSizingOf, remoteTargetsOf, scrubConnection, shutdownRemote, tryParseTarget, unavailableReason };
 //# sourceMappingURL=capture-runner.d.mts.map

package/dist/adapter/capture-runner.mjs

@@ -3,6 +3,11 @@ import "node:url";
 import.meta.url;
 import { BROWSER_NAMES, DEFAULT_BROWSER, TARGET_NAME_PATTERN, TargetLaunchError, engineOf, isBrowserName, isCaptureTarget, parseTarget, tryParseTarget, unavailableReason } from "../adapters/capture-target.mjs";
 import { createTargetOffers } from "../adapters/capture-target-offers.mjs";
-import { defineRemote, isRemoteBrowser, reachOf, remoteTargetsOf, scrubConnection } from "../adapters/remote-browser.mjs";
+import { defineRemote, hasSchemeFor, isRemoteBrowser, remoteTargetsOf, scrubConnection } from "../adapters/remote-browser.mjs";
+import { RemoteConnectError } from "../adapters/remote-lease-error.mjs";
+import { onRemoteShutdown, shutdownRemote } from "../adapters/remote-lease-shutdown.mjs";
+import { connectLeased } from "../adapters/remote-lease.mjs";
+import { UNVERIFIED_NOTE, logRemoteSizing, remoteSizingOf } from "../adapters/remote-sizing.mjs";
+import { refCounted } from "../adapters/remote-pool.mjs";
 import { RenderRuns } from "../adapters/render-runs.mjs";
-export { BROWSER_NAMES, DEFAULT_BROWSER, RenderRuns, TARGET_NAME_PATTERN, TargetLaunchError, createTargetOffers, defineRemote, engineOf, isBrowserName, isCaptureTarget, isRemoteBrowser, parseTarget, reachOf, remoteTargetsOf, scrubConnection, tryParseTarget, unavailableReason };
+export { BROWSER_NAMES, DEFAULT_BROWSER, RemoteConnectError, RenderRuns, TARGET_NAME_PATTERN, TargetLaunchError, UNVERIFIED_NOTE, connectLeased, createTargetOffers, defineRemote, engineOf, hasSchemeFor, isBrowserName, isCaptureTarget, isRemoteBrowser, logRemoteSizing, onRemoteShutdown, parseTarget, refCounted, remoteSizingOf, remoteTargetsOf, scrubConnection, shutdownRemote, tryParseTarget, unavailableReason };

package/dist/adapter/database.d.mts

@@ -2,7 +2,8 @@ import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { Adapter, AdapterMetadata } from "./metadata.mjs";
 import { SQL, Table } from "drizzle-orm";
-//#region src/adapters/database.d.ts
+/** A fenced reference write lost its generation race and should be retried. */
+declare class ReferenceGenerationConflict extends Error {}
 /** Type-safe table map enforced on every DatabaseAdapter. */
 interface Tables {
   projects: Table;
@@ -74,6 +75,57 @@ interface TxStore {
   /** Count rows matching an optional where condition. */
   count(table: Table, where?: SQL): Promise<number>;
 }
+/** An owner of durable protection for a build. Historical comparisons are not build owners. */
+interface BuildReferenceOwner {
+  type: "baseline" | "investigation";
+  id: string;
+  projectId: string;
+}
+/** One owner's complete new reference set for an atomic multi-owner mutation. */
+interface BuildReferenceChange {
+  owner: BuildReferenceOwner;
+  buildIds: readonly string[];
+}
+/** A complete owner reference replacement guarded by its last observed generation. */
+interface FencedBuildReferenceChange extends BuildReferenceChange {
+  expectedGeneration: number;
+}
+/**
+ * An explicit database capability; an ordinary transaction does not establish this contract.
+ * Implementations serialize admissions, reference changes, and deletion claims across processes.
+ * Their tests must use independent connections, including promotion/purge and pin/purge races.
+ */
+interface BuildReferenceLifecycle {
+  /** Return the durable generation for an owner, or zero before its first reference mutation.
+   * This is a snapshot: callers must pass it to a fenced mutation, which rechecks atomically. */
+  referenceGeneration(owner: BuildReferenceOwner): Promise<number>;
+  /** Atomically fence and replace multiple owners, or roll back all owners and domain writes. */
+  replaceManyFencedReferences<T>(changes: readonly FencedBuildReferenceChange[], writeDomain: (tx: TxStore) => Promise<T>): Promise<{
+    result: T;
+    generations: number[];
+  }>;
+  /** Compare and advance an owner's durable generation with its reference and domain writes.
+   * Generation zero denotes an owner with no earlier mutations. A stale generation rejects the
+   * whole transaction. Generations survive release so an old worker cannot release a newer pin. */
+  replaceFencedReferences<T>(owner: BuildReferenceOwner, expectedGeneration: number, buildIds: readonly string[], writeDomain: (tx: TxStore) => Promise<T>): Promise<{
+    result: T;
+    generation: number;
+  }>;
+  /**
+   * Atomically replace one owner's complete reference set and make its domain writes. Both old and
+   * new builds must be locked in stable order, checked for project ownership and availability,
+   * and committed with the domain mutation. Unknown or tombstoned builds reject admission.
+   */
+  replaceReferences<T>(owner: BuildReferenceOwner, buildIds: readonly string[], writeDomain: (tx: TxStore) => Promise<T>): Promise<T>;
+  /** Atomically replace several owners' reference sets and the shared domain writes. */
+  replaceManyReferences<T>(changes: readonly BuildReferenceChange[], writeDomain: (tx: TxStore) => Promise<T>): Promise<T>;
+  /**
+   * In the same concurrency domain as admissions, irreversibly tombstone a build only if no
+   * protecting reference remains. Existing tombstones are resumable and never become available.
+   * Storage deletion must happen after this operation commits, outside database locks.
+   */
+  claimDeletion(projectId: string, buildId: string): Promise<"claimed" | "protected" | "deleting" | "missing">;
+}
 /** Database-specific metadata: the family plus what the backing platform can carry. */
 interface DatabaseAdapterMetadata {
   readonly category: "database";
@@ -86,12 +138,21 @@ interface DatabaseAdapterMetadata {
 }
 /** Database abstraction over Drizzle tables, agnostic of dialect and driver. */
 interface DatabaseAdapter extends Adapter<DatabaseAdapterMetadata> {
+  /**
+   * Present only when the adapter implements the cross-process retention safety contract.
+   * `transact` by itself is not evidence of this capability.
+   */
+  readonly buildReferenceLifecycle?: BuildReferenceLifecycle;
   /** Table handles for this adapter's dialect, enforced with type safety. */
   readonly tables: Tables;
   /** Insert a row and return the inserted record. */
   insert<T extends Table>(table: T, values: T["$inferInsert"]): Promise<T["$inferSelect"]>;
   /** Update a row by id and return the updated record. */
   update<T extends Table>(table: T, id: string, values: Partial<T["$inferInsert"]>): Promise<T["$inferSelect"]>;
+  /** Atomically update a row only while `where` matches; return the current row, or null if absent.
+   * Custom adapters must implement the condition in the same database statement as the update.
+   */
+  updateWhere<T extends Table>(table: T, id: string, values: Partial<T["$inferInsert"]>, where: SQL): Promise<T["$inferSelect"] | null>;
   /** Fetch a single row by id, or null if not found. */
   get<T extends Table>(table: T, id: string): Promise<T["$inferSelect"] | null>;
   /** Delete a row by id. */
@@ -118,6 +179,5 @@ interface DrizzleAdapterOptions {
   /** Cheap liveness probe (e.g. `SELECT 1`); omitted when the driver has none. */
   ping?: () => Promise<void> | void;
 }
-//#endregion
-export { DatabaseAdapter, DatabaseAdapterMetadata, DrizzleAdapterOptions, ListOptions, MAX_LIST_LIMIT, REQUIRED_TABLE_KEYS, Tables, TxStore, clampListLimit };
+export { BuildReferenceChange, BuildReferenceLifecycle, BuildReferenceOwner, DatabaseAdapter, DatabaseAdapterMetadata, DrizzleAdapterOptions, FencedBuildReferenceChange, ListOptions, MAX_LIST_LIMIT, REQUIRED_TABLE_KEYS, ReferenceGenerationConflict, Tables, TxStore, clampListLimit };
 //# sourceMappingURL=database.d.mts.map

package/dist/adapter/database.mjs

@@ -1,7 +1,9 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/adapters/database.ts
+// src/adapters/database.ts
+/** A fenced reference write lost its generation race and should be retried. */
+var ReferenceGenerationConflict = class extends Error {};
 /** Table keys every DatabaseAdapter must expose (contract + validation share this). */
 const REQUIRED_TABLE_KEYS = [
 	"projects",
@@ -24,7 +26,6 @@ function clampListLimit(limit) {
 	if (!Number.isFinite(limit)) return MAX_LIST_LIMIT;
 	return Math.min(Math.max(Math.floor(limit), 1), MAX_LIST_LIMIT);
 }
-//#endregion
-export { MAX_LIST_LIMIT, REQUIRED_TABLE_KEYS, clampListLimit };
+export { MAX_LIST_LIMIT, REQUIRED_TABLE_KEYS, ReferenceGenerationConflict, clampListLimit };
 
 //# sourceMappingURL=database.mjs.map

package/dist/adapter/database.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"database.mjs","names":[],"sources":["../../src/adapters/database.ts"],"sourcesContent":["/**\n * Database adapter interface: query builders over explicitly typed tables.\n *\n * Canonical home of the database contract — {@link DatabaseAdapter},\n * {@link Tables}, {@link TxStore}, {@link ListOptions}, and\n * {@link DrizzleAdapterOptions}. Driver machinery lives in the database\n * packages (`@storyshelf/db-sqlite`, `@storyshelf/db-postgres`).\n */\nimport type { SQL } from \"drizzle-orm\";\nimport type { Table } from \"drizzle-orm\";\nimport type { Adapter, AdapterMetadata } from \"./metadata.ts\";\n\n/** Type-safe table map enforced on every DatabaseAdapter. */\nexport interface Tables {\n  projects: Table;\n  builds: Table;\n  captureAttempts: Table;\n  captureLogs: Table;\n  captureShards: Table;\n  captureJobs: Table;\n  buildComponents: Table;\n  buildReviews: Table;\n  siteSettings: Table;\n  snapshots: Table;\n  baselines: Table;\n  comments: Table;\n  labelTypes: Table;\n  buildLabels: Table;\n  projectLinks: Table;\n  designLinks: Table;\n  designCredentials: Table;\n  userConnections: Table;\n  designNodes: Table;\n  buildPackageUsage: Table;\n  tokens: Table;\n  webhooks: Table;\n  insights: Table;\n  aiUsage: Table;\n  aiBudgetAlerts: Table;\n  notificationChannels: Table;\n  notificationSubscriptions: Table;\n  users: Table;\n  userInviteTokens: Table;\n  projectMembers: Table;\n  projectGroupMappings: Table;\n  contentRefs: Table;\n}\n\n/** Table keys every DatabaseAdapter must expose (contract + validation share this). */\nexport const REQUIRED_TABLE_KEYS = [\n  \"projects\",\n  \"builds\",\n  \"snapshots\",\n  \"baselines\",\n  \"comments\",\n  \"labelTypes\",\n  \"buildLabels\",\n  \"tokens\",\n  \"webhooks\",\n  \"users\",\n  \"projectMembers\",\n];\n\n/** Largest page any adapter serves in one list call. */\nexport const MAX_LIST_LIMIT = 1000;\n\n/** Clamp a list limit into [1, MAX_LIST_LIMIT]; undefined stays undefined. */\nexport function clampListLimit(limit?: number): number | undefined {\n  if (limit === undefined) {\n    return undefined;\n  }\n  if (!Number.isFinite(limit)) {\n    return MAX_LIST_LIMIT;\n  }\n  return Math.min(Math.max(Math.floor(limit), 1), MAX_LIST_LIMIT);\n}\n\n/** Options that narrow and page a list query. */\nexport interface ListOptions {\n  /** SQL WHERE condition. */\n  where?: SQL;\n  /** SQL ORDER BY condition. */\n  orderBy?: SQL;\n  /** Maximum number of rows to return. */\n  limit?: number;\n  /** Number of rows to skip. */\n  offset?: number;\n}\n\n/**\n * Transactional CRUD subset available inside {@link DatabaseAdapter.transact}.\n * Mirrors the adapter surface minus metadata, lifecycle, and raw `all`\n * (opaque to transactions on some drivers).\n */\nexport interface TxStore {\n  /** Insert a row and return the inserted record. */\n  insert<T extends Table>(table: T, values: T[\"$inferInsert\"]): Promise<T[\"$inferSelect\"]>;\n  /** Update a row by id and return the updated record. */\n  update<T extends Table>(\n    table: T,\n    id: string,\n    values: Partial<T[\"$inferInsert\"]>,\n  ): Promise<T[\"$inferSelect\"]>;\n  /** Fetch a single row by id, or null if not found. */\n  get<T extends Table>(table: T, id: string): Promise<T[\"$inferSelect\"] | null>;\n  /** Delete a row by id. */\n  remove(table: Table, id: string): Promise<void>;\n  /** List rows matching the given options. */\n  list<T extends Table>(table: T, opts?: ListOptions): Promise<T[\"$inferSelect\"][]>;\n  /** Count rows matching an optional where condition. */\n  count(table: Table, where?: SQL): Promise<number>;\n}\n\n/** Database-specific metadata: the family plus what the backing platform can carry. */\nexport interface DatabaseAdapterMetadata {\n  readonly category: \"database\";\n  /**\n   * `false` when the database cannot back a deployment with `testing` (ADR 0006, decision 3): it\n   * is reachable only from a platform that ends the process after each request (Cloudflare D1).\n   * Unset means it can.\n   */\n  readonly supportsTesting?: boolean;\n}\n\n/** Database abstraction over Drizzle tables, agnostic of dialect and driver. */\nexport interface DatabaseAdapter extends Adapter<DatabaseAdapterMetadata> {\n  /** Table handles for this adapter's dialect, enforced with type safety. */\n  readonly tables: Tables;\n  /** Insert a row and return the inserted record. */\n  insert<T extends Table>(table: T, values: T[\"$inferInsert\"]): Promise<T[\"$inferSelect\"]>;\n  /** Update a row by id and return the updated record. */\n  update<T extends Table>(\n    table: T,\n    id: string,\n    values: Partial<T[\"$inferInsert\"]>,\n  ): Promise<T[\"$inferSelect\"]>;\n  /** Fetch a single row by id, or null if not found. */\n  get<T extends Table>(table: T, id: string): Promise<T[\"$inferSelect\"] | null>;\n  /** Delete a row by id. */\n  remove(table: Table, id: string): Promise<void>;\n  /** List rows matching the given options. */\n  list<T extends Table>(table: T, opts?: ListOptions): Promise<T[\"$inferSelect\"][]>;\n  /** Count rows matching an optional where condition. */\n  count(table: Table, where?: SQL): Promise<number>;\n  /** Run an arbitrary SQL query and return typed rows. */\n  all<T>(query: SQL): Promise<T[]>;\n  /**\n   * Run `fn` inside a transaction when the driver supports one.\n   * Commits on resolve, rolls back on throw. Drivers without transaction\n   * support omit this; callers must use `?.` and accept sequential execution.\n   */\n  transact?<R>(fn: (tx: TxStore) => Promise<R>): Promise<R>;\n}\n\n/** Driver-supplied identity plus lifecycle hooks. */\nexport interface DrizzleAdapterOptions {\n  metadata: AdapterMetadata & DatabaseAdapterMetadata;\n  tables: Tables;\n  migrate: () => Promise<void> | void;\n  close: () => Promise<void> | void;\n  /** Cheap liveness probe (e.g. `SELECT 1`); omitted when the driver has none. */\n  ping?: () => Promise<void> | void;\n}\n"],"mappings":";;;;;AAiDA,MAAa,sBAAsB;CACjC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AAGA,MAAa,iBAAiB;;AAG9B,SAAgB,eAAe,OAAoC;CACjE,IAAI,UAAU,KAAA,GACZ;CAEF,IAAI,CAAC,OAAO,SAAS,KAAK,GACxB,OAAO;CAET,OAAO,KAAK,IAAI,KAAK,IAAI,KAAK,MAAM,KAAK,GAAG,CAAC,GAAG,cAAc;AAChE"}
+{"version":3,"file":"database.mjs","names":[],"sources":["../../src/adapters/database.ts"],"sourcesContent":["/**\n * Database adapter interface: query builders over explicitly typed tables.\n *\n * Canonical home of the database contract — {@link DatabaseAdapter},\n * {@link Tables}, {@link TxStore}, {@link ListOptions}, and\n * {@link DrizzleAdapterOptions}. Driver machinery lives in the database\n * packages (`@storyshelf/db-sqlite`, `@storyshelf/db-postgres`).\n */\nimport type { SQL } from \"drizzle-orm\";\nimport type { Table } from \"drizzle-orm\";\nimport type { Adapter, AdapterMetadata } from \"./metadata.ts\";\n\n/** A fenced reference write lost its generation race and should be retried. */\nexport class ReferenceGenerationConflict extends Error {}\n\n/** Type-safe table map enforced on every DatabaseAdapter. */\nexport interface Tables {\n  projects: Table;\n  builds: Table;\n  captureAttempts: Table;\n  captureLogs: Table;\n  captureShards: Table;\n  captureJobs: Table;\n  buildComponents: Table;\n  buildReviews: Table;\n  siteSettings: Table;\n  snapshots: Table;\n  baselines: Table;\n  comments: Table;\n  labelTypes: Table;\n  buildLabels: Table;\n  projectLinks: Table;\n  designLinks: Table;\n  designCredentials: Table;\n  userConnections: Table;\n  designNodes: Table;\n  buildPackageUsage: Table;\n  tokens: Table;\n  webhooks: Table;\n  insights: Table;\n  aiUsage: Table;\n  aiBudgetAlerts: Table;\n  notificationChannels: Table;\n  notificationSubscriptions: Table;\n  users: Table;\n  userInviteTokens: Table;\n  projectMembers: Table;\n  projectGroupMappings: Table;\n  contentRefs: Table;\n}\n\n/** Table keys every DatabaseAdapter must expose (contract + validation share this). */\nexport const REQUIRED_TABLE_KEYS = [\n  \"projects\",\n  \"builds\",\n  \"snapshots\",\n  \"baselines\",\n  \"comments\",\n  \"labelTypes\",\n  \"buildLabels\",\n  \"tokens\",\n  \"webhooks\",\n  \"users\",\n  \"projectMembers\",\n];\n\n/** Largest page any adapter serves in one list call. */\nexport const MAX_LIST_LIMIT = 1000;\n\n/** Clamp a list limit into [1, MAX_LIST_LIMIT]; undefined stays undefined. */\nexport function clampListLimit(limit?: number): number | undefined {\n  if (limit === undefined) {\n    return undefined;\n  }\n  if (!Number.isFinite(limit)) {\n    return MAX_LIST_LIMIT;\n  }\n  return Math.min(Math.max(Math.floor(limit), 1), MAX_LIST_LIMIT);\n}\n\n/** Options that narrow and page a list query. */\nexport interface ListOptions {\n  /** SQL WHERE condition. */\n  where?: SQL;\n  /** SQL ORDER BY condition. */\n  orderBy?: SQL;\n  /** Maximum number of rows to return. */\n  limit?: number;\n  /** Number of rows to skip. */\n  offset?: number;\n}\n\n/**\n * Transactional CRUD subset available inside {@link DatabaseAdapter.transact}.\n * Mirrors the adapter surface minus metadata, lifecycle, and raw `all`\n * (opaque to transactions on some drivers).\n */\nexport interface TxStore {\n  /** Insert a row and return the inserted record. */\n  insert<T extends Table>(table: T, values: T[\"$inferInsert\"]): Promise<T[\"$inferSelect\"]>;\n  /** Update a row by id and return the updated record. */\n  update<T extends Table>(\n    table: T,\n    id: string,\n    values: Partial<T[\"$inferInsert\"]>,\n  ): Promise<T[\"$inferSelect\"]>;\n  /** Fetch a single row by id, or null if not found. */\n  get<T extends Table>(table: T, id: string): Promise<T[\"$inferSelect\"] | null>;\n  /** Delete a row by id. */\n  remove(table: Table, id: string): Promise<void>;\n  /** List rows matching the given options. */\n  list<T extends Table>(table: T, opts?: ListOptions): Promise<T[\"$inferSelect\"][]>;\n  /** Count rows matching an optional where condition. */\n  count(table: Table, where?: SQL): Promise<number>;\n}\n\n/** An owner of durable protection for a build. Historical comparisons are not build owners. */\nexport interface BuildReferenceOwner {\n  type: \"baseline\" | \"investigation\";\n  id: string;\n  projectId: string;\n}\n\n/** One owner's complete new reference set for an atomic multi-owner mutation. */\nexport interface BuildReferenceChange {\n  owner: BuildReferenceOwner;\n  buildIds: readonly string[];\n}\n\n/** A complete owner reference replacement guarded by its last observed generation. */\nexport interface FencedBuildReferenceChange extends BuildReferenceChange {\n  expectedGeneration: number;\n}\n\n/**\n * An explicit database capability; an ordinary transaction does not establish this contract.\n * Implementations serialize admissions, reference changes, and deletion claims across processes.\n * Their tests must use independent connections, including promotion/purge and pin/purge races.\n */\nexport interface BuildReferenceLifecycle {\n  /** Return the durable generation for an owner, or zero before its first reference mutation.\n   * This is a snapshot: callers must pass it to a fenced mutation, which rechecks atomically. */\n  referenceGeneration(owner: BuildReferenceOwner): Promise<number>;\n  /** Atomically fence and replace multiple owners, or roll back all owners and domain writes. */\n  replaceManyFencedReferences<T>(\n    changes: readonly FencedBuildReferenceChange[],\n    writeDomain: (tx: TxStore) => Promise<T>,\n  ): Promise<{ result: T; generations: number[] }>;\n  /** Compare and advance an owner's durable generation with its reference and domain writes.\n   * Generation zero denotes an owner with no earlier mutations. A stale generation rejects the\n   * whole transaction. Generations survive release so an old worker cannot release a newer pin. */\n  replaceFencedReferences<T>(\n    owner: BuildReferenceOwner,\n    expectedGeneration: number,\n    buildIds: readonly string[],\n    writeDomain: (tx: TxStore) => Promise<T>,\n  ): Promise<{ result: T; generation: number }>;\n  /**\n   * Atomically replace one owner's complete reference set and make its domain writes. Both old and\n   * new builds must be locked in stable order, checked for project ownership and availability,\n   * and committed with the domain mutation. Unknown or tombstoned builds reject admission.\n   */\n  replaceReferences<T>(\n    owner: BuildReferenceOwner,\n    buildIds: readonly string[],\n    writeDomain: (tx: TxStore) => Promise<T>,\n  ): Promise<T>;\n  /** Atomically replace several owners' reference sets and the shared domain writes. */\n  replaceManyReferences<T>(\n    changes: readonly BuildReferenceChange[],\n    writeDomain: (tx: TxStore) => Promise<T>,\n  ): Promise<T>;\n  /**\n   * In the same concurrency domain as admissions, irreversibly tombstone a build only if no\n   * protecting reference remains. Existing tombstones are resumable and never become available.\n   * Storage deletion must happen after this operation commits, outside database locks.\n   */\n  claimDeletion(\n    projectId: string,\n    buildId: string,\n  ): Promise<\"claimed\" | \"protected\" | \"deleting\" | \"missing\">;\n}\n\n/** Database-specific metadata: the family plus what the backing platform can carry. */\nexport interface DatabaseAdapterMetadata {\n  readonly category: \"database\";\n  /**\n   * `false` when the database cannot back a deployment with `testing` (ADR 0006, decision 3): it\n   * is reachable only from a platform that ends the process after each request (Cloudflare D1).\n   * Unset means it can.\n   */\n  readonly supportsTesting?: boolean;\n}\n\n/** Database abstraction over Drizzle tables, agnostic of dialect and driver. */\nexport interface DatabaseAdapter extends Adapter<DatabaseAdapterMetadata> {\n  /**\n   * Present only when the adapter implements the cross-process retention safety contract.\n   * `transact` by itself is not evidence of this capability.\n   */\n  readonly buildReferenceLifecycle?: BuildReferenceLifecycle;\n  /** Table handles for this adapter's dialect, enforced with type safety. */\n  readonly tables: Tables;\n  /** Insert a row and return the inserted record. */\n  insert<T extends Table>(table: T, values: T[\"$inferInsert\"]): Promise<T[\"$inferSelect\"]>;\n  /** Update a row by id and return the updated record. */\n  update<T extends Table>(\n    table: T,\n    id: string,\n    values: Partial<T[\"$inferInsert\"]>,\n  ): Promise<T[\"$inferSelect\"]>;\n  /** Atomically update a row only while `where` matches; return the current row, or null if absent.\n   * Custom adapters must implement the condition in the same database statement as the update.\n   */\n  updateWhere<T extends Table>(\n    table: T,\n    id: string,\n    values: Partial<T[\"$inferInsert\"]>,\n    where: SQL,\n  ): Promise<T[\"$inferSelect\"] | null>;\n  /** Fetch a single row by id, or null if not found. */\n  get<T extends Table>(table: T, id: string): Promise<T[\"$inferSelect\"] | null>;\n  /** Delete a row by id. */\n  remove(table: Table, id: string): Promise<void>;\n  /** List rows matching the given options. */\n  list<T extends Table>(table: T, opts?: ListOptions): Promise<T[\"$inferSelect\"][]>;\n  /** Count rows matching an optional where condition. */\n  count(table: Table, where?: SQL): Promise<number>;\n  /** Run an arbitrary SQL query and return typed rows. */\n  all<T>(query: SQL): Promise<T[]>;\n  /**\n   * Run `fn` inside a transaction when the driver supports one.\n   * Commits on resolve, rolls back on throw. Drivers without transaction\n   * support omit this; callers must use `?.` and accept sequential execution.\n   */\n  transact?<R>(fn: (tx: TxStore) => Promise<R>): Promise<R>;\n}\n\n/** Driver-supplied identity plus lifecycle hooks. */\nexport interface DrizzleAdapterOptions {\n  metadata: AdapterMetadata & DatabaseAdapterMetadata;\n  tables: Tables;\n  migrate: () => Promise<void> | void;\n  close: () => Promise<void> | void;\n  /** Cheap liveness probe (e.g. `SELECT 1`); omitted when the driver has none. */\n  ping?: () => Promise<void> | void;\n}\n"],"mappings":";;;;;AAaA,IAAa,8BAAb,cAAiD,MAAM,CAAC;;AAuCxD,MAAa,sBAAsB;CACjC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AAGA,MAAa,iBAAiB;;AAG9B,SAAgB,eAAe,OAAoC;CACjE,IAAI,UAAU,KAAA,GACZ;CAEF,IAAI,CAAC,OAAO,SAAS,KAAK,GACxB,OAAO;CAET,OAAO,KAAK,IAAI,KAAK,IAAI,KAAK,MAAM,KAAK,GAAG,CAAC,GAAG,cAAc;AAChE"}

package/dist/adapter/design.d.mts

@@ -4,7 +4,6 @@ import { Logger } from "../logger.mjs";
 import { OAuthClient } from "./oauth.mjs";
 import { Adapter, AdapterMetadata } from "./metadata.mjs";
 import { Buffer } from "node:buffer";
-//#region src/adapters/design.d.ts
 /** Design-provider metadata: identity plus the copy the settings UI shows for its credential. */
 interface DesignAdapterMetadata extends AdapterMetadata {
   readonly category: "design";
@@ -80,6 +79,5 @@ declare function parseDesignUrl(providers: readonly DesignProvider[], raw: strin
   provider: DesignProvider;
   ref: DesignRef;
 } | null;
-//#endregion
 export { DesignAdapterMetadata, DesignAuthType, DesignCallOptions, DesignClient, DesignMeta, DesignProvider, DesignRef, DesignState, InvalidDesignUrlError, parseDesignUrl };
 //# sourceMappingURL=design.d.mts.map

package/dist/adapter/design.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/adapters/design.ts
+// src/adapters/design.ts
 /** Thrown when a design link is not accepted by any configured provider. */
 var InvalidDesignUrlError = class extends Error {
 	value;
@@ -22,7 +22,6 @@ function parseDesignUrl(providers, raw) {
 	}
 	return null;
 }
-//#endregion
 export { InvalidDesignUrlError, parseDesignUrl };
 
 //# sourceMappingURL=design.mjs.map

package/dist/adapter/email-sender.d.mts

@@ -1,7 +1,6 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { Adapter } from "./metadata.mjs";
-//#region src/adapters/email-sender.d.ts
 /** A single email message (transport-agnostic). */
 interface EmailMessage {
   to: string;
@@ -22,6 +21,5 @@ interface EmailSender extends Adapter<{
 }> {
   send(message: EmailMessage): Promise<void>;
 }
-//#endregion
 export { EmailMessage, EmailSender };
 //# sourceMappingURL=email-sender.d.mts.map

package/dist/adapter/metadata.d.mts

@@ -2,7 +2,6 @@ import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { Logger } from "../logger.mjs";
 import { ShelfConfig } from "../config.mjs";
-//#region src/adapters/metadata.d.ts
 /**
  * Adapter family — which concern an adapter supplies.
  *
@@ -77,6 +76,5 @@ interface Adapter<Extra extends object = Record<string, unknown>> {
    */
   setLogger?(logger: Logger): void;
 }
-//#endregion
 export { Adapter, AdapterCategory, AdapterHealth, AdapterLifecycle, AdapterMetadata, AdapterSetupContext };
 //# sourceMappingURL=metadata.d.mts.map

package/dist/adapter/oauth.d.mts

@@ -1,6 +1,5 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/adapters/oauth.d.ts
 /**
  * Service-neutral OAuth 2 contract for "connect your own account" flows. Any
  * adapter that talks to a third party on behalf of a user (design tools,
@@ -47,6 +46,5 @@ interface OAuthConnectable {
   /** Present only when the operator configured OAuth for the service. */
   readonly oauth?: OAuthClient;
 }
-//#endregion
 export { OAuthClient, OAuthConnectable, OAuthTokens };
 //# sourceMappingURL=oauth.d.mts.map

package/dist/adapter/setup.d.mts

@@ -10,7 +10,6 @@ import { AdapterSetupContext } from "./metadata.mjs";
 import { bindAdapterLoggers, collectSetups, collectTeardowns, runAdapterSetups, runAdapterTeardowns } from "../adapters/setup-runner.mjs";
 import { validateAdapter, validateAdapterSources, validateAuth, validateBootAssembly } from "../adapters/validate.mjs";
 import { adapterSourcesOf } from "../adapters/sources.mjs";
-//#region src/adapters/setup.d.ts
 /** Adapters that can take part in lifecycle runs. */
 interface AdapterSetupSources {
   database: DatabaseAdapter;
@@ -55,6 +54,5 @@ declare class AdapterLifecycleError extends Error {
   readonly failures: AdapterSetupFailure[];
   constructor(phase: LifecyclePhase, failures: AdapterSetupFailure[]);
 }
-//#endregion
 export { AdapterLifecycleError, AdapterSetupFailure, AdapterSetupResult, AdapterSetupSources, HookEntry, LifecyclePhase, adapterSourcesOf, bindAdapterLoggers, collectSetups, collectTeardowns, runAdapterSetups, runAdapterTeardowns, validateAdapter, validateAdapterSources, validateAuth, validateBootAssembly };
 //# sourceMappingURL=setup.d.mts.map

package/dist/adapter/setup.mjs

@@ -4,7 +4,7 @@ import.meta.url;
 import { bindAdapterLoggers, collectSetups, collectTeardowns, runAdapterSetups, runAdapterTeardowns } from "../adapters/setup-runner.mjs";
 import { validateAdapter, validateAdapterSources, validateAuth, validateBootAssembly } from "../adapters/validate.mjs";
 import { adapterSourcesOf } from "../adapters/sources.mjs";
-//#region src/adapters/setup.ts
+// src/adapters/setup.ts
 /**
 * Thrown when an `app.lifecycle.setup()` or `teardown()` run finishes with failures.
 *
@@ -24,7 +24,6 @@ var AdapterLifecycleError = class extends Error {
 		this.failures = failures;
 	}
 };
-//#endregion
 export { AdapterLifecycleError, adapterSourcesOf, bindAdapterLoggers, collectSetups, collectTeardowns, runAdapterSetups, runAdapterTeardowns, validateAdapter, validateAdapterSources, validateAuth, validateBootAssembly };
 
 //# sourceMappingURL=setup.mjs.map

package/dist/adapter/storage.d.mts

@@ -1,9 +1,8 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { Adapter } from "./metadata.mjs";
-import { Readable } from "node:stream";
 import { Buffer } from "node:buffer";
-//#region src/adapters/storage.d.ts
+import { Readable } from "node:stream";
 /** Blob storage abstraction for screenshots, diffs and Storybook archives. */
 interface StorageAdapter extends Adapter<{
   readonly category: "storage";
@@ -29,6 +28,5 @@ interface StorageAdapter extends Adapter<{
    */
   readStream(path: string): Promise<Readable>;
 }
-//#endregion
 export { StorageAdapter };
 //# sourceMappingURL=storage.d.mts.map

package/dist/adapter/webhook-events.d.mts

@@ -4,7 +4,6 @@ import { DatabaseAdapter } from "./database.mjs";
 import { SecretInput } from "../utils/encrypt.mjs";
 import { WebhookTables } from "../models/webhook.mjs";
 import { Logger } from "pino";
-//#region src/adapters/webhook-events.d.ts
 /**
  * Deliver an event to every subscribed webhook of a project.
  *
@@ -24,6 +23,5 @@ interface WebhookEvent {
   data: Record<string, unknown>;
   timestamp: string;
 }
-//#endregion
 export { WebhookEvent, emitWebhookEvent };
 //# sourceMappingURL=webhook-events.d.mts.map

package/dist/adapter/webhook-events.mjs

@@ -3,9 +3,8 @@ import "node:url";
 import.meta.url;
 import { hmacSha256 } from "../utils/hash.mjs";
 import { WebhookModel } from "../models/webhook.mjs";
-//#region src/adapters/webhook-events.ts
-/** Per-delivery budget: single attempt, no retries (events already fan out). */
-const WEBHOOK_TIMEOUT_MS = 1e4;
+import { httpStatus } from "../utils/http.mjs";
+// src/adapters/webhook-events.ts
 /**
 * Deliver an event to every subscribed webhook of a project.
 *
@@ -42,7 +41,7 @@ async function deliverToWebhook(webhookModel, webhook, eventPayload, logger) {
 		return;
 	}
 	try {
-		await sendWebhook(webhook.url, plaintext, eventPayload);
+		await sendWebhook(webhook.url, plaintext, eventPayload, logger);
 		logger?.info({
 			webhookId: webhook.id,
 			host: hostOf(webhook.url)
@@ -63,21 +62,21 @@ function hostOf(url) {
 		return "[invalid-url]";
 	}
 }
-async function sendWebhook(url, secret, event) {
-	const body = JSON.stringify(event);
-	const signature = hmacSha256(secret, body);
-	await fetch(url, {
+/**
+* POST one event through `httpStatus` (default timeout and retry policy). The signature covers the
+* exact body string, and `json` serializes the event with the same `JSON.stringify`.
+*/
+async function sendWebhook(url, secret, event, logger) {
+	await httpStatus(url, {
 		method: "POST",
+		json: event,
 		headers: {
-			"Content-Type": "application/json",
 			"X-StoryShelf-Event": event.event,
-			"X-StoryShelf-Signature": signature
+			"X-StoryShelf-Signature": hmacSha256(secret, JSON.stringify(event))
 		},
-		body,
-		signal: AbortSignal.timeout(WEBHOOK_TIMEOUT_MS)
+		...logger ? { logger } : {}
 	});
 }
-//#endregion
 export { emitWebhookEvent };
 
 //# sourceMappingURL=webhook-events.mjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"webhook-events.mjs","names":[],"sources":["../../src/adapters/webhook-events.ts"],"sourcesContent":["import type { Logger } from \"pino\";\nimport { WebhookModel, type WebhookTables } from \"../models/webhook.ts\";\nimport type { Webhook } from \"../schema/webhook.ts\";\nimport type { SecretInput } from \"../utils/encrypt.ts\";\nimport { hmacSha256 } from \"../utils/hash.ts\";\nimport type { DatabaseAdapter } from \"./database.ts\";\n\n/** Per-delivery budget: single attempt, no retries (events already fan out). */\nconst WEBHOOK_TIMEOUT_MS = 10_000;\n\n/**\n * Deliver an event to every subscribed webhook of a project.\n *\n * @param db - Database adapter for loading subscriptions.\n * @param tables - Webhook table handles.\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 * @param logger - Optional logger for per-delivery outcomes.\n */\nexport async function emitWebhookEvent(\n  db: DatabaseAdapter,\n  tables: WebhookTables,\n  projectId: string,\n  event: string,\n  data: Record<string, unknown>,\n  secret: SecretInput,\n  logger?: Logger,\n): Promise<void> {\n  const webhookModel = new WebhookModel(db, tables, 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      await deliverToWebhook(webhookModel, webhook, eventPayload, logger);\n    }),\n  );\n}\n\n/** Decrypt, send, and log one webhook delivery (failures stay non-fatal). */\nasync function deliverToWebhook(\n  webhookModel: WebhookModel,\n  webhook: Webhook,\n  eventPayload: WebhookEvent,\n  logger: Logger | undefined,\n): Promise<void> {\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    logger?.warn({ webhookId: webhook.id }, \"skipping webhook with undecryptable secret\");\n    return;\n  }\n  try {\n    await sendWebhook(webhook.url, plaintext, eventPayload);\n    logger?.info({ webhookId: webhook.id, host: hostOf(webhook.url) }, \"webhook delivered\");\n  } catch (error) {\n    // Webhook delivery failures are non-fatal\n    logger?.warn(\n      { webhookId: webhook.id, host: hostOf(webhook.url), err: error },\n      \"webhook delivery failed\",\n    );\n  }\n}\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\n/** Hostname of a webhook URL for logs (never the full URL — may carry secrets). */\nfunction hostOf(url: string): string {\n  try {\n    return new URL(url).host;\n  } catch {\n    return \"[invalid-url]\";\n  }\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    signal: AbortSignal.timeout(WEBHOOK_TIMEOUT_MS),\n  });\n}\n"],"mappings":";;;;;;;AAQA,MAAM,qBAAqB;;;;;;;;;;;;AAa3B,eAAsB,iBACpB,IACA,QACA,WACA,OACA,MACA,QACA,QACe;CACf,MAAM,eAAe,IAAI,aAAa,IAAI,QAAQ,MAAM;CACxD,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,MAAM,iBAAiB,cAAc,SAAS,cAAc,MAAM;CACpE,CAAC,CACH;AACF;;AAGA,eAAe,iBACb,cACA,SACA,cACA,QACe;CACf,IAAI;CACJ,IAAI;EACF,YAAY,aAAa,cAAc,OAAO;CAChD,QAAQ;EAEN,QAAQ,KAAK,EAAE,WAAW,QAAQ,GAAG,GAAG,4CAA4C;EACpF;CACF;CACA,IAAI;EACF,MAAM,YAAY,QAAQ,KAAK,WAAW,YAAY;EACtD,QAAQ,KAAK;GAAE,WAAW,QAAQ;GAAI,MAAM,OAAO,QAAQ,GAAG;EAAE,GAAG,mBAAmB;CACxF,SAAS,OAAO;EAEd,QAAQ,KACN;GAAE,WAAW,QAAQ;GAAI,MAAM,OAAO,QAAQ,GAAG;GAAG,KAAK;EAAM,GAC/D,yBACF;CACF;AACF;;AAWA,SAAS,OAAO,KAAqB;CACnC,IAAI;EACF,OAAO,IAAI,IAAI,GAAG,CAAC,CAAC;CACtB,QAAQ;EACN,OAAO;CACT;AACF;AAEA,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;EACA,QAAQ,YAAY,QAAQ,kBAAkB;CAChD,CAAC;AACH"}
+{"version":3,"file":"webhook-events.mjs","names":[],"sources":["../../src/adapters/webhook-events.ts"],"sourcesContent":["import type { Logger } from \"pino\";\nimport { WebhookModel, type WebhookTables } from \"../models/webhook.ts\";\nimport type { Webhook } from \"../schema/webhook.ts\";\nimport type { SecretInput } from \"../utils/encrypt.ts\";\nimport { hmacSha256 } from \"../utils/hash.ts\";\nimport { httpStatus } from \"../utils/http.ts\";\nimport type { DatabaseAdapter } from \"./database.ts\";\n\n/**\n * Deliver an event to every subscribed webhook of a project.\n *\n * @param db - Database adapter for loading subscriptions.\n * @param tables - Webhook table handles.\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 * @param logger - Optional logger for per-delivery outcomes.\n */\nexport async function emitWebhookEvent(\n  db: DatabaseAdapter,\n  tables: WebhookTables,\n  projectId: string,\n  event: string,\n  data: Record<string, unknown>,\n  secret: SecretInput,\n  logger?: Logger,\n): Promise<void> {\n  const webhookModel = new WebhookModel(db, tables, 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      await deliverToWebhook(webhookModel, webhook, eventPayload, logger);\n    }),\n  );\n}\n\n/** Decrypt, send, and log one webhook delivery (failures stay non-fatal). */\nasync function deliverToWebhook(\n  webhookModel: WebhookModel,\n  webhook: Webhook,\n  eventPayload: WebhookEvent,\n  logger: Logger | undefined,\n): Promise<void> {\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    logger?.warn({ webhookId: webhook.id }, \"skipping webhook with undecryptable secret\");\n    return;\n  }\n  try {\n    // A non-2xx answer throws HttpError, so only a delivery the subscriber accepted is \"delivered\".\n    await sendWebhook(webhook.url, plaintext, eventPayload, logger);\n    logger?.info({ webhookId: webhook.id, host: hostOf(webhook.url) }, \"webhook delivered\");\n  } catch (error) {\n    // Webhook delivery failures are non-fatal\n    logger?.warn(\n      { webhookId: webhook.id, host: hostOf(webhook.url), err: error },\n      \"webhook delivery failed\",\n    );\n  }\n}\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\n/** Hostname of a webhook URL for logs (never the full URL — may carry secrets). */\nfunction hostOf(url: string): string {\n  try {\n    return new URL(url).host;\n  } catch {\n    return \"[invalid-url]\";\n  }\n}\n\n/**\n * POST one event through `httpStatus` (default timeout and retry policy). The signature covers the\n * exact body string, and `json` serializes the event with the same `JSON.stringify`.\n */\nasync function sendWebhook(\n  url: string,\n  secret: string,\n  event: WebhookEvent,\n  logger: Logger | undefined,\n): Promise<void> {\n  await httpStatus(url, {\n    method: \"POST\",\n    json: event,\n    headers: {\n      \"X-StoryShelf-Event\": event.event,\n      \"X-StoryShelf-Signature\": hmacSha256(secret, JSON.stringify(event)),\n    },\n    ...(logger ? { logger } : {}),\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAmBA,eAAsB,iBACpB,IACA,QACA,WACA,OACA,MACA,QACA,QACe;CACf,MAAM,eAAe,IAAI,aAAa,IAAI,QAAQ,MAAM;CACxD,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,MAAM,iBAAiB,cAAc,SAAS,cAAc,MAAM;CACpE,CAAC,CACH;AACF;;AAGA,eAAe,iBACb,cACA,SACA,cACA,QACe;CACf,IAAI;CACJ,IAAI;EACF,YAAY,aAAa,cAAc,OAAO;CAChD,QAAQ;EAEN,QAAQ,KAAK,EAAE,WAAW,QAAQ,GAAG,GAAG,4CAA4C;EACpF;CACF;CACA,IAAI;EAEF,MAAM,YAAY,QAAQ,KAAK,WAAW,cAAc,MAAM;EAC9D,QAAQ,KAAK;GAAE,WAAW,QAAQ;GAAI,MAAM,OAAO,QAAQ,GAAG;EAAE,GAAG,mBAAmB;CACxF,SAAS,OAAO;EAEd,QAAQ,KACN;GAAE,WAAW,QAAQ;GAAI,MAAM,OAAO,QAAQ,GAAG;GAAG,KAAK;EAAM,GAC/D,yBACF;CACF;AACF;;AAWA,SAAS,OAAO,KAAqB;CACnC,IAAI;EACF,OAAO,IAAI,IAAI,GAAG,CAAC,CAAC;CACtB,QAAQ;EACN,OAAO;CACT;AACF;;;;;AAMA,eAAe,YACb,KACA,QACA,OACA,QACe;CACf,MAAM,WAAW,KAAK;EACpB,QAAQ;EACR,MAAM;EACN,SAAS;GACP,sBAAsB,MAAM;GAC5B,0BAA0B,WAAW,QAAQ,KAAK,UAAU,KAAK,CAAC;EACpE;EACA,GAAI,SAAS,EAAE,OAAO,IAAI,CAAC;CAC7B,CAAC;AACH"}

package/dist/adapters/capture-target-offers.d.mts

@@ -2,7 +2,6 @@ import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { CaptureTarget, RunnerTarget } from "./capture-target.mjs";
 import { AdapterLifecycle } from "../adapter/metadata.mjs";
-//#region src/adapters/capture-target-offers.d.ts
 /** A runner's live target list. */
 interface TargetOffers {
   /** First declared target: what a project with no `browsers` setting resolves to. */
@@ -23,6 +22,5 @@ interface TargetOffers {
  * without `lifecycle.setup` behaves as before and a failed launch still marks its target.
  */
 declare function createTargetOffers(declared: readonly RunnerTarget[]): TargetOffers;
-//#endregion
 export { TargetOffers, createTargetOffers };
 //# sourceMappingURL=capture-target-offers.d.mts.map

package/dist/adapters/capture-target-offers.mjs

@@ -2,7 +2,7 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { TargetLaunchError } from "./capture-target.mjs";
-//#region src/adapters/capture-target-offers.ts
+// src/adapters/capture-target-offers.ts
 /**
 * What a runner offers right now, shared by the runners (ADR 0007): the targets it declared, whether
 * each can render, and the lifecycle that keeps that honest. A launch failure marks its target
@@ -52,7 +52,6 @@ function createTargetOffers(declared) {
 		})
 	};
 }
-//#endregion
 export { createTargetOffers };
 
 //# sourceMappingURL=capture-target-offers.mjs.map

package/dist/adapters/capture-target.d.mts

@@ -1,6 +1,5 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-//#region src/adapters/capture-target.d.ts
 /**
  * Capture targets (ADR 0007, decision 3): what a project names to render on. A target is a rendering
  * engine (`chromium`) or a remote one, `<engine>@<name>` (`chromium@grid`), which has its own
@@ -66,6 +65,5 @@ declare class TargetLaunchError extends Error {
     transient?: boolean;
   });
 }
-//#endregion
 export { BROWSER_NAMES, BrowserName, CaptureTarget, DEFAULT_BROWSER, ParsedTarget, RunnerTarget, TARGET_NAME_PATTERN, TargetLaunchError, TargetReach, TargetStatus, engineOf, isBrowserName, isCaptureTarget, parseTarget, tryParseTarget, unavailableReason };
 //# sourceMappingURL=capture-target.d.mts.map

package/dist/adapters/capture-target.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/adapters/capture-target.ts
+// src/adapters/capture-target.ts
 /** Engine names accepted for capture rendering (Chromium default). */
 const BROWSER_NAMES = [
 	"chromium",
@@ -70,7 +70,6 @@ var TargetLaunchError = class extends Error {
 		this.transient = options?.transient ?? false;
 	}
 };
-//#endregion
 export { BROWSER_NAMES, DEFAULT_BROWSER, TARGET_NAME_PATTERN, TargetLaunchError, engineOf, isBrowserName, isCaptureTarget, parseTarget, tryParseTarget, unavailableReason };
 
 //# sourceMappingURL=capture-target.mjs.map

package/dist/adapters/notifier/build-comment.d.mts

@@ -1,7 +1,6 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { DesiredStatus } from "./build-state.mjs";
-//#region src/adapters/notifier/build-comment.d.ts
 /** Inputs of {@link buildCommentMarkdown}. */
 interface BuildCommentInput {
   buildUrl: string;
@@ -19,6 +18,5 @@ interface BuildCommentInput {
 }
 /** Comment body (below the idempotency marker): links to the build, the Storybook and a summary. */
 declare function buildCommentMarkdown(input: BuildCommentInput): string;
-//#endregion
 export { BuildCommentInput, buildCommentMarkdown };
 //# sourceMappingURL=build-comment.d.mts.map

package/dist/adapters/notifier/build-comment.mjs

@@ -1,7 +1,7 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-//#region src/adapters/notifier/build-comment.ts
+// src/adapters/notifier/build-comment.ts
 const LABEL = {
 	testing: "Visual tests",
 	review: "Review",
@@ -18,7 +18,6 @@ function buildCommentMarkdown(input) {
 	if (input.storybookUrl !== void 0) lines.push(`- Storybook: [Open the published Storybook](${input.storybookUrl})`);
 	return lines.join("\n");
 }
-//#endregion
 export { buildCommentMarkdown };
 
 //# sourceMappingURL=build-comment.mjs.map

package/dist/adapters/notifier/build-state.d.mts

@@ -2,7 +2,6 @@ import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
 import { NotifierState, StateAnnotation } from "./types.mjs";
 import { UrlBuilder } from "../../urls.mjs";
-//#region src/adapters/notifier/build-state.d.ts
 /** Most per-snapshot annotations a build state carries; the rest are counted (`omitted`). */
 declare const MAX_ANNOTATIONS = 200;
 /** Names of the statuses below a channel's prefix. */
@@ -94,6 +93,5 @@ interface BuildStateSet {
 }
 /** Statuses and comment for a build; empty without a real commit (no SHA or a local identity). */
 declare function statusesForBuild(input: BuildStateInput): BuildStateSet;
-//#endregion
 export { BuildStateBuild, BuildStateChange, BuildStateFlags, BuildStateInput, BuildStateSet, DesiredComment, DesiredStatus, MAX_ANNOTATIONS, PublishingState, StatusName, statusesForBuild };
 //# sourceMappingURL=build-state.d.mts.map

package/dist/adapters/notifier/build-state.mjs

@@ -3,7 +3,7 @@ import "node:url";
 import.meta.url;
 import { buildCommentMarkdown } from "./build-comment.mjs";
 import { LOCAL_SHA_PREFIX } from "@storyshelf/affected";
-//#region src/adapters/notifier/build-state.ts
+// src/adapters/notifier/build-state.ts
 /**
 * The states a build's git channels show, as one pure function of the build (ADR 0014, decision 5).
 * It reads no clock, database or provider: callers hand it the build, the channel's prefix and the
@@ -212,7 +212,6 @@ function approvedText(build) {
 function plural(count, noun) {
 	return `${String(count)} ${noun}${count === 1 ? "" : "s"}`;
 }
-//#endregion
 export { MAX_ANNOTATIONS, statusesForBuild };
 
 //# sourceMappingURL=build-state.mjs.map

package/dist/adapters/notifier/events.d.mts

@@ -3,7 +3,6 @@ import __tsdown_shims_url from 'node:url';
 import { Logger } from "../../logger.mjs";
 import { ChannelOutcome, NotificationBrand, NotificationChannel, NotificationEvent, SystemNotification } from "./types.mjs";
 import { NotifierProvider } from "./provider.mjs";
-//#region src/adapters/notifier/events.d.ts
 /** Options for project-event fan-out (inline best-effort, non-fatal). */
 interface EmitNotificationsOptions {
   notifiers?: NotifierProvider[];
@@ -23,6 +22,5 @@ declare function emitNotifications(event: NotificationEvent, options?: EmitNotif
  * (e.g. `sys:user-created`, `sys:capture-failed`, `sys:purge-completed`).
  */
 declare function emitSystemNotification(event: SystemNotification, options?: EmitNotificationsOptions): Promise<void>;
-//#endregion
 export { EmitNotificationsOptions, emitNotifications, emitSystemNotification };
 //# sourceMappingURL=events.d.mts.map

package/dist/adapters/notifier/events.mjs

@@ -4,7 +4,7 @@ import.meta.url;
 import { sanitizeErrorText } from "../../utils/redact.mjs";
 import { formatNotification, formatSystemNotification } from "./format.mjs";
 import { isStateProvider } from "./provider.mjs";
-//#region src/adapters/notifier/events.ts
+// src/adapters/notifier/events.ts
 /** Check an event against a channel's allowlist (empty = all). */
 function subscribed(channel, event) {
 	if (!channel.enabled) return false;
@@ -73,7 +73,6 @@ async function emitSystemNotification(event, options = {}) {
 		await deliverReported(options, channel, formatted, "system notification failed");
 	}));
 }
-//#endregion
 export { emitNotifications, emitSystemNotification };
 
 //# sourceMappingURL=events.mjs.map