@storyshelf/core 0.6.1 → 0.7.0

package/dist/models/snapshot.mjs

@@ -1,14 +1,16 @@
 import "node:path";
 import "node:url";
 import.meta.url;
+import "../adapters/capture-target.mjs";
 import { ulid } from "../utils/ulid.mjs";
-import { eq, getTableColumns } from "drizzle-orm";
+import { col } from "./columns.mjs";
+import { and, eq, inArray } from "drizzle-orm";
 //#region src/models/snapshot.ts
 /** Snapshot records for captured stories within a build. */
 /** Data operations for snapshot records. */
 var SnapshotModel = class {
-	db;
 	tables;
+	db;
 	/**
 	* @param db - Database adapter.
 	* @param tables - Table handles.
@@ -35,22 +37,67 @@ var SnapshotModel = class {
 			storyName: input.storyName,
 			storyTitle: input.storyTitle,
 			storyImportPath: input.storyImportPath,
+			designUrl: input.designUrl ?? null,
 			viewportName: input.viewportName,
 			viewportWidth: input.viewportWidth,
 			viewportHeight: input.viewportHeight,
 			screenshotPath: input.screenshotPath,
 			infraHash: input.infraHash ?? null,
+			envChange: input.envChange ?? null,
 			inherited: input.inherited ?? false,
 			baselineId: input.baselineId ?? null,
 			baselineVersion: input.baselineVersion ?? null,
+			mode: input.mode ?? null,
+			browser: input.browser ?? "chromium",
+			durationMs: input.durationMs ?? null,
+			a11yViolations: input.a11yViolations ?? null,
 			status: "pending",
 			createdAt: now,
 			updatedAt: now
 		});
 	}
+	/**
+	* Delete the rendered snapshots a shard is about to write again: rows of `(story, engine)` pairs
+	* in `work`, so a rerun starts from a clean slate instead of colliding with rows an earlier,
+	* interrupted run left behind. Inherited rows are kept: the plan wrote them, for engines or
+	* viewports this shard does not render.
+	*/
+	async removeRendered(buildId, work) {
+		const doomed = (await this.listByBuild(buildId)).filter((row) => !row.inherited && work.some((engine) => engine.browser === (row.browser ?? "chromium") && engine.storyIds.has(row.storyId)));
+		await this.#removeAll(doomed);
+		return doomed.length;
+	}
+	/** Delete every snapshot of a build: a new plan of it starts clean. */
+	async removeForBuild(buildId) {
+		const doomed = await this.listByBuild(buildId);
+		await this.#removeAll(doomed);
+		return doomed.length;
+	}
+	async #removeAll(rows) {
+		await Promise.all(rows.map(async (row) => {
+			await this.db.remove(this.tables.snapshots, row.id);
+		}));
+	}
+	/**
+	* Milliseconds each story cost on one build, summed over its viewports and engines. Stories the
+	* renderer did not time are left out, so an empty map means this build carries no timings.
+	*/
+	async durationsByStory(buildId) {
+		const totals = /* @__PURE__ */ new Map();
+		for (const row of await this.listByBuild(buildId)) if (typeof row.durationMs === "number") totals.set(row.storyId, (totals.get(row.storyId) ?? 0) + row.durationMs);
+		return totals;
+	}
 	/** List all snapshots belonging to a build. */
 	async listByBuild(buildId) {
-		return await this.db.list(this.tables.snapshots, { where: eq(getTableColumns(this.tables.snapshots)["buildId"], buildId) });
+		return await this.db.list(this.tables.snapshots, { where: eq(col(this.tables.snapshots, "buildId"), buildId) });
+	}
+	/**
+	* Every snapshot of a story file across the project's builds. Index paths are
+	* stored raw (`./src/A.stories.tsx`), so both spellings of `importPath` match.
+	*/
+	async listByImportPath(projectId, importPath) {
+		const bare = importPath.replace(/^(?:\.\/)+/u, "");
+		return await this.db.list(this.tables.snapshots, { where: and(eq(col(this.tables.snapshots, "projectId"), projectId), inArray(col(this.tables.snapshots, "storyImportPath"), [bare, `./${bare}`])) });
 	}
 	/** Fetch a snapshot by id, or null if not found. */
 	async get(id) {

package/dist/models/snapshot.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot.mjs","names":[],"sources":["../../src/models/snapshot.ts"],"sourcesContent":["/** Snapshot records for captured stories within a build. */\nimport { eq, getTableColumns } from \"drizzle-orm\";\nimport type { SQLWrapper, Table } from \"drizzle-orm\";\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport type { Snapshot } from \"../schema/snapshot.ts\";\nimport type { SnapshotStatus } from \"../types.ts\";\nimport { ulid } from \"../utils/ulid.ts\";\n\n/** Tables required by {@link SnapshotModel}. */\nexport interface SnapshotTables {\n  snapshots: Table;\n}\n\n/** Data operations for snapshot records. */\nexport class SnapshotModel {\n  private readonly tables: SnapshotTables;\n  /**\n   * @param db - Database adapter.\n   * @param tables - Table handles.\n   */\n  constructor(\n    private readonly db: DatabaseAdapter,\n    tables?: SnapshotTables,\n  ) {\n    this.tables = tables ?? { snapshots: db.tables.snapshots };\n  }\n\n  /**\n   * Create a snapshot for a story within a build.\n   *\n   * @param projectId - Project ID.\n   * @param buildId - Build ID.\n   * @param input - Snapshot creation input.\n   * @returns The created snapshot.\n   */\n  async create(projectId: string, buildId: string, input: SnapshotCreateInput): Promise<Snapshot> {\n    const now = new Date().toISOString();\n    return (await this.db.insert(this.tables.snapshots, {\n      id: ulid(),\n      projectId,\n      buildId,\n      storyId: input.storyId,\n      storyName: input.storyName,\n      storyTitle: input.storyTitle,\n      storyImportPath: input.storyImportPath,\n      viewportName: input.viewportName,\n      viewportWidth: input.viewportWidth,\n      viewportHeight: input.viewportHeight,\n      screenshotPath: input.screenshotPath,\n      infraHash: input.infraHash ?? null,\n      inherited: input.inherited ?? false,\n      baselineId: input.baselineId ?? null,\n      baselineVersion: input.baselineVersion ?? null,\n      status: \"pending\",\n      createdAt: now,\n      updatedAt: now,\n    })) as unknown as Snapshot;\n  }\n\n  /** List all snapshots belonging to a build. */\n  async listByBuild(buildId: string): Promise<Snapshot[]> {\n    return (await this.db.list(this.tables.snapshots, {\n      where: eq(\n        getTableColumns(this.tables.snapshots)[\"buildId\"] as unknown as SQLWrapper,\n        buildId,\n      ),\n    })) as unknown as Snapshot[];\n  }\n\n  /** Fetch a snapshot by id, or null if not found. */\n  async get(id: string): Promise<Snapshot | null> {\n    return (await this.db.get(this.tables.snapshots, id)) as unknown as Snapshot | null;\n  }\n\n  /** Update mutable fields of a snapshot. */\n  async update(id: string, patch: Partial<Snapshot>): Promise<Snapshot> {\n    return (await this.db.update(this.tables.snapshots, id, {\n      ...patch,\n      updatedAt: new Date().toISOString(),\n    })) as unknown as Snapshot;\n  }\n\n  /** Set the status of a snapshot. */\n  async setStatus(id: string, status: SnapshotStatus): Promise<Snapshot> {\n    return await this.update(id, { status });\n  }\n\n  /** Record a reviewer's decision on a snapshot. */\n  async review(id: string, status: SnapshotStatus, userId: string | null): Promise<Snapshot> {\n    return await this.update(id, {\n      status,\n      reviewedBy: userId,\n      reviewedAt: new Date().toISOString(),\n    });\n  }\n}\n\n/** Input for creating a snapshot. */\nexport interface SnapshotCreateInput {\n  storyId: string;\n  storyName: string;\n  storyTitle: string;\n  storyImportPath?: string;\n  viewportName: string;\n  viewportWidth: number;\n  viewportHeight: number;\n  screenshotPath: string;\n  infraHash?: string | null;\n  inherited?: boolean;\n  baselineId?: string | null;\n  baselineVersion?: string | null;\n}\n"],"mappings":";;;;;;;;AAcA,IAAa,gBAAb,MAA2B;CAON;CANnB;;;;;CAKA,YACE,IACA,QACA;EAFiB,KAAA,KAAA;EAGjB,KAAK,SAAS,UAAU,EAAE,WAAW,GAAG,OAAO,UAAU;CAC3D;;;;;;;;;CAUA,MAAM,OAAO,WAAmB,SAAiB,OAA+C;EAC9F,MAAM,uBAAM,IAAI,KAAK,EAAA,CAAE,YAAY;EACnC,OAAQ,MAAM,KAAK,GAAG,OAAO,KAAK,OAAO,WAAW;GAClD,IAAI,KAAK;GACT;GACA;GACA,SAAS,MAAM;GACf,WAAW,MAAM;GACjB,YAAY,MAAM;GAClB,iBAAiB,MAAM;GACvB,cAAc,MAAM;GACpB,eAAe,MAAM;GACrB,gBAAgB,MAAM;GACtB,gBAAgB,MAAM;GACtB,WAAW,MAAM,aAAa;GAC9B,WAAW,MAAM,aAAa;GAC9B,YAAY,MAAM,cAAc;GAChC,iBAAiB,MAAM,mBAAmB;GAC1C,QAAQ;GACR,WAAW;GACX,WAAW;EACb,CAAC;CACH;;CAGA,MAAM,YAAY,SAAsC;EACtD,OAAQ,MAAM,KAAK,GAAG,KAAK,KAAK,OAAO,WAAW,EAChD,OAAO,GACL,gBAAgB,KAAK,OAAO,SAAS,CAAC,CAAC,YACvC,OACF,EACF,CAAC;CACH;;CAGA,MAAM,IAAI,IAAsC;EAC9C,OAAQ,MAAM,KAAK,GAAG,IAAI,KAAK,OAAO,WAAW,EAAE;CACrD;;CAGA,MAAM,OAAO,IAAY,OAA6C;EACpE,OAAQ,MAAM,KAAK,GAAG,OAAO,KAAK,OAAO,WAAW,IAAI;GACtD,GAAG;GACH,4BAAW,IAAI,KAAK,EAAA,CAAE,YAAY;EACpC,CAAC;CACH;;CAGA,MAAM,UAAU,IAAY,QAA2C;EACrE,OAAO,MAAM,KAAK,OAAO,IAAI,EAAE,OAAO,CAAC;CACzC;;CAGA,MAAM,OAAO,IAAY,QAAwB,QAA0C;EACzF,OAAO,MAAM,KAAK,OAAO,IAAI;GAC3B;GACA,YAAY;GACZ,6BAAY,IAAI,KAAK,EAAA,CAAE,YAAY;EACrC,CAAC;CACH;AACF"}
+{"version":3,"file":"snapshot.mjs","names":[],"sources":["../../src/models/snapshot.ts"],"sourcesContent":["/** Snapshot records for captured stories within a build. */\nimport { and, eq, inArray } from \"drizzle-orm\";\nimport type { Table } from \"drizzle-orm\";\nimport { DEFAULT_BROWSER } from \"../adapters/capture-runner.ts\";\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport type { Snapshot } from \"../schema/snapshot.ts\";\nimport type { SnapshotStatus } from \"../types.ts\";\nimport { ulid } from \"../utils/ulid.ts\";\nimport { col } from \"./columns.ts\";\n\n/** Tables required by {@link SnapshotModel}. */\nexport interface SnapshotTables {\n  snapshots: Table;\n}\n\n/** Data operations for snapshot records. */\nexport class SnapshotModel {\n  private readonly tables: SnapshotTables;\n  private readonly db: DatabaseAdapter;\n\n  /**\n   * @param db - Database adapter.\n   * @param tables - Table handles.\n   */\n  constructor(db: DatabaseAdapter, tables?: SnapshotTables) {\n    this.db = db;\n    this.tables = tables ?? { snapshots: db.tables.snapshots };\n  }\n\n  /**\n   * Create a snapshot for a story within a build.\n   *\n   * @param projectId - Project ID.\n   * @param buildId - Build ID.\n   * @param input - Snapshot creation input.\n   * @returns The created snapshot.\n   */\n  async create(projectId: string, buildId: string, input: SnapshotCreateInput): Promise<Snapshot> {\n    const now = new Date().toISOString();\n    return (await this.db.insert(this.tables.snapshots, {\n      id: ulid(),\n      projectId,\n      buildId,\n      storyId: input.storyId,\n      storyName: input.storyName,\n      storyTitle: input.storyTitle,\n      storyImportPath: input.storyImportPath,\n      designUrl: input.designUrl ?? null,\n      viewportName: input.viewportName,\n      viewportWidth: input.viewportWidth,\n      viewportHeight: input.viewportHeight,\n      screenshotPath: input.screenshotPath,\n      infraHash: input.infraHash ?? null,\n      envChange: input.envChange ?? null,\n      inherited: input.inherited ?? false,\n      baselineId: input.baselineId ?? null,\n      baselineVersion: input.baselineVersion ?? null,\n      mode: input.mode ?? null,\n      browser: input.browser ?? DEFAULT_BROWSER,\n      durationMs: input.durationMs ?? null,\n      a11yViolations: input.a11yViolations ?? null,\n      status: \"pending\",\n      createdAt: now,\n      updatedAt: now,\n    })) as unknown as Snapshot;\n  }\n\n  /**\n   * Delete the rendered snapshots a shard is about to write again: rows of `(story, engine)` pairs\n   * in `work`, so a rerun starts from a clean slate instead of colliding with rows an earlier,\n   * interrupted run left behind. Inherited rows are kept: the plan wrote them, for engines or\n   * viewports this shard does not render.\n   */\n  async removeRendered(\n    buildId: string,\n    work: readonly { browser: string; storyIds: ReadonlySet<string> }[],\n  ): Promise<number> {\n    const doomed = (await this.listByBuild(buildId)).filter(\n      (row) =>\n        !row.inherited &&\n        work.some(\n          (engine) =>\n            engine.browser === (row.browser ?? DEFAULT_BROWSER) && engine.storyIds.has(row.storyId),\n        ),\n    );\n    await this.#removeAll(doomed);\n    return doomed.length;\n  }\n\n  /** Delete every snapshot of a build: a new plan of it starts clean. */\n  async removeForBuild(buildId: string): Promise<number> {\n    const doomed = await this.listByBuild(buildId);\n    await this.#removeAll(doomed);\n    return doomed.length;\n  }\n\n  async #removeAll(rows: readonly Snapshot[]): Promise<void> {\n    await Promise.all(\n      rows.map(async (row) => {\n        await this.db.remove(this.tables.snapshots, row.id);\n      }),\n    );\n  }\n\n  /**\n   * Milliseconds each story cost on one build, summed over its viewports and engines. Stories the\n   * renderer did not time are left out, so an empty map means this build carries no timings.\n   */\n  async durationsByStory(buildId: string): Promise<Map<string, number>> {\n    const totals = new Map<string, number>();\n    for (const row of await this.listByBuild(buildId)) {\n      if (typeof row.durationMs === \"number\") {\n        totals.set(row.storyId, (totals.get(row.storyId) ?? 0) + row.durationMs);\n      }\n    }\n    return totals;\n  }\n\n  /** List all snapshots belonging to a build. */\n  async listByBuild(buildId: string): Promise<Snapshot[]> {\n    return (await this.db.list(this.tables.snapshots, {\n      where: eq(col(this.tables.snapshots, \"buildId\"), buildId),\n    })) as unknown as Snapshot[];\n  }\n\n  /**\n   * Every snapshot of a story file across the project's builds. Index paths are\n   * stored raw (`./src/A.stories.tsx`), so both spellings of `importPath` match.\n   */\n  async listByImportPath(projectId: string, importPath: string): Promise<Snapshot[]> {\n    const bare = importPath.replace(/^(?:\\.\\/)+/u, \"\");\n    return (await this.db.list(this.tables.snapshots, {\n      where: and(\n        eq(col(this.tables.snapshots, \"projectId\"), projectId),\n        inArray(col(this.tables.snapshots, \"storyImportPath\"), [bare, `./${bare}`]),\n      ),\n    })) as unknown as Snapshot[];\n  }\n\n  /** Fetch a snapshot by id, or null if not found. */\n  async get(id: string): Promise<Snapshot | null> {\n    return (await this.db.get(this.tables.snapshots, id)) as unknown as Snapshot | null;\n  }\n\n  /** Update mutable fields of a snapshot. */\n  async update(id: string, patch: Partial<Snapshot>): Promise<Snapshot> {\n    return (await this.db.update(this.tables.snapshots, id, {\n      ...patch,\n      updatedAt: new Date().toISOString(),\n    })) as unknown as Snapshot;\n  }\n\n  /** Set the status of a snapshot. */\n  async setStatus(id: string, status: SnapshotStatus): Promise<Snapshot> {\n    return await this.update(id, { status });\n  }\n\n  /** Record a reviewer's decision on a snapshot. */\n  async review(id: string, status: SnapshotStatus, userId: string | null): Promise<Snapshot> {\n    return await this.update(id, {\n      status,\n      reviewedBy: userId,\n      reviewedAt: new Date().toISOString(),\n    });\n  }\n}\n\n/** Input for creating a snapshot. */\nexport interface SnapshotCreateInput {\n  storyId: string;\n  storyName: string;\n  storyTitle: string;\n  storyImportPath?: string;\n  /** Figma URL declared by the story (`parameters.design` / `storyshelf.figma`). */\n  designUrl?: string | null;\n  viewportName: string;\n  viewportWidth: number;\n  viewportHeight: number;\n  screenshotPath: string;\n  infraHash?: string | null;\n  /** JSON `EnvironmentChange` when accepted as an environment migration. */\n  envChange?: string | null;\n  inherited?: boolean;\n  baselineId?: string | null;\n  baselineVersion?: string | null;\n  /** Resolved mode definition as JSON (display/capture only). */\n  mode?: string | null;\n  /** Engine the screenshot was captured with (default chromium). */\n  browser?: string;\n  /** Milliseconds the renderer spent on this capture, when it reported any. */\n  durationMs?: number | null;\n  /** JSON array of axe violation texts found on this capture; null when none. */\n  a11yViolations?: string | null;\n}\n"],"mappings":"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"}

