@storyshelf/core 0.6.2 → 0.7.0

package/dist/capture/build-state/notify-job.d.mts

@@ -0,0 +1,56 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { BuildStateDeps } from "./types.mjs";
+import { ConsumerJob, KindHandler } from "../consumer/types.mjs";
+import { QueueJobInput } from "../db-queue/types.mjs";
+//#region src/capture/build-state/notify-job.d.ts
+/** Attempts a delivery gets before it is given up (the first try and four retries). */
+declare const NOTIFY_MAX_ATTEMPTS = 5;
+/** Retry delay of a delivery: 10 s, then doubling to at most five minutes. */
+declare const NOTIFY_BACKOFF: {
+  readonly baseMs: 10000;
+  readonly maxMs: number;
+};
+/** A delivery that was given up: the channel shows the error and the admin event fires. */
+interface NotifyFailure {
+  channelId: string;
+  projectId: string | null;
+  provider: string;
+  buildId: string;
+  /** Sanitized error text. */
+  error: string;
+}
+/** What {@link createNotifyHandler} needs. */
+interface NotifyHandlerOptions {
+  deps: BuildStateDeps;
+  /** Called once when a delivery is given up, after the channel row recorded the error. Failures are logged. */
+  onFailed?: (failure: NotifyFailure) => Promise<void>;
+}
+/**
+ * The handler. Resolving acks the job (also when the build or channel is gone: nothing is left to
+ * show). A refused status rejects, so the consumer requeues with {@link NOTIFY_BACKOFF}; the last
+ * attempt records the error on the channel and raises `onFailed`.
+ */
+declare function createNotifyHandler(options: NotifyHandlerOptions): KindHandler;
+/**
+ * For the queue's `onExhausted` hook: a last attempt that lost its lease never ran its handler to
+ * the end, so the failure is surfaced here (the hook may run on several instances; recording the
+ * same error twice is harmless, the admin event may repeat).
+ */
+declare function notifyExhausted(options: NotifyHandlerOptions): (job: ConsumerJob, error: string) => Promise<void>;
+/** The slice of the database queue the enqueuer uses. */
+interface NotifyJobQueue {
+  enqueueJob(job: QueueJobInput): Promise<string>;
+}
+/**
+ * Enqueue a `notify` job for a channel and build, unless one is already waiting: it will read the
+ * build's state when it runs, so a second would deliver the same thing. A job that is already
+ * running may have read an older state, so a new one is queued behind it.
+ */
+declare function createNotifyEnqueuer(deps: Pick<BuildStateDeps, "db">, queue: NotifyJobQueue): (job: {
+  channelId: string;
+  buildId: string;
+}) => Promise<void>;
+//#endregion
+export { NOTIFY_BACKOFF, NOTIFY_MAX_ATTEMPTS, NotifyFailure, NotifyHandlerOptions, NotifyJobQueue, createNotifyEnqueuer, createNotifyHandler, notifyExhausted };
+//# sourceMappingURL=notify-job.d.mts.map

package/dist/capture/build-state/notify-job.mjs

