@storyshelf/core 0.6.1 → 0.7.0

package/dist/adapters/notifier/build-comment.mjs

@@ -0,0 +1,24 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/adapters/notifier/build-comment.ts
+const LABEL = {
+	testing: "Visual tests",
+	review: "Review",
+	storybook: "Storybook"
+};
+/** Comment body (below the idempotency marker): links to the build, the Storybook and a summary. */
+function buildCommentMarkdown(input) {
+	const lines = [`**StoryShelf** — [View build](${input.buildUrl})`];
+	for (const gate of input.gates) lines.push(`- ${LABEL[gate.name]}: ${gate.description}`);
+	if (input.counts !== void 0 && input.counts.snapshotCount > 0) {
+		const { snapshotCount, changedCount, approvedCount, rejectedCount } = input.counts;
+		lines.push(`- Snapshots: ${String(snapshotCount)} total, ${String(changedCount)} changed, ${String(approvedCount)} approved, ${String(rejectedCount)} rejected`);
+	}
+	if (input.storybookUrl !== void 0) lines.push(`- Storybook: [Open the published Storybook](${input.storybookUrl})`);
+	return lines.join("\n");
+}
+//#endregion
+export { buildCommentMarkdown };
+
+//# sourceMappingURL=build-comment.mjs.map

package/dist/adapters/notifier/build-comment.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-comment.mjs","names":[],"sources":["../../../src/adapters/notifier/build-comment.ts"],"sourcesContent":["/** Markdown of the pull-request comment, derived from the same inputs as the statuses (ADR 0014, decision 6). */\nimport type { DesiredStatus } from \"./build-state.ts\";\n\n/** Inputs of {@link buildCommentMarkdown}. */\nexport interface BuildCommentInput {\n  buildUrl: string;\n  /** Present once the Storybook is published. */\n  storybookUrl?: string | undefined;\n  /** The gating statuses (`testing` or `review`), in display order. */\n  gates: readonly DesiredStatus[];\n  /** Present when `testing` or review is on: the snapshot totals to summarize. */\n  counts?:\n    | {\n        snapshotCount: number;\n        changedCount: number;\n        approvedCount: number;\n        rejectedCount: number;\n      }\n    | undefined;\n}\n\nconst LABEL: Record<DesiredStatus[\"name\"], string> = {\n  testing: \"Visual tests\",\n  review: \"Review\",\n  storybook: \"Storybook\",\n};\n\n/** Comment body (below the idempotency marker): links to the build, the Storybook and a summary. */\nexport function buildCommentMarkdown(input: BuildCommentInput): string {\n  const lines = [`**StoryShelf** — [View build](${input.buildUrl})`];\n  for (const gate of input.gates) {\n    lines.push(`- ${LABEL[gate.name]}: ${gate.description}`);\n  }\n  if (input.counts !== undefined && input.counts.snapshotCount > 0) {\n    const { snapshotCount, changedCount, approvedCount, rejectedCount } = input.counts;\n    lines.push(\n      `- Snapshots: ${String(snapshotCount)} total, ${String(changedCount)} changed, ${String(approvedCount)} approved, ${String(rejectedCount)} rejected`,\n    );\n  }\n  if (input.storybookUrl !== undefined) {\n    lines.push(`- Storybook: [Open the published Storybook](${input.storybookUrl})`);\n  }\n  return lines.join(\"\\n\");\n}\n"],"mappings":";;;;AAqBA,MAAM,QAA+C;CACnD,SAAS;CACT,QAAQ;CACR,WAAW;AACb;;AAGA,SAAgB,qBAAqB,OAAkC;CACrE,MAAM,QAAQ,CAAC,iCAAiC,MAAM,SAAS,EAAE;CACjE,KAAK,MAAM,QAAQ,MAAM,OACvB,MAAM,KAAK,KAAK,MAAM,KAAK,MAAM,IAAI,KAAK,aAAa;CAEzD,IAAI,MAAM,WAAW,KAAA,KAAa,MAAM,OAAO,gBAAgB,GAAG;EAChE,MAAM,EAAE,eAAe,cAAc,eAAe,kBAAkB,MAAM;EAC5E,MAAM,KACJ,gBAAgB,OAAO,aAAa,EAAE,UAAU,OAAO,YAAY,EAAE,YAAY,OAAO,aAAa,EAAE,aAAa,OAAO,aAAa,EAAE,UAC5I;CACF;CACA,IAAI,MAAM,iBAAiB,KAAA,GACzB,MAAM,KAAK,+CAA+C,MAAM,aAAa,EAAE;CAEjF,OAAO,MAAM,KAAK,IAAI;AACxB"}

package/dist/adapters/notifier/build-state.d.mts

@@ -0,0 +1,99 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { NotifierState, StateAnnotation } from "./types.mjs";
+import { UrlBuilder } from "../../urls.mjs";
+//#region src/adapters/notifier/build-state.d.ts
+/** Most per-snapshot annotations a build state carries; the rest are counted (`omitted`). */
+declare const MAX_ANNOTATIONS = 200;
+/** Names of the statuses below a channel's prefix. */
+type StatusName = "testing" | "review" | "storybook";
+/** How publishing the build's Storybook stands. */
+type PublishingState = "pending" | "success" | "failure";
+/** What decides which statuses exist (ADR 0014, decision 5). */
+interface BuildStateFlags {
+  /** `testing` is on: `<prefix>/testing` is the merge gate. */
+  testing: boolean;
+  /** Review is on for the project: with `testing` off, `<prefix>/review` is the gate. */
+  review: boolean;
+}
+/** The part of a build row the function reads. */
+interface BuildStateBuild {
+  id: string;
+  gitSha: string;
+  /** Build status: `pending`, `capturing`, `comparing`, `reviewing`, `approved`, `rejected`, `failed`, `cancelled`. */
+  status: string;
+  snapshotCount: number;
+  changedCount: number;
+  approvedCount: number;
+  rejectedCount: number;
+}
+/** The part of a snapshot row the annotations read. */
+interface BuildStateChange {
+  id: string;
+  /** `changed` or `new`; anything else is not a change to review. */
+  status: string;
+  storyTitle: string;
+  storyName: string;
+  storyImportPath: string | null;
+  viewportName: string;
+  browser?: string | undefined;
+}
+/** Inputs of {@link statusesForBuild}. */
+interface BuildStateInput {
+  build: BuildStateBuild;
+  projectSlug: string;
+  /** The channel's status-name prefix, without a trailing slash. */
+  prefix: string;
+  /**
+   * Absolute links (`createUrlBuilder(publicOrigin)`). A build's state is only ever shown once a
+   * public origin is resolved (ADR 0014, decision 11), so every status links and the comment exists.
+   */
+  urls: Pick<UrlBuilder, "build" | "storybookBuild" | "snapshot">;
+  flags: BuildStateFlags;
+  publishing: PublishingState;
+  /**
+   * Approval progress of the build-level review: the approvals among each reviewer's latest
+   * verdict and the approvals the project requires. Shown on `<prefix>/review` while it waits.
+   */
+  approvals?: {
+    given: number;
+    required: number;
+  } | undefined;
+  /** The build's snapshots; the `changed` and `new` ones become annotations of `<prefix>/testing`. */
+  changes?: readonly BuildStateChange[] | undefined;
+}
+/** One commit status to show. */
+interface DesiredStatus {
+  name: StatusName;
+  /** Full name on the host, `<prefix>/<name>`. */
+  context: string;
+  state: NotifierState;
+  description: string;
+  /** What the status links to: the build page, or the published Storybook for `storybook`. */
+  url: string;
+  /** True for the Storybook status, which is never a gate. */
+  informational?: boolean;
+  /** Set on a `pending` status: `queued` before capture starts, else `running`. */
+  progress?: "queued" | "running";
+  /** Per-snapshot findings (only `testing`), at most {@link MAX_ANNOTATIONS}. */
+  annotations?: StateAnnotation[];
+  /** Changes beyond the cap. */
+  omitted?: number;
+}
+/** The pull-request comment to show. */
+interface DesiredComment {
+  /** The build page; it keys the comment, one per build. */
+  url: string;
+  markdown: string;
+  state: NotifierState;
+}
+/** Everything a channel should show for a build. */
+interface BuildStateSet {
+  statuses: DesiredStatus[];
+  comment: DesiredComment | null;
+}
+/** Statuses and comment for a build; empty without a real commit (no SHA or a local identity). */
+declare function statusesForBuild(input: BuildStateInput): BuildStateSet;
+//#endregion
+export { BuildStateBuild, BuildStateChange, BuildStateFlags, BuildStateInput, BuildStateSet, DesiredComment, DesiredStatus, MAX_ANNOTATIONS, PublishingState, StatusName, statusesForBuild };
+//# sourceMappingURL=build-state.d.mts.map