package/dist/models/token.d.mts

@@ -10,8 +10,8 @@ interface TokenTables {
 }
 /** Data operations for CI tokens. */
 declare class TokenModel {
-  private readonly db;
   private readonly tables;
+  private readonly db;
   /**
    * @param db - Database adapter.
    * @param tables - Table handles.
@@ -30,6 +30,18 @@ declare class TokenModel {
     hash: string;
     userId?: string | null;
   }): Promise<Token>;
+  /**
+   * Mint a new `shelf_` token for a project and store only its hash.
+   *
+   * @returns The stored record and the plaintext value (shown to the user once).
+   */
+  issue(projectId: string, input: {
+    name: string;
+    userId?: string | null;
+  }): Promise<{
+    token: Token;
+    value: string;
+  }>;
   /** List all tokens for a project. */
   list(projectId: string): Promise<Token[]>;
   /** Fetch a token by id within a project, or null if not found. */

package/dist/models/token.mjs

@@ -1,14 +1,16 @@
 import "node:path";
 import "node:url";
 import.meta.url;
+import { randomToken } from "../utils/hash.mjs";
 import { ulid } from "../utils/ulid.mjs";
-import { and, eq, getTableColumns } from "drizzle-orm";
+import { col } from "./columns.mjs";
+import { and, eq } from "drizzle-orm";
 //#region src/models/token.ts
 /** CI tokens for project-scoped API access. */
 /** Data operations for CI tokens. */
 var TokenModel = class {
-	db;
 	tables;
+	db;
 	/**
 	* @param db - Database adapter.
 	* @param tables - Table handles.
@@ -35,21 +37,37 @@ var TokenModel = class {
 			createdAt: (/* @__PURE__ */ new Date()).toISOString()
 		});
 	}
