@storyshelf/core 0.1.2 → 0.3.1

package/README.md

@@ -20,12 +20,12 @@ npm install @storyshelf/core
 import { createShelfRouter } from "@storyshelf/core";
 
 const app = createShelfRouter({
-  database,                 // DatabaseAdapter
-  storage,                  // StorageAdapter
-  captureRunner,            // CaptureRunner (optional)
-  auth,                    // AuthAdapter (optional)
-  gitHosts,                // GitHostProvider[] (optional)
-  logger,                  // pino Logger (optional; built internally if omitted)
+  database, // DatabaseAdapter
+  storage, // StorageAdapter
+  captureRunner, // CaptureRunner (optional)
+  auth, // AuthAdapter (optional)
+  gitHosts, // GitHostProvider[] (optional)
+  logger, // pino Logger (optional; built internally if omitted)
   ui: { name: "My Shelf" }, // UIConfig (optional)
   config: { captureConcurrency: 2, purgeTtlDays: 30 }, // ShelfConfig (optional)
 });
@@ -40,27 +40,30 @@ serve({ fetch: app.fetch, port: 3000 });
 
 Assembles the router from the provided adapters. `ShelfOptions`:
 
-| Option | Type | Description |
-| ------ | ---- | ----------- |
-| `database` | `DatabaseAdapter` | **Required.** Data access. |
-| `storage` | `StorageAdapter` | **Required.** Blob storage for screenshots, diffs, storybook archives. |
-| `captureRunner` | `CaptureRunner` | Optional. Enables the async capture pipeline (pure renderer). |
-| `captureQueue` | `CaptureQueue` | Optional. Queue adapter; defaults to `InMemoryCaptureQueue`. |
-| `auth` | `AuthAdapter` | Optional. Enables auth and the login UI. |
-| `gitHosts` | `GitHostProvider[]` | Optional. Git-host adapters (GitHub/GitLab) for status checks, merge gates, PR comments. |
-| `logger` | `Logger` (pino) | Optional. Shared logger. Construct a fallback via `createShelfLogger()`. |
-| `ui` | `UIConfig` | Optional. UI branding. |
-| `config` | `ShelfConfig` | Optional. Server behavior. |
+| Option          | Type                | Description                                                                              |
+| --------------- | ------------------- | ---------------------------------------------------------------------------------------- |
+| `database`      | `DatabaseAdapter`   | **Required.** Data access.                                                               |
+| `storage`       | `StorageAdapter`    | **Required.** Blob storage for screenshots, diffs, storybook archives.                   |
+| `captureRunner` | `CaptureRunner`     | Optional. Enables the async capture pipeline (pure renderer).                            |
+| `captureQueue`  | `CaptureQueue`      | Optional. Queue adapter; defaults to `InMemoryCaptureQueue`.                             |
+| `auth`          | `AuthAdapter`       | Optional. Enables auth and the login UI.                                                 |
+| `gitHosts`      | `GitHostProvider[]` | Optional. Git-host adapters (GitHub/GitLab) for status checks, merge gates, PR comments. |
+| `logger`        | `Logger` (pino)     | Optional. Shared logger. Construct a fallback via `createShelfLogger()`.                 |
+| `ui`            | `UIConfig`          | Optional. UI branding.                                                                   |
+| `config`        | `ShelfConfig`       | Optional. Server behavior.                                                               |
 
 ### `ShelfConfig`
 
 ```ts
 interface ShelfConfig {
-  secret?: string;              // session signing secret
+  secret?: string; // session signing secret
   publishedBaseDomain?: string; // for published storybook URLs
-  captureConcurrency?: number;  // concurrent capture jobs (default 2)
-  purgeTtlDays?: number;        // purge builds older than N days
-  viewports?: Viewport[];       // capture viewports
+  captureConcurrency?: number; // concurrent capture jobs (default 2)
+  scratchDir?: string; // capture working directory (required with captureRunner)
+  purgeTtlDays?: number; // purge builds older than N days
+  maxUploadBytes?: number; // single-zip upload cap (default 1 GiB)
+  maxInlineUnzipSize?: number; // inline statics extraction cap; unset = capture-only
+  viewports?: Viewport[]; // capture viewports
 }
 ```
 