package/dist/adapters/notifier/build-state.mjs

@@ -0,0 +1,218 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { buildCommentMarkdown } from "./build-comment.mjs";
+import { LOCAL_SHA_PREFIX } from "@storyshelf/affected";
+//#region src/adapters/notifier/build-state.ts
+/**
+* The states a build's git channels show, as one pure function of the build (ADR 0014, decision 5).
+* It reads no clock, database or provider: callers hand it the build, the channel's prefix and the
+* flags, and write the result to the host. Every transition and the end of publishing call it
+* again, so a build that was never captured still gets its statuses and a repeated call changes
+* nothing.
+*/
+/** Most per-snapshot annotations a build state carries; the rest are counted (`omitted`). */
+const MAX_ANNOTATIONS = 200;
+/** Statuses and comment for a build; empty without a real commit (no SHA or a local identity). */
+function statusesForBuild(input) {
+	const { build } = input;
+	if (build.gitSha.length === 0 || build.gitSha.startsWith(LOCAL_SHA_PREFIX)) return {
+		statuses: [],
+		comment: null
+	};
+	const links = linksOf(input);
+	const statuses = [...withAnnotations(gateStatus(input, links.build), input), storybookStatus(input.publishing, input.prefix, links)].map((status) => withProgress(status, input.build));
+	return {
+		statuses,
+		comment: commentOf(input, statuses, links)
+	};
+}
+/** `pending` is `queued` while the build waits to be captured, `running` after. */
+function withProgress(status, build) {
+	if (status.state !== "pending") return status;
+	const queued = status.name !== "storybook" && build.status === "pending";
+	return {
+		...status,
+		progress: queued ? "queued" : "running"
+	};
+}
+/** One annotation per changed snapshot, on the `testing` gate. */
+function withAnnotations(gates, input) {
+	const changed = (input.changes ?? []).filter((c) => c.status === "changed" || c.status === "new");
+	if (changed.length === 0) return gates;
+	const annotations = changed.slice(0, 200).map((change) => annotationOf(change, input));
+	const omitted = changed.length - annotations.length;
+	return gates.map((gate) => gate.name === "testing" ? {
+		...gate,
+		annotations,
+		...omitted > 0 ? { omitted } : {}
+	} : gate);
+}
+function annotationOf(change, input) {
+	const where = [change.viewportName, change.browser].filter(Boolean).join(", ");
+	const isNew = change.status === "new";
+	const name = `${change.storyTitle} / ${change.storyName}`;
+	return {
+		path: change.storyImportPath?.replace(/^(?:\.\/)+/u, "") ?? ".storybook",
+		title: where === "" ? name : `${name} (${where})`,
+		message: `${isNew ? "New snapshot" : "Visual change"}: review it at ${input.urls.snapshot(input.projectSlug, input.build.id, change.id)}`,
+		url: input.urls.snapshot(input.projectSlug, input.build.id, change.id),
+		level: isNew ? "notice" : "warning"
+	};
+}
+function commentOf(input, statuses, links) {
+	const gates = statuses.filter((status) => status.name !== "storybook");
+	return {
+		url: links.build,
+		state: gates[0]?.state ?? "success",
+		markdown: buildCommentMarkdown({
+			buildUrl: links.build,
+			storybookUrl: input.publishing === "success" ? links.storybook : void 0,
+			gates,
+			counts: input.flags.testing || input.flags.review ? input.build : void 0
+		})
+	};
+}
+/** The links to show. */
+function linksOf(input) {
+	const { urls, projectSlug, build } = input;
+	return {
+		build: urls.build(projectSlug, build.id),
+		storybook: `${urls.storybookBuild(projectSlug, build.id).replace(/\/+$/u, "")}/`
+	};
+}
+/** `testing` when it is on; `review` when only review is on; none for a hosting-only build. */
+function gateStatus(input, url) {
+	const { flags, build, prefix } = input;
+	if (flags.testing) return [{
+		name: "testing",
+		context: `${prefix}/testing`,
+		url,
+		...testingOutcome(build)
+	}];
+	if (flags.review) return [{
+		name: "review",
+		context: `${prefix}/review`,
+		url,
+		...reviewOutcome(build, input.approvals)
+	}];
+	return reviewClosed(input, url);
+}
+/**
+* Review is off and the build is accepted: a final `success`, so a `<prefix>/review` status left
+* `pending` by the time review was on (the switch-off pass accepts such builds) does not stay on
+* the pull request. The function sees no history, so every accepted build of a project with review
+* off shows it, and a host that requires the status never waits for one that will not come.
+*/
+function reviewClosed(input, url) {
+	if (input.build.status !== "approved") return [];
+	const { prefix } = input;
+	return [{
+		name: "review",
+		context: `${prefix}/review`,
+		url,
+		state: "success",
+		description: "Review is off"
+	}];
+}
+/**
+* A user cancelled the build (ADR 0006). It closes both gates the same way: the host shows
+* `cancelled` where it has the state (GitLab `canceled`, GitHub `error`), so a required status does
+* not wait for a result that will never come, and nothing says the build failed or was reviewed.
+*/
+const CANCELLED = {
+	state: "cancelled",
+	description: "Cancelled"
+};
+/** `pending` until captured, `pending` while review is open, then the review's result. */
+function testingOutcome(build) {
+	switch (build.status) {
+		case "reviewing": return {
+			state: "pending",
+			description: `Review open: ${plural(openCount(build), "change")} to review`
+		};
+		case "approved": return {
+			state: "success",
+			description: approvedText(build)
+		};
+		case "rejected": return {
+			state: "failure",
+			description: `Review closed: ${plural(build.rejectedCount, "change")} rejected`
+		};
+		case "failed": return {
+			state: "failure",
+			description: "Capture failed"
+		};
+		case "cancelled": return CANCELLED;
+		default: return {
+			state: "pending",
+			description: "Capturing and comparing screenshots"
+		};
+	}
+}
+/** The build-level verdict: `pending` until given, then `success` or `failure`. */
+function reviewOutcome(build, approvals) {
+	switch (build.status) {
+		case "approved": return {
+			state: "success",
+			description: "Build approved"
+		};
+		case "rejected": return {
+			state: "failure",
+			description: "Build rejected"
+		};
+		case "failed": return {
+			state: "failure",
+			description: "Build failed"
+		};
+		case "cancelled": return CANCELLED;
+		default: return {
+			state: "pending",
+			description: waitingText(approvals)
+		};
+	}
+}
+/** Informational: never a gate, linking to the published Storybook once there is one. */
+function storybookStatus(publishing, prefix, links) {
+	const base = {
+		name: "storybook",
+		context: `${prefix}/storybook`,
+		informational: true
+	};
+	if (publishing === "success") return {
+		...base,
+		state: "success",
+		description: "Storybook published",
+		url: links.storybook
+	};
+	if (publishing === "failure") return {
+		...base,
+		state: "failure",
+		description: "Storybook could not be published",
+		url: links.build
+	};
+	return {
+		...base,
+		state: "pending",
+		description: "Publishing Storybook",
+		url: links.build
+	};
+}
+/** `1 of 2 approvals` when the project needs several; a single approval just waits for a verdict. */
+function waitingText(approvals) {
+	if (approvals === void 0 || approvals.required <= 1) return "Waiting for a review verdict";
+	return `Waiting for approvals: ${String(approvals.given)} of ${String(approvals.required)}`;
+}
+function openCount(build) {
+	return Math.max(0, build.changedCount - build.approvedCount - build.rejectedCount);
+}
+function approvedText(build) {
+	return build.changedCount === 0 ? "Review closed: no visual changes" : `Review closed: ${plural(build.approvedCount, "change")} approved`;
+}
+function plural(count, noun) {
+	return `${String(count)} ${noun}${count === 1 ? "" : "s"}`;
+}
+//#endregion
+export { MAX_ANNOTATIONS, statusesForBuild };
+
+//# sourceMappingURL=build-state.mjs.map