+	/**
+	* Mint a new `shelf_` token for a project and store only its hash.
+	*
+	* @returns The stored record and the plaintext value (shown to the user once).
+	*/
+	async issue(projectId, input) {
+		const { value, hash } = randomToken("shelf_");
+		return {
+			token: await this.create(projectId, {
+				name: input.name,
+				hash,
+				userId: input.userId
+			}),
+			value
+		};
+	}
 	/** List all tokens for a project. */
 	async list(projectId) {
-		return await this.db.list(this.tables.tokens, { where: eq(getTableColumns(this.tables.tokens)["projectId"], projectId) });
+		return await this.db.list(this.tables.tokens, { where: eq(col(this.tables.tokens, "projectId"), projectId) });
 	}
 	/** Fetch a token by id within a project, or null if not found. */
 	async get(projectId, id) {
 		return (await this.db.list(this.tables.tokens, {
-			where: and(eq(getTableColumns(this.tables.tokens)["projectId"], projectId), eq(getTableColumns(this.tables.tokens)["id"], id)),
+			where: and(eq(col(this.tables.tokens, "projectId"), projectId), eq(col(this.tables.tokens, "id"), id)),
 			limit: 1
 		}))[0] ?? null;
 	}
 	/** Fetch a token by its hashed value, or null if not found. */
 	async findByHash(hash) {
 		return (await this.db.list(this.tables.tokens, {
-			where: eq(getTableColumns(this.tables.tokens)["hash"], hash),
+			where: eq(col(this.tables.tokens, "hash"), hash),
 			limit: 1
 		}))[0] ?? null;
 	}