@@ -0,0 +1,133 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { sanitizeErrorText } from "../../utils/redact.mjs";
+import { NotificationChannelModel } from "../../models/notification-channel.mjs";
+import { deliverBuildState } from "./deliver.mjs";
+import { CaptureJobModel } from "../../models/capture-job.mjs";
+import { isFinalAttempt } from "../consumer/retry.mjs";
+import { decodePayload } from "../db-queue/codec.mjs";
+//#region src/capture/build-state/notify-job.ts
+/**
+* The `notify` job kind (ADR 0014, decision 7; ADR 0006, decision 4): one job per `(channel,
+* build)` state change. The job names a channel and a build, never a status: the handler reads the
+* build when it runs, so a retried or reordered job cannot post a stale state, and a queued job
+* for the same pair already covers a newer request.
+*/
+/** Attempts a delivery gets before it is given up (the first try and four retries). */
+const NOTIFY_MAX_ATTEMPTS = 5;
+/** Retry delay of a delivery: 10 s, then doubling to at most five minutes. */
+const NOTIFY_BACKOFF = {
+	baseMs: 1e4,
+	maxMs: 3e5
+};
+/** Longest error text kept on a channel row. */
+const MAX_ERROR_LENGTH = 500;
+/** The channel a `notify` job delivers to. */
+function channelIdOf(job) {
+	const id = job.data?.["channelId"];
+	return typeof id === "string" ? id : "";
+}
+/**
+* The handler. Resolving acks the job (also when the build or channel is gone: nothing is left to
+* show). A refused status rejects, so the consumer requeues with {@link NOTIFY_BACKOFF}; the last
+* attempt records the error on the channel and raises `onFailed`.
+*/
+function createNotifyHandler(options) {
+	const { deps } = options;
+	return {
+		accepts: (job) => job.buildId.length > 0 && channelIdOf(job).length > 0,
+		backoff: NOTIFY_BACKOFF,
+		run: async (job, context) => {
+			const channelId = channelIdOf(job);
+			try {
+				const result = await deliverBuildState(deps, {
+					buildId: job.buildId,
+					channelId
+				});
+				if (result === "delivered") await channelModel(deps).recordOutcome(channelId);
+				else context.logger.info({ result }, "nothing to deliver");
+			} catch (error) {
+				if (isFinalAttempt(job)) await surfaceFailure(options, {
+					channelId,
+					buildId: job.buildId,
+					error
+				});
+				throw error;
+			}
+		}
+	};
+}
+/**
+* For the queue's `onExhausted` hook: a last attempt that lost its lease never ran its handler to
+* the end, so the failure is surfaced here (the hook may run on several instances; recording the
+* same error twice is harmless, the admin event may repeat).
+*/
+function notifyExhausted(options) {
+	return async (job, error) => {
+		await surfaceFailure(options, {
+			channelId: channelIdOf(job),
+			buildId: job.buildId,
+			error
+		});
+	};
+}
+async function surfaceFailure(options, failure) {
+	const { deps } = options;
+	const text = sanitizeErrorText(errorText(failure.error), MAX_ERROR_LENGTH);
+	deps.logger.error({
+		channelId: failure.channelId,
+		buildId: failure.buildId,
+		error: text
+	}, "state delivery given up");
+	try {
+		await recordAndAlert(options, {
+			...failure,
+			error: text
+		});
+	} catch (error) {
+		deps.logger.warn({
+			err: error,
+			channelId: failure.channelId
+		}, "failed to record the failure");
+	}
+}
+/** Put the error on the channel row, then raise `onFailed`; a channel that is gone needs neither. */
+async function recordAndAlert(options, failure) {
+	const model = channelModel(options.deps);
+	const row = await model.get(failure.channelId);
+	if (row === null) return;
+	await model.recordOutcome(row.id, failure.error);
+	await options.onFailed?.({
+		channelId: row.id,
+		projectId: row.projectId,
+		provider: row.provider,
+		buildId: failure.buildId,
+		error: failure.error
+	});
+}
+function errorText(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function channelModel(deps) {
+	return new NotificationChannelModel(deps.db, { notificationChannels: deps.db.tables.notificationChannels }, deps.secret);
+}
+/**
+* Enqueue a `notify` job for a channel and build, unless one is already waiting: it will read the
+* build's state when it runs, so a second would deliver the same thing. A job that is already
+* running may have read an older state, so a new one is queued behind it.
+*/
+function createNotifyEnqueuer(deps, queue) {
+	return async ({ channelId, buildId }) => {
+		if (!(await new CaptureJobModel(deps.db).listForBuild(buildId)).some((row) => row.kind === "notify" && row.status === "queued" && decodePayload(row.payload).data?.["channelId"] === channelId)) await queue.enqueueJob({
+			kind: "notify",
+			buildId,
+			data: { channelId },
+			maxAttempts: 5
+		});
+	};
+}
+//#endregion
+export { NOTIFY_BACKOFF, NOTIFY_MAX_ATTEMPTS, createNotifyEnqueuer, createNotifyHandler, notifyExhausted };
+
+//# sourceMappingURL=notify-job.mjs.map

package/dist/capture/build-state/notify-job.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify-job.mjs","names":[],"sources":["../../../src/capture/build-state/notify-job.ts"],"sourcesContent":["/**\n * The `notify` job kind (ADR 0014, decision 7; ADR 0006, decision 4): one job per `(channel,\n * build)` state change. The job names a channel and a build, never a status: the handler reads the\n * build when it runs, so a retried or reordered job cannot post a stale state, and a queued job\n * for the same pair already covers a newer request.\n */\nimport { CaptureJobModel } from \"../../models/capture-job.ts\";\nimport { NotificationChannelModel } from \"../../models/notification-channel.ts\";\nimport { sanitizeErrorText } from \"../../utils/redact.ts\";\nimport { isFinalAttempt } from \"../consumer/retry.ts\";\nimport type { ConsumerJob, KindHandler } from \"../consumer/types.ts\";\nimport { decodePayload } from \"../db-queue/codec.ts\";\nimport type { QueueJobInput } from \"../db-queue/types.ts\";\nimport { deliverBuildState } from \"./deliver.ts\";\nimport type { BuildStateDeps } from \"./types.ts\";\n\n/** Attempts a delivery gets before it is given up (the first try and four retries). */\nexport const NOTIFY_MAX_ATTEMPTS = 5;\n\n/** Retry delay of a delivery: 10 s, then doubling to at most five minutes. */\nexport const NOTIFY_BACKOFF = { baseMs: 10_000, maxMs: 5 * 60_000 } as const;\n\n/** Longest error text kept on a channel row. */\nconst MAX_ERROR_LENGTH = 500;\n\n/** A delivery that was given up: the channel shows the error and the admin event fires. */\nexport interface NotifyFailure {\n  channelId: string;\n  projectId: string | null;\n  provider: string;\n  buildId: string;\n  /** Sanitized error text. */\n  error: string;\n}\n\n/** What {@link createNotifyHandler} needs. */\nexport interface NotifyHandlerOptions {\n  deps: BuildStateDeps;\n  /** Called once when a delivery is given up, after the channel row recorded the error. Failures are logged. */\n  onFailed?: (failure: NotifyFailure) => Promise<void>;\n}\n\n/** The channel a `notify` job delivers to. */\nfunction channelIdOf(job: Pick<ConsumerJob, \"data\">): string {\n  const id = job.data?.[\"channelId\"];\n  return typeof id === \"string\" ? id : \"\";\n}\n\n/**\n * The handler. Resolving acks the job (also when the build or channel is gone: nothing is left to\n * show). A refused status rejects, so the consumer requeues with {@link NOTIFY_BACKOFF}; the last\n * attempt records the error on the channel and raises `onFailed`.\n */\nexport function createNotifyHandler(options: NotifyHandlerOptions): KindHandler {\n  const { deps } = options;\n  return {\n    accepts: (job) => job.buildId.length > 0 && channelIdOf(job).length > 0,\n    backoff: NOTIFY_BACKOFF,\n    run: async (job, context) => {\n      const channelId = channelIdOf(job);\n      try {\n        const result = await deliverBuildState(deps, { buildId: job.buildId, channelId });\n        if (result === \"delivered\") {\n          await channelModel(deps).recordOutcome(channelId);\n        } else {\n          context.logger.info({ result }, \"nothing to deliver\");\n        }\n      } catch (error) {\n        if (isFinalAttempt(job)) {\n          await surfaceFailure(options, { channelId, buildId: job.buildId, error });\n        }\n        throw error;\n      }\n    },\n  };\n}\n\n/**\n * For the queue's `onExhausted` hook: a last attempt that lost its lease never ran its handler to\n * the end, so the failure is surfaced here (the hook may run on several instances; recording the\n * same error twice is harmless, the admin event may repeat).\n */\nexport function notifyExhausted(\n  options: NotifyHandlerOptions,\n): (job: ConsumerJob, error: string) => Promise<void> {\n  return async (job, error) => {\n    await surfaceFailure(options, { channelId: channelIdOf(job), buildId: job.buildId, error });\n  };\n}\n\nasync function surfaceFailure(\n  options: NotifyHandlerOptions,\n  failure: { channelId: string; buildId: string; error: unknown },\n): Promise<void> {\n  const { deps } = options;\n  const text = sanitizeErrorText(errorText(failure.error), MAX_ERROR_LENGTH);\n  deps.logger.error(\n    { channelId: failure.channelId, buildId: failure.buildId, error: text },\n    \"state delivery given up\",\n  );\n  try {\n    await recordAndAlert(options, { ...failure, error: text });\n  } catch (error) {\n    deps.logger.warn({ err: error, channelId: failure.channelId }, \"failed to record the failure\");\n  }\n}\n\n/** Put the error on the channel row, then raise `onFailed`; a channel that is gone needs neither. */\nasync function recordAndAlert(\n  options: NotifyHandlerOptions,\n  failure: { channelId: string; buildId: string; error: string },\n): Promise<void> {\n  const model = channelModel(options.deps);\n  const row = await model.get(failure.channelId);\n  if (row === null) {\n    return;\n  }\n  await model.recordOutcome(row.id, failure.error);\n  await options.onFailed?.({\n    channelId: row.id,\n    projectId: row.projectId,\n    provider: row.provider,\n    buildId: failure.buildId,\n    error: failure.error,\n  });\n}\n\nfunction errorText(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\nfunction channelModel(deps: BuildStateDeps): NotificationChannelModel {\n  return new NotificationChannelModel(\n    deps.db,\n    { notificationChannels: deps.db.tables.notificationChannels },\n    deps.secret,\n  );\n}\n\n/** The slice of the database queue the enqueuer uses. */\nexport interface NotifyJobQueue {\n  enqueueJob(job: QueueJobInput): Promise<string>;\n}\n\n/**\n * Enqueue a `notify` job for a channel and build, unless one is already waiting: it will read the\n * build's state when it runs, so a second would deliver the same thing. A job that is already\n * running may have read an older state, so a new one is queued behind it.\n */\nexport function createNotifyEnqueuer(\n  deps: Pick<BuildStateDeps, \"db\">,\n  queue: NotifyJobQueue,\n): (job: { channelId: string; buildId: string }) => Promise<void> {\n  return async ({ channelId, buildId }) => {\n    // Built per call: a host that never enqueues must not touch `capture_jobs`.\n    const rows = await new CaptureJobModel(deps.db).listForBuild(buildId);\n    const waiting = rows.some(\n      (row) =>\n        row.kind === \"notify\" &&\n        row.status === \"queued\" &&\n        decodePayload(row.payload).data?.[\"channelId\"] === channelId,\n    );\n    if (!waiting) {\n      await queue.enqueueJob({\n        kind: \"notify\",\n        buildId,\n        data: { channelId },\n        maxAttempts: NOTIFY_MAX_ATTEMPTS,\n      });\n    }\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAiBA,MAAa,sBAAsB;;AAGnC,MAAa,iBAAiB;CAAE,QAAQ;CAAQ,OAAO;AAAW;;AAGlE,MAAM,mBAAmB;;AAoBzB,SAAS,YAAY,KAAwC;CAC3D,MAAM,KAAK,IAAI,OAAO;CACtB,OAAO,OAAO,OAAO,WAAW,KAAK;AACvC;;;;;;AAOA,SAAgB,oBAAoB,SAA4C;CAC9E,MAAM,EAAE,SAAS;CACjB,OAAO;EACL,UAAU,QAAQ,IAAI,QAAQ,SAAS,KAAK,YAAY,GAAG,CAAC,CAAC,SAAS;EACtE,SAAS;EACT,KAAK,OAAO,KAAK,YAAY;GAC3B,MAAM,YAAY,YAAY,GAAG;GACjC,IAAI;IACF,MAAM,SAAS,MAAM,kBAAkB,MAAM;KAAE,SAAS,IAAI;KAAS;IAAU,CAAC;IAChF,IAAI,WAAW,aACb,MAAM,aAAa,IAAI,CAAC,CAAC,cAAc,SAAS;SAEhD,QAAQ,OAAO,KAAK,EAAE,OAAO,GAAG,oBAAoB;GAExD,SAAS,OAAO;IACd,IAAI,eAAe,GAAG,GACpB,MAAM,eAAe,SAAS;KAAE;KAAW,SAAS,IAAI;KAAS;IAAM,CAAC;IAE1E,MAAM;GACR;EACF;CACF;AACF;;;;;;AAOA,SAAgB,gBACd,SACoD;CACpD,OAAO,OAAO,KAAK,UAAU;EAC3B,MAAM,eAAe,SAAS;GAAE,WAAW,YAAY,GAAG;GAAG,SAAS,IAAI;GAAS;EAAM,CAAC;CAC5F;AACF;AAEA,eAAe,eACb,SACA,SACe;CACf,MAAM,EAAE,SAAS;CACjB,MAAM,OAAO,kBAAkB,UAAU,QAAQ,KAAK,GAAG,gBAAgB;CACzE,KAAK,OAAO,MACV;EAAE,WAAW,QAAQ;EAAW,SAAS,QAAQ;EAAS,OAAO;CAAK,GACtE,yBACF;CACA,IAAI;EACF,MAAM,eAAe,SAAS;GAAE,GAAG;GAAS,OAAO;EAAK,CAAC;CAC3D,SAAS,OAAO;EACd,KAAK,OAAO,KAAK;GAAE,KAAK;GAAO,WAAW,QAAQ;EAAU,GAAG,8BAA8B;CAC/F;AACF;;AAGA,eAAe,eACb,SACA,SACe;CACf,MAAM,QAAQ,aAAa,QAAQ,IAAI;CACvC,MAAM,MAAM,MAAM,MAAM,IAAI,QAAQ,SAAS;CAC7C,IAAI,QAAQ,MACV;CAEF,MAAM,MAAM,cAAc,IAAI,IAAI,QAAQ,KAAK;CAC/C,MAAM,QAAQ,WAAW;EACvB,WAAW,IAAI;EACf,WAAW,IAAI;EACf,UAAU,IAAI;EACd,SAAS,QAAQ;EACjB,OAAO,QAAQ;CACjB,CAAC;AACH;AAEA,SAAS,UAAU,OAAwB;CACzC,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAC9D;AAEA,SAAS,aAAa,MAAgD;CACpE,OAAO,IAAI,yBACT,KAAK,IACL,EAAE,sBAAsB,KAAK,GAAG,OAAO,qBAAqB,GAC5D,KAAK,MACP;AACF;;;;;;AAYA,SAAgB,qBACd,MACA,OACgE;CAChE,OAAO,OAAO,EAAE,WAAW,cAAc;EASvC,IAAI,EANY,MADG,IAAI,gBAAgB,KAAK,EAAE,CAAC,CAAC,aAAa,OAAO,EAAA,CAC/C,MAClB,QACC,IAAI,SAAS,YACb,IAAI,WAAW,YACf,cAAc,IAAI,OAAO,CAAC,CAAC,OAAO,iBAAiB,SAE5C,GACT,MAAM,MAAM,WAAW;GACrB,MAAM;GACN;GACA,MAAM,EAAE,UAAU;GAClB,aAAA;EACF,CAAC;CAEL;AACF"}

