@storyshelf/app 0.6.2 → 0.7.0

package/dist/capture-alerts.mjs

@@ -0,0 +1,46 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { notifyProjectWith, notifySystemWith } from "./notify.mjs";
+import { BuildModel, ProjectModel } from "@storyshelf/core/models";
+//#region src/capture-alerts.ts
+/**
+* Builds already alerted about, keyed by the build's last update. A sharded build settles one job
+* per shard and every one of them sees the failed build; only the first alerts. A retry rewrites
+* the build, so its next failure is a new key.
+*/
+const alerted = /* @__PURE__ */ new Set();
+function alreadyAlerted(build) {
+	const key = `${build.id}@${build.updatedAt}`;
+	if (alerted.has(key)) return true;
+	alerted.add(key);
+	return false;
+}
+/** Alert admins when a capture leaves its build failed. */
+async function notifyCaptureFailed(options, config, logger, buildId, publicOrigin) {
+	const build = await new BuildModel(options.database).get(buildId);
+	if (build?.status !== "failed" || alreadyAlerted(build)) return;
+	const deps = {
+		db: options.database,
+		config,
+		ui: options.ui ?? {},
+		logger,
+		notifiers: options.notifications?.notifiers ?? [],
+		notificationsConfig: options.notifications?.config,
+		publicOrigin: publicOrigin ? { url: publicOrigin } : void 0
+	};
+	await notifySystemWith(deps, "sys:capture-failed", {
+		buildId,
+		projectId: build.projectId,
+		gitBranch: build.gitBranch
+	});
+	const project = await new ProjectModel(options.database).get(build.projectId);
+	if (project) await notifyProjectWith(deps, project, "build:failed", {
+		buildId,
+		status: "failed"
+	}, `/builds/${buildId}`);
+}
+//#endregion
+export { alreadyAlerted, notifyCaptureFailed };
+
+//# sourceMappingURL=capture-alerts.mjs.map

package/dist/capture-alerts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-alerts.mjs","names":[],"sources":["../src/capture-alerts.ts"],"sourcesContent":["/** Admin alerts for captures that leave their build failed; the app, not the capture child, sends them. */\nimport type { ShelfConfig, ShelfOptions } from \"@storyshelf/core/config\";\nimport type { Logger } from \"@storyshelf/core/logger\";\nimport { BuildModel, ProjectModel } from \"@storyshelf/core/models\";\nimport { notifyProjectWith, notifySystemWith } from \"./notify.ts\";\n\n/**\n * Builds already alerted about, keyed by the build's last update. A sharded build settles one job\n * per shard and every one of them sees the failed build; only the first alerts. A retry rewrites\n * the build, so its next failure is a new key.\n */\nconst alerted = new Set<string>();\n\nexport function alreadyAlerted(build: { id: string; updatedAt: string }): boolean {\n  const key = `${build.id}@${build.updatedAt}`;\n  if (alerted.has(key)) {\n    return true;\n  }\n  alerted.add(key);\n  return false;\n}\n\n/** Alert admins when a capture leaves its build failed. */\nexport async function notifyCaptureFailed(\n  options: ShelfOptions,\n  config: ShelfConfig,\n  logger: Logger,\n  buildId: string,\n  publicOrigin?: () => Promise<string | undefined>,\n): Promise<void> {\n  const build = await new BuildModel(options.database).get(buildId);\n  if (build?.status !== \"failed\" || alreadyAlerted(build)) {\n    return;\n  }\n  const deps = {\n    db: options.database,\n    config,\n    ui: options.ui ?? {},\n    logger,\n    notifiers: options.notifications?.notifiers ?? [],\n    notificationsConfig: options.notifications?.config,\n    publicOrigin: publicOrigin ? { url: publicOrigin } : undefined,\n  };\n  await notifySystemWith(deps, \"sys:capture-failed\", {\n    buildId,\n    projectId: build.projectId,\n    gitBranch: build.gitBranch,\n  });\n  // Subscribers of the project's `build:failed` topic hear of a failed capture too.\n  const project = await new ProjectModel(options.database).get(build.projectId);\n  if (project) {\n    await notifyProjectWith(\n      deps,\n      project,\n      \"build:failed\",\n      { buildId, status: \"failed\" },\n      `/builds/${buildId}`,\n    );\n  }\n}\n"],"mappings":";;;;;;;;;;;AAWA,MAAM,0BAAU,IAAI,IAAY;AAEhC,SAAgB,eAAe,OAAmD;CAChF,MAAM,MAAM,GAAG,MAAM,GAAG,GAAG,MAAM;CACjC,IAAI,QAAQ,IAAI,GAAG,GACjB,OAAO;CAET,QAAQ,IAAI,GAAG;CACf,OAAO;AACT;;AAGA,eAAsB,oBACpB,SACA,QACA,QACA,SACA,cACe;CACf,MAAM,QAAQ,MAAM,IAAI,WAAW,QAAQ,QAAQ,CAAC,CAAC,IAAI,OAAO;CAChE,IAAI,OAAO,WAAW,YAAY,eAAe,KAAK,GACpD;CAEF,MAAM,OAAO;EACX,IAAI,QAAQ;EACZ;EACA,IAAI,QAAQ,MAAM,CAAC;EACnB;EACA,WAAW,QAAQ,eAAe,aAAa,CAAC;EAChD,qBAAqB,QAAQ,eAAe;EAC5C,cAAc,eAAe,EAAE,KAAK,aAAa,IAAI,KAAA;CACvD;CACA,MAAM,iBAAiB,MAAM,sBAAsB;EACjD;EACA,WAAW,MAAM;EACjB,WAAW,MAAM;CACnB,CAAC;CAED,MAAM,UAAU,MAAM,IAAI,aAAa,QAAQ,QAAQ,CAAC,CAAC,IAAI,MAAM,SAAS;CAC5E,IAAI,SACF,MAAM,kBACJ,MACA,SACA,gBACA;EAAE;EAAS,QAAQ;CAAS,GAC5B,WAAW,SACb;AAEJ"}

package/dist/capture-process.mjs

@@ -0,0 +1,59 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { DIFF_WORKERS_ENV, IMAGE_ENGINE_ENV } from "@storyshelf/core/diff";
+import { detectResources } from "@storyshelf/core/utils";
+import { CAPTURE_RETRIES_ENV, CAPTURE_SHARD_SIZE_ENV, canForkCaptureChild, createForkedCaptureHandler, decideCaptureProcess, forkCaptureChild } from "@storyshelf/core/capture";
+//#region src/capture-process.ts
+/** Chooses between in-process and forked capture, and builds the forked handler. */
+/**
+* Whether to fork a capture child. `mode: "fork"` forces it (and fails if it cannot); `auto` forks
+* when a `workerEntry` is set and the host can afford a second process.
+*
+* @throws When `mode` is `"fork"` but the runtime cannot fork.
+*/
+function shouldForkCapture(testing, logger) {
+	if (!testing?.workerEntry || testing.mode === "in-process") return false;
+	if (testing.mode === "fork") return requireFork();
+	const decision = decideForHost();
+	if (decision.mode === "in-process") logger.info({ reason: decision.reason }, "capture workerEntry set; capturing in-process");
+	return decision.mode === "fork";
+}
+function requireFork() {
+	if (!canForkCaptureChild()) throw new Error("testing.mode \"fork\" is set but child processes are unavailable here");
+	return true;
+}
+function decideForHost() {
+	const { cpus, memoryBytes } = detectResources();
+	return decideCaptureProcess({
+		cpus,
+		memoryBytes,
+		canFork: canForkCaptureChild()
+	});
+}
+/** Settings the parent hands to a forked child through its environment. */
+function childEnvOf(deps) {
+	const env = { [CAPTURE_RETRIES_ENV]: String(deps.retries) };
+	if (deps.shardSize !== void 0) env[CAPTURE_SHARD_SIZE_ENV] = String(deps.shardSize);
+	if (deps.imageEngine !== void 0) env[IMAGE_ENGINE_ENV] = deps.imageEngine;
+	if (deps.diffThreads !== void 0) env[DIFF_WORKERS_ENV] = String(deps.diffThreads);
+	return env;
+}
+/** The `capture` handler that runs jobs in a forked child, with the in-process handler as its fallback. */
+function createForkedHandler(deps) {
+	const env = childEnvOf(deps);
+	return createForkedCaptureHandler({
+		spawn: () => forkCaptureChild({
+			entry: deps.workerEntry,
+			env
+		}),
+		fallback: deps.fallback,
+		maxRetries: deps.retries,
+		onCrashed: deps.onCrashed,
+		logger: deps.logger
+	});
+}
+//#endregion
+export { childEnvOf, createForkedHandler, shouldForkCapture };
+
+//# sourceMappingURL=capture-process.mjs.map

