@storyshelf/core 0.6.2 → 0.8.0

package/dist/capture/attempt-logger.mjs

@@ -0,0 +1,83 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { redactSecrets } from "../utils/redact.mjs";
+import { emitAttemptLog } from "../models/capture-attempt.mjs";
+// src/capture/attempt-logger.ts
+/** Longest error text recorded on an attempt-log line. */
+const ERROR_TEXT_MAX = 500;
+/** Mirrored levels; `debug` stays in pino only so attempt logs keep the signal. */
+const MIRRORED_LEVELS = [
+	"info",
+	"warn",
+	"error"
+];
+/**
+* Mirror a logger's `info`/`warn`/`error` lines onto the attempt log.
+*
+* Writes go through one promise chain: `capture_logs` numbers lines with a
+* read-then-insert, so concurrent appends (parallel pages failing at once)
+* would collide on `seq`. With no recorder the logger is returned unchanged.
+*/
+function mirrorAttemptLog(logger, record, levelFor = (level) => level) {
+	let chain = Promise.resolve();
+	const enqueue = (level, message, fields) => {
+		if (!record) return;
+		const recorded = levelFor(level, fields);
+		chain = chain.then(async () => {
+			await emitAttemptLog(record, logger, recorded, message, fields);
+		});
+	};
+	const base = logger ?? silentLogger();
+	return {
+		logger: new Proxy(base, { get(target, property, receiver) {
+			const level = MIRRORED_LEVELS.find((name) => name === property);
+			if (!level) return Reflect.get(target, property, receiver);
+			return (first, second, ...rest) => {
+				const args = [
+					first,
+					second,
+					...rest
+				];
+				while (args.length > 1 && args.at(-1) === void 0) args.pop();
+				Reflect.apply(target[level], target, args);
+				const [fields, message] = parseArgs(first, second);
+				enqueue(level, message, fields);
+			};
+		} }),
+		log: (level, message, fields) => {
+			base[level](fields ?? {}, message);
+			enqueue(level, message, fields === void 0 ? void 0 : plainFields(fields));
+		},
+		flush: async () => {
+			await chain;
+		}
+	};
+}
+/** pino call shapes: `(fields, message)` or `(message)`. */
+function parseArgs(first, second) {
+	if (typeof first === "string") return [void 0, first];
+	return [first && typeof first === "object" ? plainFields(first) : void 0, typeof second === "string" ? second : ""];
+}
+/** JSON-safe copy: an `Error` under `err` becomes its capped message. */
+function plainFields(fields) {
+	const copy = { ...fields };
+	const err = copy["err"];
+	if (err instanceof Error) copy["err"] = redactSecrets(err.message).slice(0, ERROR_TEXT_MAX);
+	return copy;
+}
+function noop() {}
+/** Stand-in when no logger was configured, so callers can log unconditionally. */
+function silentLogger() {
+	const stub = {
+		info: noop,
+		warn: noop,
+		error: noop,
+		debug: noop
+	};
+	stub["child"] = () => stub;
+	return stub;
+}
+export { mirrorAttemptLog };
+
+//# sourceMappingURL=attempt-logger.mjs.map