package/dist/capture/build-state/publisher.d.mts

@@ -0,0 +1,23 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { BuildStateDeps, BuildStatePublisher } from "./types.mjs";
+//#region src/capture/build-state/publisher.d.ts
+/** What {@link createBuildStatePublisher} needs. */
+interface BuildStatePublisherOptions {
+  deps: BuildStateDeps;
+  /**
+   * Queues a `notify` job. Set when this instance (or another one) consumes the queue; absent, the
+   * state is delivered inline in the caller's request, without durability.
+   */
+  enqueue?: ((job: {
+    channelId: string;
+    buildId: string;
+  }) => Promise<void>) | undefined;
+}
+/** Logged once when the first request finds no public origin, and again after one came back and went. */
+declare const PAUSED_MESSAGE = "notifications are paused until a public URL is set (PUBLIC_BASE_URL or a confirmed detected origin)";
+/** A publisher over `options.deps`. */
+declare function createBuildStatePublisher(options: BuildStatePublisherOptions): BuildStatePublisher;
+//#endregion
+export { BuildStatePublisherOptions, PAUSED_MESSAGE, createBuildStatePublisher };
+//# sourceMappingURL=publisher.d.mts.map

package/dist/capture/build-state/publisher.mjs

@@ -0,0 +1,107 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { sanitizeErrorText } from "../../utils/redact.mjs";
+import { NotificationChannelModel } from "../../models/notification-channel.mjs";
+import { loadBuild, stateTargets, writeTo } from "./deliver.mjs";
+//#region src/capture/build-state/publisher.ts
+/**
+* The one entry point for "this build changed, show it" (ADR 0014, decisions 5 and 7). Every build
+* transition and the end of publishing call `request`; it hands each git channel of the project a
+* durable `notify` job, or, on a host with no queue consumer, delivers inline. While no public
+* origin is resolved it does neither (ADR 0014, decision 11): every link would be empty.
+*/
+/** Logged once when the first request finds no public origin, and again after one came back and went. */
+const PAUSED_MESSAGE = "notifications are paused until a public URL is set (PUBLIC_BASE_URL or a confirmed detected origin)";
+/** A publisher over `options.deps`. */
+function createBuildStatePublisher(options) {
+	const { deps } = options;
+	const pause = { logged: false };
+	return { request: async (buildId) => {
+		try {
+			const origin = await deps.publicOrigin();
+			if (!origin) {
+				logPaused(deps, pause, buildId);
+				return;
+			}
+			pause.logged = false;
+			await requestAll(options, {
+				buildId,
+				origin
+			});
+		} catch (error) {
+			deps.logger.warn({
+				err: error,
+				buildId
+			}, "failed to request the build state");
+		}
+	} };
+}
+/** Warn on the first request of a pause only. */
+function logPaused(deps, pause, buildId) {
+	if (!pause.logged) deps.logger.warn({ buildId }, PAUSED_MESSAGE);
+	pause.logged = true;
+}
+/** Ask every state channel of the build's project to show it. */
+async function requestAll(options, where) {
+	const { deps } = options;
+	const { buildId, origin } = where;
+	const loaded = await loadBuild(deps, buildId);
+	if (loaded === null) return;
+	const targets = await stateTargets(deps, loaded.project.id);
+	await Promise.allSettled(targets.map(async (target) => {
+		await requestOne(options, {
+			buildId,
+			loaded,
+			target,
+			origin
+		});
+	}));
+}
+/** Queue the delivery; inline when there is no queue, or when queueing itself failed. */
+async function requestOne(options, request) {
+	const { enqueue, deps } = options;
+	const { buildId, loaded, target, origin } = request;
+	if (enqueue !== void 0) try {
+		await enqueue({
+			channelId: target.channel.id,
+			buildId
+		});
+		return;
+	} catch (error) {
+		deps.logger.warn({
+			err: error,
+			channelId: target.channel.id,
+			buildId
+		}, "failed to queue the state delivery; delivering inline");
+	}
+	await deliverInline(deps, loaded, {
+		target,
+		origin
+	});
+}
+/** Deliver now and record the outcome on the channel; never throws. */
+async function deliverInline(deps, loaded, where) {
+	const { target } = where;
+	const channels = new NotificationChannelModel(deps.db, { notificationChannels: deps.db.tables.notificationChannels }, deps.secret);
+	let error;
+	try {
+		await writeTo(deps, loaded, where);
+	} catch (writeError) {
+		deps.logger.warn({
+			err: writeError,
+			channelId: target.channel.id
+		}, "state delivery failed");
+		error = sanitizeErrorText(writeError instanceof Error ? writeError.message : String(writeError), 500);
+	}
+	await channels.recordOutcome(target.channel.id, error).catch((recordError) => {
+		deps.logger.warn({
+			err: recordError,
+			channelId: target.channel.id
+		}, "failed to record outcome");
+	});
+}
+//#endregion
+export { PAUSED_MESSAGE, createBuildStatePublisher };
+
+//# sourceMappingURL=publisher.mjs.map