package/dist/adapters/notifier/build-state.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-state.mjs","names":[],"sources":["../../../src/adapters/notifier/build-state.ts"],"sourcesContent":["/**\n * The states a build's git channels show, as one pure function of the build (ADR 0014, decision 5).\n * It reads no clock, database or provider: callers hand it the build, the channel's prefix and the\n * flags, and write the result to the host. Every transition and the end of publishing call it\n * again, so a build that was never captured still gets its statuses and a repeated call changes\n * nothing.\n */\nimport { LOCAL_SHA_PREFIX } from \"@storyshelf/affected\";\nimport type { UrlBuilder } from \"../../urls.ts\";\nimport { buildCommentMarkdown } from \"./build-comment.ts\";\nimport type { NotifierState, StateAnnotation } from \"./types.ts\";\n\n/** Most per-snapshot annotations a build state carries; the rest are counted (`omitted`). */\nexport const MAX_ANNOTATIONS = 200;\n\n/** Names of the statuses below a channel's prefix. */\nexport type StatusName = \"testing\" | \"review\" | \"storybook\";\n\n/** How publishing the build's Storybook stands. */\nexport type PublishingState = \"pending\" | \"success\" | \"failure\";\n\n/** What decides which statuses exist (ADR 0014, decision 5). */\nexport interface BuildStateFlags {\n  /** `testing` is on: `<prefix>/testing` is the merge gate. */\n  testing: boolean;\n  /** Review is on for the project: with `testing` off, `<prefix>/review` is the gate. */\n  review: boolean;\n}\n\n/** The part of a build row the function reads. */\nexport interface BuildStateBuild {\n  id: string;\n  gitSha: string;\n  /** Build status: `pending`, `capturing`, `comparing`, `reviewing`, `approved`, `rejected`, `failed`, `cancelled`. */\n  status: string;\n  snapshotCount: number;\n  changedCount: number;\n  approvedCount: number;\n  rejectedCount: number;\n}\n\n/** The part of a snapshot row the annotations read. */\nexport interface BuildStateChange {\n  id: string;\n  /** `changed` or `new`; anything else is not a change to review. */\n  status: string;\n  storyTitle: string;\n  storyName: string;\n  storyImportPath: string | null;\n  viewportName: string;\n  browser?: string | undefined;\n}\n\n/** Inputs of {@link statusesForBuild}. */\nexport interface BuildStateInput {\n  build: BuildStateBuild;\n  projectSlug: string;\n  /** The channel's status-name prefix, without a trailing slash. */\n  prefix: string;\n  /**\n   * Absolute links (`createUrlBuilder(publicOrigin)`). A build's state is only ever shown once a\n   * public origin is resolved (ADR 0014, decision 11), so every status links and the comment exists.\n   */\n  urls: Pick<UrlBuilder, \"build\" | \"storybookBuild\" | \"snapshot\">;\n  flags: BuildStateFlags;\n  publishing: PublishingState;\n  /**\n   * Approval progress of the build-level review: the approvals among each reviewer's latest\n   * verdict and the approvals the project requires. Shown on `<prefix>/review` while it waits.\n   */\n  approvals?: { given: number; required: number } | undefined;\n  /** The build's snapshots; the `changed` and `new` ones become annotations of `<prefix>/testing`. */\n  changes?: readonly BuildStateChange[] | undefined;\n}\n\n/** One commit status to show. */\nexport interface DesiredStatus {\n  name: StatusName;\n  /** Full name on the host, `<prefix>/<name>`. */\n  context: string;\n  state: NotifierState;\n  description: string;\n  /** What the status links to: the build page, or the published Storybook for `storybook`. */\n  url: string;\n  /** True for the Storybook status, which is never a gate. */\n  informational?: boolean;\n  /** Set on a `pending` status: `queued` before capture starts, else `running`. */\n  progress?: \"queued\" | \"running\";\n  /** Per-snapshot findings (only `testing`), at most {@link MAX_ANNOTATIONS}. */\n  annotations?: StateAnnotation[];\n  /** Changes beyond the cap. */\n  omitted?: number;\n}\n\n/** The pull-request comment to show. */\nexport interface DesiredComment {\n  /** The build page; it keys the comment, one per build. */\n  url: string;\n  markdown: string;\n  state: NotifierState;\n}\n\n/** Everything a channel should show for a build. */\nexport interface BuildStateSet {\n  statuses: DesiredStatus[];\n  comment: DesiredComment | null;\n}\n\n/** Statuses and comment for a build; empty without a real commit (no SHA or a local identity). */\nexport function statusesForBuild(input: BuildStateInput): BuildStateSet {\n  const { build } = input;\n  if (build.gitSha.length === 0 || build.gitSha.startsWith(LOCAL_SHA_PREFIX)) {\n    return { statuses: [], comment: null };\n  }\n  const links = linksOf(input);\n  const statuses = [\n    ...withAnnotations(gateStatus(input, links.build), input),\n    storybookStatus(input.publishing, input.prefix, links),\n  ].map((status) => withProgress(status, input.build));\n  return { statuses, comment: commentOf(input, statuses, links) };\n}\n\n/** `pending` is `queued` while the build waits to be captured, `running` after. */\nfunction withProgress(status: DesiredStatus, build: BuildStateBuild): DesiredStatus {\n  if (status.state !== \"pending\") {\n    return status;\n  }\n  const queued = status.name !== \"storybook\" && build.status === \"pending\";\n  return { ...status, progress: queued ? \"queued\" : \"running\" };\n}\n\n/** One annotation per changed snapshot, on the `testing` gate. */\nfunction withAnnotations(gates: DesiredStatus[], input: BuildStateInput): DesiredStatus[] {\n  const changed = (input.changes ?? []).filter((c) => c.status === \"changed\" || c.status === \"new\");\n  if (changed.length === 0) {\n    return gates;\n  }\n  const annotations = changed\n    .slice(0, MAX_ANNOTATIONS)\n    .map((change) => annotationOf(change, input));\n  const omitted = changed.length - annotations.length;\n  return gates.map((gate) =>\n    gate.name === \"testing\" ? { ...gate, annotations, ...(omitted > 0 ? { omitted } : {}) } : gate,\n  );\n}\n\nfunction annotationOf(change: BuildStateChange, input: BuildStateInput): StateAnnotation {\n  const where = [change.viewportName, change.browser].filter(Boolean).join(\", \");\n  const isNew = change.status === \"new\";\n  const name = `${change.storyTitle} / ${change.storyName}`;\n  return {\n    path: change.storyImportPath?.replace(/^(?:\\.\\/)+/u, \"\") ?? \".storybook\",\n    title: where === \"\" ? name : `${name} (${where})`,\n    message: `${isNew ? \"New snapshot\" : \"Visual change\"}: review it at ${input.urls.snapshot(input.projectSlug, input.build.id, change.id)}`,\n    url: input.urls.snapshot(input.projectSlug, input.build.id, change.id),\n    level: isNew ? \"notice\" : \"warning\",\n  };\n}\n\nfunction commentOf(\n  input: BuildStateInput,\n  statuses: DesiredStatus[],\n  links: Links,\n): DesiredComment {\n  const gates = statuses.filter((status) => status.name !== \"storybook\");\n  return {\n    url: links.build,\n    state: gates[0]?.state ?? \"success\",\n    markdown: buildCommentMarkdown({\n      buildUrl: links.build,\n      storybookUrl: input.publishing === \"success\" ? links.storybook : undefined,\n      gates,\n      counts: input.flags.testing || input.flags.review ? input.build : undefined,\n    }),\n  };\n}\n\ninterface Links {\n  build: string;\n  storybook: string;\n}\n\n/** The links to show. */\nfunction linksOf(input: BuildStateInput): Links {\n  const { urls, projectSlug, build } = input;\n  return {\n    build: urls.build(projectSlug, build.id),\n    storybook: `${urls.storybookBuild(projectSlug, build.id).replace(/\\/+$/u, \"\")}/`,\n  };\n}\n\n/** `testing` when it is on; `review` when only review is on; none for a hosting-only build. */\nfunction gateStatus(input: BuildStateInput, url: string): DesiredStatus[] {\n  const { flags, build, prefix } = input;\n  if (flags.testing) {\n    return [{ name: \"testing\", context: `${prefix}/testing`, url, ...testingOutcome(build) }];\n  }\n  if (flags.review) {\n    return [\n      {\n        name: \"review\",\n        context: `${prefix}/review`,\n        url,\n        ...reviewOutcome(build, input.approvals),\n      },\n    ];\n  }\n  return reviewClosed(input, url);\n}\n\n/**\n * Review is off and the build is accepted: a final `success`, so a `<prefix>/review` status left\n * `pending` by the time review was on (the switch-off pass accepts such builds) does not stay on\n * the pull request. The function sees no history, so every accepted build of a project with review\n * off shows it, and a host that requires the status never waits for one that will not come.\n */\nfunction reviewClosed(input: BuildStateInput, url: string): DesiredStatus[] {\n  if (input.build.status !== \"approved\") {\n    return [];\n  }\n  const { prefix } = input;\n  return [\n    {\n      name: \"review\",\n      context: `${prefix}/review`,\n      url,\n      state: \"success\",\n      description: \"Review is off\",\n    },\n  ];\n}\n\ntype Outcome = Pick<DesiredStatus, \"state\" | \"description\">;\n\n/**\n * A user cancelled the build (ADR 0006). It closes both gates the same way: the host shows\n * `cancelled` where it has the state (GitLab `canceled`, GitHub `error`), so a required status does\n * not wait for a result that will never come, and nothing says the build failed or was reviewed.\n */\nconst CANCELLED: Outcome = { state: \"cancelled\", description: \"Cancelled\" };\n\n/** `pending` until captured, `pending` while review is open, then the review's result. */\nfunction testingOutcome(build: BuildStateBuild): Outcome {\n  switch (build.status) {\n    case \"reviewing\": {\n      return {\n        state: \"pending\",\n        description: `Review open: ${plural(openCount(build), \"change\")} to review`,\n      };\n    }\n    case \"approved\": {\n      return { state: \"success\", description: approvedText(build) };\n    }\n    case \"rejected\": {\n      return {\n        state: \"failure\",\n        description: `Review closed: ${plural(build.rejectedCount, \"change\")} rejected`,\n      };\n    }\n    case \"failed\": {\n      return { state: \"failure\", description: \"Capture failed\" };\n    }\n    case \"cancelled\": {\n      return CANCELLED;\n    }\n    default: {\n      return { state: \"pending\", description: \"Capturing and comparing screenshots\" };\n    }\n  }\n}\n\n/** The build-level verdict: `pending` until given, then `success` or `failure`. */\nfunction reviewOutcome(build: BuildStateBuild, approvals: BuildStateInput[\"approvals\"]): Outcome {\n  switch (build.status) {\n    case \"approved\": {\n      return { state: \"success\", description: \"Build approved\" };\n    }\n    case \"rejected\": {\n      return { state: \"failure\", description: \"Build rejected\" };\n    }\n    case \"failed\": {\n      return { state: \"failure\", description: \"Build failed\" };\n    }\n    case \"cancelled\": {\n      return CANCELLED;\n    }\n    default: {\n      return { state: \"pending\", description: waitingText(approvals) };\n    }\n  }\n}\n\n/** Informational: never a gate, linking to the published Storybook once there is one. */\nfunction storybookStatus(publishing: PublishingState, prefix: string, links: Links): DesiredStatus {\n  const base = { name: \"storybook\", context: `${prefix}/storybook`, informational: true } as const;\n  if (publishing === \"success\") {\n    return {\n      ...base,\n      state: \"success\",\n      description: \"Storybook published\",\n      url: links.storybook,\n    };\n  }\n  if (publishing === \"failure\") {\n    return {\n      ...base,\n      state: \"failure\",\n      description: \"Storybook could not be published\",\n      url: links.build,\n    };\n  }\n  return { ...base, state: \"pending\", description: \"Publishing Storybook\", url: links.build };\n}\n\n/** `1 of 2 approvals` when the project needs several; a single approval just waits for a verdict. */\nfunction waitingText(approvals: BuildStateInput[\"approvals\"]): string {\n  if (approvals === undefined || approvals.required <= 1) {\n    return \"Waiting for a review verdict\";\n  }\n  return `Waiting for approvals: ${String(approvals.given)} of ${String(approvals.required)}`;\n}\n\nfunction openCount(build: BuildStateBuild): number {\n  return Math.max(0, build.changedCount - build.approvedCount - build.rejectedCount);\n}\n\nfunction approvedText(build: BuildStateBuild): string {\n  return build.changedCount === 0\n    ? \"Review closed: no visual changes\"\n    : `Review closed: ${plural(build.approvedCount, \"change\")} approved`;\n}\n\nfunction plural(count: number, noun: string): string {\n  return `${String(count)} ${noun}${count === 1 ? \"\" : \"s\"}`;\n}\n"],"mappings":"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"}