package/dist/models/token.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"token.mjs","names":[],"sources":["../../src/models/token.ts"],"sourcesContent":["/** CI tokens for project-scoped API access. */\nimport { and, eq, getTableColumns } from \"drizzle-orm\";\nimport type { SQLWrapper, Table } from \"drizzle-orm\";\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport type { Token } from \"../schema/token.ts\";\nimport { ulid } from \"../utils/ulid.ts\";\n\n/** Tables required by {@link TokenModel}. */\nexport interface TokenTables {\n  tokens: Table;\n}\n\n/** Data operations for CI tokens. */\nexport class TokenModel {\n  private readonly tables: TokenTables;\n  /**\n   * @param db - Database adapter.\n   * @param tables - Table handles.\n   */\n  constructor(\n    private readonly db: DatabaseAdapter,\n    tables?: TokenTables,\n  ) {\n    this.tables = tables ?? { tokens: db.tables.tokens };\n  }\n\n  /**\n   * Create a token record storing its hash.\n   *\n   * @param projectId - Project ID.\n   * @param input - Token name, hash, and optional owning user ID (null for\n   * legacy/admin-token minting; such tokens resolve as viewer).\n   * @returns The created token.\n   */\n  async create(\n    projectId: string,\n    input: { name: string; hash: string; userId?: string | null },\n  ): Promise<Token> {\n    return (await this.db.insert(this.tables.tokens, {\n      id: ulid(),\n      projectId,\n      name: input.name,\n      hash: input.hash,\n      userId: input.userId ?? null,\n      createdAt: new Date().toISOString(),\n    })) as unknown as Token;\n  }\n\n  /** List all tokens for a project. */\n  async list(projectId: string): Promise<Token[]> {\n    return (await this.db.list(this.tables.tokens, {\n      where: eq(\n        getTableColumns(this.tables.tokens)[\"projectId\"] as unknown as SQLWrapper,\n        projectId,\n      ),\n    })) as unknown as Token[];\n  }\n\n  /** Fetch a token by id within a project, or null if not found. */\n  async get(projectId: string, id: string): Promise<Token | null> {\n    const rows = (await this.db.list(this.tables.tokens, {\n      where: and(\n        eq(getTableColumns(this.tables.tokens)[\"projectId\"] as unknown as SQLWrapper, projectId),\n        eq(getTableColumns(this.tables.tokens)[\"id\"] as unknown as SQLWrapper, id),\n      ),\n      limit: 1,\n    })) as unknown as Token[];\n    return rows[0] ?? null;\n  }\n\n  /** Fetch a token by its hashed value, or null if not found. */\n  async findByHash(hash: string): Promise<Token | null> {\n    const rows = (await this.db.list(this.tables.tokens, {\n      where: eq(getTableColumns(this.tables.tokens)[\"hash\"] as unknown as SQLWrapper, hash),\n      limit: 1,\n    })) as unknown as Token[];\n    return rows[0] ?? null;\n  }\n\n  /** Delete a token by id. */\n  async remove(id: string): Promise<void> {\n    await this.db.remove(this.tables.tokens, id);\n  }\n}\n"],"mappings":";;;;;;;;AAaA,IAAa,aAAb,MAAwB;CAOH;CANnB;;;;;CAKA,YACE,IACA,QACA;EAFiB,KAAA,KAAA;EAGjB,KAAK,SAAS,UAAU,EAAE,QAAQ,GAAG,OAAO,OAAO;CACrD;;;;;;;;;CAUA,MAAM,OACJ,WACA,OACgB;EAChB,OAAQ,MAAM,KAAK,GAAG,OAAO,KAAK,OAAO,QAAQ;GAC/C,IAAI,KAAK;GACT;GACA,MAAM,MAAM;GACZ,MAAM,MAAM;GACZ,QAAQ,MAAM,UAAU;GACxB,4BAAW,IAAI,KAAK,EAAA,CAAE,YAAY;EACpC,CAAC;CACH;;CAGA,MAAM,KAAK,WAAqC;EAC9C,OAAQ,MAAM,KAAK,GAAG,KAAK,KAAK,OAAO,QAAQ,EAC7C,OAAO,GACL,gBAAgB,KAAK,OAAO,MAAM,CAAC,CAAC,cACpC,SACF,EACF,CAAC;CACH;;CAGA,MAAM,IAAI,WAAmB,IAAmC;EAQ9D,QAAO,MAPa,KAAK,GAAG,KAAK,KAAK,OAAO,QAAQ;GACnD,OAAO,IACL,GAAG,gBAAgB,KAAK,OAAO,MAAM,CAAC,CAAC,cAAuC,SAAS,GACvF,GAAG,gBAAgB,KAAK,OAAO,MAAM,CAAC,CAAC,OAAgC,EAAE,CAC3E;GACA,OAAO;EACT,CAAC,EAAA,CACW,MAAM;CACpB;;CAGA,MAAM,WAAW,MAAqC;EAKpD,QAAO,MAJa,KAAK,GAAG,KAAK,KAAK,OAAO,QAAQ;GACnD,OAAO,GAAG,gBAAgB,KAAK,OAAO,MAAM,CAAC,CAAC,SAAkC,IAAI;GACpF,OAAO;EACT,CAAC,EAAA,CACW,MAAM;CACpB;;CAGA,MAAM,OAAO,IAA2B;EACtC,MAAM,KAAK,GAAG,OAAO,KAAK,OAAO,QAAQ,EAAE;CAC7C;AACF"}
+{"version":3,"file":"token.mjs","names":[],"sources":["../../src/models/token.ts"],"sourcesContent":["/** CI tokens for project-scoped API access. */\nimport { and, eq } from \"drizzle-orm\";\nimport type { Table } from \"drizzle-orm\";\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport type { Token } from \"../schema/token.ts\";\nimport { randomToken } from \"../utils/hash.ts\";\nimport { ulid } from \"../utils/ulid.ts\";\nimport { col } from \"./columns.ts\";\n\n/** Tables required by {@link TokenModel}. */\nexport interface TokenTables {\n  tokens: Table;\n}\n\n/** Data operations for CI tokens. */\nexport class TokenModel {\n  private readonly tables: TokenTables;\n  private readonly db: DatabaseAdapter;\n\n  /**\n   * @param db - Database adapter.\n   * @param tables - Table handles.\n   */\n  constructor(db: DatabaseAdapter, tables?: TokenTables) {\n    this.db = db;\n    this.tables = tables ?? { tokens: db.tables.tokens };\n  }\n\n  /**\n   * Create a token record storing its hash.\n   *\n   * @param projectId - Project ID.\n   * @param input - Token name, hash, and optional owning user ID (null for\n   * legacy/admin-token minting; such tokens resolve as viewer).\n   * @returns The created token.\n   */\n  async create(\n    projectId: string,\n    input: { name: string; hash: string; userId?: string | null },\n  ): Promise<Token> {\n    return (await this.db.insert(this.tables.tokens, {\n      id: ulid(),\n      projectId,\n      name: input.name,\n      hash: input.hash,\n      userId: input.userId ?? null,\n      createdAt: new Date().toISOString(),\n    })) as unknown as Token;\n  }\n\n  /**\n   * Mint a new `shelf_` token for a project and store only its hash.\n   *\n   * @returns The stored record and the plaintext value (shown to the user once).\n   */\n  async issue(\n    projectId: string,\n    input: { name: string; userId?: string | null },\n  ): Promise<{ token: Token; value: string }> {\n    const { value, hash } = randomToken(\"shelf_\");\n    const token = await this.create(projectId, { name: input.name, hash, userId: input.userId });\n    return { token, value };\n  }\n\n  /** List all tokens for a project. */\n  async list(projectId: string): Promise<Token[]> {\n    return (await this.db.list(this.tables.tokens, {\n      where: eq(col(this.tables.tokens, \"projectId\"), projectId),\n    })) as unknown as Token[];\n  }\n\n  /** Fetch a token by id within a project, or null if not found. */\n  async get(projectId: string, id: string): Promise<Token | null> {\n    const rows = (await this.db.list(this.tables.tokens, {\n      where: and(\n        eq(col(this.tables.tokens, \"projectId\"), projectId),\n        eq(col(this.tables.tokens, \"id\"), id),\n      ),\n      limit: 1,\n    })) as unknown as Token[];\n    return rows[0] ?? null;\n  }\n\n  /** Fetch a token by its hashed value, or null if not found. */\n  async findByHash(hash: string): Promise<Token | null> {\n    const rows = (await this.db.list(this.tables.tokens, {\n      where: eq(col(this.tables.tokens, \"hash\"), hash),\n      limit: 1,\n    })) as unknown as Token[];\n    return rows[0] ?? null;\n  }\n\n  /** Delete a token by id. */\n  async remove(id: string): Promise<void> {\n    await this.db.remove(this.tables.tokens, id);\n  }\n}\n"],"mappings":";;;;;;;;;;AAeA,IAAa,aAAb,MAAwB;CACtB;CACA;;;;;CAMA,YAAY,IAAqB,QAAsB;EACrD,KAAK,KAAK;EACV,KAAK,SAAS,UAAU,EAAE,QAAQ,GAAG,OAAO,OAAO;CACrD;;;;;;;;;CAUA,MAAM,OACJ,WACA,OACgB;EAChB,OAAQ,MAAM,KAAK,GAAG,OAAO,KAAK,OAAO,QAAQ;GAC/C,IAAI,KAAK;GACT;GACA,MAAM,MAAM;GACZ,MAAM,MAAM;GACZ,QAAQ,MAAM,UAAU;GACxB,4BAAW,IAAI,KAAK,EAAA,CAAE,YAAY;EACpC,CAAC;CACH;;;;;;CAOA,MAAM,MACJ,WACA,OAC0C;EAC1C,MAAM,EAAE,OAAO,SAAS,YAAY,QAAQ;EAE5C,OAAO;GAAE,OAAA,MADW,KAAK,OAAO,WAAW;IAAE,MAAM,MAAM;IAAM;IAAM,QAAQ,MAAM;GAAO,CAAC;GAC3E;EAAM;CACxB;;CAGA,MAAM,KAAK,WAAqC;EAC9C,OAAQ,MAAM,KAAK,GAAG,KAAK,KAAK,OAAO,QAAQ,EAC7C,OAAO,GAAG,IAAI,KAAK,OAAO,QAAQ,WAAW,GAAG,SAAS,EAC3D,CAAC;CACH;;CAGA,MAAM,IAAI,WAAmB,IAAmC;EAQ9D,QAAO,MAPa,KAAK,GAAG,KAAK,KAAK,OAAO,QAAQ;GACnD,OAAO,IACL,GAAG,IAAI,KAAK,OAAO,QAAQ,WAAW,GAAG,SAAS,GAClD,GAAG,IAAI,KAAK,OAAO,QAAQ,IAAI,GAAG,EAAE,CACtC;GACA,OAAO;EACT,CAAC,EAAA,CACW,MAAM;CACpB;;CAGA,MAAM,WAAW,MAAqC;EAKpD,QAAO,MAJa,KAAK,GAAG,KAAK,KAAK,OAAO,QAAQ;GACnD,OAAO,GAAG,IAAI,KAAK,OAAO,QAAQ,MAAM,GAAG,IAAI;GAC/C,OAAO;EACT,CAAC,EAAA,CACW,MAAM;CACpB;;CAGA,MAAM,OAAO,IAA2B;EACtC,MAAM,KAAK,GAAG,OAAO,KAAK,OAAO,QAAQ,EAAE;CAC7C;AACF"}