package/dist/capture-process.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-process.mjs","names":[],"sources":["../src/capture-process.ts"],"sourcesContent":["/** Chooses between in-process and forked capture, and builds the forked handler. */\nimport {\n  canForkCaptureChild,\n  CAPTURE_RETRIES_ENV,\n  CAPTURE_SHARD_SIZE_ENV,\n  createForkedCaptureHandler,\n  decideCaptureProcess,\n  forkCaptureChild,\n  type ForkDecision,\n  type ForkedCaptureHandler,\n  type KindHandler,\n  type ConsumerJob,\n} from \"@storyshelf/core/capture\";\nimport type { ShelfTestingOptions } from \"@storyshelf/core/config\";\nimport { DIFF_WORKERS_ENV, IMAGE_ENGINE_ENV } from \"@storyshelf/core/diff\";\nimport type { Logger } from \"@storyshelf/core/logger\";\nimport { detectResources } from \"@storyshelf/core/utils\";\n\n/**\n * Whether to fork a capture child. `mode: \"fork\"` forces it (and fails if it cannot); `auto` forks\n * when a `workerEntry` is set and the host can afford a second process.\n *\n * @throws When `mode` is `\"fork\"` but the runtime cannot fork.\n */\nexport function shouldForkCapture(\n  testing: ShelfTestingOptions | undefined,\n  logger: Logger,\n): boolean {\n  if (!testing?.workerEntry || testing.mode === \"in-process\") {\n    return false;\n  }\n  if (testing.mode === \"fork\") {\n    return requireFork();\n  }\n  const decision = decideForHost();\n  if (decision.mode === \"in-process\") {\n    logger.info({ reason: decision.reason }, \"capture workerEntry set; capturing in-process\");\n  }\n  return decision.mode === \"fork\";\n}\n\nfunction requireFork(): true {\n  if (!canForkCaptureChild()) {\n    throw new Error('testing.mode \"fork\" is set but child processes are unavailable here');\n  }\n  return true;\n}\n\nfunction decideForHost(): ForkDecision {\n  const { cpus, memoryBytes } = detectResources();\n  return decideCaptureProcess({ cpus, memoryBytes, canFork: canForkCaptureChild() });\n}\n\n/** Dependencies for {@link createForkedHandler}. */\nexport interface ForkedHandlerDeps {\n  workerEntry: string;\n  /** Captures per shard for big builds, handed to the child (`testing.shardSize`). */\n  shardSize?: number;\n  /** `testing.images.engine`, handed to the child so it diffs with the same codec. */\n  imageEngine?: string;\n  /** `testing.compare.threads`, handed to the child's diff pool. */\n  diffThreads?: number;\n  /** `testing.retries`, handed to the child, which stamps it on the shard jobs it queues. */\n  retries: number;\n  /** Takes over if forking stops being viable. */\n  fallback: KindHandler;\n  /** A job the child kept killing on its last attempt: write its failure. */\n  onCrashed: (job: ConsumerJob, error: string) => Promise<void>;\n  logger: Logger;\n}\n\n/** Settings the parent hands to a forked child through its environment. */\nexport function childEnvOf(\n  deps: Pick<ForkedHandlerDeps, \"shardSize\" | \"imageEngine\" | \"diffThreads\" | \"retries\">,\n): Record<string, string> {\n  const env: Record<string, string> = { [CAPTURE_RETRIES_ENV]: String(deps.retries) };\n  if (deps.shardSize !== undefined) {\n    env[CAPTURE_SHARD_SIZE_ENV] = String(deps.shardSize);\n  }\n  if (deps.imageEngine !== undefined) {\n    env[IMAGE_ENGINE_ENV] = deps.imageEngine;\n  }\n  if (deps.diffThreads !== undefined) {\n    env[DIFF_WORKERS_ENV] = String(deps.diffThreads);\n  }\n  return env;\n}\n\n/** The `capture` handler that runs jobs in a forked child, with the in-process handler as its fallback. */\nexport function createForkedHandler(deps: ForkedHandlerDeps): ForkedCaptureHandler {\n  const env = childEnvOf(deps);\n  return createForkedCaptureHandler({\n    spawn: () => forkCaptureChild({ entry: deps.workerEntry, env }),\n    fallback: deps.fallback,\n    maxRetries: deps.retries,\n    onCrashed: deps.onCrashed,\n    logger: deps.logger,\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;AAwBA,SAAgB,kBACd,SACA,QACS;CACT,IAAI,CAAC,SAAS,eAAe,QAAQ,SAAS,cAC5C,OAAO;CAET,IAAI,QAAQ,SAAS,QACnB,OAAO,YAAY;CAErB,MAAM,WAAW,cAAc;CAC/B,IAAI,SAAS,SAAS,cACpB,OAAO,KAAK,EAAE,QAAQ,SAAS,OAAO,GAAG,+CAA+C;CAE1F,OAAO,SAAS,SAAS;AAC3B;AAEA,SAAS,cAAoB;CAC3B,IAAI,CAAC,oBAAoB,GACvB,MAAM,IAAI,MAAM,uEAAqE;CAEvF,OAAO;AACT;AAEA,SAAS,gBAA8B;CACrC,MAAM,EAAE,MAAM,gBAAgB,gBAAgB;CAC9C,OAAO,qBAAqB;EAAE;EAAM;EAAa,SAAS,oBAAoB;CAAE,CAAC;AACnF;;AAqBA,SAAgB,WACd,MACwB;CACxB,MAAM,MAA8B,GAAG,sBAAsB,OAAO,KAAK,OAAO,EAAE;CAClF,IAAI,KAAK,cAAc,KAAA,GACrB,IAAI,0BAA0B,OAAO,KAAK,SAAS;CAErD,IAAI,KAAK,gBAAgB,KAAA,GACvB,IAAI,oBAAoB,KAAK;CAE/B,IAAI,KAAK,gBAAgB,KAAA,GACvB,IAAI,oBAAoB,OAAO,KAAK,WAAW;CAEjD,OAAO;AACT;;AAGA,SAAgB,oBAAoB,MAA+C;CACjF,MAAM,MAAM,WAAW,IAAI;CAC3B,OAAO,2BAA2B;EAChC,aAAa,iBAAiB;GAAE,OAAO,KAAK;GAAa;EAAI,CAAC;EAC9D,UAAU,KAAK;EACf,YAAY,KAAK;EACjB,WAAW,KAAK;EAChB,QAAQ,KAAK;CACf,CAAC;AACH"}