package/dist/capture/build-state/publisher.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"publisher.mjs","names":[],"sources":["../../../src/capture/build-state/publisher.ts"],"sourcesContent":["/**\n * The one entry point for \"this build changed, show it\" (ADR 0014, decisions 5 and 7). Every build\n * transition and the end of publishing call `request`; it hands each git channel of the project a\n * durable `notify` job, or, on a host with no queue consumer, delivers inline. While no public\n * origin is resolved it does neither (ADR 0014, decision 11): every link would be empty.\n */\nimport { NotificationChannelModel } from \"../../models/notification-channel.ts\";\nimport { sanitizeErrorText } from \"../../utils/redact.ts\";\nimport { loadBuild, stateTargets, writeTo } from \"./deliver.ts\";\nimport type { BuildStateDeps, BuildStatePublisher, StateTarget } from \"./types.ts\";\n\n/** What {@link createBuildStatePublisher} needs. */\nexport interface BuildStatePublisherOptions {\n  deps: BuildStateDeps;\n  /**\n   * Queues a `notify` job. Set when this instance (or another one) consumes the queue; absent, the\n   * state is delivered inline in the caller's request, without durability.\n   */\n  enqueue?: ((job: { channelId: string; buildId: string }) => Promise<void>) | undefined;\n}\n\n/** Logged once when the first request finds no public origin, and again after one came back and went. */\nexport const PAUSED_MESSAGE =\n  \"notifications are paused until a public URL is set (PUBLIC_BASE_URL or a confirmed detected origin)\";\n\n/** A publisher over `options.deps`. */\nexport function createBuildStatePublisher(\n  options: BuildStatePublisherOptions,\n): BuildStatePublisher {\n  const { deps } = options;\n  const pause = { logged: false };\n  return {\n    request: async (buildId) => {\n      try {\n        const origin = await deps.publicOrigin();\n        if (!origin) {\n          logPaused(deps, pause, buildId);\n          return;\n        }\n        pause.logged = false;\n        await requestAll(options, { buildId, origin });\n      } catch (error) {\n        deps.logger.warn({ err: error, buildId }, \"failed to request the build state\");\n      }\n    },\n  };\n}\n\n/** Warn on the first request of a pause only. */\nfunction logPaused(deps: BuildStateDeps, pause: { logged: boolean }, buildId: string): void {\n  if (!pause.logged) {\n    deps.logger.warn({ buildId }, PAUSED_MESSAGE);\n  }\n  pause.logged = true;\n}\n\n/** Ask every state channel of the build's project to show it. */\nasync function requestAll(\n  options: BuildStatePublisherOptions,\n  where: { buildId: string; origin: string },\n): Promise<void> {\n  const { deps } = options;\n  const { buildId, origin } = where;\n  const loaded = await loadBuild(deps, buildId);\n  if (loaded === null) {\n    return;\n  }\n  const targets = await stateTargets(deps, loaded.project.id);\n  await Promise.allSettled(\n    targets.map(async (target) => {\n      await requestOne(options, { buildId, loaded, target, origin });\n    }),\n  );\n}\n\n/** Queue the delivery; inline when there is no queue, or when queueing itself failed. */\nasync function requestOne(\n  options: BuildStatePublisherOptions,\n  request: {\n    buildId: string;\n    loaded: NonNullable<Awaited<ReturnType<typeof loadBuild>>>;\n    target: StateTarget;\n    origin: string;\n  },\n): Promise<void> {\n  const { enqueue, deps } = options;\n  const { buildId, loaded, target, origin } = request;\n  if (enqueue !== undefined) {\n    try {\n      await enqueue({ channelId: target.channel.id, buildId });\n      return;\n    } catch (error) {\n      deps.logger.warn(\n        { err: error, channelId: target.channel.id, buildId },\n        \"failed to queue the state delivery; delivering inline\",\n      );\n    }\n  }\n  await deliverInline(deps, loaded, { target, origin });\n}\n\n/** Deliver now and record the outcome on the channel; never throws. */\nasync function deliverInline(\n  deps: BuildStateDeps,\n  loaded: Parameters<typeof writeTo>[1],\n  where: Parameters<typeof writeTo>[2],\n): Promise<void> {\n  const { target } = where;\n  const channels = new NotificationChannelModel(\n    deps.db,\n    { notificationChannels: deps.db.tables.notificationChannels },\n    deps.secret,\n  );\n  let error: string | undefined;\n  try {\n    await writeTo(deps, loaded, where);\n  } catch (writeError) {\n    deps.logger.warn({ err: writeError, channelId: target.channel.id }, \"state delivery failed\");\n    error = sanitizeErrorText(\n      writeError instanceof Error ? writeError.message : String(writeError),\n      500,\n    );\n  }\n  await channels.recordOutcome(target.channel.id, error).catch((recordError: unknown) => {\n    deps.logger.warn(\n      { err: recordError, channelId: target.channel.id },\n      \"failed to record outcome\",\n    );\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;AAsBA,MAAa,iBACX;;AAGF,SAAgB,0BACd,SACqB;CACrB,MAAM,EAAE,SAAS;CACjB,MAAM,QAAQ,EAAE,QAAQ,MAAM;CAC9B,OAAO,EACL,SAAS,OAAO,YAAY;EAC1B,IAAI;GACF,MAAM,SAAS,MAAM,KAAK,aAAa;GACvC,IAAI,CAAC,QAAQ;IACX,UAAU,MAAM,OAAO,OAAO;IAC9B;GACF;GACA,MAAM,SAAS;GACf,MAAM,WAAW,SAAS;IAAE;IAAS;GAAO,CAAC;EAC/C,SAAS,OAAO;GACd,KAAK,OAAO,KAAK;IAAE,KAAK;IAAO;GAAQ,GAAG,mCAAmC;EAC/E;CACF,EACF;AACF;;AAGA,SAAS,UAAU,MAAsB,OAA4B,SAAuB;CAC1F,IAAI,CAAC,MAAM,QACT,KAAK,OAAO,KAAK,EAAE,QAAQ,GAAG,cAAc;CAE9C,MAAM,SAAS;AACjB;;AAGA,eAAe,WACb,SACA,OACe;CACf,MAAM,EAAE,SAAS;CACjB,MAAM,EAAE,SAAS,WAAW;CAC5B,MAAM,SAAS,MAAM,UAAU,MAAM,OAAO;CAC5C,IAAI,WAAW,MACb;CAEF,MAAM,UAAU,MAAM,aAAa,MAAM,OAAO,QAAQ,EAAE;CAC1D,MAAM,QAAQ,WACZ,QAAQ,IAAI,OAAO,WAAW;EAC5B,MAAM,WAAW,SAAS;GAAE;GAAS;GAAQ;GAAQ;EAAO,CAAC;CAC/D,CAAC,CACH;AACF;;AAGA,eAAe,WACb,SACA,SAMe;CACf,MAAM,EAAE,SAAS,SAAS;CAC1B,MAAM,EAAE,SAAS,QAAQ,QAAQ,WAAW;CAC5C,IAAI,YAAY,KAAA,GACd,IAAI;EACF,MAAM,QAAQ;GAAE,WAAW,OAAO,QAAQ;GAAI;EAAQ,CAAC;EACvD;CACF,SAAS,OAAO;EACd,KAAK,OAAO,KACV;GAAE,KAAK;GAAO,WAAW,OAAO,QAAQ;GAAI;EAAQ,GACpD,uDACF;CACF;CAEF,MAAM,cAAc,MAAM,QAAQ;EAAE;EAAQ;CAAO,CAAC;AACtD;;AAGA,eAAe,cACb,MACA,QACA,OACe;CACf,MAAM,EAAE,WAAW;CACnB,MAAM,WAAW,IAAI,yBACnB,KAAK,IACL,EAAE,sBAAsB,KAAK,GAAG,OAAO,qBAAqB,GAC5D,KAAK,MACP;CACA,IAAI;CACJ,IAAI;EACF,MAAM,QAAQ,MAAM,QAAQ,KAAK;CACnC,SAAS,YAAY;EACnB,KAAK,OAAO,KAAK;GAAE,KAAK;GAAY,WAAW,OAAO,QAAQ;EAAG,GAAG,uBAAuB;EAC3F,QAAQ,kBACN,sBAAsB,QAAQ,WAAW,UAAU,OAAO,UAAU,GACpE,GACF;CACF;CACA,MAAM,SAAS,cAAc,OAAO,QAAQ,IAAI,KAAK,CAAC,CAAC,OAAO,gBAAyB;EACrF,KAAK,OAAO,KACV;GAAE,KAAK;GAAa,WAAW,OAAO,QAAQ;EAAG,GACjD,0BACF;CACF,CAAC;AACH"}