package/dist/models/usage.d.mts

@@ -0,0 +1,76 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DatabaseAdapter } from "../adapter/database.mjs";
+import { BuildPackageUsage, ProjectLink } from "../schema/usage.mjs";
+import { Table } from "drizzle-orm";
+//#region src/models/usage.d.ts
+/** Tables required by {@link PackageUsageModel}. */
+interface PackageUsageTables {
+  buildPackageUsage: Table;
+  projectLinks: Table;
+}
+/** A usage row as reported by the CLI at upload time. */
+interface PackageUsageInput {
+  storyImportPath: string;
+  packageName: string;
+  modulePath: string;
+  version?: string | null;
+}
+/** A candidate upstream story: where it is defined and its Storybook id. */
+interface UpstreamStory {
+  importPath: string;
+  storyId: string;
+}
+/**
+ * Pick the upstream story that documents the package module a story reaches.
+ * Exact stem match only (`dist/Button.js` ↔ `Button.stories.tsx`): resolves to the
+ * first story id of the single matching story file, or null when nothing matches
+ * or several different files share the stem (callers then fall back to the library).
+ */
+declare function matchUpstreamStory(modulePath: string, stories: readonly UpstreamStory[]): string | null;
+/** Data operations for build package usage and project links. */
+declare class PackageUsageModel {
+  private readonly tables;
+  private readonly db;
+  /**
+   * @param db - Database adapter.
+   * @param tables - Table handles.
+   */
+  constructor(db: DatabaseAdapter, tables?: PackageUsageTables);
+  /**
+   * Replace the usage rows of a build, so re-reporting is idempotent.
+   * Runs in one transaction when the driver supports it and is serialized per
+   * build, so concurrent re-reports leave exactly one report's rows.
+   *
+   * @returns The number of rows stored.
+   */
+  replaceForBuild(projectId: string, buildId: string, rows: readonly PackageUsageInput[]): Promise<number>;
+  /**
+   * Explicitly remove all usage rows of a build (no reliance on FK cascade).
+   *
+   * @returns The number of rows removed.
+   */
+  removeForBuild(buildId: string): Promise<number>;
+  /** List all usage rows of a build. */
+  listForBuild(buildId: string): Promise<BuildPackageUsage[]>;
+  /** List the packages a downstream project links to upstream projects. */
+  listLinks(downstreamId: string): Promise<ProjectLink[]>;
+  /** List the usage rows of one story file within a build. */
+  listForStory(buildId: string, storyImportPath: string): Promise<BuildPackageUsage[]>;
+  /**
+   * Replace a downstream project's links with the given list, atomically when
+   * the driver supports transactions and serialized per downstream project.
+   *
+   * @returns The stored links.
+   */
+  replaceLinks(downstreamId: string, links: readonly {
+    upstreamId: string;
+    packageName: string;
+  }[]): Promise<ProjectLink[]>;
+  /** Run `work` in a transaction when the driver has one, else directly on the adapter. */
+  private atomic;
+  private buildWhere;
+}
+//#endregion
+export { PackageUsageInput, PackageUsageModel, PackageUsageTables, UpstreamStory, matchUpstreamStory };
+//# sourceMappingURL=usage.d.mts.map

package/dist/models/usage.mjs

@@ -0,0 +1,149 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { ulid } from "../utils/ulid.mjs";
+import { col } from "./columns.mjs";
+import { and, eq } from "drizzle-orm";
+//#region src/models/usage.ts
+/** Per-build package usage and cross-project package links. */
+/** `Button.stories.tsx` / `Button.js` / `Button/index.js` → `Button`. */
+function componentStem(path) {
+	const parts = path.split("/").filter((part) => part.length > 0);
+	const file = (parts.at(-1) ?? "").replace(/(?:\.stories)?\.[cm]?[jt]sx?$|\.vue$|\.svelte$/u, "");
+	return file === "index" ? parts.at(-2) ?? file : file;
+}
+/**
+* Pick the upstream story that documents the package module a story reaches.
+* Exact stem match only (`dist/Button.js` ↔ `Button.stories.tsx`): resolves to the
+* first story id of the single matching story file, or null when nothing matches
+* or several different files share the stem (callers then fall back to the library).
+*/
+function matchUpstreamStory(modulePath, stories) {
+	const stem = componentStem(modulePath);
+	if (!stem) return null;
+	const matching = stories.filter((story) => componentStem(story.importPath) === stem);
+	if (new Set(matching.map((story) => story.importPath)).size !== 1) return null;
+	return matching.map((story) => story.storyId).toSorted()[0] ?? null;
+}
+/** Data operations for build package usage and project links. */
+var PackageUsageModel = class {
+	tables;
+	db;
+	/**
+	* @param db - Database adapter.
+	* @param tables - Table handles.
+	*/
+	constructor(db, tables) {
+		this.db = db;
+		this.tables = tables ?? {
+			buildPackageUsage: db.tables.buildPackageUsage,
+			projectLinks: db.tables.projectLinks
+		};
+	}
+	/**
+	* Replace the usage rows of a build, so re-reporting is idempotent.
+	* Runs in one transaction when the driver supports it and is serialized per
+	* build, so concurrent re-reports leave exactly one report's rows.
+	*
+	* @returns The number of rows stored.
+	*/
+	async replaceForBuild(projectId, buildId, rows) {
+		const table = this.tables.buildPackageUsage;
+		const createdAt = (/* @__PURE__ */ new Date()).toISOString();
+		return await serialized(`usage:${buildId}`, async () => await this.atomic(async (store) => {
+			await removeAll(store, table, this.buildWhere(buildId));
+			await Promise.all(rows.map(async (row) => {
+				await store.insert(table, {
+					id: ulid(),
+					projectId,
+					buildId,
+					storyImportPath: row.storyImportPath,
+					packageName: row.packageName,
+					modulePath: row.modulePath,
+					version: row.version ?? null,
+					createdAt
+				});
+			}));
+			return rows.length;
+		}));
+	}
+	/**
+	* Explicitly remove all usage rows of a build (no reliance on FK cascade).
+	*
+	* @returns The number of rows removed.
+	*/
+	async removeForBuild(buildId) {
+		return await removeAll(this.db, this.tables.buildPackageUsage, this.buildWhere(buildId));
+	}
+	/** List all usage rows of a build. */
+	async listForBuild(buildId) {
+		return await this.db.list(this.tables.buildPackageUsage, { where: this.buildWhere(buildId) });
+	}
+	/** List the packages a downstream project links to upstream projects. */
+	async listLinks(downstreamId) {
+		const table = this.tables.projectLinks;
+		return await this.db.list(table, { where: eq(col(table, "downstreamId"), downstreamId) });
+	}
+	/** List the usage rows of one story file within a build. */
+	async listForStory(buildId, storyImportPath) {
+		const table = this.tables.buildPackageUsage;
+		return await this.db.list(table, { where: and(eq(col(table, "buildId"), buildId), eq(col(table, "storyImportPath"), storyImportPath)) });
+	}
+	/**
+	* Replace a downstream project's links with the given list, atomically when
+	* the driver supports transactions and serialized per downstream project.
+	*
+	* @returns The stored links.
+	*/
+	async replaceLinks(downstreamId, links) {
+		const table = this.tables.projectLinks;
+		const where = eq(col(table, "downstreamId"), downstreamId);
+		const createdAt = (/* @__PURE__ */ new Date()).toISOString();
+		return await serialized(`links:${downstreamId}`, async () => await this.atomic(async (store) => {
+			await removeAll(store, table, where);
+			return await Promise.all(links.map(async (link) => await store.insert(table, {
+				id: ulid(),
+				downstreamId,
+				upstreamId: link.upstreamId,
+				packageName: link.packageName,
+				createdAt
+			})));
+		}));
+	}
+	/** Run `work` in a transaction when the driver has one, else directly on the adapter. */
+	async atomic(work) {
+		return this.db.transact ? await this.db.transact(work) : await work(this.db);
+	}
+	buildWhere(buildId) {
+		return eq(col(this.tables.buildPackageUsage, "buildId"), buildId);
+	}
+};
+/** Delete every row of `table` matching `where`; returns the number removed. */
+async function removeAll(store, table, where) {
+	const rows = await store.list(table, { where });
+	await Promise.all(rows.map(async (row) => {
+		await store.remove(table, row.id);
+	}));
+	return rows.length;
+}
+/** In-process tail of pending replaces, keyed by the rows they own. */
+const pending = /* @__PURE__ */ new Map();
+/**
+* Chain `task` after any in-flight call with the same key so overlapping replaces
+* of the same rows never interleave (covers drivers without `transact` and
+* drivers whose transactions do not serialize callers sharing one connection).
+*/
+async function serialized(key, task) {
+	const run = (pending.get(key) ?? Promise.resolve()).then(task, task);
+	const tail = run.catch(() => null);
+	pending.set(key, tail);
+	try {
+		return await run;
+	} finally {
+		if (pending.get(key) === tail) pending.delete(key);
+	}
+}
+//#endregion
+export { PackageUsageModel, matchUpstreamStory };
+
+//# sourceMappingURL=usage.mjs.map