package/dist/capture/attempt-logger.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt-logger.mjs","names":[],"sources":["../../src/capture/attempt-logger.ts"],"sourcesContent":["import type { Logger } from \"pino\";\nimport { emitAttemptLog, type AttemptLogRecorder } from \"../models/capture-attempt.ts\";\nimport type { CaptureLogLevel } from \"../schema/capture-attempt.ts\";\nimport { redactSecrets } from \"../utils/redact.ts\";\n\n/** Longest error text recorded on an attempt-log line. */\nconst ERROR_TEXT_MAX = 500;\n\n/** Mirrored levels; `debug` stays in pino only so attempt logs keep the signal. */\nconst MIRRORED_LEVELS = [\"info\", \"warn\", \"error\"] as const;\n\n/** A logger that also records `info`/`warn`/`error` lines on the build attempt. */\nexport interface AttemptMirror {\n  /** Logger to hand to a runner: same as the original, plus attempt-log recording. */\n  logger: Logger;\n  /** Record one line on the attempt (and in pino); serialized with the mirrored lines. */\n  log(level: CaptureLogLevel, message: string, fields?: Record<string, unknown>): void;\n  /** Wait for every recorded line to be written. */\n  flush(): Promise<void>;\n}\n\n/**\n * Mirror a logger's `info`/`warn`/`error` lines onto the attempt log.\n *\n * Writes go through one promise chain: `capture_logs` numbers lines with a\n * read-then-insert, so concurrent appends (parallel pages failing at once)\n * would collide on `seq`. With no recorder the logger is returned unchanged.\n */\nexport function mirrorAttemptLog(\n  logger: Logger | undefined,\n  record: AttemptLogRecorder | undefined,\n  /** Optionally re-level a recorded line (pino keeps the original level). */\n  levelFor: (level: CaptureLogLevel, fields?: Record<string, unknown>) => CaptureLogLevel = (\n    level,\n  ) => level,\n): AttemptMirror {\n  let chain: Promise<void> = Promise.resolve();\n  const enqueue = (level: CaptureLogLevel, message: string, fields?: unknown): void => {\n    if (!record) return;\n    const recorded = levelFor(level, fields as Record<string, unknown> | undefined);\n    chain = chain.then(async () => {\n      await emitAttemptLog(record, logger, recorded, message, fields);\n    });\n  };\n  const base = logger ?? silentLogger();\n  const mirrored = new Proxy(base, {\n    get(target, property, receiver): unknown {\n      const level = MIRRORED_LEVELS.find((name) => name === property);\n      if (!level) return Reflect.get(target, property, receiver);\n      return (first: unknown, second?: unknown, ...rest: unknown[]): void => {\n        const args = [first, second, ...rest];\n        while (args.length > 1 && args.at(-1) === undefined) args.pop();\n        Reflect.apply(target[level], target, args);\n        const [fields, message] = parseArgs(first, second);\n        enqueue(level, message, fields);\n      };\n    },\n  });\n  return {\n    logger: mirrored,\n    log: (level, message, fields) => {\n      base[level](fields ?? {}, message);\n      enqueue(level, message, fields === undefined ? undefined : plainFields(fields));\n    },\n    flush: async () => {\n      await chain;\n    },\n  };\n}\n\n/** pino call shapes: `(fields, message)` or `(message)`. */\nfunction parseArgs(first: unknown, second: unknown): [Record<string, unknown> | undefined, string] {\n  if (typeof first === \"string\") return [undefined, first];\n  const fields = first && typeof first === \"object\" ? plainFields(first) : undefined;\n  return [fields, typeof second === \"string\" ? second : \"\"];\n}\n\n/** JSON-safe copy: an `Error` under `err` becomes its capped message. */\nfunction plainFields(fields: object): Record<string, unknown> {\n  const copy: Record<string, unknown> = { ...fields };\n  const err = copy[\"err\"];\n  if (err instanceof Error) copy[\"err\"] = redactSecrets(err.message).slice(0, ERROR_TEXT_MAX);\n  return copy;\n}\n\nfunction noop(): void {}\n\n/** Stand-in when no logger was configured, so callers can log unconditionally. */\nfunction silentLogger(): Logger {\n  const stub: Record<string, unknown> = { info: noop, warn: noop, error: noop, debug: noop };\n  stub[\"child\"] = (): unknown => stub;\n  return stub as unknown as Logger;\n}\n"],"mappings":";;;;;;;AAMA,MAAM,iBAAiB;;AAGvB,MAAM,kBAAkB;CAAC;CAAQ;CAAQ;AAAO;;;;;;;;AAmBhD,SAAgB,iBACd,QACA,QAEA,YACE,UACG,OACU;CACf,IAAI,QAAuB,QAAQ,QAAQ;CAC3C,MAAM,WAAW,OAAwB,SAAiB,WAA2B;EACnF,IAAI,CAAC,QAAQ;EACb,MAAM,WAAW,SAAS,OAAO,MAA6C;EAC9E,QAAQ,MAAM,KAAK,YAAY;GAC7B,MAAM,eAAe,QAAQ,QAAQ,UAAU,SAAS,MAAM;EAChE,CAAC;CACH;CACA,MAAM,OAAO,UAAU,aAAa;CAcpC,OAAO;EACL,QAAQ,IAdW,MAAM,MAAM,EAC/B,IAAI,QAAQ,UAAU,UAAmB;GACvC,MAAM,QAAQ,gBAAgB,MAAM,SAAS,SAAS,QAAQ;GAC9D,IAAI,CAAC,OAAO,OAAO,QAAQ,IAAI,QAAQ,UAAU,QAAQ;GACzD,QAAQ,OAAgB,QAAkB,GAAG,SAA0B;IACrE,MAAM,OAAO;KAAC;KAAO;KAAQ,GAAG;IAAI;IACpC,OAAO,KAAK,SAAS,KAAK,KAAK,GAAG,EAAE,MAAM,KAAA,GAAW,KAAK,IAAI;IAC9D,QAAQ,MAAM,OAAO,QAAQ,QAAQ,IAAI;IACzC,MAAM,CAAC,QAAQ,WAAW,UAAU,OAAO,MAAM;IACjD,QAAQ,OAAO,SAAS,MAAM;GAChC;EACF,EACF,CAEiB;EACf,MAAM,OAAO,SAAS,WAAW;GAC/B,KAAK,MAAM,CAAC,UAAU,CAAC,GAAG,OAAO;GACjC,QAAQ,OAAO,SAAS,WAAW,KAAA,IAAY,KAAA,IAAY,YAAY,MAAM,CAAC;EAChF;EACA,OAAO,YAAY;GACjB,MAAM;EACR;CACF;AACF;;AAGA,SAAS,UAAU,OAAgB,QAAgE;CACjG,IAAI,OAAO,UAAU,UAAU,OAAO,CAAC,KAAA,GAAW,KAAK;CAEvD,OAAO,CADQ,SAAS,OAAO,UAAU,WAAW,YAAY,KAAK,IAAI,KAAA,GACzD,OAAO,WAAW,WAAW,SAAS,EAAE;AAC1D;;AAGA,SAAS,YAAY,QAAyC;CAC5D,MAAM,OAAgC,EAAE,GAAG,OAAO;CAClD,MAAM,MAAM,KAAK;CACjB,IAAI,eAAe,OAAO,KAAK,SAAS,cAAc,IAAI,OAAO,CAAC,CAAC,MAAM,GAAG,cAAc;CAC1F,OAAO;AACT;AAEA,SAAS,OAAa,CAAC;;AAGvB,SAAS,eAAuB;CAC9B,MAAM,OAAgC;EAAE,MAAM;EAAM,MAAM;EAAM,OAAO;EAAM,OAAO;CAAK;CACzF,KAAK,iBAA0B;CAC/B,OAAO;AACT"}