package/dist/capture/build-state/resume.d.mts

@@ -0,0 +1,9 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { BuildStateDeps, BuildStatePublisher } from "./types.mjs";
+//#region src/capture/build-state/resume.d.ts
+/** Ask `publisher` for the state of every open recent build; resolves to how many were asked. Never rejects. */
+declare function requestOpenBuildStates(deps: Pick<BuildStateDeps, "db" | "logger">, publisher: BuildStatePublisher): Promise<number>;
+//#endregion
+export { requestOpenBuildStates };
+//# sourceMappingURL=resume.d.mts.map

package/dist/capture/build-state/resume.mjs

@@ -0,0 +1,47 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { BuildModel } from "../../models/build.mjs";
+import { ProjectModel } from "../../models/project.mjs";
+import { LOCAL_SHA_PREFIX } from "@storyshelf/affected";
+//#region src/capture/build-state/resume.ts
+/**
+* Re-requesting the state of builds still open. Requests made while no public origin was resolved
+* were dropped (ADR 0014, decision 11), so once one is, the builds that can still change are asked
+* again; settled builds keep what they last showed until their next transition.
+*/
+/** Builds that have not reached a verdict. */
+const OPEN = /* @__PURE__ */ new Set([
+	"pending",
+	"capturing",
+	"comparing",
+	"reviewing"
+]);
+/** Newest builds looked at per project. */
+const PER_PROJECT = 25;
+/** Ask `publisher` for the state of every open recent build; resolves to how many were asked. Never rejects. */
+async function requestOpenBuildStates(deps, publisher) {
+	try {
+		const projects = await new ProjectModel(deps.db).list();
+		const ids = (await Promise.all(projects.map(async (project) => await openBuildIds(deps, project.id)))).flat();
+		await Promise.all(ids.map(async (id) => {
+			await publisher.request(id);
+		}));
+		return ids.length;
+	} catch (error) {
+		deps.logger.warn({ err: error }, "failed to re-request the state of open builds");
+		return 0;
+	}
+}
+/** The newest builds of a project that have not reached a verdict. */
+async function openBuildIds(deps, projectId) {
+	return (await new BuildModel(deps.db).list(projectId, { limit: PER_PROJECT })).filter((build) => OPEN.has(build.status) && hasGitCommit(build.gitSha)).map((build) => build.id);
+}
+/** A build with no commit, or a local upload, has no git state to show (see `statusesForBuild`). */
+function hasGitCommit(gitSha) {
+	return gitSha.length > 0 && !gitSha.startsWith(LOCAL_SHA_PREFIX);
+}
+//#endregion
+export { requestOpenBuildStates };
+
+//# sourceMappingURL=resume.mjs.map