package/dist/models/usage.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.mjs","names":[],"sources":["../../src/models/usage.ts"],"sourcesContent":["/** Per-build package usage and cross-project package links. */\nimport { and, eq } from \"drizzle-orm\";\nimport type { SQL, Table } from \"drizzle-orm\";\nimport type { DatabaseAdapter, TxStore } from \"../adapters/database.ts\";\nimport type { BuildPackageUsage, ProjectLink } from \"../schema/usage.ts\";\nimport { ulid } from \"../utils/ulid.ts\";\nimport { col } from \"./columns.ts\";\n\n/** Tables required by {@link PackageUsageModel}. */\nexport interface PackageUsageTables {\n  buildPackageUsage: Table;\n  projectLinks: Table;\n}\n\n/** A usage row as reported by the CLI at upload time. */\nexport interface PackageUsageInput {\n  storyImportPath: string;\n  packageName: string;\n  modulePath: string;\n  version?: string | null;\n}\n\n/** A candidate upstream story: where it is defined and its Storybook id. */\nexport interface UpstreamStory {\n  importPath: string;\n  storyId: string;\n}\n\n/** `Button.stories.tsx` / `Button.js` / `Button/index.js` → `Button`. */\nfunction componentStem(path: string): string {\n  const parts = path.split(\"/\").filter((part) => part.length > 0);\n  const last = parts.at(-1) ?? \"\";\n  const file = last.replace(/(?:\\.stories)?\\.[cm]?[jt]sx?$|\\.vue$|\\.svelte$/u, \"\");\n  return file === \"index\" ? (parts.at(-2) ?? file) : file;\n}\n\n/**\n * Pick the upstream story that documents the package module a story reaches.\n * Exact stem match only (`dist/Button.js` ↔ `Button.stories.tsx`): resolves to the\n * first story id of the single matching story file, or null when nothing matches\n * or several different files share the stem (callers then fall back to the library).\n */\nexport function matchUpstreamStory(\n  modulePath: string,\n  stories: readonly UpstreamStory[],\n): string | null {\n  const stem = componentStem(modulePath);\n  if (!stem) {\n    return null;\n  }\n  const matching = stories.filter((story) => componentStem(story.importPath) === stem);\n  if (new Set(matching.map((story) => story.importPath)).size !== 1) {\n    return null;\n  }\n  return matching.map((story) => story.storyId).toSorted()[0] ?? null;\n}\n\n/** Data operations for build package usage and project links. */\nexport class PackageUsageModel {\n  private readonly tables: PackageUsageTables;\n\n  private readonly db: DatabaseAdapter;\n\n  /**\n   * @param db - Database adapter.\n   * @param tables - Table handles.\n   */\n  constructor(db: DatabaseAdapter, tables?: PackageUsageTables) {\n    this.db = db;\n    this.tables = tables ?? {\n      buildPackageUsage: db.tables.buildPackageUsage,\n      projectLinks: db.tables.projectLinks,\n    };\n  }\n\n  /**\n   * Replace the usage rows of a build, so re-reporting is idempotent.\n   * Runs in one transaction when the driver supports it and is serialized per\n   * build, so concurrent re-reports leave exactly one report's rows.\n   *\n   * @returns The number of rows stored.\n   */\n  async replaceForBuild(\n    projectId: string,\n    buildId: string,\n    rows: readonly PackageUsageInput[],\n  ): Promise<number> {\n    const table = this.tables.buildPackageUsage;\n    const createdAt = new Date().toISOString();\n    return await serialized(\n      `usage:${buildId}`,\n      async () =>\n        await this.atomic(async (store) => {\n          await removeAll(store, table, this.buildWhere(buildId));\n          await Promise.all(\n            rows.map(async (row) => {\n              await store.insert(table, {\n                id: ulid(),\n                projectId,\n                buildId,\n                storyImportPath: row.storyImportPath,\n                packageName: row.packageName,\n                modulePath: row.modulePath,\n                version: row.version ?? null,\n                createdAt,\n              });\n            }),\n          );\n          return rows.length;\n        }),\n    );\n  }\n\n  /**\n   * Explicitly remove all usage rows of a build (no reliance on FK cascade).\n   *\n   * @returns The number of rows removed.\n   */\n  async removeForBuild(buildId: string): Promise<number> {\n    return await removeAll(this.db, this.tables.buildPackageUsage, this.buildWhere(buildId));\n  }\n\n  /** List all usage rows of a build. */\n  async listForBuild(buildId: string): Promise<BuildPackageUsage[]> {\n    return (await this.db.list(this.tables.buildPackageUsage, {\n      where: this.buildWhere(buildId),\n    })) as unknown as BuildPackageUsage[];\n  }\n\n  /** List the packages a downstream project links to upstream projects. */\n  async listLinks(downstreamId: string): Promise<ProjectLink[]> {\n    const table = this.tables.projectLinks;\n    return (await this.db.list(table, {\n      where: eq(col(table, \"downstreamId\"), downstreamId),\n    })) as unknown as ProjectLink[];\n  }\n\n  /** List the usage rows of one story file within a build. */\n  async listForStory(buildId: string, storyImportPath: string): Promise<BuildPackageUsage[]> {\n    const table = this.tables.buildPackageUsage;\n    return (await this.db.list(table, {\n      where: and(\n        eq(col(table, \"buildId\"), buildId),\n        eq(col(table, \"storyImportPath\"), storyImportPath),\n      ),\n    })) as unknown as BuildPackageUsage[];\n  }\n\n  /**\n   * Replace a downstream project's links with the given list, atomically when\n   * the driver supports transactions and serialized per downstream project.\n   *\n   * @returns The stored links.\n   */\n  async replaceLinks(\n    downstreamId: string,\n    links: readonly { upstreamId: string; packageName: string }[],\n  ): Promise<ProjectLink[]> {\n    const table = this.tables.projectLinks;\n    const where = eq(col(table, \"downstreamId\"), downstreamId);\n    const createdAt = new Date().toISOString();\n    return await serialized(\n      `links:${downstreamId}`,\n      async () =>\n        await this.atomic(async (store) => {\n          await removeAll(store, table, where);\n          return await Promise.all(\n            links.map(\n              async (link) =>\n                (await store.insert(table, {\n                  id: ulid(),\n                  downstreamId,\n                  upstreamId: link.upstreamId,\n                  packageName: link.packageName,\n                  createdAt,\n                })) as unknown as ProjectLink,\n            ),\n          );\n        }),\n    );\n  }\n\n  /** Run `work` in a transaction when the driver has one, else directly on the adapter. */\n  private async atomic<R>(work: (store: TxStore) => Promise<R>): Promise<R> {\n    return this.db.transact ? await this.db.transact(work) : await work(this.db);\n  }\n\n  private buildWhere(buildId: string): SQL {\n    return eq(col(this.tables.buildPackageUsage, \"buildId\"), buildId);\n  }\n}\n\n/** Delete every row of `table` matching `where`; returns the number removed. */\nasync function removeAll(store: TxStore, table: Table, where: SQL): Promise<number> {\n  const rows = (await store.list(table, { where })) as unknown as { id: string }[];\n  await Promise.all(\n    rows.map(async (row) => {\n      await store.remove(table, row.id);\n    }),\n  );\n  return rows.length;\n}\n\n/** In-process tail of pending replaces, keyed by the rows they own. */\nconst pending = new Map<string, Promise<unknown>>();\n\n/**\n * Chain `task` after any in-flight call with the same key so overlapping replaces\n * of the same rows never interleave (covers drivers without `transact` and\n * drivers whose transactions do not serialize callers sharing one connection).\n */\nasync function serialized<R>(key: string, task: () => Promise<R>): Promise<R> {\n  const previous = pending.get(key) ?? Promise.resolve();\n  const run = previous.then(task, task);\n  const tail = run.catch(() => null);\n  pending.set(key, tail);\n  try {\n    return await run;\n  } finally {\n    if (pending.get(key) === tail) {\n      pending.delete(key);\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/models/user.d.mts