package/dist/capture-setup.mjs

@@ -2,138 +2,116 @@ import "node:path";
 import "node:url";
 import.meta.url;
 import { credentialKeys } from "./credential-keys.mjs";
-import { notifySystemWith } from "./notify.mjs";
-import { captureMetrics, currentTraceparent } from "@storyshelf/observability";
-import { InMemoryCaptureQueue, createDispatchJob, recoverStuckCaptures } from "@storyshelf/core/capture";
-import { BuildModel } from "@storyshelf/core/models";
+import { notifyCaptureFailed } from "./capture-alerts.mjs";
+import { createForkedHandler, shouldForkCapture } from "./capture-process.mjs";
+import { DEFAULT_SCRATCH_DIR } from "@storyshelf/core/config";
+import { currentTraceparent } from "@storyshelf/observability";
+import { DEFAULT_RETRIES, captureDispatchDeps, createCaptureHandler, failCrashedCapture, isFinalAttempt } from "@storyshelf/core/capture";
 //#region src/capture-setup.ts
-/** Enqueue a build, continuing the active request trace when present. */
-async function enqueueJob(queue, buildId, reqId) {
-	const traceparent = currentTraceparent();
-	await queue.enqueue({
-		buildId,
-		reqId,
-		...traceparent ? { traceparent } : {}
-	});
-}
-/** Wrap the dispatch job with duration + outcome metrics. */
-async function timedRunJob(runJob, job) {
-	const instruments = captureMetrics();
-	const start = performance.now();
-	try {
-		await runJob(job);
-	} catch (error) {
-		instruments.jobsFailed.add(1);
-		instruments.jobDuration.record(performance.now() - start);
-		throw error;
-	}
-	instruments.jobsCompleted.add(1);
-	instruments.jobDuration.record(performance.now() - start);
-}
-/** Alert admins when an in-process capture leaves its build failed. */
-async function notifyCaptureFailed(options, config, logger, buildId) {
-	const build = await new BuildModel(options.database).get(buildId);
-	if (build?.status !== "failed") return;
-	await notifySystemWith({
-		db: options.database,
-		config,
-		ui: options.ui ?? {},
-		logger,
-		notifiers: options.notifiers ?? []
-	}, "sys:capture-failed", {
-		buildId,
-		projectId: build.projectId,
-		gitBranch: build.gitBranch
-	});
+/** Queue a build, continuing the active request trace when present. */
+function enqueuerFor(queue) {
+	return async (buildId, reqId) => {
+		const traceparent = currentTraceparent();
+		await queue.enqueue({
+			buildId,
+			reqId,
+			...traceparent ? { traceparent } : {}
+		});
+	};
 }
-/** Assemble the capture queue and its enqueue hook. */
-function setupCaptureQueue(options, config, gitHosts, logger) {
-	if (!options.captureQueue && !options.captureRunner) return {
+/**
+* Wire capture for `options`: `testing` always has a runner, so this instance consumes the
+* captures it queues. Shard jobs go back onto the same queue the capture came from.
+*/
+function setupCapture(options, config, delivery, logger, jobs) {
+	const testing = options.testing;
+	if (testing === void 0) return {
 		queue: null,
-		enqueueCapture: void 0
+		enqueueCapture: void 0,
+		handler: null
 	};
-	if (options.captureQueue) {
-		const queue = options.captureQueue;
-		const enqueueCapture = async (buildId, reqId) => {
-			await enqueueJob(queue, buildId, reqId);
-		};
-		if (!options.captureRunner) return {
-			queue: options.captureQueue,
-			enqueueCapture
-		};
-		if (!config.scratchDir) return {
-			queue: options.captureQueue,
-			enqueueCapture
-		};
-		return {
-			queue: options.captureQueue,
-			enqueueCapture
-		};
-	}
-	if (!options.captureRunner) return {
-		queue: null,
-		enqueueCapture: void 0
+	const queue = jobs.view;
+	const enqueueCapture = enqueuerFor(queue);
+	const handlerOptions = captureHandlerOptions(options, config, delivery, logger, {
+		runner: testing.runner,
+		enqueue: async (job) => {
+			await queue.enqueue(job);
+		}
+	});
+	const retries = options.testing?.retries ?? DEFAULT_RETRIES;
+	const dispatch = captureDispatchDeps(handlerOptions, retries);
+	const failed = async (job, error) => {
+		await failCrashedCapture(dispatch, job, error);
+		await notifyCaptureFailed(options, config, logger, job.buildId, delivery.publicOrigin);
+	};
+	jobs.exhausted.capture = failed;
+	const inProcess = createCaptureHandler(handlerOptions);
+	return {
+		queue,
+		enqueueCapture,
+		handler: alerting(shouldForkCapture(testing, logger) ? forkedHandler(options, {
+			fallback: inProcess,
+			retries,
+			onCrashed: failed,
+			logger
+		}) : inProcess, retries, async (buildId) => {
+			await notifyCaptureFailed(options, config, logger, buildId, delivery.publicOrigin);
+		})
 	};
-	if (!config.scratchDir) throw new Error("captureRunner is enabled but ShelfConfig.scratchDir is not set");
-	const jobOptions = {
+}
+function captureHandlerOptions(options, config, delivery, logger, parts) {
+	return {
 		db: options.database,
-		tables: {
-			projects: options.database.tables.projects,
-			builds: options.database.tables.builds,
-			buildLabels: options.database.tables.buildLabels,
-			snapshots: options.database.tables.snapshots,
-			baselines: options.database.tables.baselines,
-			captureAttempts: options.database.tables.captureAttempts,
-			captureLogs: options.database.tables.captureLogs
-		},
 		storage: options.storage,
-		runner: options.captureRunner,
-		scratchDir: config.scratchDir,
+		runner: parts.runner,
+		scratchDir: config.scratchDir ?? DEFAULT_SCRATCH_DIR,
 		viewports: config.viewports,
 		logger,
-		secret: credentialKeys(config)
-	};
-	const dispatchDeps = {
-		db: options.database,
-		tables: {
-			projects: options.database.tables.projects,
-			builds: options.database.tables.builds,
-			buildLabels: options.database.tables.buildLabels,
-			snapshots: options.database.tables.snapshots,
-			projectStatusConfigs: options.database.tables.projectStatusConfigs,
-			captureAttempts: options.database.tables.captureAttempts,
-			captureLogs: options.database.tables.captureLogs
-		},
-		jobOptions,
-		gitHosts,
 		secret: credentialKeys(config),
-		logger
-	};
-	const runJob = createDispatchJob(dispatchDeps);
-	const captureQueue = options.captureQueue ?? new InMemoryCaptureQueue({
-		concurrency: config.captureConcurrency ?? 2,
-		logger,
-		runJob: async (job) => {
-			await timedRunJob(runJob, job);
-			await notifyCaptureFailed(options, config, logger, job.buildId);
-		}
-	});
-	const enqueueCapture = async (buildId, reqId) => {
-		await enqueueJob(captureQueue, buildId, reqId);
+		design: options.design,
+		shardSize: options.testing?.shardSize,
+		notifiers: delivery.notifiers,
+		buildState: delivery.buildState,
+		publicOrigin: delivery.publicOrigin,
+		config,
+		enqueue: parts.enqueue,
+		maxRetries: options.testing?.retries
 	};
-	const recoverStuck = async () => await recoverStuckCaptures({
-		deps: dispatchDeps,
-		enqueue: async (buildId) => {
-			await enqueueCapture(buildId);
-		}
+}
+function forkedHandler(options, parts) {
+	const testing = options.testing;
+	return createForkedHandler({
+		workerEntry: testing?.workerEntry ?? "",
+		shardSize: testing?.shardSize,
+		imageEngine: testing?.images?.engine,
+		diffThreads: testing?.compare?.threads,
+		...parts
 	});
+}
+/**
+* Alert admins when a capture left its build failed: after a run that ended, and after a final
+* attempt that threw (the build may then already be failed by a crash hook). Alerts stay in this
+* process whichever process rendered.
+*/
+function alerting(inner, retries, alert) {
 	return {
-		queue: captureQueue,
-		enqueueCapture,
-		recoverStuck
+		accepts: (job) => inner.accepts?.(job) !== false,
+		run: async (job, context) => {
+			try {
+				await inner.run(job, context);
+			} catch (error) {
+				if (isFinalAttempt(job, retries)) await alert(job.buildId);
+				throw error;
+			}
+			await alert(job.buildId);
+		},
+		cancel: async (job) => {
+			await inner.cancel?.(job);
+		},
+		...inner.close ? { close: inner.close } : {}
 	};
 }
 //#endregion
-export { setupCaptureQueue };
+export { setupCapture };
 
 //# sourceMappingURL=capture-setup.mjs.map

package/dist/capture-setup.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"capture-setup.mjs","names":[],"sources":["../src/capture-setup.ts"],"sourcesContent":["import type { CaptureQueue } from \"@storyshelf/core/adapter/capture-queue\";\nimport type { GitHostProvider } from \"@storyshelf/core/adapter/git-host\";\nimport {\n  createDispatchJob,\n  InMemoryCaptureQueue,\n  recoverStuckCaptures,\n} from \"@storyshelf/core/capture\";\nimport type {\n  CaptureDispatchJob,\n  CaptureJobOptions,\n  DispatchDeps,\n  RecoveryResult,\n} from \"@storyshelf/core/capture\";\nimport type { ShelfConfig, ShelfOptions } from \"@storyshelf/core/config\";\nimport type { Logger } from \"@storyshelf/core/logger\";\nimport { BuildModel } from \"@storyshelf/core/models\";\nimport { captureMetrics, currentTraceparent } from \"@storyshelf/observability\";\nimport { credentialKeys } from \"./credential-keys.ts\";\nimport { notifySystemWith } from \"./notify.ts\";\n\n/**\n * Wiring for the capture queue: the queue instance (if any) and a helper\n * to enqueue a build for rendering. When no `captureRunner` is configured\n * both are null/undefined and builds remain `pending` until a runner is added.\n */\nexport interface QueueWiring {\n  queue: CaptureQueue | null;\n  enqueueCapture: ((buildId: string, reqId?: string) => Promise<void>) | undefined;\n  /**\n   * Boot sweep for builds a restart left in `capturing` (requeue once, else fail).\n   * Only set for the in-process queue; remote queues redeliver on their own.\n   */\n  recoverStuck?: () => Promise<RecoveryResult>;\n}\n\n/** Enqueue a build, continuing the active request trace when present. */\nasync function enqueueJob(queue: CaptureQueue, buildId: string, reqId?: string): Promise<void> {\n  const traceparent = currentTraceparent();\n  await queue.enqueue({ buildId, reqId, ...(traceparent ? { traceparent } : {}) });\n}\n\n/** Wrap the dispatch job with duration + outcome metrics. */\nasync function timedRunJob(\n  runJob: (job: CaptureDispatchJob) => Promise<void>,\n  job: CaptureDispatchJob,\n): Promise<void> {\n  const instruments = captureMetrics();\n  const start = performance.now();\n  try {\n    await runJob(job);\n  } catch (error) {\n    instruments.jobsFailed.add(1);\n    instruments.jobDuration.record(performance.now() - start);\n    throw error;\n  }\n  instruments.jobsCompleted.add(1);\n  instruments.jobDuration.record(performance.now() - start);\n}\n\n/** Alert admins when an in-process capture leaves its build failed. */\nasync function notifyCaptureFailed(\n  options: ShelfOptions,\n  config: ShelfConfig,\n  logger: Logger,\n  buildId: string,\n): Promise<void> {\n  const build = await new BuildModel(options.database).get(buildId);\n  if (build?.status !== \"failed\") {\n    return;\n  }\n  await notifySystemWith(\n    {\n      db: options.database,\n      config,\n      ui: options.ui ?? {},\n      logger,\n      notifiers: options.notifiers ?? [],\n    },\n    \"sys:capture-failed\",\n    { buildId, projectId: build.projectId, gitBranch: build.gitBranch },\n  );\n}\n\n/** Assemble the capture queue and its enqueue hook. */\nexport function setupCaptureQueue(\n  options: ShelfOptions,\n  config: ShelfConfig,\n  gitHosts: GitHostProvider[],\n  logger: Logger,\n): QueueWiring {\n  if (!options.captureQueue && !options.captureRunner) {\n    return { queue: null, enqueueCapture: undefined };\n  }\n  if (options.captureQueue) {\n    const queue = options.captureQueue;\n    const enqueueCapture = async (buildId: string, reqId?: string): Promise<void> => {\n      await enqueueJob(queue, buildId, reqId);\n    };\n    if (!options.captureRunner) {\n      return { queue: options.captureQueue, enqueueCapture };\n    }\n    // Both queue and runner supplied: runner is ignored server-side for remote queues;\n    // enqueue goes to the supplied queue and capture is handled by an external worker.\n    if (!config.scratchDir) {\n      return { queue: options.captureQueue, enqueueCapture };\n    }\n    // If scratchDir is set with both, still prefer the supplied queue; no in-memory queue needed.\n    return { queue: options.captureQueue, enqueueCapture };\n  }\n  if (!options.captureRunner) {\n    return { queue: null, enqueueCapture: undefined };\n  }\n  if (!config.scratchDir) {\n    throw new Error(\"captureRunner is enabled but ShelfConfig.scratchDir is not set\");\n  }\n  const jobOptions: CaptureJobOptions = {\n    db: options.database,\n    tables: {\n      projects: options.database.tables.projects,\n      builds: options.database.tables.builds,\n      buildLabels: options.database.tables.buildLabels,\n      snapshots: options.database.tables.snapshots,\n      baselines: options.database.tables.baselines,\n      captureAttempts: options.database.tables.captureAttempts,\n      captureLogs: options.database.tables.captureLogs,\n    },\n    storage: options.storage,\n    runner: options.captureRunner,\n    scratchDir: config.scratchDir,\n    viewports: config.viewports,\n    logger,\n    secret: credentialKeys(config),\n  };\n  const dispatchDeps: DispatchDeps = {\n    db: options.database,\n    tables: {\n      projects: options.database.tables.projects,\n      builds: options.database.tables.builds,\n      buildLabels: options.database.tables.buildLabels,\n      snapshots: options.database.tables.snapshots,\n      projectStatusConfigs: options.database.tables.projectStatusConfigs,\n      captureAttempts: options.database.tables.captureAttempts,\n      captureLogs: options.database.tables.captureLogs,\n    },\n    jobOptions,\n    gitHosts,\n    secret: credentialKeys(config),\n    logger,\n  };\n  const runJob = createDispatchJob(dispatchDeps);\n  const captureQueue =\n    options.captureQueue ??\n    new InMemoryCaptureQueue({\n      concurrency: config.captureConcurrency ?? 2,\n      logger,\n      runJob: async (job: CaptureDispatchJob): Promise<void> => {\n        await timedRunJob(runJob, job);\n        // In-process completions only: remote-queue workers own their own\n        // alerting (the server never sees those outcomes).\n        await notifyCaptureFailed(options, config, logger, job.buildId);\n      },\n    });\n  const enqueueCapture = async (buildId: string, reqId?: string): Promise<void> => {\n    await enqueueJob(captureQueue, buildId, reqId);\n  };\n  const recoverStuck = async (): Promise<RecoveryResult> =>\n    await recoverStuckCaptures({\n      deps: dispatchDeps,\n      enqueue: async (buildId) => {\n        await enqueueCapture(buildId);\n      },\n    });\n  return { queue: captureQueue, enqueueCapture, recoverStuck };\n}\n"],"mappings":"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"}
+{"version":3,"file":"capture-setup.mjs","names":[],"sources":["../src/capture-setup.ts"],"sourcesContent":["/**\n * Capture wiring (ADR 0006, decisions 4 to 6): where uploads queue their capture, and the handler\n * of `capture` jobs. Captures queue on the shared database queue. The handler runs them in this process, or in a forked child the parent pushes jobs\n * to (`testing.workerEntry`). The consumer that polls the queue and calls the handler is built\n * in `jobs-setup.ts`.\n */\nimport type { CaptureQueue } from \"@storyshelf/core/adapter/capture-queue\";\nimport type { CaptureRunner } from \"@storyshelf/core/adapter/capture-runner\";\nimport type { NotifierProvider } from \"@storyshelf/core/adapter/notifier\";\nimport {\n  captureDispatchDeps,\n  createCaptureHandler,\n  DEFAULT_RETRIES,\n  failCrashedCapture,\n  isFinalAttempt,\n  type BuildStatePublisher,\n  type CaptureHandlerOptions,\n  type ConsumerJob,\n  type KindHandler,\n} from \"@storyshelf/core/capture\";\nimport { DEFAULT_SCRATCH_DIR } from \"@storyshelf/core/config\";\nimport type { ShelfConfig, ShelfOptions } from \"@storyshelf/core/config\";\nimport type { Logger } from \"@storyshelf/core/logger\";\nimport { currentTraceparent } from \"@storyshelf/observability\";\nimport { notifyCaptureFailed } from \"./capture-alerts.ts\";\nimport { createForkedHandler, shouldForkCapture } from \"./capture-process.ts\";\nimport { credentialKeys } from \"./credential-keys.ts\";\nimport type { JobQueue } from \"./job-queue.ts\";\n\n/** The `capture` handler, with a way to stop a forked child once the consumer has drained. */\nexport interface CaptureHandler extends KindHandler {\n  close?: () => Promise<void>;\n}\n\n/** What uploads and the consumer need of capture. */\nexport interface CaptureWiring {\n  /** Where captures queue: the database queue, or null without `testing`. */\n  queue: CaptureQueue | null;\n  /** Queues a capture for a build; undefined without `testing`. */\n  enqueueCapture: ((buildId: string, reqId?: string) => Promise<void>) | undefined;\n  /** Runs `capture` jobs here; null without `testing`. */\n  handler: CaptureHandler | null;\n}\n\n/** What a capture hands its results to. */\ninterface Delivery {\n  notifiers: NotifierProvider[];\n  buildState: BuildStatePublisher;\n  /** The resolved public origin (ADR 0007): status links and targets that need a URL use it. */\n  publicOrigin: () => Promise<string | undefined>;\n}\n\n/** Queue a build, continuing the active request trace when present. */\nfunction enqueuerFor(queue: CaptureQueue): (buildId: string, reqId?: string) => Promise<void> {\n  return async (buildId, reqId) => {\n    const traceparent = currentTraceparent();\n    await queue.enqueue({ buildId, reqId, ...(traceparent ? { traceparent } : {}) });\n  };\n}\n\n/**\n * Wire capture for `options`: `testing` always has a runner, so this instance consumes the\n * captures it queues. Shard jobs go back onto the same queue the capture came from.\n */\nexport function setupCapture(\n  options: ShelfOptions,\n  config: ShelfConfig,\n  delivery: Delivery,\n  logger: Logger,\n  jobs: JobQueue,\n): CaptureWiring {\n  const testing = options.testing;\n  if (testing === undefined) {\n    return { queue: null, enqueueCapture: undefined, handler: null };\n  }\n  const queue = jobs.view;\n  const enqueueCapture = enqueuerFor(queue);\n  const handlerOptions = captureHandlerOptions(options, config, delivery, logger, {\n    runner: testing.runner,\n    enqueue: async (job) => {\n      await queue.enqueue(job);\n    },\n  });\n  const retries = options.testing?.retries ?? DEFAULT_RETRIES;\n  const dispatch = captureDispatchDeps(handlerOptions, retries);\n  const failed = async (job: ConsumerJob, error: string): Promise<void> => {\n    await failCrashedCapture(dispatch, job, error);\n    await notifyCaptureFailed(options, config, logger, job.buildId, delivery.publicOrigin);\n  };\n  jobs.exhausted.capture = failed;\n  const inProcess = createCaptureHandler(handlerOptions);\n  const handler = shouldForkCapture(testing, logger)\n    ? forkedHandler(options, { fallback: inProcess, retries, onCrashed: failed, logger })\n    : inProcess;\n  return {\n    queue,\n    enqueueCapture,\n    handler: alerting(handler, retries, async (buildId) => {\n      await notifyCaptureFailed(options, config, logger, buildId, delivery.publicOrigin);\n    }),\n  };\n}\n\nfunction captureHandlerOptions(\n  options: ShelfOptions,\n  config: ShelfConfig,\n  delivery: Delivery,\n  logger: Logger,\n  parts: { runner: CaptureRunner; enqueue: CaptureHandlerOptions[\"enqueue\"] },\n): CaptureHandlerOptions {\n  return {\n    db: options.database,\n    storage: options.storage,\n    runner: parts.runner,\n    // `resolveShelfOptions` defaults scratchDir; the fallback covers hand-built configs.\n    scratchDir: config.scratchDir ?? DEFAULT_SCRATCH_DIR,\n    viewports: config.viewports,\n    logger,\n    secret: credentialKeys(config),\n    design: options.design,\n    shardSize: options.testing?.shardSize,\n    notifiers: delivery.notifiers,\n    buildState: delivery.buildState,\n    publicOrigin: delivery.publicOrigin,\n    config,\n    enqueue: parts.enqueue,\n    maxRetries: options.testing?.retries,\n  };\n}\n\nfunction forkedHandler(\n  options: ShelfOptions,\n  parts: {\n    fallback: KindHandler;\n    retries: number;\n    onCrashed: (job: ConsumerJob, error: string) => Promise<void>;\n    logger: Logger;\n  },\n): CaptureHandler {\n  const testing = options.testing;\n  return createForkedHandler({\n    workerEntry: testing?.workerEntry ?? \"\",\n    shardSize: testing?.shardSize,\n    imageEngine: testing?.images?.engine,\n    diffThreads: testing?.compare?.threads,\n    ...parts,\n  });\n}\n\n/**\n * Alert admins when a capture left its build failed: after a run that ended, and after a final\n * attempt that threw (the build may then already be failed by a crash hook). Alerts stay in this\n * process whichever process rendered.\n */\nfunction alerting(\n  inner: CaptureHandler,\n  retries: number,\n  alert: (buildId: string) => Promise<void>,\n): CaptureHandler {\n  return {\n    accepts: (job) => inner.accepts?.(job) !== false,\n    run: async (job, context) => {\n      try {\n        await inner.run(job, context);\n      } catch (error) {\n        if (isFinalAttempt(job, retries)) {\n          await alert(job.buildId);\n        }\n        throw error;\n      }\n      await alert(job.buildId);\n    },\n    cancel: async (job) => {\n      await inner.cancel?.(job);\n    },\n    ...(inner.close ? { close: inner.close } : {}),\n  };\n}\n"],"mappings":";;;;;;;;;;;AAqDA,SAAS,YAAY,OAAyE;CAC5F,OAAO,OAAO,SAAS,UAAU;EAC/B,MAAM,cAAc,mBAAmB;EACvC,MAAM,MAAM,QAAQ;GAAE;GAAS;GAAO,GAAI,cAAc,EAAE,YAAY,IAAI,CAAC;EAAG,CAAC;CACjF;AACF;;;;;AAMA,SAAgB,aACd,SACA,QACA,UACA,QACA,MACe;CACf,MAAM,UAAU,QAAQ;CACxB,IAAI,YAAY,KAAA,GACd,OAAO;EAAE,OAAO;EAAM,gBAAgB,KAAA;EAAW,SAAS;CAAK;CAEjE,MAAM,QAAQ,KAAK;CACnB,MAAM,iBAAiB,YAAY,KAAK;CACxC,MAAM,iBAAiB,sBAAsB,SAAS,QAAQ,UAAU,QAAQ;EAC9E,QAAQ,QAAQ;EAChB,SAAS,OAAO,QAAQ;GACtB,MAAM,MAAM,QAAQ,GAAG;EACzB;CACF,CAAC;CACD,MAAM,UAAU,QAAQ,SAAS,WAAW;CAC5C,MAAM,WAAW,oBAAoB,gBAAgB,OAAO;CAC5D,MAAM,SAAS,OAAO,KAAkB,UAAiC;EACvE,MAAM,mBAAmB,UAAU,KAAK,KAAK;EAC7C,MAAM,oBAAoB,SAAS,QAAQ,QAAQ,IAAI,SAAS,SAAS,YAAY;CACvF;CACA,KAAK,UAAU,UAAU;CACzB,MAAM,YAAY,qBAAqB,cAAc;CAIrD,OAAO;EACL;EACA;EACA,SAAS,SANK,kBAAkB,SAAS,MAAM,IAC7C,cAAc,SAAS;GAAE,UAAU;GAAW;GAAS,WAAW;GAAQ;EAAO,CAAC,IAClF,WAIyB,SAAS,OAAO,YAAY;GACrD,MAAM,oBAAoB,SAAS,QAAQ,QAAQ,SAAS,SAAS,YAAY;EACnF,CAAC;CACH;AACF;AAEA,SAAS,sBACP,SACA,QACA,UACA,QACA,OACuB;CACvB,OAAO;EACL,IAAI,QAAQ;EACZ,SAAS,QAAQ;EACjB,QAAQ,MAAM;EAEd,YAAY,OAAO,cAAc;EACjC,WAAW,OAAO;EAClB;EACA,QAAQ,eAAe,MAAM;EAC7B,QAAQ,QAAQ;EAChB,WAAW,QAAQ,SAAS;EAC5B,WAAW,SAAS;EACpB,YAAY,SAAS;EACrB,cAAc,SAAS;EACvB;EACA,SAAS,MAAM;EACf,YAAY,QAAQ,SAAS;CAC/B;AACF;AAEA,SAAS,cACP,SACA,OAMgB;CAChB,MAAM,UAAU,QAAQ;CACxB,OAAO,oBAAoB;EACzB,aAAa,SAAS,eAAe;EACrC,WAAW,SAAS;EACpB,aAAa,SAAS,QAAQ;EAC9B,aAAa,SAAS,SAAS;EAC/B,GAAG;CACL,CAAC;AACH;;;;;;AAOA,SAAS,SACP,OACA,SACA,OACgB;CAChB,OAAO;EACL,UAAU,QAAQ,MAAM,UAAU,GAAG,MAAM;EAC3C,KAAK,OAAO,KAAK,YAAY;GAC3B,IAAI;IACF,MAAM,MAAM,IAAI,KAAK,OAAO;GAC9B,SAAS,OAAO;IACd,IAAI,eAAe,KAAK,OAAO,GAC7B,MAAM,MAAM,IAAI,OAAO;IAEzB,MAAM;GACR;GACA,MAAM,MAAM,IAAI,OAAO;EACzB;EACA,QAAQ,OAAO,QAAQ;GACrB,MAAM,MAAM,SAAS,GAAG;EAC1B;EACA,GAAI,MAAM,QAAQ,EAAE,OAAO,MAAM,MAAM,IAAI,CAAC;CAC9C;AACF"}

package/dist/connections.mjs

@@ -0,0 +1,34 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { credentialKeys } from "./credential-keys.mjs";
+import { getStore } from "./store.mjs";
+import { ConnectionModel } from "@storyshelf/core/models";
+//#region src/connections.ts
+/**
+* Services a user can connect their own account to. Today only design providers
+* offer OAuth; a future issue-tracker or notifier adapter that exposes
+* `oauth` joins by being listed here — routes, state signing, storage and
+* refresh are shared.
+*/
+function connectableServices() {
+	return [...getStore().design];
+}
+/** The service addressed by `kind` when the operator configured OAuth for it, else undefined. */
+function findConnectable(kind) {
+	return connectableServices().find((service) => service.metadata.kind === kind && service.oauth);
+}
+/** Connection storage bound to the server's credential keys. */
+function connectionModel() {
+	const { db, config } = getStore();
+	return new ConnectionModel(db, credentialKeys(config));
+}
+/** Connecting needs authentication (a user to own it) and a server secret (to sign the flow). */
+function canConnect() {
+	const { authEnabled, user, config } = getStore();
+	return authEnabled && Boolean(user) && Boolean(config.secret);
+}
+//#endregion
+export { canConnect, connectableServices, connectionModel, findConnectable };
+
+//# sourceMappingURL=connections.mjs.map

package/dist/connections.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"connections.mjs","names":[],"sources":["../src/connections.ts"],"sourcesContent":["import type { OAuthConnectable } from \"@storyshelf/core/adapter/oauth\";\nimport { ConnectionModel } from \"@storyshelf/core/models\";\nimport { credentialKeys } from \"./credential-keys.ts\";\nimport { getStore } from \"./store.ts\";\n\n/**\n * Services a user can connect their own account to. Today only design providers\n * offer OAuth; a future issue-tracker or notifier adapter that exposes\n * `oauth` joins by being listed here — routes, state signing, storage and\n * refresh are shared.\n */\nexport function connectableServices(): OAuthConnectable[] {\n  return [...getStore().design];\n}\n\n/** A connectable service whose operator configured OAuth. */\nexport type Connectable = Required<OAuthConnectable>;\n\n/** The service addressed by `kind` when the operator configured OAuth for it, else undefined. */\nexport function findConnectable(kind: string): Connectable | undefined {\n  const found = connectableServices().find(\n    (service) => service.metadata.kind === kind && service.oauth,\n  );\n  return found as Connectable | undefined;\n}\n\n/** Connection storage bound to the server's credential keys. */\nexport function connectionModel(): ConnectionModel {\n  const { db, config } = getStore();\n  return new ConnectionModel(db, credentialKeys(config));\n}\n\n/** Connecting needs authentication (a user to own it) and a server secret (to sign the flow). */\nexport function canConnect(): boolean {\n  const { authEnabled, user, config } = getStore();\n  return authEnabled && Boolean(user) && Boolean(config.secret);\n}\n"],"mappings":";;;;;;;;;;;;;AAWA,SAAgB,sBAA0C;CACxD,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC,MAAM;AAC9B;;AAMA,SAAgB,gBAAgB,MAAuC;CAIrE,OAHc,oBAAoB,CAAC,CAAC,MACjC,YAAY,QAAQ,SAAS,SAAS,QAAQ,QAAQ,KAE9C;AACb;;AAGA,SAAgB,kBAAmC;CACjD,MAAM,EAAE,IAAI,WAAW,SAAS;CAChC,OAAO,IAAI,gBAAgB,IAAI,eAAe,MAAM,CAAC;AACvD;;AAGA,SAAgB,aAAsB;CACpC,MAAM,EAAE,aAAa,MAAM,WAAW,SAAS;CAC/C,OAAO,eAAe,QAAQ,IAAI,KAAK,QAAQ,OAAO,MAAM;AAC9D"}

package/dist/consumer-setup.mjs

@@ -0,0 +1,58 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { captureMetrics } from "@storyshelf/observability";
+import { createCaptureConsumer } from "@storyshelf/core/capture";
+//#region src/consumer-setup.ts
+/**
+* The consumer of the app's queues (ADR 0006, decision 5): built when first started, so a host
+* that never starts one never touches the queue, and drained as a unit on teardown.
+*/
+/** One consumer from options that are only worked out on the first `start()`. */
+function lazyConsumer(options, closers = []) {
+	let built;
+	return {
+		start: async () => {
+			built ??= createCaptureConsumer(options());
+			await built.start();
+		},
+		stop: async () => {
+			await built?.stop();
+			for (const close of closers) await close();
+		},
+		isRunning: () => built?.isRunning() ?? false
+	};
+}
+/** Several consumers as one: they start together and drain together. */
+function combineConsumers(consumers) {
+	const [only, ...rest] = consumers;
+	if (only === void 0) return null;
+	if (rest.length === 0) return only;
+	return {
+		start: async () => {
+			await Promise.all(consumers.map(async (consumer) => {
+				await consumer.start();
+			}));
+		},
+		stop: async () => {
+			await Promise.all(consumers.map(async (consumer) => {
+				await consumer.stop();
+			}));
+		},
+		isRunning: () => consumers.some((consumer) => consumer.isRunning())
+	};
+}
+/** Job counts and durations on the capture instruments, told apart by `job.kind`. */
+function jobMetrics() {
+	return { jobFinished: (event) => {
+		const instruments = captureMetrics();
+		const attributes = { "job.kind": event.kind };
+		instruments.jobDuration.record(event.durationMs, attributes);
+		if (event.outcome === "completed") instruments.jobsCompleted.add(1, attributes);
+		else if (event.outcome === "failed") instruments.jobsFailed.add(1, attributes);
+	} };
+}
+//#endregion
+export { combineConsumers, jobMetrics, lazyConsumer };
+
+//# sourceMappingURL=consumer-setup.mjs.map

package/dist/consumer-setup.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumer-setup.mjs","names":[],"sources":["../src/consumer-setup.ts"],"sourcesContent":["/**\n * The consumer of the app's queues (ADR 0006, decision 5): built when first started, so a host\n * that never starts one never touches the queue, and drained as a unit on teardown.\n */\nimport {\n  createCaptureConsumer,\n  type CaptureConsumer,\n  type CaptureConsumerOptions,\n  type ConsumerMetrics,\n} from \"@storyshelf/core/capture\";\nimport { captureMetrics } from \"@storyshelf/observability\";\n\n/** One consumer from options that are only worked out on the first `start()`. */\nexport function lazyConsumer(\n  options: () => CaptureConsumerOptions,\n  closers: (() => Promise<void>)[] = [],\n): CaptureConsumer {\n  let built: CaptureConsumer | undefined;\n  return {\n    start: async () => {\n      built ??= createCaptureConsumer(options());\n      await built.start();\n    },\n    // Stopping one never started is a no-op; the closers (forked child, queue wake) still run.\n    stop: async () => {\n      await built?.stop();\n      for (const close of closers) {\n        // oxlint-disable-next-line no-await-in-loop -- close in order, after the drain\n        await close();\n      }\n    },\n    isRunning: () => built?.isRunning() ?? false,\n  };\n}\n\n/** Several consumers as one: they start together and drain together. */\nexport function combineConsumers(consumers: CaptureConsumer[]): CaptureConsumer | null {\n  const [only, ...rest] = consumers;\n  if (only === undefined) {\n    return null;\n  }\n  if (rest.length === 0) {\n    return only;\n  }\n  return {\n    start: async () => {\n      await Promise.all(\n        consumers.map(async (consumer) => {\n          await consumer.start();\n        }),\n      );\n    },\n    stop: async () => {\n      await Promise.all(\n        consumers.map(async (consumer) => {\n          await consumer.stop();\n        }),\n      );\n    },\n    isRunning: () => consumers.some((consumer) => consumer.isRunning()),\n  };\n}\n\n/** Job counts and durations on the capture instruments, told apart by `job.kind`. */\nexport function jobMetrics(): ConsumerMetrics {\n  return {\n    jobFinished: (event) => {\n      const instruments = captureMetrics();\n      const attributes = { \"job.kind\": event.kind };\n      instruments.jobDuration.record(event.durationMs, attributes);\n      if (event.outcome === \"completed\") {\n        instruments.jobsCompleted.add(1, attributes);\n      } else if (event.outcome === \"failed\") {\n        instruments.jobsFailed.add(1, attributes);\n      }\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;AAaA,SAAgB,aACd,SACA,UAAmC,CAAC,GACnB;CACjB,IAAI;CACJ,OAAO;EACL,OAAO,YAAY;GACjB,UAAU,sBAAsB,QAAQ,CAAC;GACzC,MAAM,MAAM,MAAM;EACpB;EAEA,MAAM,YAAY;GAChB,MAAM,OAAO,KAAK;GAClB,KAAK,MAAM,SAAS,SAElB,MAAM,MAAM;EAEhB;EACA,iBAAiB,OAAO,UAAU,KAAK;CACzC;AACF;;AAGA,SAAgB,iBAAiB,WAAsD;CACrF,MAAM,CAAC,MAAM,GAAG,QAAQ;CACxB,IAAI,SAAS,KAAA,GACX,OAAO;CAET,IAAI,KAAK,WAAW,GAClB,OAAO;CAET,OAAO;EACL,OAAO,YAAY;GACjB,MAAM,QAAQ,IACZ,UAAU,IAAI,OAAO,aAAa;IAChC,MAAM,SAAS,MAAM;GACvB,CAAC,CACH;EACF;EACA,MAAM,YAAY;GAChB,MAAM,QAAQ,IACZ,UAAU,IAAI,OAAO,aAAa;IAChC,MAAM,SAAS,KAAK;GACtB,CAAC,CACH;EACF;EACA,iBAAiB,UAAU,MAAM,aAAa,SAAS,UAAU,CAAC;CACpE;AACF;;AAGA,SAAgB,aAA8B;CAC5C,OAAO,EACL,cAAc,UAAU;EACtB,MAAM,cAAc,eAAe;EACnC,MAAM,aAAa,EAAE,YAAY,MAAM,KAAK;EAC5C,YAAY,YAAY,OAAO,MAAM,YAAY,UAAU;EAC3D,IAAI,MAAM,YAAY,aACpB,YAAY,cAAc,IAAI,GAAG,UAAU;OACtC,IAAI,MAAM,YAAY,UAC3B,YAAY,WAAW,IAAI,GAAG,UAAU;CAE5C,EACF;AACF"}

package/dist/git-status.mjs

@@ -0,0 +1,46 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { credentialKeys } from "./credential-keys.mjs";
+import { getStore } from "./store.mjs";
+import { notificationOrigin } from "./notifications-pause.mjs";
+import { buildStateFlags } from "./build-state-flags.mjs";
+import { createBuildStatePublisher, requestOpenBuildStates } from "@storyshelf/core/capture";
+//#region src/git-status.ts
+/** Ask for a build's state to be shown on its project's git channels (ADR 0014, decision 5). */
+/**
+* Show the build's current state (commit statuses and the pull-request comment) on every git
+* channel of its project. Called on every transition a request causes: build creation, a review
+* outcome, a retry. Delivery reads the build when it runs, so the call needs no state of its own;
+* it never rejects, so a git host cannot fail the action that triggered it.
+*/
+async function requestBuildState(buildId) {
+	const store = getStore();
+	await (store.buildState ?? inlinePublisher(store)).request(buildId);
+}
+/**
+* An origin just became resolved (an admin confirmed or reported one): requests made while none was
+* were dropped, so ask again for the builds that can still change (ADR 0014, decision 11).
+* Resolves to how many builds were asked; never rejects.
+*/
+async function requestOpenBuildStatesNow() {
+	const store = getStore();
+	return await requestOpenBuildStates(store, { request: requestBuildState });
+}
+/** Hand-built stores have no wiring: deliver inline through the store's own adapters. */
+function inlinePublisher(store) {
+	return createBuildStatePublisher({ deps: {
+		db: store.db,
+		storage: store.storage,
+		notifiers: store.notifiers,
+		secret: credentialKeys(store.config),
+		config: store.config,
+		publicOrigin: async () => await notificationOrigin(store),
+		flags: (project) => buildStateFlags(store.testing, project),
+		logger: store.logger
+	} });
+}
+//#endregion
+export { requestBuildState, requestOpenBuildStatesNow };
+
+//# sourceMappingURL=git-status.mjs.map

package/dist/git-status.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-status.mjs","names":[],"sources":["../src/git-status.ts"],"sourcesContent":["/** Ask for a build's state to be shown on its project's git channels (ADR 0014, decision 5). */\nimport { createBuildStatePublisher, requestOpenBuildStates } from \"@storyshelf/core/capture\";\nimport { buildStateFlags } from \"./build-state-flags.ts\";\nimport { credentialKeys } from \"./credential-keys.ts\";\nimport { notificationOrigin } from \"./notifications-pause.ts\";\nimport { getStore, type Store } from \"./store.ts\";\n\n/**\n * Show the build's current state (commit statuses and the pull-request comment) on every git\n * channel of its project. Called on every transition a request causes: build creation, a review\n * outcome, a retry. Delivery reads the build when it runs, so the call needs no state of its own;\n * it never rejects, so a git host cannot fail the action that triggered it.\n */\nexport async function requestBuildState(buildId: string): Promise<void> {\n  const store = getStore();\n  await (store.buildState ?? inlinePublisher(store)).request(buildId);\n}\n\n/**\n * An origin just became resolved (an admin confirmed or reported one): requests made while none was\n * were dropped, so ask again for the builds that can still change (ADR 0014, decision 11).\n * Resolves to how many builds were asked; never rejects.\n */\nexport async function requestOpenBuildStatesNow(): Promise<number> {\n  const store = getStore();\n  return await requestOpenBuildStates(store, { request: requestBuildState });\n}\n\n/** Hand-built stores have no wiring: deliver inline through the store's own adapters. */\nfunction inlinePublisher(store: Store): ReturnType<typeof createBuildStatePublisher> {\n  return createBuildStatePublisher({\n    deps: {\n      db: store.db,\n      storage: store.storage,\n      notifiers: store.notifiers,\n      secret: credentialKeys(store.config),\n      config: store.config,\n      publicOrigin: async () => await notificationOrigin(store),\n      flags: (project) => buildStateFlags(store.testing, project),\n      logger: store.logger,\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAaA,eAAsB,kBAAkB,SAAgC;CACtE,MAAM,QAAQ,SAAS;CACvB,OAAO,MAAM,cAAc,gBAAgB,KAAK,EAAA,CAAG,QAAQ,OAAO;AACpE;;;;;;AAOA,eAAsB,4BAA6C;CACjE,MAAM,QAAQ,SAAS;CACvB,OAAO,MAAM,uBAAuB,OAAO,EAAE,SAAS,kBAAkB,CAAC;AAC3E;;AAGA,SAAS,gBAAgB,OAA4D;CACnF,OAAO,0BAA0B,EAC/B,MAAM;EACJ,IAAI,MAAM;EACV,SAAS,MAAM;EACf,WAAW,MAAM;EACjB,QAAQ,eAAe,MAAM,MAAM;EACnC,QAAQ,MAAM;EACd,cAAc,YAAY,MAAM,mBAAmB,KAAK;EACxD,QAAQ,YAAY,gBAAgB,MAAM,SAAS,OAAO;EAC1D,QAAQ,MAAM;CAChB,EACF,CAAC;AACH"}

package/dist/hidden-data.mjs

@@ -0,0 +1,24 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/hidden-data.ts
+/**
+* Snapshots stored in the database. With `testing` off they are hidden, not deleted (ADR 0006,
+* decision 1): the System page and the startup log say how many.
+*/
+async function countHiddenSnapshots(db) {
+	return await db.count(db.tables.snapshots);
+}
+/** Log the mode at boot; with `testing` off, also how much captured data it hides. */
+async function logHostingOnlyMode(db, logger) {
+	const hiddenSnapshots = await countHiddenSnapshots(db);
+	if (hiddenSnapshots > 0) {
+		logger.warn({ hiddenSnapshots }, "testing is off: existing snapshots are hidden, not deleted; they reappear when testing is turned on");
+		return;
+	}
+	logger.info("testing is off: hosting Storybooks only (no capture, compare or baselines)");
+}
+//#endregion
+export { countHiddenSnapshots, logHostingOnlyMode };
+
+//# sourceMappingURL=hidden-data.mjs.map

package/dist/hidden-data.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hidden-data.mjs","names":[],"sources":["../src/hidden-data.ts"],"sourcesContent":["import type { DatabaseAdapter } from \"@storyshelf/core/adapter/database\";\nimport type { Logger } from \"@storyshelf/core/logger\";\n\n/**\n * Snapshots stored in the database. With `testing` off they are hidden, not deleted (ADR 0006,\n * decision 1): the System page and the startup log say how many.\n */\nexport async function countHiddenSnapshots(db: DatabaseAdapter): Promise<number> {\n  return await db.count(db.tables.snapshots);\n}\n\n/** Log the mode at boot; with `testing` off, also how much captured data it hides. */\nexport async function logHostingOnlyMode(db: DatabaseAdapter, logger: Logger): Promise<void> {\n  const hiddenSnapshots = await countHiddenSnapshots(db);\n  if (hiddenSnapshots > 0) {\n    logger.warn(\n      { hiddenSnapshots },\n      \"testing is off: existing snapshots are hidden, not deleted; they reappear when testing is turned on\",\n    );\n    return;\n  }\n  logger.info(\"testing is off: hosting Storybooks only (no capture, compare or baselines)\");\n}\n"],"mappings":";;;;;;;;AAOA,eAAsB,qBAAqB,IAAsC;CAC/E,OAAO,MAAM,GAAG,MAAM,GAAG,OAAO,SAAS;AAC3C;;AAGA,eAAsB,mBAAmB,IAAqB,QAA+B;CAC3F,MAAM,kBAAkB,MAAM,qBAAqB,EAAE;CACrD,IAAI,kBAAkB,GAAG;EACvB,OAAO,KACL,EAAE,gBAAgB,GAClB,qGACF;EACA;CACF;CACA,OAAO,KAAK,4EAA4E;AAC1F"}