package/dist/capture/build-state/resume.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume.mjs","names":[],"sources":["../../../src/capture/build-state/resume.ts"],"sourcesContent":["/**\n * Re-requesting the state of builds still open. Requests made while no public origin was resolved\n * were dropped (ADR 0014, decision 11), so once one is, the builds that can still change are asked\n * again; settled builds keep what they last showed until their next transition.\n */\nimport { LOCAL_SHA_PREFIX } from \"@storyshelf/affected\";\nimport { BuildModel } from \"../../models/build.ts\";\nimport { ProjectModel } from \"../../models/project.ts\";\nimport type { BuildStatus } from \"../../types.ts\";\nimport type { BuildStateDeps, BuildStatePublisher } from \"./types.ts\";\n\n/** Builds that have not reached a verdict. */\nconst OPEN: ReadonlySet<BuildStatus> = new Set([\"pending\", \"capturing\", \"comparing\", \"reviewing\"]);\n\n/** Newest builds looked at per project. */\nconst PER_PROJECT = 25;\n\n/** Ask `publisher` for the state of every open recent build; resolves to how many were asked. Never rejects. */\nexport async function requestOpenBuildStates(\n  deps: Pick<BuildStateDeps, \"db\" | \"logger\">,\n  publisher: BuildStatePublisher,\n): Promise<number> {\n  try {\n    const projects = await new ProjectModel(deps.db).list();\n    const lists = await Promise.all(\n      projects.map(async (project) => await openBuildIds(deps, project.id)),\n    );\n    const ids = lists.flat();\n    await Promise.all(\n      ids.map(async (id) => {\n        await publisher.request(id);\n      }),\n    );\n    return ids.length;\n  } catch (error) {\n    deps.logger.warn({ err: error }, \"failed to re-request the state of open builds\");\n    return 0;\n  }\n}\n\n/** The newest builds of a project that have not reached a verdict. */\nasync function openBuildIds(\n  deps: Pick<BuildStateDeps, \"db\">,\n  projectId: string,\n): Promise<string[]> {\n  const recent = await new BuildModel(deps.db).list(projectId, { limit: PER_PROJECT });\n  return recent\n    .filter((build) => OPEN.has(build.status) && hasGitCommit(build.gitSha))\n    .map((build) => build.id);\n}\n\n/** A build with no commit, or a local upload, has no git state to show (see `statusesForBuild`). */\nfunction hasGitCommit(gitSha: string): boolean {\n  return gitSha.length > 0 && !gitSha.startsWith(LOCAL_SHA_PREFIX);\n}\n"],"mappings":";;;;;;;;;;;;;AAYA,MAAM,uBAAiC,IAAI,IAAI;CAAC;CAAW;CAAa;CAAa;AAAW,CAAC;;AAGjG,MAAM,cAAc;;AAGpB,eAAsB,uBACpB,MACA,WACiB;CACjB,IAAI;EACF,MAAM,WAAW,MAAM,IAAI,aAAa,KAAK,EAAE,CAAC,CAAC,KAAK;EAItD,MAAM,OAAM,MAHQ,QAAQ,IAC1B,SAAS,IAAI,OAAO,YAAY,MAAM,aAAa,MAAM,QAAQ,EAAE,CAAC,CACtE,EAAA,CACkB,KAAK;EACvB,MAAM,QAAQ,IACZ,IAAI,IAAI,OAAO,OAAO;GACpB,MAAM,UAAU,QAAQ,EAAE;EAC5B,CAAC,CACH;EACA,OAAO,IAAI;CACb,SAAS,OAAO;EACd,KAAK,OAAO,KAAK,EAAE,KAAK,MAAM,GAAG,+CAA+C;EAChF,OAAO;CACT;AACF;;AAGA,eAAe,aACb,MACA,WACmB;CAEnB,QAAO,MADc,IAAI,WAAW,KAAK,EAAE,CAAC,CAAC,KAAK,WAAW,EAAE,OAAO,YAAY,CAAC,EAAA,CAEhF,QAAQ,UAAU,KAAK,IAAI,MAAM,MAAM,KAAK,aAAa,MAAM,MAAM,CAAC,CAAC,CACvE,KAAK,UAAU,MAAM,EAAE;AAC5B;;AAGA,SAAS,aAAa,QAAyB;CAC7C,OAAO,OAAO,SAAS,KAAK,CAAC,OAAO,WAAW,gBAAgB;AACjE"}

package/dist/capture/build-state/types.d.mts