@@ -10,8 +10,8 @@ interface UserTables {
 }
 /** Data operations for users. */
 declare class UserModel {
-  private readonly db;
   private readonly tables;
+  private readonly db;
   /**
    * @param db - Database adapter.
    * @param tables - Table handles.

package/dist/models/user.mjs

@@ -1,13 +1,14 @@
 import "node:path";
 import "node:url";
 import.meta.url;
-import { eq, getTableColumns } from "drizzle-orm";
+import { col } from "./columns.mjs";
+import { eq } from "drizzle-orm";
 //#region src/models/user.ts
 /** User lookups for token and membership resolution. */
 /** Data operations for users. */
 var UserModel = class {
-	db;
 	tables;
+	db;
 	/**
 	* @param db - Database adapter.
 	* @param tables - Table handles.
@@ -19,7 +20,7 @@ var UserModel = class {
 	/** Fetch a user by id, or null if not found (e.g. deleted after tokens were minted). */
 	async get(id) {
 		return (await this.db.list(this.tables.users, {
-			where: eq(getTableColumns(this.tables.users)["id"], id),
+			where: eq(col(this.tables.users, "id"), id),
 			limit: 1
 		}))[0] ?? null;
 	}

package/dist/models/user.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"user.mjs","names":[],"sources":["../../src/models/user.ts"],"sourcesContent":["/** User lookups for token and membership resolution. */\nimport { eq, getTableColumns } from \"drizzle-orm\";\nimport type { SQLWrapper, Table } from \"drizzle-orm\";\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport type { User } from \"../schema/user.ts\";\n\n/** Tables required by {@link UserModel}. */\nexport interface UserTables {\n  users: Table;\n}\n\n/** Data operations for users. */\nexport class UserModel {\n  private readonly tables: UserTables;\n  /**\n   * @param db - Database adapter.\n   * @param tables - Table handles.\n   */\n  constructor(\n    private readonly db: DatabaseAdapter,\n    tables?: UserTables,\n  ) {\n    this.tables = tables ?? { users: db.tables.users };\n  }\n\n  /** Fetch a user by id, or null if not found (e.g. deleted after tokens were minted). */\n  async get(id: string): Promise<User | null> {\n    const rows = (await this.db.list(this.tables.users, {\n      where: eq(getTableColumns(this.tables.users)[\"id\"] as unknown as SQLWrapper, id),\n      limit: 1,\n    })) as unknown as User[];\n    return rows[0] ?? null;\n  }\n\n  /**\n   * Insert or update a user row from an authenticated identity (login sync).\n   * Email, name, avatar, and site role refresh on every login; the row id\n   * (the provider `sub`) is stable. Preserves `displayNameOverride` so a\n   * user-edited name survives IdP refresh; `passwordHash` and `disabled`\n   * are never clobbered by SSO sync.\n   */\n  async upsert(input: {\n    id: string;\n    email: string;\n    name: string;\n    avatarUrl?: string | null;\n    role: User[\"role\"];\n    authProvider?: User[\"authProvider\"];\n  }): Promise<User> {\n    const now = new Date().toISOString();\n    const existing = await this.get(input.id);\n    if (!existing) {\n      return (await this.db.insert(this.tables.users, {\n        id: input.id,\n        email: input.email,\n        name: input.name,\n        avatarUrl: input.avatarUrl ?? null,\n        role: input.role,\n        lastLoginAt: now,\n        createdAt: now,\n        passwordHash: null,\n        displayNameOverride: null,\n        authProvider: input.authProvider ?? \"oidc\",\n        disabled: false,\n      })) as unknown as User;\n    }\n    return (await this.db.update(this.tables.users, existing.id, {\n      email: input.email,\n      // Keep a user-edited display name: `name` stays the IdP value,\n      // `displayNameOverride` is the source of truth for rendering.\n      name: input.name,\n      avatarUrl: input.avatarUrl ?? null,\n      role: input.role,\n      lastLoginAt: now,\n    })) as unknown as User;\n  }\n\n  /** Update the display name override for a user (profile edit). */\n  async setDisplayNameOverride(id: string, displayName: string | null): Promise<User> {\n    return (await this.db.update(this.tables.users, id, {\n      displayNameOverride: displayName?.trim() ? displayName.trim() : null,\n    })) as unknown as User;\n  }\n}\n"],"mappings":";;;;;;;AAYA,IAAa,YAAb,MAAuB;CAOF;CANnB;;;;;CAKA,YACE,IACA,QACA;EAFiB,KAAA,KAAA;EAGjB,KAAK,SAAS,UAAU,EAAE,OAAO,GAAG,OAAO,MAAM;CACnD;;CAGA,MAAM,IAAI,IAAkC;EAK1C,QAAO,MAJa,KAAK,GAAG,KAAK,KAAK,OAAO,OAAO;GAClD,OAAO,GAAG,gBAAgB,KAAK,OAAO,KAAK,CAAC,CAAC,OAAgC,EAAE;GAC/E,OAAO;EACT,CAAC,EAAA,CACW,MAAM;CACpB;;;;;;;;CASA,MAAM,OAAO,OAOK;EAChB,MAAM,uBAAM,IAAI,KAAK,EAAA,CAAE,YAAY;EACnC,MAAM,WAAW,MAAM,KAAK,IAAI,MAAM,EAAE;EACxC,IAAI,CAAC,UACH,OAAQ,MAAM,KAAK,GAAG,OAAO,KAAK,OAAO,OAAO;GAC9C,IAAI,MAAM;GACV,OAAO,MAAM;GACb,MAAM,MAAM;GACZ,WAAW,MAAM,aAAa;GAC9B,MAAM,MAAM;GACZ,aAAa;GACb,WAAW;GACX,cAAc;GACd,qBAAqB;GACrB,cAAc,MAAM,gBAAgB;GACpC,UAAU;EACZ,CAAC;EAEH,OAAQ,MAAM,KAAK,GAAG,OAAO,KAAK,OAAO,OAAO,SAAS,IAAI;GAC3D,OAAO,MAAM;GAGb,MAAM,MAAM;GACZ,WAAW,MAAM,aAAa;GAC9B,MAAM,MAAM;GACZ,aAAa;EACf,CAAC;CACH;;CAGA,MAAM,uBAAuB,IAAY,aAA2C;EAClF,OAAQ,MAAM,KAAK,GAAG,OAAO,KAAK,OAAO,OAAO,IAAI,EAClD,qBAAqB,aAAa,KAAK,IAAI,YAAY,KAAK,IAAI,KAClE,CAAC;CACH;AACF"}
+{"version":3,"file":"user.mjs","names":[],"sources":["../../src/models/user.ts"],"sourcesContent":["/** User lookups for token and membership resolution. */\nimport { eq } from \"drizzle-orm\";\nimport type { Table } from \"drizzle-orm\";\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport type { User } from \"../schema/user.ts\";\nimport { col } from \"./columns.ts\";\n\n/** Tables required by {@link UserModel}. */\nexport interface UserTables {\n  users: Table;\n}\n\n/** Data operations for users. */\nexport class UserModel {\n  private readonly tables: UserTables;\n  private readonly db: DatabaseAdapter;\n\n  /**\n   * @param db - Database adapter.\n   * @param tables - Table handles.\n   */\n  constructor(db: DatabaseAdapter, tables?: UserTables) {\n    this.db = db;\n    this.tables = tables ?? { users: db.tables.users };\n  }\n\n  /** Fetch a user by id, or null if not found (e.g. deleted after tokens were minted). */\n  async get(id: string): Promise<User | null> {\n    const rows = (await this.db.list(this.tables.users, {\n      where: eq(col(this.tables.users, \"id\"), id),\n      limit: 1,\n    })) as unknown as User[];\n    return rows[0] ?? null;\n  }\n\n  /**\n   * Insert or update a user row from an authenticated identity (login sync).\n   * Email, name, avatar, and site role refresh on every login; the row id\n   * (the provider `sub`) is stable. Preserves `displayNameOverride` so a\n   * user-edited name survives IdP refresh; `passwordHash` and `disabled`\n   * are never clobbered by SSO sync.\n   */\n  async upsert(input: {\n    id: string;\n    email: string;\n    name: string;\n    avatarUrl?: string | null;\n    role: User[\"role\"];\n    authProvider?: User[\"authProvider\"];\n  }): Promise<User> {\n    const now = new Date().toISOString();\n    const existing = await this.get(input.id);\n    if (!existing) {\n      return (await this.db.insert(this.tables.users, {\n        id: input.id,\n        email: input.email,\n        name: input.name,\n        avatarUrl: input.avatarUrl ?? null,\n        role: input.role,\n        lastLoginAt: now,\n        createdAt: now,\n        passwordHash: null,\n        displayNameOverride: null,\n        authProvider: input.authProvider ?? \"oidc\",\n        disabled: false,\n      })) as unknown as User;\n    }\n    return (await this.db.update(this.tables.users, existing.id, {\n      email: input.email,\n      // Keep a user-edited display name: `name` stays the IdP value,\n      // `displayNameOverride` is the source of truth for rendering.\n      name: input.name,\n      avatarUrl: input.avatarUrl ?? null,\n      role: input.role,\n      lastLoginAt: now,\n    })) as unknown as User;\n  }\n\n  /** Update the display name override for a user (profile edit). */\n  async setDisplayNameOverride(id: string, displayName: string | null): Promise<User> {\n    return (await this.db.update(this.tables.users, id, {\n      displayNameOverride: displayName?.trim() ? displayName.trim() : null,\n    })) as unknown as User;\n  }\n}\n"],"mappings":";;;;;;;;AAaA,IAAa,YAAb,MAAuB;CACrB;CACA;;;;;CAMA,YAAY,IAAqB,QAAqB;EACpD,KAAK,KAAK;EACV,KAAK,SAAS,UAAU,EAAE,OAAO,GAAG,OAAO,MAAM;CACnD;;CAGA,MAAM,IAAI,IAAkC;EAK1C,QAAO,MAJa,KAAK,GAAG,KAAK,KAAK,OAAO,OAAO;GAClD,OAAO,GAAG,IAAI,KAAK,OAAO,OAAO,IAAI,GAAG,EAAE;GAC1C,OAAO;EACT,CAAC,EAAA,CACW,MAAM;CACpB;;;;;;;;CASA,MAAM,OAAO,OAOK;EAChB,MAAM,uBAAM,IAAI,KAAK,EAAA,CAAE,YAAY;EACnC,MAAM,WAAW,MAAM,KAAK,IAAI,MAAM,EAAE;EACxC,IAAI,CAAC,UACH,OAAQ,MAAM,KAAK,GAAG,OAAO,KAAK,OAAO,OAAO;GAC9C,IAAI,MAAM;GACV,OAAO,MAAM;GACb,MAAM,MAAM;GACZ,WAAW,MAAM,aAAa;GAC9B,MAAM,MAAM;GACZ,aAAa;GACb,WAAW;GACX,cAAc;GACd,qBAAqB;GACrB,cAAc,MAAM,gBAAgB;GACpC,UAAU;EACZ,CAAC;EAEH,OAAQ,MAAM,KAAK,GAAG,OAAO,KAAK,OAAO,OAAO,SAAS,IAAI;GAC3D,OAAO,MAAM;GAGb,MAAM,MAAM;GACZ,WAAW,MAAM,aAAa;GAC9B,MAAM,MAAM;GACZ,aAAa;EACf,CAAC;CACH;;CAGA,MAAM,uBAAuB,IAAY,aAA2C;EAClF,OAAQ,MAAM,KAAK,GAAG,OAAO,KAAK,OAAO,OAAO,IAAI,EAClD,qBAAqB,aAAa,KAAK,IAAI,YAAY,KAAK,IAAI,KAClE,CAAC;CACH;AACF"}

package/dist/models/webhook.d.mts

@@ -11,9 +11,9 @@ interface WebhookTables {
 }
 /** Data operations for webhook subscriptions. */
 declare class WebhookModel {
-  private readonly db;
   private readonly tables;
   private readonly secret?;
+  private readonly db;
   /**
    * @param db - Database adapter.
    * @param tables - Table handles.
@@ -22,6 +22,20 @@ declare class WebhookModel {
   constructor(db: DatabaseAdapter, tables?: WebhookTables, secret?: SecretInput);
   /** List all webhooks for a project. */
   list(projectId: string): Promise<Webhook[]>;
+  /** Validate a webhook target URL; returns an error message, or null when acceptable. */
+  static urlError(url: string | undefined): string | null;
+  /**
+   * Create a webhook with a freshly generated `whsec_` signing secret.
+   *
+   * @returns The stored webhook and the plaintext secret (shown to the user once).
+   */
+  issue(projectId: string, input: {
+    url: string;
+    events?: string[];
+  }): Promise<{
+    webhook: Webhook;
+    secret: string;
+  }>;
   /**
    * Create a webhook subscription for a project.
    *

package/dist/models/webhook.mjs

@@ -1,16 +1,18 @@
 import "node:path";
 import "node:url";
 import.meta.url;
+import { randomToken } from "../utils/hash.mjs";
 import { decryptCredential, encrypt } from "../utils/encrypt.mjs";
 import { ulid } from "../utils/ulid.mjs";
-import { eq, getTableColumns } from "drizzle-orm";
+import { col } from "./columns.mjs";
+import { eq } from "drizzle-orm";
 //#region src/models/webhook.ts
 /** Webhook subscriptions for project events. */
 /** Data operations for webhook subscriptions. */
 var WebhookModel = class {
-	db;
 	tables;
 	secret;
+	db;
 	/**
 	* @param db - Database adapter.
 	* @param tables - Table handles.
@@ -23,7 +25,34 @@ var WebhookModel = class {
 	}
 	/** List all webhooks for a project. */
 	async list(projectId) {
-		return await this.db.list(this.tables.webhooks, { where: eq(getTableColumns(this.tables.webhooks)["projectId"], projectId) });
+		return await this.db.list(this.tables.webhooks, { where: eq(col(this.tables.webhooks, "projectId"), projectId) });
+	}
+	/** Validate a webhook target URL; returns an error message, or null when acceptable. */
+	static urlError(url) {
+		if (!url) return "A valid URL is required";
+		let protocol;
+		try {
+			({protocol} = new URL(url));
+		} catch {
+			return "Enter a valid URL";
+		}
+		return protocol === "https:" || protocol === "http:" ? null : "URL must use http or https";
+	}
+	/**
+	* Create a webhook with a freshly generated `whsec_` signing secret.
+	*
+	* @returns The stored webhook and the plaintext secret (shown to the user once).
+	*/
+	async issue(projectId, input) {
+		const secret = randomToken("whsec_").value;
+		return {
+			webhook: await this.create(projectId, {
+				url: input.url,
+				events: input.events,
+				secret
+			}),
+			secret
+		};
 	}
 	/**
 	* Create a webhook subscription for a project.
@@ -51,7 +80,7 @@ var WebhookModel = class {
 	/** Fetch a webhook by id scoped to a project, or null if not found. */
 	async get(projectId, id) {
 		const found = (await this.db.list(this.tables.webhooks, {
-			where: eq(getTableColumns(this.tables.webhooks)["id"], id),
+			where: eq(col(this.tables.webhooks, "id"), id),
 			limit: 1
 		}))[0] ?? null;
 		return found?.projectId === projectId ? found : null;