package/dist/capture/browsers.d.mts

@@ -0,0 +1,33 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { CaptureTarget, RunnerTarget } from "../adapters/capture-target.mjs";
+/** Upper bound on targets per project (each multiplies render time). */
+declare const MAX_BROWSERS = 3;
+/** Parse the project's JSON `browsers` column; `null` when unset or malformed. */
+declare function parseBrowsers(raw: string | null | undefined): CaptureTarget[] | null;
+/**
+ * Targets to capture, primary first: the project's `browsers` list, else its single `browser`.
+ * Throws when the list exceeds {@link MAX_BROWSERS}.
+ */
+declare function resolveBrowsers(project: {
+  browser?: string | undefined;
+  browsers?: string | null | undefined;
+}): CaptureTarget[];
+/**
+ * The primary target of a resolved target list: its first entry. The single owner of "primary":
+ * axe runs only here (ADR 0004, decision 6), so one story is not checked once per target.
+ */
+declare function primaryTargetOf(targets: readonly CaptureTarget[]): CaptureTarget | undefined;
+/** Throw when more than {@link MAX_BROWSERS} targets are requested. */
+declare function assertBrowserCount(browsers: readonly string[]): void;
+/**
+ * Why `target` cannot render on a runner offering `offered`: it is not on the list, or it is and is
+ * unavailable. `null` when it can, and always when the runner publishes no list.
+ */
+declare function refusalFor(target: CaptureTarget, offered?: readonly RunnerTarget[]): string | null;
+/** The targets of `offered`, for messages; `none` for an empty list. */
+declare function listTargets(offered: readonly RunnerTarget[]): string;
+/** Throw, naming every refusal, when the runner cannot render one of `targets`. */
+declare function assertSupportedBrowsers(targets: readonly CaptureTarget[], offered?: readonly RunnerTarget[]): void;
+export { MAX_BROWSERS, assertBrowserCount, assertSupportedBrowsers, listTargets, parseBrowsers, primaryTargetOf, refusalFor, resolveBrowsers };
+//# sourceMappingURL=browsers.d.mts.map

package/dist/capture/browsers.mjs