@@ -78,33 +81,34 @@ interface UIConfig {
 
 ### Adapter interfaces
 
-All adapters are constructor-injected (no AsyncLocalStorage). See `docs/architecture.md` for the entity model and workflow.
+All adapters are constructor-injected (no AsyncLocalStorage). See `docs/architecture.md` for the entity model and workflow. Import each from its subpath — the barrel (`@storyshelf/core`) exports only the router and its types.
 
-- `DatabaseAdapter` — `insert`, `update`, `get`, `remove`, `list`, `count`, `all`, `migrate`, `close`. Also exports `ListOptions`.
-- `StorageAdapter` — `read`, `write`, `delete`, `exists`, `list(prefix)`.
-- `AuthAdapter` — `check(request)`, `createSession(user)`, `destroySession(sessionId)`, optional `handleCallback(callback)`. Also exports `AuthUser`, `AuthCallback`, and the shared `SESSION_COOKIE`.
-- `CaptureRunner` — a **pure capture renderer**: `render(input) => RenderResult`, `cancel(buildId)`. Also exports `JobStatus`, `RenderedSnapshot`, `RenderResult`.
-- `GitHostProvider` / `GitHostAdapter` — set commit status checks, detect merges, and upsert PR comments. Real providers ship in `@storyshelf/git-github` and `@storyshelf/git-gitlab`. Also exports `CheckStatus`.
+- `DatabaseAdapter` (`core/adapter/database`) — `insert`, `update`, `get`, `remove`, `list`, `count`, `all`, `migrate`, `close`. Also exports `ListOptions` and the `createDrizzleAdapter` factory.
+- `StorageAdapter` (`core/adapter/storage`) — `read`, `write`, `delete`, `exists`, `list(prefix)`.
+- `AuthAdapter` (`core/adapter/auth`) — `check(request)`, `createSession(user)`, `destroySession(sessionId)`, optional `handleCallback(callback)`. Also exports `AuthUser`, `AuthCallback`, and the shared `SESSION_COOKIE`.
+- `CaptureRunner` (`core/adapter/capture-runner`) — a **pure capture renderer**: `render(input) => RenderResult`, `cancel(buildId)`. Also exports `RenderedSnapshot`, `RenderResult`, `StoryEntry`, `StorySourceAdapter`, `Viewport`.
+- `CaptureQueue` (`core/adapter/capture-queue`) — `enqueue({ buildId, reqId? })`, plus `status`, `active`, `recent`. Also exports `CaptureJob`, `QueueEntry`, `JobStatus`.
+- `GitHostProvider` / `GitHostAdapter` (`core/adapter/git-host`) — set commit status checks, detect merges, and upsert PR comments. Real providers ship in `@storyshelf/git-github` and `@storyshelf/git-gitlab`. Also exports `CheckStatus`.
 
 ### Logging
 
-`core` uses **pino** for structured JSON logging. `createShelfLogger({ level, transports, env })` builds a logger writing to stdout by default, with optional extra pino worker transports (Sentry, PostHog, Datadog, GCP, OTEL collector, etc.). Pass the resulting `Logger` to `createShelfRouter({ logger })` (or construct it at your composition root) so request and background logs share one stream. The capture orchestrator derives a `reqId`-scoped child for background capture work, correlating each capture back to the triggering HTTP request. See ADR 0014.
+`core` uses **pino** for structured JSON logging. `createShelfLogger({ level, transports, env })` (from `core/logger`) builds a logger writing to stdout by default, with optional extra pino worker transports (Sentry, PostHog, Datadog, GCP, OTEL collector, etc.). Pass the resulting `Logger` to `createShelfRouter({ logger })` (or construct it at your composition root) so request and background logs share one stream. The capture orchestrator derives a `reqId`-scoped child for background capture work, correlating each capture back to the triggering HTTP request. See ADR 0014.
 
 ### Capture, diff, and retention
 
-- `executeCaptureJob({ buildId, reqId }, deps)` — the capture **orchestrator**: loads the build, marks it `capturing`, extracts the uploaded archive into `scratchDir`, discovers stories, delegates rendering to a pure `CaptureRunner`, and persists. `createShelfRouter` wires it into a `CaptureQueue` when `capture` is supplied (and requires `ShelfConfig.scratchDir`). Also exports `CaptureJobOptions`.
-- `persistCapture(ctx: CaptureContext)` — writes screenshots, diffs against the branch baseline, creates snapshots, and finalizes a build from a pure renderer's `captures`. Also exports `CaptureContext` and the `StorySourceAdapter`/`StoryEntry`/`Viewport` types.
-- `StorybookAdapter` — reads a built Storybook's `index.json`/`stories.json`.
-- `diffImages(baseline: Buffer, current: Buffer, options: DiffOptions): DiffResult` — pixelmatch-based diff. Also exports `DiffOptions`, `DiffResult`.
-- `CaptureQueue` — the **capture queue adapter**: `enqueue({ buildId, reqId? })`, plus `status`, `active`, `recent`. `enqueue` returns once a build is queued (async, "queued"); the job runs in a worker. Default is `InMemoryCaptureQueue` (in-process, concurrency-limited, for long-lived hosts); supply a remote queue with a separate worker for serverless. Also exports `CaptureJob`, `QueueEntry`, `JobStatus`.
-- `Retention` — `new Retention(db, storage, logger?)`, with `purge(project, { ttlDays, keepLatestPerBranch })`.
+Import from `core/capture`, `core/diff`, and the model entries — never from the barrel:
+
+- `executeCaptureJob({ buildId, reqId }, deps)` (`core/capture`) — the capture **orchestrator**: loads the build, marks it `capturing`, extracts the uploaded archive into `scratchDir`, discovers stories, delegates rendering to a pure `CaptureRunner`, and persists. `createShelfRouter` wires it into a `CaptureQueue` when `capture` is supplied (and requires `ShelfConfig.scratchDir`). Also exports `CaptureJobOptions`.
+- `persistCapture(ctx: CaptureContext)` (`core/capture`) — writes screenshots, diffs against the branch baseline, creates snapshots, and finalizes a build from a pure renderer's `captures`. Also exports `CaptureContext`.
+- `StorybookAdapter` (`core/capture`) — reads a built Storybook's `index.json`/`stories.json`.
+- `InMemoryCaptureQueue` (`core/capture`) — in-process, concurrency-limited queue for long-lived hosts; supply a remote queue with a separate worker for serverless.
+- `diffImages(baseline: Buffer, current: Buffer, options: DiffOptions): DiffResult` (`core/diff`) — pixelmatch-based diff. Also exports `DiffOptions`, `DiffResult`.
+- Models, schema, and row types back every entity; retention runs inside the router. (Models are private implementation details with no public entry — reach row types via `core/schema`.)
 
 ### Helpers
 
-- `createUrlBuilder(baseUrl, publishedBaseDomain?)` — type-safe URL builder. Also exports `UrlBuilder`.
-- `ulid`, `slugify`.
-- Path helpers: `screenshotPath`, `diffPath`, `baselinePath`, `storybookDir`, `storybookZipPath`.
-- `RenderedContent` type for the server-rendered UI.
+- `createUrlBuilder(baseUrl, publishedBaseDomain?)` (`core/urls`) — type-safe URL builder. Also exports `UrlBuilder`.
+- Path helpers (`core/paths`): `screenshotPath`, `diffPath`, `baselinePath`, `storybookDir`, `storybookZipPath`.
 
 ## How it fits in
 
@@ -116,13 +120,13 @@ See `docs/architecture.md` and the ADRs in `docs/adr/`.
 
 The core router is runtime-agnostic (Web `Request`/`Response`, `fetch`, `crypto`, `URL`). The only Node-specific piece is the in-process `InMemoryCaptureQueue`, which suits long-lived Node servers; serverless runtimes swap in a remote `CaptureQueue` (e.g. `@storyshelf/queue-sqs`) plus a separate worker. You assemble a server for any platform — `storyshelf server init` generates a scaffold with the adapters you choose:
 
-| Platform | Database | Storage | Capture queue | Server entry |
-|----------|----------|---------|---------------|--------------|
-| **Vercel** | `@storyshelf/db-turso` | `@storyshelf/storage-s3` (R2/S3) | Remote `CaptureQueue` + worker | Hono + `@hono/vercel-edge` |
-| **Cloudflare Workers** | `@storyshelf/db-turso` | `@storyshelf/storage-s3` (R2) | Workers Queues `CaptureQueue` | Hono + Workers entry |
-| **Azure Functions** | `@storyshelf/db-turso` | `@storyshelf/storage-s3` (Blob) | Azure Queues `CaptureQueue` | Hono + Azure handler |
-| **AWS Lambda** | `@storyshelf/db-turso` | `@storyshelf/storage-s3` | SQS `CaptureQueue` | Hono + Lambda handler |
-| **Deno Deploy** | `@storyshelf/db-turso` | `@storyshelf/storage-s3` | Custom `CaptureQueue` (Deno KV) | Hono + Deno entry |
-| **Bun / Node (VPS, Fly, Railway, Render)** | `db-sqlite` / `db-turso` | `storage-local` / `storage-s3` | `InMemoryCaptureQueue` | `storyshelf-server serve` |
+| Platform                                   | Database                 | Storage                          | Capture queue                   | Server entry               |
+| ------------------------------------------ | ------------------------ | -------------------------------- | ------------------------------- | -------------------------- |
+| **Vercel**                                 | `@storyshelf/db-turso`   | `@storyshelf/storage-s3` (R2/S3) | Remote `CaptureQueue` + worker  | Hono + `@hono/vercel-edge` |
+| **Cloudflare Workers**                     | `@storyshelf/db-turso`   | `@storyshelf/storage-s3` (R2)    | Workers Queues `CaptureQueue`   | Hono + Workers entry       |
+| **Azure Functions**                        | `@storyshelf/db-turso`   | `@storyshelf/storage-s3` (Blob)  | Azure Queues `CaptureQueue`     | Hono + Azure handler       |
+| **AWS Lambda**                             | `@storyshelf/db-turso`   | `@storyshelf/storage-s3`         | SQS `CaptureQueue`              | Hono + Lambda handler      |
+| **Deno Deploy**                            | `@storyshelf/db-turso`   | `@storyshelf/storage-s3`         | Custom `CaptureQueue` (Deno KV) | Hono + Deno entry          |
+| **Bun / Node (VPS, Fly, Railway, Render)** | `db-sqlite` / `db-turso` | `storage-local` / `storage-s3`   | `InMemoryCaptureQueue`          | `storyshelf-server serve`  |
 
 All clouds are equal — pick the adapters that match your infrastructure. See the **Deployment** guide for recipes including a minimal Turso + S3 + `InMemoryCaptureQueue` example.

package/dist/adapter/auth.d.mts

@@ -1,7 +1,7 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { AdapterMetadata } from "../adapters/metadata.mjs";
 import { ProjectRole, SiteRole } from "../types.mjs";
+import { Adapter } from "./metadata.mjs";
 //#region src/adapters/auth.d.ts
 /** Shared session cookie name used by all auth adapters (ADR 0008). */
 declare const SESSION_COOKIE = "storyshelf_session";
@@ -33,9 +33,9 @@ interface ProjectAccess {
   role: ProjectRole;
 }
 /** Pluggable authentication abstraction (ADR 0008). */
-interface AuthAdapter {
-  /** Adapter identity. */
-  readonly metadata?: AdapterMetadata;
+interface AuthAdapter extends Adapter<{
+  readonly category: "auth";
+}> {
   /** Resolve the current user from a request, or null if unauthenticated. */
   check(request: Request): Promise<AuthUser | null>;
   /** Create a session for a user and return a session token. */

package/dist/adapter/auth.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"auth.mjs","names":[],"sources":["../../src/adapters/auth.ts"],"sourcesContent":["import type { AdapterMetadata } from \"./metadata.ts\";\nimport type { ProjectRole, SiteRole } from \"../types.ts\";\n\n/** Shared session cookie name used by all auth adapters (ADR 0008). */\nexport const SESSION_COOKIE = \"storyshelf_session\";\n\n/** An authenticated user of the platform. */\nexport interface AuthUser {\n  /** User ID. */\n  id: string;\n  /** User email. */\n  email: string;\n  /** Display name. */\n  name: string;\n  /** Optional avatar URL. */\n  avatarUrl?: string;\n  /** Site-wide role. */\n  role: SiteRole;\n}\n\n/** Data passed to an auth adapter when an OAuth callback is received. */\nexport interface AuthCallback {\n  /** Provider name. */\n  provider: string;\n  /** Authorization code from the provider. */\n  code: string;\n  /** Anti-CSRF state value. */\n  state: string;\n}\n\n/** Access controls granted to a user for a specific project. */\nexport interface ProjectAccess {\n  /** Project role. */\n  role: ProjectRole;\n}\n\n/** Pluggable authentication abstraction (ADR 0008). */\nexport interface AuthAdapter {\n  /** Adapter identity. */\n  readonly metadata?: AdapterMetadata;\n  /** Resolve the current user from a request, or null if unauthenticated. */\n  check(request: Request): Promise<AuthUser | null>;\n  /** Create a session for a user and return a session token. */\n  createSession(user: AuthUser): Promise<string>;\n  /** Destroy a session by its id. */\n  destroySession(sessionId: string): Promise<void>;\n  /** Handle an OAuth callback and return the resolved user, if supported. */\n  handleCallback?(callback: AuthCallback): Promise<AuthUser | null>;\n}\n"],"mappings":";;;;;AAIA,MAAa,iBAAiB"}
+{"version":3,"file":"auth.mjs","names":[],"sources":["../../src/adapters/auth.ts"],"sourcesContent":["import type { ProjectRole, SiteRole } from \"../types.ts\";\n/**\n * Auth adapter interface: authenticate users and resolve project access.\n */\nimport type { Adapter } from \"./metadata.ts\";\n\n/** Shared session cookie name used by all auth adapters (ADR 0008). */\nexport const SESSION_COOKIE = \"storyshelf_session\";\n\n/** An authenticated user of the platform. */\nexport interface AuthUser {\n  /** User ID. */\n  id: string;\n  /** User email. */\n  email: string;\n  /** Display name. */\n  name: string;\n  /** Optional avatar URL. */\n  avatarUrl?: string;\n  /** Site-wide role. */\n  role: SiteRole;\n}\n\n/** Data passed to an auth adapter when an OAuth callback is received. */\nexport interface AuthCallback {\n  /** Provider name. */\n  provider: string;\n  /** Authorization code from the provider. */\n  code: string;\n  /** Anti-CSRF state value. */\n  state: string;\n}\n\n/** Access controls granted to a user for a specific project. */\nexport interface ProjectAccess {\n  /** Project role. */\n  role: ProjectRole;\n}\n\n/** Pluggable authentication abstraction (ADR 0008). */\nexport interface AuthAdapter extends Adapter<{ readonly category: \"auth\" }> {\n  /** Resolve the current user from a request, or null if unauthenticated. */\n  check(request: Request): Promise<AuthUser | null>;\n  /** Create a session for a user and return a session token. */\n  createSession(user: AuthUser): Promise<string>;\n  /** Destroy a session by its id. */\n  destroySession(sessionId: string): Promise<void>;\n  /** Handle an OAuth callback and return the resolved user, if supported. */\n  handleCallback?(callback: AuthCallback): Promise<AuthUser | null>;\n}\n"],"mappings":";;;;;AAOA,MAAa,iBAAiB"}

package/dist/{adapters → adapter}/capture-queue.d.mts

@@ -1,8 +1,10 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { AdapterMetadata } from "./metadata.mjs";
+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. */
 interface QueueEntry {
   buildId: string;
   status: JobStatus;
@@ -32,9 +34,9 @@ interface CaptureJob {
  *
  * `status`/`active`/`recent` back the live queue view regardless of transport.
  */
-interface CaptureQueue {
-  /** Adapter identity. */
-  readonly metadata?: AdapterMetadata;
+interface CaptureQueue extends Adapter<{
+  readonly category: "capture-queue";
+}> {
   /** Submit a build for capture. Resolves once the build is queued. */
   enqueue(job: CaptureJob): Promise<void>;
   /** Return the current status entry for a build, or null if untracked. */

package/dist/adapter/capture-queue.mjs

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

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

@@ -1,8 +1,8 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { AdapterMetadata } from "../adapters/metadata.mjs";
-import { StoryEntry, Viewport } from "../capture/adapter.mjs";
-import { JobStatus } from "../adapters/capture-queue.mjs";
+import { JobStatus } from "./capture-queue.mjs";
+import { StoryEntry, StorySourceAdapter, Viewport } from "../capture/adapter.mjs";
+import { Adapter } from "./metadata.mjs";
 import { Logger } from "pino";
 //#region src/adapters/capture-runner.d.ts
 /** A screenshot produced by a capture renderer. */
@@ -41,9 +41,9 @@ interface RenderResult {
  * orchestrator's job (see `capture/orchestrator.ts`), keeping every adapter
  * implementation free of server concerns.
  */
-interface CaptureRunner {
-  /** Adapter identity. */
-  readonly metadata?: AdapterMetadata;
+interface CaptureRunner extends Adapter<{
+  readonly category: "capture-runner";
+}> {
   /**
    * Render configured viewports for the given stories of an extracted
    * Storybook and return the screenshot buffers.
@@ -70,5 +70,5 @@ interface CaptureRunner {
   cancel(buildId: string): Promise<void>;
 }
 //#endregion
-export { CaptureRunner, type JobStatus, RenderFailure, RenderResult, RenderedSnapshot };
+export { CaptureRunner, type JobStatus, RenderFailure, RenderResult, RenderedSnapshot, type StoryEntry, type StorySourceAdapter, type Viewport };
 //# sourceMappingURL=capture-runner.d.mts.map

package/dist/adapter/database.d.mts

@@ -1,6 +1,6 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { AdapterMetadata } from "../adapters/metadata.mjs";
+import { Adapter, AdapterMetadata } from "./metadata.mjs";
 import { SQL } from "drizzle-orm";
 import { AnySQLiteTable } from "drizzle-orm/sqlite-core";
 //#region src/adapters/database.d.ts
@@ -16,9 +16,9 @@ interface ListOptions {
   offset?: number;
 }
 /** Database abstraction over Drizzle tables, agnostic of the underlying driver. */
-interface DatabaseAdapter {
-  /** Adapter identity. */
-  readonly metadata?: AdapterMetadata;
+interface DatabaseAdapter extends Adapter<{
+  readonly category: "database";
+}> {
   /** Insert a row and return the inserted record. */
   insert<T extends AnySQLiteTable>(table: T, values: T["$inferInsert"]): Promise<T["$inferSelect"]>;
   /** Update a row by id and return the updated record. */
@@ -33,11 +33,22 @@ interface DatabaseAdapter {
   count(table: AnySQLiteTable, where?: SQL): Promise<number>;
   /** Run an arbitrary SQL query and return typed rows. */
   all<T>(query: SQL): Promise<T[]>;
-  /** Apply any pending schema migrations. */
-  migrate(): Promise<void>;
-  /** Close the underlying database connection. */
-  close(): Promise<void>;
 }
+/** Driver-supplied identity plus lifecycle hooks. */
+interface DrizzleAdapterOptions {
+  metadata: AdapterMetadata & {
+    readonly category: "database";
+  };
+  migrate: () => Promise<void> | void;
+  close: () => Promise<void> | void;
+}
+/**
+ * Build a {@link DatabaseAdapter} over any SQLite-compatible Drizzle
+ * dialect. Sync results (node:sqlite) and promises (libSQL) are both
+ * awaited, so drivers only supply connection setup, metadata, and the
+ * driver-specific migrate/close.
+ */
+declare function createDrizzleAdapter(db: unknown, options: DrizzleAdapterOptions): DatabaseAdapter;
 //#endregion
-export { DatabaseAdapter, ListOptions };
+export { DatabaseAdapter, DrizzleAdapterOptions, ListOptions, createDrizzleAdapter };
 //# sourceMappingURL=database.d.mts.map

package/dist/adapter/database.mjs

@@ -1,4 +1,63 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-export {};
+import { eq, getTableColumns } from "drizzle-orm";
+//#region src/adapters/database.ts
+function idOf(table) {
+	const id = getTableColumns(table)["id"];
+	if (!id) throw new Error("Table has no id column");
+	return id;
+}
+function applyListOptions(query, opts) {
+	let current = query;
+	if (opts.where) current = current.where(opts.where);
+	if (opts.orderBy) current = current.orderBy(opts.orderBy);
+	if (opts.limit !== void 0) current = current.limit(opts.limit);
+	if (opts.offset !== void 0) current = current.offset(opts.offset);
+	return current;
+}
+/**
+* Build the database lifecycle: migrations run in `init`, the connection
+* closes in `close`. Close tolerates repeated calls (drivers may not).
+*/
+function buildLifecycle(options) {
+	let closed = false;
+	return {
+		init: async () => {
+			await options.migrate();
+		},
+		close: async () => {
+			if (closed) return;
+			closed = true;
+			await options.close();
+		}
+	};
+}
+/**
+* Build a {@link DatabaseAdapter} over any SQLite-compatible Drizzle
+* dialect. Sync results (node:sqlite) and promises (libSQL) are both
+* awaited, so drivers only supply connection setup, metadata, and the
+* driver-specific migrate/close.
+*/
+function createDrizzleAdapter(db, options) {
+	const drizzle = db;
+	return {
+		metadata: options.metadata,
+		lifecycle: buildLifecycle(options),
+		insert: async (table, values) => await drizzle.insert(table).values(values).returning().get(),
+		update: async (table, id, values) => await drizzle.update(table).set(values).where(eq(idOf(table), id)).returning().get(),
+		get: async (table, id) => await drizzle.select().from(table).where(eq(idOf(table), id)).limit(1).get() ?? null,
+		remove: async (table, id) => {
+			await drizzle.delete(table).where(eq(idOf(table), id)).run();
+		},
+		list: async (table, opts = {}) => {
+			return await applyListOptions(drizzle.select().from(table), opts).all();
+		},
+		count: async (table, where) => await drizzle.$count(table, where),
+		all: async (query) => await drizzle.all(query)
+	};
+}
+//#endregion
+export { createDrizzleAdapter };
+
+//# sourceMappingURL=database.mjs.map

package/dist/adapter/database.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.mjs","names":[],"sources":["../../src/adapters/database.ts"],"sourcesContent":["/**\n * Database adapter interface: query builders over explicitly typed tables.\n */\nimport type { SQL } from \"drizzle-orm\";\nimport { eq, getTableColumns } from \"drizzle-orm\";\nimport type { AnySQLiteTable, SQLiteColumn } from \"drizzle-orm/sqlite-core\";\nimport type { Adapter, AdapterLifecycle, AdapterMetadata } from \"./metadata.ts\";\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/** Database abstraction over Drizzle tables, agnostic of the underlying driver. */\nexport interface DatabaseAdapter extends Adapter<{ readonly category: \"database\" }> {\n  /** Insert a row and return the inserted record. */\n  insert<T extends AnySQLiteTable>(table: T, values: T[\"$inferInsert\"]): Promise<T[\"$inferSelect\"]>;\n  /** Update a row by id and return the updated record. */\n  update<T extends AnySQLiteTable>(\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 AnySQLiteTable>(table: T, id: string): Promise<T[\"$inferSelect\"] | null>;\n  /** Delete a row by id. */\n  remove(table: AnySQLiteTable, id: string): Promise<void>;\n  /** List rows matching the given options. */\n  list<T extends AnySQLiteTable>(table: T, opts?: ListOptions): Promise<T[\"$inferSelect\"][]>;\n  /** Count rows matching an optional where condition. */\n  count(table: AnySQLiteTable, where?: SQL): Promise<number>;\n  /** Run an arbitrary SQL query and return typed rows. */\n  all<T>(query: SQL): Promise<T[]>;\n}\n\n/** A value or a promise of one (sync node:sqlite vs async libSQL drivers). */\ntype MaybePromise<T> = T | Promise<T>;\n\n/** Chainable select surface shared by the sync and async Drizzle dialects. */\ninterface DrizzleSelectChain {\n  where(where: SQL): DrizzleSelectChain;\n  orderBy(order: SQL): DrizzleSelectChain;\n  limit(n: number): DrizzleSelectChain;\n  offset(n: number): DrizzleSelectChain;\n  get(): MaybePromise<unknown>;\n  all(): MaybePromise<unknown[]>;\n}\n\n/**\n * Minimal Drizzle surface consumed by {@link createDrizzleAdapter}. Drivers\n * pass their dialect instance as `unknown`; the cast lives here, once, so\n * driver packages stay fully typed. Covered by the adapter contract tests.\n */\ninterface DrizzleLike {\n  insert(table: AnySQLiteTable): {\n    values(values: unknown): { returning(): { get(): MaybePromise<unknown> } };\n  };\n  update(table: AnySQLiteTable): {\n    set(values: unknown): { where(where: SQL): { returning(): { get(): MaybePromise<unknown> } } };\n  };\n  select(): { from(table: AnySQLiteTable): DrizzleSelectChain };\n  delete(table: AnySQLiteTable): { where(where: SQL): { run(): MaybePromise<unknown> } };\n  $count(table: AnySQLiteTable, where?: SQL): MaybePromise<number>;\n  all<T>(query: SQL): MaybePromise<T[]>;\n}\n\n/** Driver-supplied identity plus lifecycle hooks. */\nexport interface DrizzleAdapterOptions {\n  metadata: AdapterMetadata & { readonly category: \"database\" };\n  migrate: () => Promise<void> | void;\n  close: () => Promise<void> | void;\n}\n\nfunction idOf(table: AnySQLiteTable): SQLiteColumn {\n  const id = getTableColumns(table)[\"id\"];\n  if (!id) {\n    throw new Error(\"Table has no id column\");\n  }\n  return id;\n}\n\nfunction applyListOptions(query: DrizzleSelectChain, opts: ListOptions): DrizzleSelectChain {\n  let current = query;\n  if (opts.where) {\n    current = current.where(opts.where);\n  }\n  if (opts.orderBy) {\n    current = current.orderBy(opts.orderBy);\n  }\n  if (opts.limit !== undefined) {\n    current = current.limit(opts.limit);\n  }\n  if (opts.offset !== undefined) {\n    current = current.offset(opts.offset);\n  }\n  return current;\n}\n\n/**\n * Build the database lifecycle: migrations run in `init`, the connection\n * closes in `close`. Close tolerates repeated calls (drivers may not).\n */\nfunction buildLifecycle(options: DrizzleAdapterOptions): AdapterLifecycle {\n  let closed = false;\n  return {\n    init: async () => {\n      await options.migrate();\n    },\n    close: async () => {\n      if (closed) {\n        return;\n      }\n      closed = true;\n      await options.close();\n    },\n  };\n}\n\n/**\n * Build a {@link DatabaseAdapter} over any SQLite-compatible Drizzle\n * dialect. Sync results (node:sqlite) and promises (libSQL) are both\n * awaited, so drivers only supply connection setup, metadata, and the\n * driver-specific migrate/close.\n */\nexport function createDrizzleAdapter(db: unknown, options: DrizzleAdapterOptions): DatabaseAdapter {\n  const drizzle = db as DrizzleLike;\n  return {\n    metadata: options.metadata,\n    lifecycle: buildLifecycle(options),\n    insert: async <T extends AnySQLiteTable>(\n      table: T,\n      values: T[\"$inferInsert\"],\n    ): Promise<T[\"$inferSelect\"]> =>\n      (await drizzle.insert(table).values(values).returning().get()) as T[\"$inferSelect\"],\n    update: async <T extends AnySQLiteTable>(\n      table: T,\n      id: string,\n      values: Partial<T[\"$inferInsert\"]>,\n    ): Promise<T[\"$inferSelect\"]> =>\n      (await drizzle\n        .update(table)\n        .set(values)\n        .where(eq(idOf(table), id))\n        .returning()\n        .get()) as T[\"$inferSelect\"],\n    get: async <T extends AnySQLiteTable>(\n      table: T,\n      id: string,\n    ): Promise<T[\"$inferSelect\"] | null> =>\n      ((await drizzle\n        .select()\n        .from(table)\n        .where(eq(idOf(table), id))\n        .limit(1)\n        .get()) as T[\"$inferSelect\"] | undefined) ?? null,\n    remove: async (table: AnySQLiteTable, id: string): Promise<void> => {\n      await drizzle\n        .delete(table)\n        .where(eq(idOf(table), id))\n        .run();\n    },\n    list: async <T extends AnySQLiteTable>(\n      table: T,\n      opts: ListOptions = {},\n    ): Promise<T[\"$inferSelect\"][]> => {\n      const query = applyListOptions(drizzle.select().from(table), opts);\n      const rows: unknown = await query.all();\n      return rows as T[\"$inferSelect\"][];\n    },\n    count: async (table: AnySQLiteTable, where?: SQL): Promise<number> =>\n      await drizzle.$count(table, where),\n    all: async <T>(query: SQL): Promise<T[]> => await drizzle.all(query),\n  };\n}\n"],"mappings":";;;;;AAgFA,SAAS,KAAK,OAAqC;CACjD,MAAM,KAAK,gBAAgB,KAAK,CAAC,CAAC;CAClC,IAAI,CAAC,IACH,MAAM,IAAI,MAAM,wBAAwB;CAE1C,OAAO;AACT;AAEA,SAAS,iBAAiB,OAA2B,MAAuC;CAC1F,IAAI,UAAU;CACd,IAAI,KAAK,OACP,UAAU,QAAQ,MAAM,KAAK,KAAK;CAEpC,IAAI,KAAK,SACP,UAAU,QAAQ,QAAQ,KAAK,OAAO;CAExC,IAAI,KAAK,UAAU,KAAA,GACjB,UAAU,QAAQ,MAAM,KAAK,KAAK;CAEpC,IAAI,KAAK,WAAW,KAAA,GAClB,UAAU,QAAQ,OAAO,KAAK,MAAM;CAEtC,OAAO;AACT;;;;;AAMA,SAAS,eAAe,SAAkD;CACxE,IAAI,SAAS;CACb,OAAO;EACL,MAAM,YAAY;GAChB,MAAM,QAAQ,QAAQ;EACxB;EACA,OAAO,YAAY;GACjB,IAAI,QACF;GAEF,SAAS;GACT,MAAM,QAAQ,MAAM;EACtB;CACF;AACF;;;;;;;AAQA,SAAgB,qBAAqB,IAAa,SAAiD;CACjG,MAAM,UAAU;CAChB,OAAO;EACL,UAAU,QAAQ;EAClB,WAAW,eAAe,OAAO;EACjC,QAAQ,OACN,OACA,WAEC,MAAM,QAAQ,OAAO,KAAK,CAAC,CAAC,OAAO,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI;EAC9D,QAAQ,OACN,OACA,IACA,WAEC,MAAM,QACJ,OAAO,KAAK,CAAC,CACb,IAAI,MAAM,CAAC,CACX,MAAM,GAAG,KAAK,KAAK,GAAG,EAAE,CAAC,CAAC,CAC1B,UAAU,CAAC,CACX,IAAI;EACT,KAAK,OACH,OACA,OAEE,MAAM,QACL,OAAO,CAAC,CACR,KAAK,KAAK,CAAC,CACX,MAAM,GAAG,KAAK,KAAK,GAAG,EAAE,CAAC,CAAC,CAC1B,MAAM,CAAC,CAAC,CACR,IAAI,KAAwC;EACjD,QAAQ,OAAO,OAAuB,OAA8B;GAClE,MAAM,QACH,OAAO,KAAK,CAAC,CACb,MAAM,GAAG,KAAK,KAAK,GAAG,EAAE,CAAC,CAAC,CAC1B,IAAI;EACT;EACA,MAAM,OACJ,OACA,OAAoB,CAAC,MACY;GAGjC,OAAO,MAFO,iBAAiB,QAAQ,OAAO,CAAC,CAAC,KAAK,KAAK,GAAG,IAC7B,CAAC,CAAC,IAAI;EAExC;EACA,OAAO,OAAO,OAAuB,UACnC,MAAM,QAAQ,OAAO,OAAO,KAAK;EACnC,KAAK,OAAU,UAA6B,MAAM,QAAQ,IAAI,KAAK;CACrE;AACF"}

package/dist/adapter/git-host/comments.d.mts

@@ -0,0 +1,41 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Logger } from "pino";
+//#region src/adapters/git-host/comments.d.ts
+/** A review thread (PR or MR) hosting a single StoryShelf comment. */
+interface ReviewThread {
+  /** List existing comments as id/body pairs. */
+  list(): Promise<{
+    id: string | number;
+    body: string;
+  }[]>;
+  /** Replace the body of an existing comment, returning its id. */
+  update(id: string | number, body: string): Promise<string>;
+  /** Create a comment, returning its id. */
+  create(body: string): Promise<string>;
+}
+/** Dependencies for an idempotent review-comment upsert. */
+interface UpsertReviewCommentOptions {
+  /** Canonical build/review URL — anchors the idempotency marker. */
+  url: string;
+  /** Markdown body appended below the marker. */
+  markdown: string;
+  /** Known thread number, skipping the lookup when provided. */
+  prNumber?: number;
+  /** Commit SHA used for the thread lookup and log context. */
+  sha: string;
+  logger?: Logger;
+  /** Resolve the thread number for the commit (PR number or MR iid). */
+  resolveNumber: () => Promise<number | undefined>;
+  /** Open the thread's comment store once the number is known. */
+  thread: (number: number) => ReviewThread;
+}
+/**
+ * Create or update the single StoryShelf review comment for a build,
+ * idempotent via the url marker. Returns the comment id, or `""` when no
+ * review thread exists for the commit.
+ */
+declare function upsertReviewComment(opts: UpsertReviewCommentOptions): Promise<string>;
+//#endregion
+export { ReviewThread, UpsertReviewCommentOptions, upsertReviewComment };
+//# sourceMappingURL=comments.d.mts.map

package/dist/adapter/git-host/comments.mjs

@@ -0,0 +1,54 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { commentMarker } from "./helpers.mjs";
+//#region src/adapters/git-host/comments.ts
+/** Resolve the thread number, preferring the explicit value. */
+async function resolveThreadNumber(opts) {
+	return opts.prNumber ?? await opts.resolveNumber();
+}
+/** Update the marked comment if present, else create it. */
+async function findOrCreateComment(thread, marker, body, prNumber, logger) {
+	const existing = (await thread.list()).find((comment) => comment.body.includes(marker));
+	if (existing) {
+		const id = await thread.update(existing.id, body);
+		logger?.info({
+			prNumber,
+			commentId: id
+		}, "review comment updated");
+		return id;
+	}
+	const id = await thread.create(body);
+	logger?.info({
+		prNumber,
+		commentId: id
+	}, "review comment created");
+	return id;
+}
+/**
+* Create or update the single StoryShelf review comment for a build,
+* idempotent via the url marker. Returns the comment id, or `""` when no
+* review thread exists for the commit.
+*/
+async function upsertReviewComment(opts) {
+	const marker = commentMarker(opts.url);
+	const body = `${marker}\n${opts.markdown}`;
+	const number = await resolveThreadNumber(opts);
+	if (number === void 0) {
+		opts.logger?.debug({ sha: opts.sha }, "no review thread found for comment, skipping");
+		return "";
+	}
+	try {
+		return await findOrCreateComment(opts.thread(number), marker, body, number, opts.logger);
+	} catch (error) {
+		opts.logger?.error({
+			err: error,
+			prNumber: number
+		}, "failed to upsert review comment");
+		throw error;
+	}
+}
+//#endregion
+export { upsertReviewComment };
+
+//# sourceMappingURL=comments.mjs.map

package/dist/adapter/git-host/comments.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"comments.mjs","names":[],"sources":["../../../src/adapters/git-host/comments.ts"],"sourcesContent":["import type { Logger } from \"pino\";\nimport { commentMarker } from \"./helpers.ts\";\n\n/** A review thread (PR or MR) hosting a single StoryShelf comment. */\nexport interface ReviewThread {\n  /** List existing comments as id/body pairs. */\n  list(): Promise<{ id: string | number; body: string }[]>;\n  /** Replace the body of an existing comment, returning its id. */\n  update(id: string | number, body: string): Promise<string>;\n  /** Create a comment, returning its id. */\n  create(body: string): Promise<string>;\n}\n\n/** Dependencies for an idempotent review-comment upsert. */\nexport interface UpsertReviewCommentOptions {\n  /** Canonical build/review URL — anchors the idempotency marker. */\n  url: string;\n  /** Markdown body appended below the marker. */\n  markdown: string;\n  /** Known thread number, skipping the lookup when provided. */\n  prNumber?: number;\n  /** Commit SHA used for the thread lookup and log context. */\n  sha: string;\n  logger?: Logger;\n  /** Resolve the thread number for the commit (PR number or MR iid). */\n  resolveNumber: () => Promise<number | undefined>;\n  /** Open the thread's comment store once the number is known. */\n  thread: (number: number) => ReviewThread;\n}\n\n/** Resolve the thread number, preferring the explicit value. */\nasync function resolveThreadNumber(opts: UpsertReviewCommentOptions): Promise<number | undefined> {\n  return opts.prNumber ?? (await opts.resolveNumber());\n}\n\n/** Update the marked comment if present, else create it. */\nasync function findOrCreateComment(\n  thread: ReviewThread,\n  marker: string,\n  body: string,\n  prNumber: number,\n  logger?: Logger,\n): Promise<string> {\n  const existing = (await thread.list()).find((comment) => comment.body.includes(marker));\n  if (existing) {\n    const id = await thread.update(existing.id, body);\n    logger?.info({ prNumber, commentId: id }, \"review comment updated\");\n    return id;\n  }\n  const id = await thread.create(body);\n  logger?.info({ prNumber, commentId: id }, \"review comment created\");\n  return id;\n}\n\n/**\n * Create or update the single StoryShelf review comment for a build,\n * idempotent via the url marker. Returns the comment id, or `\"\"` when no\n * review thread exists for the commit.\n */\nexport async function upsertReviewComment(opts: UpsertReviewCommentOptions): Promise<string> {\n  const marker = commentMarker(opts.url);\n  const body = `${marker}\\n${opts.markdown}`;\n  const number = await resolveThreadNumber(opts);\n  if (number === undefined) {\n    opts.logger?.debug({ sha: opts.sha }, \"no review thread found for comment, skipping\");\n    return \"\";\n  }\n  try {\n    return await findOrCreateComment(opts.thread(number), marker, body, number, opts.logger);\n  } catch (error) {\n    opts.logger?.error({ err: error, prNumber: number }, \"failed to upsert review comment\");\n    throw error;\n  }\n}\n"],"mappings":";;;;;;AA+BA,eAAe,oBAAoB,MAA+D;CAChG,OAAO,KAAK,YAAa,MAAM,KAAK,cAAc;AACpD;;AAGA,eAAe,oBACb,QACA,QACA,MACA,UACA,QACiB;CACjB,MAAM,YAAY,MAAM,OAAO,KAAK,EAAA,CAAG,MAAM,YAAY,QAAQ,KAAK,SAAS,MAAM,CAAC;CACtF,IAAI,UAAU;EACZ,MAAM,KAAK,MAAM,OAAO,OAAO,SAAS,IAAI,IAAI;EAChD,QAAQ,KAAK;GAAE;GAAU,WAAW;EAAG,GAAG,wBAAwB;EAClE,OAAO;CACT;CACA,MAAM,KAAK,MAAM,OAAO,OAAO,IAAI;CACnC,QAAQ,KAAK;EAAE;EAAU,WAAW;CAAG,GAAG,wBAAwB;CAClE,OAAO;AACT;;;;;;AAOA,eAAsB,oBAAoB,MAAmD;CAC3F,MAAM,SAAS,cAAc,KAAK,GAAG;CACrC,MAAM,OAAO,GAAG,OAAO,IAAI,KAAK;CAChC,MAAM,SAAS,MAAM,oBAAoB,IAAI;CAC7C,IAAI,WAAW,KAAA,GAAW;EACxB,KAAK,QAAQ,MAAM,EAAE,KAAK,KAAK,IAAI,GAAG,8CAA8C;EACpF,OAAO;CACT;CACA,IAAI;EACF,OAAO,MAAM,oBAAoB,KAAK,OAAO,MAAM,GAAG,QAAQ,MAAM,QAAQ,KAAK,MAAM;CACzF,SAAS,OAAO;EACd,KAAK,QAAQ,MAAM;GAAE,KAAK;GAAO,UAAU;EAAO,GAAG,iCAAiC;EACtF,MAAM;CACR;AACF"}

package/dist/adapter/git-host/helpers.d.mts

@@ -6,6 +6,7 @@ import { CheckStatus } from "../git-host.mjs";
 declare function describeStatus(status: CheckStatus): string;
 /** Markdown comment body helpers — single comment per build, idempotent via marker. */
 declare function commentMarker(url: string): string;
+/** Build the Markdown body for a StoryShelf status comment. */
 declare function buildCommentMarkdown(status: CheckStatus, url: string, context: string): string;
 //#endregion
 export { buildCommentMarkdown, commentMarker, describeStatus };

package/dist/adapter/git-host/helpers.mjs

@@ -15,6 +15,7 @@ function describeStatus(status) {
 function commentMarker(url) {
 	return `<!-- storyshelf:${url} -->`;
 }
+/** Build the Markdown body for a StoryShelf status comment. */
 function buildCommentMarkdown(status, url, context) {
 	switch (status) {
 		case "pending": return `Visual tests pending for \`${context}\` — [View build](${url})`;

package/dist/adapter/git-host/helpers.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.mjs","names":[],"sources":["../../../src/adapters/git-host/helpers.ts"],"sourcesContent":["import type { CheckStatus } from \"./index.ts\";\n\n/** Human description for a check status — shared across GitHub/GitLab. */\nexport function describeStatus(status: CheckStatus): string {\n  switch (status) {\n    case \"pending\": {\n      return \"Visual tests pending\";\n    }\n    case \"success\": {\n      return \"Visual tests passed\";\n    }\n    case \"failure\": {\n      return \"Visual changes detected or tests failed\";\n    }\n    default: {\n      return \"Visual changes detected or tests failed\";\n    }\n  }\n}\n\n/** Markdown comment body helpers — single comment per build, idempotent via marker. */\nexport function commentMarker(url: string): string {\n  return `<!-- storyshelf:${url} -->`;\n}\n\nexport function buildCommentMarkdown(status: CheckStatus, url: string, context: string): string {\n  switch (status) {\n    case \"pending\": {\n      return `Visual tests pending for \\`${context}\\` — [View build](${url})`;\n    }\n    case \"success\": {\n      return `Visual tests passed for \\`${context}\\` — [View build](${url})`;\n    }\n    case \"failure\": {\n      return `Visual changes detected for \\`${context}\\` — [View build](${url})`;\n    }\n    default: {\n      return `Visual tests for \\`${context}\\` — [View build](${url})`;\n    }\n  }\n}\n"],"mappings":";;;;;AAGA,SAAgB,eAAe,QAA6B;CAC1D,QAAQ,QAAR;EACE,KAAK,WACH,OAAO;EAET,KAAK,WACH,OAAO;EAET,KAAK,WACH,OAAO;EAET,SACE,OAAO;CAEX;AACF;;AAGA,SAAgB,cAAc,KAAqB;CACjD,OAAO,mBAAmB,IAAI;AAChC;AAEA,SAAgB,qBAAqB,QAAqB,KAAa,SAAyB;CAC9F,QAAQ,QAAR;EACE,KAAK,WACH,OAAO,8BAA8B,QAAQ,oBAAoB,IAAI;EAEvE,KAAK,WACH,OAAO,6BAA6B,QAAQ,oBAAoB,IAAI;EAEtE,KAAK,WACH,OAAO,iCAAiC,QAAQ,oBAAoB,IAAI;EAE1E,SACE,OAAO,sBAAsB,QAAQ,oBAAoB,IAAI;CAEjE;AACF"}
+{"version":3,"file":"helpers.mjs","names":[],"sources":["../../../src/adapters/git-host/helpers.ts"],"sourcesContent":["import type { CheckStatus } from \"./index.ts\";\n\n/** Human description for a check status — shared across GitHub/GitLab. */\nexport function describeStatus(status: CheckStatus): string {\n  switch (status) {\n    case \"pending\": {\n      return \"Visual tests pending\";\n    }\n    case \"success\": {\n      return \"Visual tests passed\";\n    }\n    case \"failure\": {\n      return \"Visual changes detected or tests failed\";\n    }\n    default: {\n      return \"Visual changes detected or tests failed\";\n    }\n  }\n}\n\n/** Markdown comment body helpers — single comment per build, idempotent via marker. */\nexport function commentMarker(url: string): string {\n  return `<!-- storyshelf:${url} -->`;\n}\n\n/** Build the Markdown body for a StoryShelf status comment. */\nexport function buildCommentMarkdown(status: CheckStatus, url: string, context: string): string {\n  switch (status) {\n    case \"pending\": {\n      return `Visual tests pending for \\`${context}\\` — [View build](${url})`;\n    }\n    case \"success\": {\n      return `Visual tests passed for \\`${context}\\` — [View build](${url})`;\n    }\n    case \"failure\": {\n      return `Visual changes detected for \\`${context}\\` — [View build](${url})`;\n    }\n    default: {\n      return `Visual tests for \\`${context}\\` — [View build](${url})`;\n    }\n  }\n}\n"],"mappings":";;;;;AAGA,SAAgB,eAAe,QAA6B;CAC1D,QAAQ,QAAR;EACE,KAAK,WACH,OAAO;EAET,KAAK,WACH,OAAO;EAET,KAAK,WACH,OAAO;EAET,SACE,OAAO;CAEX;AACF;;AAGA,SAAgB,cAAc,KAAqB;CACjD,OAAO,mBAAmB,IAAI;AAChC;;AAGA,SAAgB,qBAAqB,QAAqB,KAAa,SAAyB;CAC9F,QAAQ,QAAR;EACE,KAAK,WACH,OAAO,8BAA8B,QAAQ,oBAAoB,IAAI;EAEvE,KAAK,WACH,OAAO,6BAA6B,QAAQ,oBAAoB,IAAI;EAEtE,KAAK,WACH,OAAO,iCAAiC,QAAQ,oBAAoB,IAAI;EAE1E,SACE,OAAO,sBAAsB,QAAQ,oBAAoB,IAAI;CAEjE;AACF"}

package/dist/adapter/git-host.d.mts

@@ -1,14 +1,12 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { GitAdapterMetadata } from "../adapters/metadata.mjs";
+import { Adapter, GitAdapterMetadata } from "./metadata.mjs";
 import { Logger } from "pino";
 //#region src/adapters/git-host/index.d.ts
 /** Status of a git-host provider check. */
 type CheckStatus = "pending" | "success" | "failure";
 /** Descriptor — registered at startup, validates per-project config. */
-interface GitHostProvider {
-  /** Adapter identity (name, version, description, kind="github", logo, schema). */
-  readonly metadata: GitAdapterMetadata;
+interface GitHostProvider extends Adapter<GitAdapterMetadata> {
   /** Create a configured instance bound to a project config + decrypted token. */
   create(opts: {
     config: unknown;
@@ -17,9 +15,7 @@ interface GitHostProvider {
   }): GitHostAdapter;
 }
 /** Runtime — bound to a project config + token, posts statuses/comments. */
-interface GitHostAdapter {
-  /** Adapter identity. */
-  readonly metadata: GitAdapterMetadata;
+interface GitHostAdapter extends Adapter<GitAdapterMetadata> {
   /** Set the status of a commit. */
   setStatus(opts: {
     context: string;

package/dist/adapter/init.d.mts

@@ -0,0 +1,58 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { CaptureQueue } from "./capture-queue.mjs";
+import { CaptureRunner } from "./capture-runner.mjs";
+import { DatabaseAdapter } from "./database.mjs";
+import { GitHostProvider } from "./git-host.mjs";
+import { StorageAdapter } from "./storage.mjs";
+import { AdapterInitContext } from "./metadata.mjs";
+import { AuthAdapter } from "./auth.mjs";
+import { Logger } from "pino";
+//#region src/adapters/init.d.ts
+/** Adapters that can take part in lifecycle runs. */
+interface AdapterInitSources {
+  database: DatabaseAdapter;
+  storage: StorageAdapter;
+  captureRunner?: CaptureRunner;
+  captureQueue?: CaptureQueue;
+  auth?: AuthAdapter;
+  gitHosts?: GitHostProvider[];
+}
+/** One collected hook bound to its adapter identity. */
+interface HookEntry {
+  readonly category: string;
+  readonly kind: string;
+  readonly name: string;
+  readonly run: (ctx: AdapterInitContext) => Promise<void>;
+}
+/** One failed hook, with its adapter identity attached. */
+interface AdapterInitFailure {
+  readonly category: string;
+  readonly kind: string;
+  readonly name: string;
+  readonly error: string;
+}
+/** Settled outcome of a lifecycle run (never rejects — use `ok`). */
+interface AdapterInitResult {
+  readonly ok: boolean;
+  readonly failures: AdapterInitFailure[];
+}
+/** Lifecycle phase a run covers. */
+type LifecyclePhase = "init" | "close";
+/** Thrown when an `app.lifecycle.init()` or `close()` run has failures. */
+declare class AdapterLifecycleError extends Error {
+  readonly phase: LifecyclePhase;
+  readonly failures: AdapterInitFailure[];
+  constructor(phase: LifecyclePhase, failures: AdapterInitFailure[]);
+}
+/** Collect every available `init` hook in deterministic order. */
+declare function collectInits(sources: AdapterInitSources): HookEntry[];
+/** Collect every available `close` hook in deterministic order. */
+declare function collectCloses(sources: AdapterInitSources): HookEntry[];
+/** Run init hooks concurrently; failures are collected, never thrown. */
+declare function runAdapterInits(entries: HookEntry[], ctx: AdapterInitContext, logger: Logger): Promise<AdapterInitResult>;
+/** Run close hooks concurrently; failures are collected, never thrown. */
+declare function runAdapterCloses(entries: HookEntry[], ctx: AdapterInitContext, logger: Logger): Promise<AdapterInitResult>;
+//#endregion
+export { AdapterInitFailure, AdapterInitResult, AdapterInitSources, AdapterLifecycleError, HookEntry, LifecyclePhase, collectCloses, collectInits, runAdapterCloses, runAdapterInits };
+//# sourceMappingURL=init.d.mts.map