@@ -0,0 +1,49 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DatabaseAdapter } from "../../adapter/database.mjs";
+import { Logger } from "../../logger.mjs";
+import { NotificationChannel } from "../../adapters/notifier/types.mjs";
+import { NotifierProvider, StateNotifierProvider } from "../../adapters/notifier/provider.mjs";
+import { StorageAdapter } from "../../adapter/storage.mjs";
+import { ShelfConfig } from "../../config.mjs";
+import { BuildStateFlags } from "../../adapters/notifier/build-state.mjs";
+import { SecretInput } from "../../utils/encrypt.mjs";
+import { Project } from "../../schema/project.mjs";
+//#region src/capture/build-state/types.d.ts
+/** What delivering a build's state needs. */
+interface BuildStateDeps {
+  db: DatabaseAdapter;
+  /** Read to tell whether the build's Storybook is published; without it publishing reads as pending. */
+  storage?: StorageAdapter | undefined;
+  /** Notifier providers; only the `state` ones (git hosts) take part. */
+  notifiers: readonly NotifierProvider[];
+  /** Server secret that decrypts channel tokens. */
+  secret: SecretInput;
+  /** The published-Storybook domain for Storybook links. */
+  config: Pick<ShelfConfig, "publishedBaseDomain">;
+  /**
+   * The resolved public origin (ADR 0007, decision 6): the origin every link starts with. While it
+   * resolves to nothing, no state is requested or delivered (ADR 0014, decision 11).
+   */
+  publicOrigin: () => Promise<string | undefined>;
+  /** Which statuses a project's builds show: `testing` from the server options, review from the project. */
+  flags: (project: Project) => BuildStateFlags;
+  logger: Logger;
+}
+/** A channel with the provider that delivers to it. */
+interface StateTarget {
+  channel: NotificationChannel;
+  provider: StateNotifierProvider;
+}
+/** Why a delivery wrote nothing. */
+type SkipReason = "no-build" | "no-channel" | "disabled" | "no-provider" | "no-origin";
+/**
+ * Asks for a build's current state to be shown on its project's git channels. Never rejects: the
+ * request that triggered it must not fail because a git host did.
+ */
+interface BuildStatePublisher {
+  request(buildId: string): Promise<void>;
+}
+//#endregion
+export { BuildStateDeps, BuildStatePublisher, SkipReason, StateTarget };
+//# sourceMappingURL=types.d.mts.map

package/dist/capture/catalog/catalogue.d.mts

@@ -0,0 +1,22 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DatabaseAdapter } from "../../adapter/database.mjs";
+import { StorageAdapter } from "../../adapter/storage.mjs";
+import { Catalog } from "./types.mjs";
+//#region src/capture/catalog/catalogue.d.ts
+/** What cataloguing reads and writes. */
+interface CatalogDeps {
+  db: DatabaseAdapter;
+  storage: StorageAdapter;
+}
+/**
+ * Catalogue a build from its published statics: replace its `build_components` rows, then persist
+ * `catalog.json`. Resolves to the catalog, or null when the build has no readable index
+ * (statics purged, or not a Storybook), in which case nothing is written.
+ */
+declare function catalogueBuild(deps: CatalogDeps, projectId: string, buildId: string): Promise<Catalog | null>;
+/** A build's persisted catalog, or null when it has none (or an unreadable one). */
+declare function readCatalog(storage: StorageAdapter, projectId: string, buildId: string): Promise<Catalog | null>;
+//#endregion
+export { CatalogDeps, catalogueBuild, readCatalog };
+//# sourceMappingURL=catalogue.d.mts.map

package/dist/capture/catalog/catalogue.mjs

@@ -0,0 +1,53 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { catalogPath } from "../../paths.mjs";
+import { BuildComponentModel } from "../../models/build-component.mjs";
+import { groupComponents, toBuildComponent } from "./components.mjs";
+import { parseStorybookIndexText } from "./parse.mjs";
+import { readPublishedFile } from "./read.mjs";
+//#region src/capture/catalog/catalogue.ts
+/** Index files a Storybook may publish, newest format first. */
+const INDEX_FILES = ["index.json", "stories.json"];
+/**
+* Catalogue a build from its published statics: replace its `build_components` rows, then persist
+* `catalog.json`. Resolves to the catalog, or null when the build has no readable index
+* (statics purged, or not a Storybook), in which case nothing is written.
+*/
+async function catalogueBuild(deps, projectId, buildId) {
+	const entries = await readIndexEntries(deps.storage, projectId, buildId);
+	if (!entries) return null;
+	const catalog = {
+		v: 1,
+		entries
+	};
+	await new BuildComponentModel(deps.db).replaceForBuild(projectId, buildId, groupComponents(entries).map((component) => toBuildComponent(component)));
+	await deps.storage.write(catalogPath(projectId, buildId), Buffer.from(JSON.stringify(catalog)));
+	return catalog;
+}
+/** A build's persisted catalog, or null when it has none (or an unreadable one). */
+async function readCatalog(storage, projectId, buildId) {
+	const path = catalogPath(projectId, buildId);
+	try {
+		if (!await storage.exists(path)) return null;
+		const parsed = JSON.parse((await storage.read(path)).toString("utf8"));
+		return parsed.v === 1 && Array.isArray(parsed.entries) ? {
+			v: 1,
+			entries: parsed.entries
+		} : null;
+	} catch {
+		return null;
+	}
+}
+async function readIndexEntries(storage, projectId, buildId) {
+	for (const name of INDEX_FILES) {
+		const file = await readPublishedFile(storage, projectId, buildId, name).catch(() => null);
+		const entries = file ? parseStorybookIndexText(file.toString("utf8")) : null;
+		if (entries) return entries;
+	}
+	return null;
+}
+//#endregion
+export { catalogueBuild, readCatalog };
+
+//# sourceMappingURL=catalogue.mjs.map