@@ -0,0 +1,66 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { DEFAULT_BROWSER, isCaptureTarget, unavailableReason } from "../adapters/capture-target.mjs";
+// src/capture/browsers.ts
+/** Which capture targets a project renders on, and the guards around that list (ADR 0007). */
+/** Upper bound on targets per project (each multiplies render time). */
+const MAX_BROWSERS = 3;
+/** Parse the project's JSON `browsers` column; `null` when unset or malformed. */
+function parseBrowsers(raw) {
+	if (!raw) return null;
+	try {
+		const parsed = JSON.parse(raw);
+		return Array.isArray(parsed) && parsed.every((entry) => isCaptureTarget(entry)) ? dedupe(parsed) : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Targets to capture, primary first: the project's `browsers` list, else its single `browser`.
+* Throws when the list exceeds {@link MAX_BROWSERS}.
+*/
+function resolveBrowsers(project) {
+	const listed = parseBrowsers(project.browsers);
+	const single = isCaptureTarget(project.browser) ? project.browser : DEFAULT_BROWSER;
+	const browsers = listed && listed.length > 0 ? listed : [single];
+	assertBrowserCount(browsers);
+	return browsers;
+}
+/**
+* The primary target of a resolved target list: its first entry. The single owner of "primary":
+* axe runs only here (ADR 0004, decision 6), so one story is not checked once per target.
+*/
+function primaryTargetOf(targets) {
+	return targets[0];
+}
+/** Throw when more than {@link MAX_BROWSERS} targets are requested. */
+function assertBrowserCount(browsers) {
+	if (browsers.length > 3) throw new Error(`At most 3 browsers are supported (got ${browsers.length})`);
+}
+/**
+* Why `target` cannot render on a runner offering `offered`: it is not on the list, or it is and is
+* unavailable. `null` when it can, and always when the runner publishes no list.
+*/
+function refusalFor(target, offered) {
+	if (offered === void 0) return null;
+	const entry = offered.find((candidate) => candidate.target === target);
+	if (entry === void 0) return `${target} is not offered by this capture runner (offered: ${listTargets(offered)})`;
+	const reason = unavailableReason(entry.status);
+	return reason === null ? null : `${target} is unavailable: ${reason}`;
+}
+/** The targets of `offered`, for messages; `none` for an empty list. */
+function listTargets(offered) {
+	return offered.length > 0 ? offered.map((entry) => entry.target).join(", ") : "none";
+}
+/** Throw, naming every refusal, when the runner cannot render one of `targets`. */
+function assertSupportedBrowsers(targets, offered) {
+	const refusals = targets.flatMap((target) => refusalFor(target, offered) ?? []);
+	if (refusals.length > 0) throw new Error(`Capture runner cannot render: ${refusals.join("; ")}`);
+}
+function dedupe(browsers) {
+	return [...new Set(browsers)];
+}
+export { MAX_BROWSERS, assertBrowserCount, assertSupportedBrowsers, listTargets, parseBrowsers, primaryTargetOf, refusalFor, resolveBrowsers };
+
+//# sourceMappingURL=browsers.mjs.map

package/dist/capture/browsers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"browsers.mjs","names":[],"sources":["../../src/capture/browsers.ts"],"sourcesContent":["/** Which capture targets a project renders on, and the guards around that list (ADR 0007). */\nimport {\n  DEFAULT_BROWSER,\n  isCaptureTarget,\n  unavailableReason,\n  type CaptureTarget,\n  type RunnerTarget,\n} from \"../adapters/capture-target.ts\";\n\n/** Upper bound on targets per project (each multiplies render time). */\nexport const MAX_BROWSERS = 3;\n\n/** Parse the project's JSON `browsers` column; `null` when unset or malformed. */\nexport function parseBrowsers(raw: string | null | undefined): CaptureTarget[] | null {\n  if (!raw) return null;\n  try {\n    const parsed: unknown = JSON.parse(raw);\n    return Array.isArray(parsed) && parsed.every((entry) => isCaptureTarget(entry))\n      ? dedupe(parsed)\n      : null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Targets to capture, primary first: the project's `browsers` list, else its single `browser`.\n * Throws when the list exceeds {@link MAX_BROWSERS}.\n */\nexport function resolveBrowsers(project: {\n  browser?: string | undefined;\n  browsers?: string | null | undefined;\n}): CaptureTarget[] {\n  const listed = parseBrowsers(project.browsers);\n  const single = isCaptureTarget(project.browser) ? project.browser : DEFAULT_BROWSER;\n  const browsers = listed && listed.length > 0 ? listed : [single];\n  assertBrowserCount(browsers);\n  return browsers;\n}\n\n/**\n * The primary target of a resolved target list: its first entry. The single owner of \"primary\":\n * axe runs only here (ADR 0004, decision 6), so one story is not checked once per target.\n */\nexport function primaryTargetOf(targets: readonly CaptureTarget[]): CaptureTarget | undefined {\n  return targets[0];\n}\n\n/** Throw when more than {@link MAX_BROWSERS} targets are requested. */\nexport function assertBrowserCount(browsers: readonly string[]): void {\n  if (browsers.length > MAX_BROWSERS) {\n    throw new Error(`At most ${MAX_BROWSERS} browsers are supported (got ${browsers.length})`);\n  }\n}\n\n/**\n * Why `target` cannot render on a runner offering `offered`: it is not on the list, or it is and is\n * unavailable. `null` when it can, and always when the runner publishes no list.\n */\nexport function refusalFor(\n  target: CaptureTarget,\n  offered?: readonly RunnerTarget[],\n): string | null {\n  if (offered === undefined) {\n    return null;\n  }\n  const entry = offered.find((candidate) => candidate.target === target);\n  if (entry === undefined) {\n    return `${target} is not offered by this capture runner (offered: ${listTargets(offered)})`;\n  }\n  const reason = unavailableReason(entry.status);\n  return reason === null ? null : `${target} is unavailable: ${reason}`;\n}\n\n/** The targets of `offered`, for messages; `none` for an empty list. */\nexport function listTargets(offered: readonly RunnerTarget[]): string {\n  return offered.length > 0 ? offered.map((entry) => entry.target).join(\", \") : \"none\";\n}\n\n/** Throw, naming every refusal, when the runner cannot render one of `targets`. */\nexport function assertSupportedBrowsers(\n  targets: readonly CaptureTarget[],\n  offered?: readonly RunnerTarget[],\n): void {\n  const refusals = targets.flatMap((target) => refusalFor(target, offered) ?? []);\n  if (refusals.length > 0) {\n    throw new Error(`Capture runner cannot render: ${refusals.join(\"; \")}`);\n  }\n}\n\nfunction dedupe(browsers: CaptureTarget[]): CaptureTarget[] {\n  return [...new Set(browsers)];\n}\n"],"mappings":";;;;;;;AAUA,MAAa,eAAe;;AAG5B,SAAgB,cAAc,KAAwD;CACpF,IAAI,CAAC,KAAK,OAAO;CACjB,IAAI;EACF,MAAM,SAAkB,KAAK,MAAM,GAAG;EACtC,OAAO,MAAM,QAAQ,MAAM,KAAK,OAAO,OAAO,UAAU,gBAAgB,KAAK,CAAC,IAC1E,OAAO,MAAM,IACb;CACN,QAAQ;EACN,OAAO;CACT;AACF;;;;;AAMA,SAAgB,gBAAgB,SAGZ;CAClB,MAAM,SAAS,cAAc,QAAQ,QAAQ;CAC7C,MAAM,SAAS,gBAAgB,QAAQ,OAAO,IAAI,QAAQ,UAAU;CACpE,MAAM,WAAW,UAAU,OAAO,SAAS,IAAI,SAAS,CAAC,MAAM;CAC/D,mBAAmB,QAAQ;CAC3B,OAAO;AACT;;;;;AAMA,SAAgB,gBAAgB,SAA8D;CAC5F,OAAO,QAAQ;AACjB;;AAGA,SAAgB,mBAAmB,UAAmC;CACpE,IAAI,SAAS,SAAA,GACX,MAAM,IAAI,MAAM,yCAAuD,SAAS,OAAO,EAAE;AAE7F;;;;;AAMA,SAAgB,WACd,QACA,SACe;CACf,IAAI,YAAY,KAAA,GACd,OAAO;CAET,MAAM,QAAQ,QAAQ,MAAM,cAAc,UAAU,WAAW,MAAM;CACrE,IAAI,UAAU,KAAA,GACZ,OAAO,GAAG,OAAO,mDAAmD,YAAY,OAAO,EAAE;CAE3F,MAAM,SAAS,kBAAkB,MAAM,MAAM;CAC7C,OAAO,WAAW,OAAO,OAAO,GAAG,OAAO,mBAAmB;AAC/D;;AAGA,SAAgB,YAAY,SAA0C;CACpE,OAAO,QAAQ,SAAS,IAAI,QAAQ,KAAK,UAAU,MAAM,MAAM,CAAC,CAAC,KAAK,IAAI,IAAI;AAChF;;AAGA,SAAgB,wBACd,SACA,SACM;CACN,MAAM,WAAW,QAAQ,SAAS,WAAW,WAAW,QAAQ,OAAO,KAAK,CAAC,CAAC;CAC9E,IAAI,SAAS,SAAS,GACpB,MAAM,IAAI,MAAM,iCAAiC,SAAS,KAAK,IAAI,GAAG;AAE1E;AAEA,SAAS,OAAO,UAA4C;CAC1D,OAAO,CAAC,GAAG,IAAI,IAAI,QAAQ,CAAC;AAC9B"}

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

@@ -0,0 +1,30 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Build } from "../../schema/build.mjs";
+import { Project } from "../../schema/project.mjs";
+import { BuildStateDeps, SkipReason, StateTarget } from "./types.mjs";
+/**
+ * Show the build's current state on one channel. Throws when the host refuses a status, so the
+ * caller can retry; resolves to why nothing was written when the build or channel is gone.
+ */
+declare function deliverBuildState(deps: BuildStateDeps, ids: {
+  buildId: string;
+  channelId: string;
+}): Promise<"delivered" | SkipReason>;
+/** The build and its project, or null when either is gone. */
+declare function loadBuild(deps: BuildStateDeps, buildId: string): Promise<{
+  build: Build;
+  project: Project;
+} | null>;
+/** Write `target`'s view of the build, linking to `origin`; throws on a refused status. */
+declare function writeTo(deps: BuildStateDeps, loaded: {
+  build: Build;
+  project: Project;
+}, where: {
+  target: StateTarget;
+  origin: string;
+}): Promise<void>;
+/** The project's enabled channels with a wired `state` provider; unreadable secrets are logged and skipped. */
+declare function stateTargets(deps: BuildStateDeps, projectId: string): Promise<StateTarget[]>;
+export { deliverBuildState, loadBuild, stateTargets, writeTo };
+//# sourceMappingURL=deliver.d.mts.map

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