package/dist/adapters/notifier/events.d.mts

@@ -1,8 +1,8 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { NotificationBrand, NotificationChannel, NotificationEvent, SystemNotification } from "./types.mjs";
-import { NotifierProvider } from "./provider.mjs";
 import { Logger } from "../../logger.mjs";
+import { ChannelOutcome, NotificationBrand, NotificationChannel, NotificationEvent, SystemNotification } from "./types.mjs";
+import { NotifierProvider } from "./provider.mjs";
 //#region src/adapters/notifier/events.d.ts
 /** Options for project-event fan-out (inline best-effort, non-fatal). */
 interface EmitNotificationsOptions {
@@ -10,6 +10,8 @@ interface EmitNotificationsOptions {
   channels?: NotificationChannel[];
   brand?: NotificationBrand;
   logger?: Logger;
+  /** Called once per attempted channel so the host can record or clear its last error. */
+  onOutcome?: (outcome: ChannelOutcome) => Promise<void> | void;
 }
 /**
  * Deliver a project event to every subscribed channel.

package/dist/adapters/notifier/events.mjs

@@ -1,13 +1,20 @@
 import "node:path";
 import "node:url";
 import.meta.url;
+import { sanitizeErrorText } from "../../utils/redact.mjs";
 import { formatNotification, formatSystemNotification } from "./format.mjs";
+import { isStateProvider } from "./provider.mjs";
 //#region src/adapters/notifier/events.ts
 /** Check an event against a channel's allowlist (empty = all). */
 function subscribed(channel, event) {
 	if (!channel.enabled) return false;
 	return channel.events.length === 0 || channel.events.includes(event);
 }
+/** `state` channels (git hosts) follow build state, never the message fan-out. */
+function isMessageChannel(notifiers, channel) {
+	const provider = providerFor(notifiers, channel.provider);
+	return provider === void 0 || !isStateProvider(provider);
+}
 /** Resolve a provider for a channel kind, or undefined when unwired. */
 function providerFor(notifiers, kind) {
 	return notifiers?.find((candidate) => candidate.metadata.kind === kind);
@@ -16,6 +23,7 @@ function providerFor(notifiers, kind) {
 async function deliver(notifiers, channel, formatted) {
 	const provider = providerFor(notifiers, channel.provider);
 	if (!provider) throw new Error(`notifier missing: ${channel.provider}`);
+	if (isStateProvider(provider)) throw new Error(`notifier ${channel.provider} delivers state, not messages`);
 	await provider.create({
 		config: channel.config,
 		secret: channel.secret
@@ -24,22 +32,33 @@ async function deliver(notifiers, channel, formatted) {
 		formatted
 	});
 }
+/** Deliver to one channel, report the outcome and swallow the failure (logged). */
+async function deliverReported(options, channel, formatted, failure) {
+	let problem;
+	try {
+		await deliver(options.notifiers, channel, formatted);
+	} catch (error) {
+		options.logger?.warn({
+			err: error,
+			channelId: channel.id
+		}, failure);
+		problem = sanitizeErrorText(error instanceof Error ? error.message : String(error), 500);
+	}
+	await options.onOutcome?.({
+		channelId: channel.id,
+		...problem === void 0 ? {} : { error: problem }
+	});
+}
 /**
 * Deliver a project event to every subscribed channel.
 * Inline best-effort: `Promise.allSettled`, failures logged and swallowed.
 */
 async function emitNotifications(event, options = {}) {
-	const targets = (options.channels ?? []).filter((channel) => subscribed(channel, event.event));
+	const targets = (options.channels ?? []).filter((channel) => subscribed(channel, event.event) && isMessageChannel(options.notifiers, channel));
 	if (targets.length === 0) return;
+	const formatted = formatNotification(event, options.brand);
 	await Promise.allSettled(targets.map(async (channel) => {
-		try {
-			await deliver(options.notifiers, channel, formatNotification(event, options.brand));
-		} catch (error) {
-			options.logger?.warn({
-				err: error,
-				channelId: channel.id
-			}, "notification failed");
-		}
+		await deliverReported(options, channel, formatted, "notification failed");
 	}));
 }
 /**
@@ -47,17 +66,11 @@ async function emitNotifications(event, options = {}) {
 * (e.g. `sys:user-created`, `sys:capture-failed`, `sys:purge-completed`).
 */
 async function emitSystemNotification(event, options = {}) {
-	const targets = (options.channels ?? []).filter((channel) => channel.projectId === null && subscribed(channel, event.event));
+	const targets = (options.channels ?? []).filter((channel) => channel.projectId === null && subscribed(channel, event.event) && isMessageChannel(options.notifiers, channel));
 	if (targets.length === 0) return;
+	const formatted = formatSystemNotification(event, options.brand);
 	await Promise.allSettled(targets.map(async (channel) => {
-		try {
-			await deliver(options.notifiers, channel, formatSystemNotification(event, options.brand));
-		} catch (error) {
-			options.logger?.warn({
-				err: error,
-				channelId: channel.id
-			}, "system notification failed");
-		}
+		await deliverReported(options, channel, formatted, "system notification failed");
 	}));
 }
 //#endregion

package/dist/adapters/notifier/events.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"events.mjs","names":[],"sources":["../../../src/adapters/notifier/events.ts"],"sourcesContent":["import type { Logger } from \"../../logger.ts\";\nimport { formatNotification, formatSystemNotification } from \"./format.ts\";\nimport type { NotifierProvider } from \"./provider.ts\";\nimport type {\n  NotificationBrand,\n  NotificationChannel,\n  NotificationEvent,\n  SystemNotification,\n} from \"./types.ts\";\n\n/** Options for project-event fan-out (inline best-effort, non-fatal). */\nexport interface EmitNotificationsOptions {\n  notifiers?: NotifierProvider[];\n  channels?: NotificationChannel[];\n  brand?: NotificationBrand;\n  logger?: Logger;\n}\n\n/** Check an event against a channel's allowlist (empty = all). */\nfunction subscribed(channel: NotificationChannel, event: string): boolean {\n  if (!channel.enabled) {\n    return false;\n  }\n  return channel.events.length === 0 || channel.events.includes(event);\n}\n\n/** Resolve a provider for a channel kind, or undefined when unwired. */\nfunction providerFor(\n  notifiers: NotifierProvider[] | undefined,\n  kind: string,\n): NotifierProvider | undefined {\n  return notifiers?.find((candidate) => candidate.metadata.kind === kind);\n}\n\n/** Send one formatted event through a channel's provider (throws on failure). */\nasync function deliver(\n  notifiers: NotifierProvider[] | undefined,\n  channel: NotificationChannel,\n  formatted: ReturnType<typeof formatNotification>,\n): Promise<void> {\n  const provider = providerFor(notifiers, channel.provider);\n  if (!provider) {\n    throw new Error(`notifier missing: ${channel.provider}`);\n  }\n  const sender = provider.create({ config: channel.config, secret: channel.secret });\n  await sender.send({ channel, formatted });\n}\n\n/**\n * Deliver a project event to every subscribed channel.\n * Inline best-effort: `Promise.allSettled`, failures logged and swallowed.\n */\nexport async function emitNotifications(\n  event: NotificationEvent,\n  options: EmitNotificationsOptions = {},\n): Promise<void> {\n  const targets = (options.channels ?? []).filter((channel) => subscribed(channel, event.event));\n  if (targets.length === 0) {\n    return;\n  }\n  await Promise.allSettled(\n    targets.map(async (channel) => {\n      try {\n        await deliver(options.notifiers, channel, formatNotification(event, options.brand));\n      } catch (error) {\n        options.logger?.warn({ err: error, channelId: channel.id }, \"notification failed\");\n      }\n    }),\n  );\n}\n\n/**\n * Deliver a site-wide admin alert to project-less channels\n * (e.g. `sys:user-created`, `sys:capture-failed`, `sys:purge-completed`).\n */\nexport async function emitSystemNotification(\n  event: SystemNotification,\n  options: EmitNotificationsOptions = {},\n): Promise<void> {\n  const targets = (options.channels ?? []).filter(\n    (channel) => channel.projectId === null && subscribed(channel, event.event),\n  );\n  if (targets.length === 0) {\n    return;\n  }\n  await Promise.allSettled(\n    targets.map(async (channel) => {\n      try {\n        await deliver(options.notifiers, channel, formatSystemNotification(event, options.brand));\n      } catch (error) {\n        options.logger?.warn({ err: error, channelId: channel.id }, \"system notification failed\");\n      }\n    }),\n  );\n}\n"],"mappings":";;;;;;AAmBA,SAAS,WAAW,SAA8B,OAAwB;CACxE,IAAI,CAAC,QAAQ,SACX,OAAO;CAET,OAAO,QAAQ,OAAO,WAAW,KAAK,QAAQ,OAAO,SAAS,KAAK;AACrE;;AAGA,SAAS,YACP,WACA,MAC8B;CAC9B,OAAO,WAAW,MAAM,cAAc,UAAU,SAAS,SAAS,IAAI;AACxE;;AAGA,eAAe,QACb,WACA,SACA,WACe;CACf,MAAM,WAAW,YAAY,WAAW,QAAQ,QAAQ;CACxD,IAAI,CAAC,UACH,MAAM,IAAI,MAAM,qBAAqB,QAAQ,UAAU;CAGzD,MADe,SAAS,OAAO;EAAE,QAAQ,QAAQ;EAAQ,QAAQ,QAAQ;CAAO,CACrE,CAAC,CAAC,KAAK;EAAE;EAAS;CAAU,CAAC;AAC1C;;;;;AAMA,eAAsB,kBACpB,OACA,UAAoC,CAAC,GACtB;CACf,MAAM,WAAW,QAAQ,YAAY,CAAC,EAAA,CAAG,QAAQ,YAAY,WAAW,SAAS,MAAM,KAAK,CAAC;CAC7F,IAAI,QAAQ,WAAW,GACrB;CAEF,MAAM,QAAQ,WACZ,QAAQ,IAAI,OAAO,YAAY;EAC7B,IAAI;GACF,MAAM,QAAQ,QAAQ,WAAW,SAAS,mBAAmB,OAAO,QAAQ,KAAK,CAAC;EACpF,SAAS,OAAO;GACd,QAAQ,QAAQ,KAAK;IAAE,KAAK;IAAO,WAAW,QAAQ;GAAG,GAAG,qBAAqB;EACnF;CACF,CAAC,CACH;AACF;;;;;AAMA,eAAsB,uBACpB,OACA,UAAoC,CAAC,GACtB;CACf,MAAM,WAAW,QAAQ,YAAY,CAAC,EAAA,CAAG,QACtC,YAAY,QAAQ,cAAc,QAAQ,WAAW,SAAS,MAAM,KAAK,CAC5E;CACA,IAAI,QAAQ,WAAW,GACrB;CAEF,MAAM,QAAQ,WACZ,QAAQ,IAAI,OAAO,YAAY;EAC7B,IAAI;GACF,MAAM,QAAQ,QAAQ,WAAW,SAAS,yBAAyB,OAAO,QAAQ,KAAK,CAAC;EAC1F,SAAS,OAAO;GACd,QAAQ,QAAQ,KAAK;IAAE,KAAK;IAAO,WAAW,QAAQ;GAAG,GAAG,4BAA4B;EAC1F;CACF,CAAC,CACH;AACF"}
+{"version":3,"file":"events.mjs","names":[],"sources":["../../../src/adapters/notifier/events.ts"],"sourcesContent":["import type { Logger } from \"../../logger.ts\";\nimport { sanitizeErrorText } from \"../../utils/redact.ts\";\nimport { formatNotification, formatSystemNotification } from \"./format.ts\";\nimport { isStateProvider, type NotifierProvider } from \"./provider.ts\";\nimport type {\n  ChannelOutcome,\n  NotificationBrand,\n  NotificationChannel,\n  NotificationEvent,\n  SystemNotification,\n} from \"./types.ts\";\n\n/** Options for project-event fan-out (inline best-effort, non-fatal). */\nexport interface EmitNotificationsOptions {\n  notifiers?: NotifierProvider[];\n  channels?: NotificationChannel[];\n  brand?: NotificationBrand;\n  logger?: Logger;\n  /** Called once per attempted channel so the host can record or clear its last error. */\n  onOutcome?: (outcome: ChannelOutcome) => Promise<void> | void;\n}\n\n/** Check an event against a channel's allowlist (empty = all). */\nfunction subscribed(channel: NotificationChannel, event: string): boolean {\n  if (!channel.enabled) {\n    return false;\n  }\n  return channel.events.length === 0 || channel.events.includes(event);\n}\n\n/** `state` channels (git hosts) follow build state, never the message fan-out. */\nfunction isMessageChannel(\n  notifiers: NotifierProvider[] | undefined,\n  channel: NotificationChannel,\n): boolean {\n  const provider = providerFor(notifiers, channel.provider);\n  return provider === undefined || !isStateProvider(provider);\n}\n\n/** Resolve a provider for a channel kind, or undefined when unwired. */\nfunction providerFor(\n  notifiers: NotifierProvider[] | undefined,\n  kind: string,\n): NotifierProvider | undefined {\n  return notifiers?.find((candidate) => candidate.metadata.kind === kind);\n}\n\n/** Send one formatted event through a channel's provider (throws on failure). */\nasync function deliver(\n  notifiers: NotifierProvider[] | undefined,\n  channel: NotificationChannel,\n  formatted: ReturnType<typeof formatNotification>,\n): Promise<void> {\n  const provider = providerFor(notifiers, channel.provider);\n  if (!provider) {\n    throw new Error(`notifier missing: ${channel.provider}`);\n  }\n  if (isStateProvider(provider)) {\n    throw new Error(`notifier ${channel.provider} delivers state, not messages`);\n  }\n  const sender = provider.create({ config: channel.config, secret: channel.secret });\n  await sender.send({ channel, formatted });\n}\n\n/** Deliver to one channel, report the outcome and swallow the failure (logged). */\nasync function deliverReported(\n  options: EmitNotificationsOptions,\n  channel: NotificationChannel,\n  formatted: ReturnType<typeof formatNotification>,\n  failure: string,\n): Promise<void> {\n  let problem: string | undefined;\n  try {\n    await deliver(options.notifiers, channel, formatted);\n  } catch (error) {\n    options.logger?.warn({ err: error, channelId: channel.id }, failure);\n    problem = sanitizeErrorText(error instanceof Error ? error.message : String(error), 500);\n  }\n  await options.onOutcome?.({\n    channelId: channel.id,\n    ...(problem === undefined ? {} : { error: problem }),\n  });\n}\n\n/**\n * Deliver a project event to every subscribed channel.\n * Inline best-effort: `Promise.allSettled`, failures logged and swallowed.\n */\nexport async function emitNotifications(\n  event: NotificationEvent,\n  options: EmitNotificationsOptions = {},\n): Promise<void> {\n  const targets = (options.channels ?? []).filter(\n    (channel) => subscribed(channel, event.event) && isMessageChannel(options.notifiers, channel),\n  );\n  if (targets.length === 0) {\n    return;\n  }\n  const formatted = formatNotification(event, options.brand);\n  await Promise.allSettled(\n    targets.map(async (channel) => {\n      await deliverReported(options, channel, formatted, \"notification failed\");\n    }),\n  );\n}\n\n/**\n * Deliver a site-wide admin alert to project-less channels\n * (e.g. `sys:user-created`, `sys:capture-failed`, `sys:purge-completed`).\n */\nexport async function emitSystemNotification(\n  event: SystemNotification,\n  options: EmitNotificationsOptions = {},\n): Promise<void> {\n  const targets = (options.channels ?? []).filter(\n    (channel) =>\n      channel.projectId === null &&\n      subscribed(channel, event.event) &&\n      isMessageChannel(options.notifiers, channel),\n  );\n  if (targets.length === 0) {\n    return;\n  }\n  const formatted = formatSystemNotification(event, options.brand);\n  await Promise.allSettled(\n    targets.map(async (channel) => {\n      await deliverReported(options, channel, formatted, \"system notification failed\");\n    }),\n  );\n}\n"],"mappings":";;;;;;;;AAuBA,SAAS,WAAW,SAA8B,OAAwB;CACxE,IAAI,CAAC,QAAQ,SACX,OAAO;CAET,OAAO,QAAQ,OAAO,WAAW,KAAK,QAAQ,OAAO,SAAS,KAAK;AACrE;;AAGA,SAAS,iBACP,WACA,SACS;CACT,MAAM,WAAW,YAAY,WAAW,QAAQ,QAAQ;CACxD,OAAO,aAAa,KAAA,KAAa,CAAC,gBAAgB,QAAQ;AAC5D;;AAGA,SAAS,YACP,WACA,MAC8B;CAC9B,OAAO,WAAW,MAAM,cAAc,UAAU,SAAS,SAAS,IAAI;AACxE;;AAGA,eAAe,QACb,WACA,SACA,WACe;CACf,MAAM,WAAW,YAAY,WAAW,QAAQ,QAAQ;CACxD,IAAI,CAAC,UACH,MAAM,IAAI,MAAM,qBAAqB,QAAQ,UAAU;CAEzD,IAAI,gBAAgB,QAAQ,GAC1B,MAAM,IAAI,MAAM,YAAY,QAAQ,SAAS,8BAA8B;CAG7E,MADe,SAAS,OAAO;EAAE,QAAQ,QAAQ;EAAQ,QAAQ,QAAQ;CAAO,CACrE,CAAC,CAAC,KAAK;EAAE;EAAS;CAAU,CAAC;AAC1C;;AAGA,eAAe,gBACb,SACA,SACA,WACA,SACe;CACf,IAAI;CACJ,IAAI;EACF,MAAM,QAAQ,QAAQ,WAAW,SAAS,SAAS;CACrD,SAAS,OAAO;EACd,QAAQ,QAAQ,KAAK;GAAE,KAAK;GAAO,WAAW,QAAQ;EAAG,GAAG,OAAO;EACnE,UAAU,kBAAkB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GAAG,GAAG;CACzF;CACA,MAAM,QAAQ,YAAY;EACxB,WAAW,QAAQ;EACnB,GAAI,YAAY,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO,QAAQ;CACpD,CAAC;AACH;;;;;AAMA,eAAsB,kBACpB,OACA,UAAoC,CAAC,GACtB;CACf,MAAM,WAAW,QAAQ,YAAY,CAAC,EAAA,CAAG,QACtC,YAAY,WAAW,SAAS,MAAM,KAAK,KAAK,iBAAiB,QAAQ,WAAW,OAAO,CAC9F;CACA,IAAI,QAAQ,WAAW,GACrB;CAEF,MAAM,YAAY,mBAAmB,OAAO,QAAQ,KAAK;CACzD,MAAM,QAAQ,WACZ,QAAQ,IAAI,OAAO,YAAY;EAC7B,MAAM,gBAAgB,SAAS,SAAS,WAAW,qBAAqB;CAC1E,CAAC,CACH;AACF;;;;;AAMA,eAAsB,uBACpB,OACA,UAAoC,CAAC,GACtB;CACf,MAAM,WAAW,QAAQ,YAAY,CAAC,EAAA,CAAG,QACtC,YACC,QAAQ,cAAc,QACtB,WAAW,SAAS,MAAM,KAAK,KAC/B,iBAAiB,QAAQ,WAAW,OAAO,CAC/C;CACA,IAAI,QAAQ,WAAW,GACrB;CAEF,MAAM,YAAY,yBAAyB,OAAO,QAAQ,KAAK;CAC/D,MAAM,QAAQ,WACZ,QAAQ,IAAI,OAAO,YAAY;EAC7B,MAAM,gBAAgB,SAAS,SAAS,WAAW,4BAA4B;CACjF,CAAC,CACH;AACF"}

package/dist/adapters/notifier/provider.d.mts

@@ -1,32 +1,78 @@
 import __tsdown_shims_path from 'node:path';
 import __tsdown_shims_url from 'node:url';
-import { FormattedNotification, NotificationChannel } from "./types.mjs";
+import { FormattedNotification, NotificationChannel, NotifierState, NotifierStateTarget } from "./types.mjs";
 import { Adapter, AdapterMetadata } from "../../adapter/metadata.mjs";
 import { z } from "zod";
 import { Logger } from "pino";
 //#region src/adapters/notifier/provider.d.ts
+/** How a provider delivers: `message` sends once, `state` makes a host show a named state. */
+type NotifierDelivery = "message" | "state";
 /** Notifier-specific metadata (adds logo + config validation schema). */
 interface NotifierMetadata extends AdapterMetadata {
   readonly category: "notifier";
   readonly logo?: string;
   readonly schema: z.ZodType;
+  /** Delivery kind; absent means `message` (chat, email). */
+  readonly delivery?: NotifierDelivery;
 }
-/** Descriptor — registered at startup, validates per-channel config. */
-interface NotifierProvider extends Adapter<NotifierMetadata> {
+/** Metadata of a `message` provider (Slack, Teams, email). */
+interface MessageNotifierMetadata extends NotifierMetadata {
+  readonly delivery?: "message";
+}
+/** Metadata of a `state` provider (GitHub, GitLab): `delivery` is mandatory. */
+interface StateNotifierMetadata extends NotifierMetadata {
+  readonly delivery: "state";
+}
+/** Descriptor of a `message` provider, registered at startup. */
+interface MessageNotifierProvider extends Adapter<MessageNotifierMetadata> {
   create(opts: {
     config: unknown;
     secret?: string;
     logger?: Logger;
-  }): NotifierAdapter;
+  }): MessageNotifierAdapter;
 }
-/** Runtime — bound to one channel config + decrypted secret, sends one message. */
-interface NotifierAdapter extends Adapter<NotifierMetadata> {
+/** Descriptor of a `state` provider, registered at startup. */
+interface StateNotifierProvider extends Adapter<StateNotifierMetadata> {
+  create(opts: {
+    config: unknown;
+    secret?: string;
+    logger?: Logger;
+  }): StateNotifierAdapter;
+}
+/** Descriptor — registered at startup, validates per-channel config. */
+type NotifierProvider = MessageNotifierProvider | StateNotifierProvider;
+/** Runtime of a `message` provider — bound to one channel config + secret, sends one message. */
+interface MessageNotifierAdapter extends Adapter<MessageNotifierMetadata> {
   send(input: {
     channel: NotificationChannel;
     formatted: FormattedNotification;
     logger?: Logger;
   }): Promise<void>;
 }
+/** Input of one idempotent state write. */
+interface SetStateInput {
+  channel: NotificationChannel;
+  /** What to make the host show: a commit status or a pull-request comment. */
+  target: NotifierStateTarget;
+  state: NotifierState;
+  /**
+   * Link back to the build page; also keys the pull-request comment. Absent while no public origin
+   * is known (ADR 0007): a status then has no link and a comment is not written.
+   */
+  url?: string | undefined;
+  logger?: Logger;
+}
+/**
+ * Runtime of a `state` provider: idempotent, latest call wins. A provider that
+ * cannot show a target kind (no comment support) skips it silently.
+ */
+interface StateNotifierAdapter extends Adapter<StateNotifierMetadata> {
+  setState(input: SetStateInput): Promise<void>;
+}
+/** Runtime — bound to one channel config + decrypted secret. */
+type NotifierAdapter = MessageNotifierAdapter | StateNotifierAdapter;
+/** True when the provider delivers state (git hosts) rather than messages. */
+declare function isStateProvider(provider: NotifierProvider): provider is StateNotifierProvider;
 //#endregion
-export { NotifierAdapter, NotifierMetadata, NotifierProvider };
+export { MessageNotifierAdapter, MessageNotifierMetadata, MessageNotifierProvider, NotifierAdapter, NotifierDelivery, NotifierMetadata, NotifierProvider, SetStateInput, StateNotifierAdapter, StateNotifierMetadata, StateNotifierProvider, isStateProvider };
 //# sourceMappingURL=provider.d.mts.map

package/dist/adapters/notifier/provider.mjs

@@ -0,0 +1,12 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/adapters/notifier/provider.ts
+/** True when the provider delivers state (git hosts) rather than messages. */
+function isStateProvider(provider) {
+	return provider.metadata.delivery === "state";
+}
+//#endregion
+export { isStateProvider };
+
+//# sourceMappingURL=provider.mjs.map

package/dist/adapters/notifier/provider.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.mjs","names":[],"sources":["../../../src/adapters/notifier/provider.ts"],"sourcesContent":["import type { Logger } from \"pino\";\nimport type { z } from \"zod\";\nimport type { Adapter, AdapterMetadata } from \"../metadata.ts\";\nimport type {\n  FormattedNotification,\n  NotificationChannel,\n  NotifierState,\n  NotifierStateTarget,\n} from \"./types.ts\";\n\n/** How a provider delivers: `message` sends once, `state` makes a host show a named state. */\nexport type NotifierDelivery = \"message\" | \"state\";\n\n/** Notifier-specific metadata (adds logo + config validation schema). */\nexport interface NotifierMetadata extends AdapterMetadata {\n  readonly category: \"notifier\";\n  readonly logo?: string;\n  readonly schema: z.ZodType;\n  /** Delivery kind; absent means `message` (chat, email). */\n  readonly delivery?: NotifierDelivery;\n}\n\n/** Metadata of a `message` provider (Slack, Teams, email). */\nexport interface MessageNotifierMetadata extends NotifierMetadata {\n  readonly delivery?: \"message\";\n}\n\n/** Metadata of a `state` provider (GitHub, GitLab): `delivery` is mandatory. */\nexport interface StateNotifierMetadata extends NotifierMetadata {\n  readonly delivery: \"state\";\n}\n\n/** Descriptor of a `message` provider, registered at startup. */\nexport interface MessageNotifierProvider extends Adapter<MessageNotifierMetadata> {\n  create(opts: { config: unknown; secret?: string; logger?: Logger }): MessageNotifierAdapter;\n}\n\n/** Descriptor of a `state` provider, registered at startup. */\nexport interface StateNotifierProvider extends Adapter<StateNotifierMetadata> {\n  create(opts: { config: unknown; secret?: string; logger?: Logger }): StateNotifierAdapter;\n}\n\n/** Descriptor — registered at startup, validates per-channel config. */\nexport type NotifierProvider = MessageNotifierProvider | StateNotifierProvider;\n\n/** Runtime of a `message` provider — bound to one channel config + secret, sends one message. */\nexport interface MessageNotifierAdapter extends Adapter<MessageNotifierMetadata> {\n  send(input: {\n    channel: NotificationChannel;\n    formatted: FormattedNotification;\n    logger?: Logger;\n  }): Promise<void>;\n}\n\n/** Input of one idempotent state write. */\nexport interface SetStateInput {\n  channel: NotificationChannel;\n  /** What to make the host show: a commit status or a pull-request comment. */\n  target: NotifierStateTarget;\n  state: NotifierState;\n  /**\n   * Link back to the build page; also keys the pull-request comment. Absent while no public origin\n   * is known (ADR 0007): a status then has no link and a comment is not written.\n   */\n  url?: string | undefined;\n  logger?: Logger;\n}\n\n/**\n * Runtime of a `state` provider: idempotent, latest call wins. A provider that\n * cannot show a target kind (no comment support) skips it silently.\n */\nexport interface StateNotifierAdapter extends Adapter<StateNotifierMetadata> {\n  setState(input: SetStateInput): Promise<void>;\n}\n\n/** Runtime — bound to one channel config + decrypted secret. */\nexport type NotifierAdapter = MessageNotifierAdapter | StateNotifierAdapter;\n\n/** True when the provider delivers state (git hosts) rather than messages. */\nexport function isStateProvider(provider: NotifierProvider): provider is StateNotifierProvider {\n  return provider.metadata.delivery === \"state\";\n}\n"],"mappings":";;;;;AAgFA,SAAgB,gBAAgB,UAA+D;CAC7F,OAAO,SAAS,SAAS,aAAa;AACxC"}