package/dist/capture/catalog/catalogue.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalogue.mjs","names":[],"sources":["../../../src/capture/catalog/catalogue.ts"],"sourcesContent":["/** Cataloguing a published build: read its Storybook index, persist `catalog.json` and component rows. */\nimport type { DatabaseAdapter } from \"../../adapters/database.ts\";\nimport type { StorageAdapter } from \"../../adapters/storage.ts\";\nimport { BuildComponentModel } from \"../../models/build-component.ts\";\nimport { catalogPath } from \"../../utils/paths.ts\";\nimport { groupComponents, toBuildComponent } from \"./components.ts\";\nimport { parseStorybookIndexText } from \"./parse.ts\";\nimport { readPublishedFile } from \"./read.ts\";\nimport type { Catalog, CatalogEntry } from \"./types.ts\";\n\n/** What cataloguing reads and writes. */\nexport interface CatalogDeps {\n  db: DatabaseAdapter;\n  storage: StorageAdapter;\n}\n\n/** Index files a Storybook may publish, newest format first. */\nconst INDEX_FILES = [\"index.json\", \"stories.json\"] as const;\n\n/**\n * Catalogue a build from its published statics: replace its `build_components` rows, then persist\n * `catalog.json`. Resolves to the catalog, or null when the build has no readable index\n * (statics purged, or not a Storybook), in which case nothing is written.\n */\nexport async function catalogueBuild(\n  deps: CatalogDeps,\n  projectId: string,\n  buildId: string,\n): Promise<Catalog | null> {\n  const entries = await readIndexEntries(deps.storage, projectId, buildId);\n  if (!entries) {\n    return null;\n  }\n  const catalog: Catalog = { v: 1, entries };\n  // The rows go first: catalog.json is the marker that cataloguing finished, so a crash between the\n  // two leaves a build the lazy loader catalogues again, never one with a catalog and no rows.\n  await new BuildComponentModel(deps.db).replaceForBuild(\n    projectId,\n    buildId,\n    groupComponents(entries).map((component) => toBuildComponent(component)),\n  );\n  await deps.storage.write(catalogPath(projectId, buildId), Buffer.from(JSON.stringify(catalog)));\n  return catalog;\n}\n\n/** A build's persisted catalog, or null when it has none (or an unreadable one). */\nexport async function readCatalog(\n  storage: StorageAdapter,\n  projectId: string,\n  buildId: string,\n): Promise<Catalog | null> {\n  const path = catalogPath(projectId, buildId);\n  try {\n    if (!(await storage.exists(path))) {\n      return null;\n    }\n    const parsed = JSON.parse((await storage.read(path)).toString(\"utf8\")) as Partial<Catalog>;\n    return parsed.v === 1 && Array.isArray(parsed.entries)\n      ? { v: 1, entries: parsed.entries }\n      : null;\n  } catch {\n    return null;\n  }\n}\n\nasync function readIndexEntries(\n  storage: StorageAdapter,\n  projectId: string,\n  buildId: string,\n): Promise<CatalogEntry[] | null> {\n  for (const name of INDEX_FILES) {\n    // eslint-disable-next-line no-await-in-loop -- stop at the first index that parses\n    const file = await readPublishedFile(storage, projectId, buildId, name).catch(() => null);\n    const entries = file ? parseStorybookIndexText(file.toString(\"utf8\")) : null;\n    if (entries) {\n      return entries;\n    }\n  }\n  return null;\n}\n"],"mappings":";;;;;;;;;;AAiBA,MAAM,cAAc,CAAC,cAAc,cAAc;;;;;;AAOjD,eAAsB,eACpB,MACA,WACA,SACyB;CACzB,MAAM,UAAU,MAAM,iBAAiB,KAAK,SAAS,WAAW,OAAO;CACvE,IAAI,CAAC,SACH,OAAO;CAET,MAAM,UAAmB;EAAE,GAAG;EAAG;CAAQ;CAGzC,MAAM,IAAI,oBAAoB,KAAK,EAAE,CAAC,CAAC,gBACrC,WACA,SACA,gBAAgB,OAAO,CAAC,CAAC,KAAK,cAAc,iBAAiB,SAAS,CAAC,CACzE;CACA,MAAM,KAAK,QAAQ,MAAM,YAAY,WAAW,OAAO,GAAG,OAAO,KAAK,KAAK,UAAU,OAAO,CAAC,CAAC;CAC9F,OAAO;AACT;;AAGA,eAAsB,YACpB,SACA,WACA,SACyB;CACzB,MAAM,OAAO,YAAY,WAAW,OAAO;CAC3C,IAAI;EACF,IAAI,CAAE,MAAM,QAAQ,OAAO,IAAI,GAC7B,OAAO;EAET,MAAM,SAAS,KAAK,OAAO,MAAM,QAAQ,KAAK,IAAI,EAAA,CAAG,SAAS,MAAM,CAAC;EACrE,OAAO,OAAO,MAAM,KAAK,MAAM,QAAQ,OAAO,OAAO,IACjD;GAAE,GAAG;GAAG,SAAS,OAAO;EAAQ,IAChC;CACN,QAAQ;EACN,OAAO;CACT;AACF;AAEA,eAAe,iBACb,SACA,WACA,SACgC;CAChC,KAAK,MAAM,QAAQ,aAAa;EAE9B,MAAM,OAAO,MAAM,kBAAkB,SAAS,WAAW,SAAS,IAAI,CAAC,CAAC,YAAY,IAAI;EACxF,MAAM,UAAU,OAAO,wBAAwB,KAAK,SAAS,MAAM,CAAC,IAAI;EACxE,IAAI,SACF,OAAO;CAEX;CACA,OAAO;AACT"}

package/dist/capture/catalog/components.d.mts

@@ -0,0 +1,23 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { CatalogComponent, CatalogEntry } from "./types.mjs";
+import { BuildComponentInput } from "../../models/build-component.mjs";
+//#region src/capture/catalog/components.d.ts
+/** Group entries by story file (entries without one by title), ordered by title then file. */
+declare function groupComponents(entries: readonly CatalogEntry[]): CatalogComponent[];
+/** What `build_components` stores of a component. */
+declare function toBuildComponent(component: CatalogComponent): BuildComponentInput;
+/** SHA-256 over the entries' id, name, type and title, in id order: equal sets hash equal. */
+declare function hashEntries(entries: readonly CatalogEntry[]): string;
+/** How one component's entries differ between two builds. */
+interface EntryChanges {
+  added: number;
+  removed: number;
+  /** Same id, new display name. */
+  renamed: number;
+}
+/** Entries added, removed and renamed from `before` to `after` (matched by entry id). */
+declare function diffEntries(before: readonly CatalogEntry[], after: readonly CatalogEntry[]): EntryChanges;
+//#endregion
+export { EntryChanges, diffEntries, groupComponents, hashEntries, toBuildComponent };
+//# sourceMappingURL=components.d.mts.map

package/dist/capture/catalog/components.mjs

@@ -0,0 +1,55 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { createHash } from "node:crypto";
+//#region src/capture/catalog/components.ts
+/** Catalog entries grouped into components, hashed, and compared between builds. */
+/** Group entries by story file (entries without one by title), ordered by title then file. */
+function groupComponents(entries) {
+	return [...Map.groupBy(entries, (entry) => entry.importPath || `title:${entry.title}`).values()].map((group) => {
+		const [first] = group;
+		return {
+			importPath: first?.importPath ?? "",
+			title: first?.title ?? "",
+			storyCount: group.filter((entry) => entry.type === "story").length,
+			hash: hashEntries(group),
+			entries: group
+		};
+	}).toSorted((a, b) => a.title.localeCompare(b.title) || a.importPath.localeCompare(b.importPath));
+}
+/** What `build_components` stores of a component. */
+function toBuildComponent(component) {
+	const { importPath, title, storyCount, hash } = component;
+	return {
+		importPath,
+		title,
+		storyCount,
+		hash
+	};
+}
+/** SHA-256 over the entries' id, name, type and title, in id order: equal sets hash equal. */
+function hashEntries(entries) {
+	const lines = entries.map((entry) => [
+		entry.id,
+		entry.name,
+		entry.type,
+		entry.title
+	].join("	")).toSorted();
+	return createHash("sha256").update(lines.join("\n")).digest("hex");
+}
+/** Entries added, removed and renamed from `before` to `after` (matched by entry id). */
+function diffEntries(before, after) {
+	const was = new Map(before.map((entry) => [entry.id, entry]));
+	const now = new Map(after.map((entry) => [entry.id, entry]));
+	let renamed = 0;
+	for (const [id, entry] of now) if (was.has(id) && was.get(id)?.name !== entry.name) renamed += 1;
+	return {
+		added: [...now.keys()].filter((id) => !was.has(id)).length,
+		removed: [...was.keys()].filter((id) => !now.has(id)).length,
+		renamed
+	};
+}
+//#endregion
+export { diffEntries, groupComponents, hashEntries, toBuildComponent };
+
+//# sourceMappingURL=components.mjs.map