@@ -0,0 +1,117 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { isStateProvider } from "../../adapters/notifier/provider.mjs";
+import { statusesForBuild } from "../../adapters/notifier/build-state.mjs";
+import { channelPrefix, writeBuildState } from "../../adapters/notifier/state.mjs";
+import { BuildModel } from "../../models/build.mjs";
+import { SnapshotModel } from "../../models/snapshot.mjs";
+import { ProjectModel } from "../../models/project.mjs";
+import { latestVerdicts } from "../../models/build-review-status.mjs";
+import { BuildReviewModel } from "../../models/build-review.mjs";
+import { NotificationChannelModel } from "../../models/notification-channel.mjs";
+import { createUrlBuilder } from "../../urls.mjs";
+import { publishingOf } from "../publish/published.mjs";
+// src/capture/build-state/deliver.ts
+/**
+* Delivering a build's state to git channels: read the build now, compute what each channel shows
+* ({@link statusesForBuild}), write it. Reading at delivery time is what makes a retried, delayed
+* or reordered request harmless (ADR 0014, decision 7).
+*/
+/**
+* Show the build's current state on one channel. Throws when the host refuses a status, so the
+* caller can retry; resolves to why nothing was written when the build or channel is gone.
+*/
+async function deliverBuildState(deps, ids) {
+	const loaded = await loadBuild(deps, ids.buildId);
+	const origin = loaded === null ? void 0 : await deps.publicOrigin();
+	if (loaded === null || !origin) return loaded === null ? "no-build" : "no-origin";
+	const target = await loadTarget(deps, ids.channelId, loaded.project.id);
+	if (typeof target === "string") return target;
+	await writeTo(deps, loaded, {
+		target,
+		origin
+	});
+	return "delivered";
+}
+/** The build and its project, or null when either is gone. */
+async function loadBuild(deps, buildId) {
+	const build = await new BuildModel(deps.db).get(buildId);
+	const project = build ? await new ProjectModel(deps.db).get(build.projectId) : null;
+	return build && project ? {
+		build,
+		project
+	} : null;
+}
+/** Write `target`'s view of the build, linking to `origin`; throws on a refused status. */
+async function writeTo(deps, loaded, where) {
+	const { build, project } = loaded;
+	const { target, origin } = where;
+	const states = statusesForBuild({
+		build,
+		projectSlug: project.slug,
+		prefix: channelPrefix(target.channel),
+		urls: createUrlBuilder(origin, deps.config.publishedBaseDomain),
+		flags: deps.flags(project),
+		publishing: await publishingOf(deps.storage, build),
+		approvals: await approvalsOf(deps, build, project),
+		changes: await changesOf(deps, build, project)
+	});
+	if (states.statuses.length === 0) {
+		deps.logger.info({ buildId: build.id }, "no commit to show a state on");
+		return;
+	}
+	await writeBuildState(target.provider, target.channel, {
+		sha: build.gitSha,
+		states,
+		logger: deps.logger
+	});
+}
+/** The project's enabled channels with a wired `state` provider; unreadable secrets are logged and skipped. */
+async function stateTargets(deps, projectId) {
+	const model = channelModel(deps);
+	return (await model.list(projectId)).flatMap((row) => {
+		const view = row.enabled ? model.toView(row) : null;
+		if (row.enabled && view === null) deps.logger.warn({
+			channelId: row.id,
+			provider: row.provider
+		}, "failed to decrypt channel secret");
+		return view === null ? [] : targetOf(deps, view);
+	});
+}
+/** One channel by id, or why it cannot take part. */
+async function loadTarget(deps, channelId, projectId) {
+	const model = channelModel(deps);
+	const row = await model.get(channelId);
+	if (row === null || row.projectId !== projectId) return "no-channel";
+	if (!row.enabled) return "disabled";
+	const view = model.toView(row);
+	if (view === null) throw new Error("channel secret cannot be decrypted with the configured keys");
+	return targetOf(deps, view)[0] ?? "no-provider";
+}
+function targetOf(deps, channel) {
+	const provider = deps.notifiers.find((candidate) => candidate.metadata.kind === channel.provider);
+	return provider !== void 0 && isStateProvider(provider) ? [{
+		channel,
+		provider
+	}] : [];
+}
+function channelModel(deps) {
+	return new NotificationChannelModel(deps.db, { notificationChannels: deps.db.tables.notificationChannels }, deps.secret);
+}
+/** Approval progress for `<prefix>/review`; only read when that status is the gate. */
+async function approvalsOf(deps, build, project) {
+	const flags = deps.flags(project);
+	if (flags.testing || !flags.review) return;
+	return {
+		given: latestVerdicts(await new BuildReviewModel(deps.db).listByBuild(build.id)).filter((review) => review.verdict === "approved").length,
+		required: Math.max(1, project.reviewApprovals ?? 1)
+	};
+}
+/** The build's snapshots for the annotations; read only when `testing` is on and something changed. */
+async function changesOf(deps, build, project) {
+	return deps.flags(project).testing && build.changedCount > 0 ? await new SnapshotModel(deps.db).listByBuild(build.id) : void 0;
+}
+export { deliverBuildState, loadBuild, stateTargets, writeTo };
+
+//# sourceMappingURL=deliver.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deliver.mjs","names":[],"sources":["../../../src/capture/build-state/deliver.ts"],"sourcesContent":["/**\n * Delivering a build's state to git channels: read the build now, compute what each channel shows\n * ({@link statusesForBuild}), write it. Reading at delivery time is what makes a retried, delayed\n * or reordered request harmless (ADR 0014, decision 7).\n */\nimport { channelPrefix, statusesForBuild, writeBuildState } from \"../../adapters/notifier/index.ts\";\nimport { isStateProvider } from \"../../adapters/notifier/provider.ts\";\nimport { latestVerdicts } from \"../../models/build-review-status.ts\";\nimport { BuildReviewModel } from \"../../models/build-review.ts\";\nimport { BuildModel } from \"../../models/build.ts\";\nimport { NotificationChannelModel } from \"../../models/notification-channel.ts\";\nimport { ProjectModel } from \"../../models/project.ts\";\nimport { SnapshotModel } from \"../../models/snapshot.ts\";\nimport type { Build } from \"../../schema/build.ts\";\nimport type { Project } from \"../../schema/project.ts\";\nimport type { Snapshot } from \"../../schema/snapshot.ts\";\nimport { createUrlBuilder } from \"../../urls.ts\";\nimport { publishingOf } from \"../publish/published.ts\";\nimport type { BuildStateDeps, SkipReason, StateTarget } from \"./types.ts\";\n\n/**\n * Show the build's current state on one channel. Throws when the host refuses a status, so the\n * caller can retry; resolves to why nothing was written when the build or channel is gone.\n */\nexport async function deliverBuildState(\n  deps: BuildStateDeps,\n  ids: { buildId: string; channelId: string },\n): Promise<\"delivered\" | SkipReason> {\n  const loaded = await loadBuild(deps, ids.buildId);\n  // The origin can disappear between queueing and running (a cleared setting): nothing is shown.\n  const origin = loaded === null ? undefined : await deps.publicOrigin();\n  if (loaded === null || !origin) {\n    return loaded === null ? \"no-build\" : \"no-origin\";\n  }\n  const target = await loadTarget(deps, ids.channelId, loaded.project.id);\n  if (typeof target === \"string\") {\n    return target;\n  }\n  await writeTo(deps, loaded, { target, origin });\n  return \"delivered\";\n}\n\n/** The build and its project, or null when either is gone. */\nexport async function loadBuild(\n  deps: BuildStateDeps,\n  buildId: string,\n): Promise<{ build: Build; project: Project } | null> {\n  const build = await new BuildModel(deps.db).get(buildId);\n  const project = build ? await new ProjectModel(deps.db).get(build.projectId) : null;\n  return build && project ? { build, project } : null;\n}\n\n/** Write `target`'s view of the build, linking to `origin`; throws on a refused status. */\nexport async function writeTo(\n  deps: BuildStateDeps,\n  loaded: { build: Build; project: Project },\n  where: { target: StateTarget; origin: string },\n): Promise<void> {\n  const { build, project } = loaded;\n  const { target, origin } = where;\n  const states = statusesForBuild({\n    build,\n    projectSlug: project.slug,\n    prefix: channelPrefix(target.channel),\n    urls: createUrlBuilder(origin, deps.config.publishedBaseDomain),\n    flags: deps.flags(project),\n    publishing: await publishingOf(deps.storage, build),\n    approvals: await approvalsOf(deps, build, project),\n    changes: await changesOf(deps, build, project),\n  });\n  if (states.statuses.length === 0) {\n    deps.logger.info({ buildId: build.id }, \"no commit to show a state on\");\n    return;\n  }\n  await writeBuildState(target.provider, target.channel, {\n    sha: build.gitSha,\n    states,\n    logger: deps.logger,\n  });\n}\n\n/** The project's enabled channels with a wired `state` provider; unreadable secrets are logged and skipped. */\nexport async function stateTargets(\n  deps: BuildStateDeps,\n  projectId: string,\n): Promise<StateTarget[]> {\n  const model = channelModel(deps);\n  const rows = await model.list(projectId);\n  return rows.flatMap((row) => {\n    const view = row.enabled ? model.toView(row) : null;\n    if (row.enabled && view === null) {\n      deps.logger.warn(\n        { channelId: row.id, provider: row.provider },\n        \"failed to decrypt channel secret\",\n      );\n    }\n    return view === null ? [] : targetOf(deps, view);\n  });\n}\n\n/** One channel by id, or why it cannot take part. */\nasync function loadTarget(\n  deps: BuildStateDeps,\n  channelId: string,\n  projectId: string,\n): Promise<StateTarget | Extract<SkipReason, \"no-channel\" | \"disabled\" | \"no-provider\">> {\n  const model = channelModel(deps);\n  const row = await model.get(channelId);\n  if (row === null || row.projectId !== projectId) {\n    return \"no-channel\";\n  }\n  if (!row.enabled) {\n    return \"disabled\";\n  }\n  const view = model.toView(row);\n  if (view === null) {\n    throw new Error(\"channel secret cannot be decrypted with the configured keys\");\n  }\n  return targetOf(deps, view)[0] ?? \"no-provider\";\n}\n\nfunction targetOf(deps: BuildStateDeps, channel: StateTarget[\"channel\"]): StateTarget[] {\n  const provider = deps.notifiers.find((candidate) => candidate.metadata.kind === channel.provider);\n  return provider !== undefined && isStateProvider(provider) ? [{ channel, provider }] : [];\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/** Approval progress for `<prefix>/review`; only read when that status is the gate. */\nasync function approvalsOf(\n  deps: BuildStateDeps,\n  build: Build,\n  project: Project,\n): Promise<{ given: number; required: number } | undefined> {\n  const flags = deps.flags(project);\n  if (flags.testing || !flags.review) {\n    return undefined;\n  }\n  const reviews = latestVerdicts(await new BuildReviewModel(deps.db).listByBuild(build.id));\n  return {\n    given: reviews.filter((review) => review.verdict === \"approved\").length,\n    required: Math.max(1, project.reviewApprovals ?? 1),\n  };\n}\n\n/** The build's snapshots for the annotations; read only when `testing` is on and something changed. */\nasync function changesOf(\n  deps: BuildStateDeps,\n  build: Build,\n  project: Project,\n): Promise<Snapshot[] | undefined> {\n  const wanted = deps.flags(project).testing && build.changedCount > 0;\n  return wanted ? await new SnapshotModel(deps.db).listByBuild(build.id) : undefined;\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,8 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { BuildStateDeps, BuildStatePublisher, SkipReason, StateTarget } from "./types.mjs";
+import { deliverBuildState, loadBuild, stateTargets, writeTo } from "./deliver.mjs";
+import { NOTIFY_BACKOFF, NOTIFY_MAX_ATTEMPTS, NotifyFailure, NotifyHandlerOptions, NotifyJobQueue, createNotifyEnqueuer, createNotifyHandler, notifyExhausted } from "./notify-job.mjs";
+import { BuildStatePublisherOptions, PAUSED_MESSAGE, createBuildStatePublisher } from "./publisher.mjs";
+import { requestOpenBuildStates } from "./resume.mjs";
+export { type BuildStateDeps, type BuildStatePublisher, type BuildStatePublisherOptions, NOTIFY_BACKOFF, NOTIFY_MAX_ATTEMPTS, type NotifyFailure, type NotifyHandlerOptions, type NotifyJobQueue, PAUSED_MESSAGE, type SkipReason, type StateTarget, createBuildStatePublisher, createNotifyEnqueuer, createNotifyHandler, deliverBuildState, loadBuild, notifyExhausted, requestOpenBuildStates, stateTargets, writeTo };

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

@@ -0,0 +1,54 @@
+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";
+/** 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>;
+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,132 @@
+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";
+// 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
+		});
+	};
+}
+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,21 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { BuildStateDeps, BuildStatePublisher } from "./types.mjs";
+/** 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;
+export { BuildStatePublisherOptions, PAUSED_MESSAGE, createBuildStatePublisher };
+//# sourceMappingURL=publisher.d.mts.map