@storyshelf/notify-git 0.0.0-stage → 0.6.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siddhant Gupta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# @storyshelf/notify-git
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Git notification providers for StoryShelf: a `state` channel makes GitHub or GitLab show the current state of a build as a commit status (the merge gate) and a single pull-request or merge-request comment. Zero runtime dependencies — every call goes through `@storyshelf/core/utils` (`httpJson`: timeout + retry with `Retry-After`).
+
+## Install
+
+```sh
+nub add @storyshelf/notify-git
+```
+
+## Quick start
+
+```ts
+import { createShelfApp } from "@storyshelf/app";
+import { gitNotifiers } from "@storyshelf/notify-git";
+
+const app = createShelfApp({ database, storage, notifications: { notifiers: gitNotifiers } });
+```
+
+`gitNotifiers` lists `gitHubNotifier` (`github`), `gitLabNotifier` (`gitlab`) and `gitLogNotifier` (`git-log`, writes to the server log). Combine it with other families: `notifiers: [...chatNotifiers, ...gitNotifiers]`.
+
+Project admins then add a git channel on the project's **Notifications** settings page (or through `POST /api/v1/projects/{slug}/notification-channels`):
+
+- `config`: `{ owner, repo, prefix? }` for GitHub; GitLab also takes `host` (self-managed hosts). `prefix` names the statuses (`<prefix>/testing`, default `storyshelf`); give each project that shares a repository its own prefix.
+- `secret`: the token (GitHub: `repo:status`; GitLab: `api`), stored encrypted and decrypted in memory only at delivery time.
+- GitHub only, `mode`: `statuses` (default; commit statuses with the token) or `checks` (check runs posted by a GitHub App). In `checks` mode `config` also holds `appId` and `installationId`, and the secret is the App's **private key** (PEM) instead of a token. The key is never returned by the API or shown in the UI. GitLab always uses commit statuses.
+
+A git channel is project-scoped and its event filter is fixed: it follows the build's state, not a topic list.
+
+## Providers
+
+`gitNotifiers` aggregates all three providers:
+
+| Provider kind | Writes to                                        | Use for                     |
+| ------------- | ------------------------------------------------ | --------------------------- |
+| `github`      | GitHub commit statuses and pull-request comments | GitHub.com repositories     |
+| `gitlab`      | GitLab commit statuses and merge-request notes   | GitLab.com or self-managed  |
+| `git-log`     | The server log                                   | Tests and local development |
+
+The log provider's kind is `git-log` because `notify-chat` already owns `log`; provider kinds are unique across packages.
+
+## Delivery contract
+
+A `state` provider (`metadata.delivery: "state"`) creates an adapter with one method, `setState({ channel, target, state, url })`:
+
+- `target: { kind: "status", sha, context, description? }` — set the commit status named exactly `context` (the caller owns the prefix; the provider adds nothing).
+- `target: { kind: "comment", sha, markdown }` — create or update the one comment per build (keyed by a hidden marker built from `url`) on the pull request of the commit; skipped when the commit has no pull request.
+- A status target may carry `progress` (`queued` | `running`, for a `pending` state), `informational`, `annotations` and `omitted` (see below). Providers that cannot show them ignore them.
+- `state`: `pending`, `success`, `failure` or `cancelled`.
+
+### GitHub check runs
+
+In `checks` mode a status target becomes a **check run** named exactly `context` (so `storyshelf/testing` is still the name you require). The run mirrors the build: `queued` (not captured yet), `in_progress` (capturing, comparing, review open), then `completed` with `success`, `failure` or `cancelled`; the informational `<prefix>/storybook` run completes `neutral` instead of `failure`. Runs are keyed by commit SHA and the stable `external_id` `storyshelf:<context>`: an existing run is updated, never duplicated. The run's `details_url` is the absolute build URL. `<prefix>/testing` carries one **annotation** per `new` or `changed` snapshot, anchored at the story file, whose `raw_details` is that snapshot's review URL; they are posted in batches of 50 through check-run updates, at most 200 in total, and the summary says `and N more changed snapshots` with a link to the build. Annotations already on the run are skipped, so a repeated delivery adds nothing. The pure mapping lives in `github-check-mapper.ts`; nothing posts from a call site.
+
+Authentication has no dependencies: the provider signs an RS256 JWT with `node:crypto`, exchanges it at `POST /app/installations/{id}/access_tokens` through `httpJson`, and caches the installation token per channel until five minutes before it expires. The pull-request comment uses the same token.
+
+Writes are idempotent and the latest call wins. A rejected write throws, and the host records the error on the channel row. Nothing is read from the git host during capture.
+
+## Direct use
+
+Each provider is a `StateNotifierProvider` from `@storyshelf/core/adapter/notifier`. Bind one to a channel and call `setState`:
+
+```ts
+import { gitHubNotifier } from "@storyshelf/notify-git";
+
+const adapter = gitHubNotifier.create({
+  config: { owner: "acme", repo: "widgets" },
+  secret: process.env.GITHUB_TOKEN,
+});
+
+await adapter.setState({
+  channel,
+  target: { kind: "status", sha, context: "storyshelf/testing", description: "Review closed" },
+  state: "success",
+  url: "https://shelf.example.com/projects/web/builds/01J...",
+});
+```
+
+The status `context` is used verbatim: the caller owns the prefix, the provider adds nothing. StoryShelf derives the contexts, descriptions and links itself; direct use is for custom hosts. A `{ kind: "comment", sha, markdown }` target upserts the review comment instead.
+
+## Development
+
+```sh
+nub run build     # bundle with tsdown
+nub run fmt       # format with oxfmt
+nub run lint      # type-aware lint with oxlint
+nub run test      # vitest suite (the *.live.test.ts files need LIVE_CLOUD=1 and tokens)
+```
+
+See [ADR 0014](../../docs/adr/0014-git-hosts-and-notifications.md).

package/dist/describe.mjs

@@ -0,0 +1,21 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/describe.ts
+/** Short description shown beside a commit status. */
+function describeState(state) {
+	switch (state) {
+		case "pending": return "Visual tests pending";
+		case "success": return "Visual tests passed";
+		case "cancelled": return "Cancelled";
+		default: return "Visual changes detected or tests failed";
+	}
+}
+/** Hidden marker that keys the single comment per build (idempotent upsert). */
+function commentMarker(url) {
+	return `<!-- storyshelf:${url} -->`;
+}
+//#endregion
+export { commentMarker, describeState };
+
+//# sourceMappingURL=describe.mjs.map

package/dist/describe.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.mjs","names":[],"sources":["../src/describe.ts"],"sourcesContent":["/** Human text for a build state and the comment marker shared by GitHub and GitLab. */\nimport type { NotifierState } from \"@storyshelf/core/adapter/notifier\";\n\n/** Short description shown beside a commit status. */\nexport function describeState(state: NotifierState): string {\n  switch (state) {\n    case \"pending\": {\n      return \"Visual tests pending\";\n    }\n    case \"success\": {\n      return \"Visual tests passed\";\n    }\n    case \"cancelled\": {\n      return \"Cancelled\";\n    }\n    default: {\n      return \"Visual changes detected or tests failed\";\n    }\n  }\n}\n\n/** Hidden marker that keys the single comment per build (idempotent upsert). */\nexport function commentMarker(url: string): string {\n  return `<!-- storyshelf:${url} -->`;\n}\n"],"mappings":";;;;;AAIA,SAAgB,cAAc,OAA8B;CAC1D,QAAQ,OAAR;EACE,KAAK,WACH,OAAO;EAET,KAAK,WACH,OAAO;EAET,KAAK,aACH,OAAO;EAET,SACE,OAAO;CAEX;AACF;;AAGA,SAAgB,cAAc,KAAqB;CACjD,OAAO,mBAAmB,IAAI;AAChC"}

package/dist/github-api.mjs

@@ -0,0 +1,25 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/github-api.ts
+/** GitHub REST API helpers (base URL + auth headers). */
+function apiBase() {
+	return "https://api.github.com";
+}
+/** Join a `/repos/{owner}/{repo}` path with a suffix. */
+function repoPath(owner, repo, suffix = "") {
+	return `${apiBase()}/repos/${owner}/${repo}${suffix}`;
+}
+/** Headers for GitHub REST API requests. */
+function githubHeaders(token) {
+	return {
+		accept: "application/vnd.github+json",
+		authorization: `Bearer ${token}`,
+		"content-type": "application/json",
+		"x-github-api-version": "2022-11-28"
+	};
+}
+//#endregion
+export { apiBase, githubHeaders, repoPath };
+
+//# sourceMappingURL=github-api.mjs.map

package/dist/github-api.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-api.mjs","names":[],"sources":["../src/github-api.ts"],"sourcesContent":["/** GitHub REST API helpers (base URL + auth headers). */\nexport function apiBase(): string {\n  return \"https://api.github.com\";\n}\n\n/** Join a `/repos/{owner}/{repo}` path with a suffix. */\nexport function repoPath(owner: string, repo: string, suffix = \"\"): string {\n  return `${apiBase()}/repos/${owner}/${repo}${suffix}`;\n}\n\n/** Headers for GitHub REST API requests. */\nexport function githubHeaders(token: string): Record<string, string> {\n  return {\n    accept: \"application/vnd.github+json\",\n    authorization: `Bearer ${token}`,\n    \"content-type\": \"application/json\",\n    \"x-github-api-version\": \"2022-11-28\",\n  };\n}\n"],"mappings":";;;;;AACA,SAAgB,UAAkB;CAChC,OAAO;AACT;;AAGA,SAAgB,SAAS,OAAe,MAAc,SAAS,IAAY;CACzE,OAAO,GAAG,QAAQ,EAAE,SAAS,MAAM,GAAG,OAAO;AAC/C;;AAGA,SAAgB,cAAc,OAAuC;CACnE,OAAO;EACL,QAAQ;EACR,eAAe,UAAU;EACzB,gBAAgB;EAChB,wBAAwB;CAC1B;AACF"}

package/dist/github-app.mjs

@@ -0,0 +1,67 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { apiBase, githubHeaders } from "./github-api.mjs";
+import { httpJson } from "@storyshelf/core/utils";
+import { createHash, createSign } from "node:crypto";
+//#region src/github-app.ts
+/**
+* GitHub App authentication without dependencies: an RS256 JWT signed with `node:crypto`, traded
+* for an installation token that is cached per channel until shortly before it expires.
+*/
+/** A cached installation token is replaced this long before GitHub expires it. */
+const TOKEN_REFRESH_MARGIN_MS = 3e5;
+const cache = /* @__PURE__ */ new Map();
+const inflight = /* @__PURE__ */ new Map();
+/** An installation token for the channel: cached, or exchanged with a fresh App JWT. */
+async function installationToken(creds) {
+	const key = cacheKey(creds);
+	const cached = cache.get(key);
+	if (cached && cached.expiresAt - 3e5 > Date.now()) return cached.token;
+	const pending = inflight.get(key) ?? exchange(creds, key);
+	inflight.set(key, pending);
+	try {
+		return await pending;
+	} finally {
+		inflight.delete(key);
+	}
+}
+async function exchange(creds, key) {
+	const jwt = signAppJwt(creds, Date.now());
+	const response = await httpJson(`${apiBase()}/app/installations/${encodeURIComponent(creds.installationId)}/access_tokens`, {
+		method: "POST",
+		headers: githubHeaders(jwt)
+	});
+	if (typeof response.token !== "string" || typeof response.expires_at !== "string") throw new TypeError("GitHub did not return an installation token");
+	cache.set(key, {
+		token: response.token,
+		expiresAt: Date.parse(response.expires_at)
+	});
+	return response.token;
+}
+/** The cache key never holds the private key itself, only its digest. */
+function cacheKey(creds) {
+	const digest = createHash("sha256").update(creds.privateKey).digest("hex").slice(0, 16);
+	return `${creds.appId}:${creds.installationId}:${digest}`;
+}
+/** An App JWT (RS256), valid for nine minutes; `now` is in milliseconds. */
+function signAppJwt(creds, now) {
+	const seconds = Math.floor(now / 1e3);
+	const header = base64url(JSON.stringify({
+		alg: "RS256",
+		typ: "JWT"
+	}));
+	const claims = base64url(JSON.stringify({
+		iat: seconds - 60,
+		exp: seconds + 540,
+		iss: creds.appId
+	}));
+	return `${header}.${claims}.${base64url(createSign("RSA-SHA256").update(`${header}.${claims}`).sign(creds.privateKey.replaceAll(String.raw`\n`, "\n")))}`;
+}
+function base64url(value) {
+	return Buffer.from(value).toString("base64url");
+}
+//#endregion
+export { TOKEN_REFRESH_MARGIN_MS, installationToken, signAppJwt };
+
+//# sourceMappingURL=github-app.mjs.map

package/dist/github-app.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-app.mjs","names":[],"sources":["../src/github-app.ts"],"sourcesContent":["import { httpJson } from \"@storyshelf/core/utils\";\n/**\n * GitHub App authentication without dependencies: an RS256 JWT signed with `node:crypto`, traded\n * for an installation token that is cached per channel until shortly before it expires.\n */\nimport { createHash, createSign } from \"node:crypto\";\nimport { apiBase, githubHeaders } from \"./github-api.ts\";\n\n/** The App credentials of one channel. */\nexport interface AppCredentials {\n  appId: string;\n  installationId: string;\n  /** The App's private key (PEM); a one-line key with literal `\\n` is accepted. */\n  privateKey: string;\n}\n\n/** A cached installation token is replaced this long before GitHub expires it. */\nexport const TOKEN_REFRESH_MARGIN_MS = 5 * 60 * 1000;\n\ninterface CachedToken {\n  token: string;\n  expiresAt: number;\n}\n\nconst cache = new Map<string, CachedToken>();\nconst inflight = new Map<string, Promise<string>>();\n\n/** An installation token for the channel: cached, or exchanged with a fresh App JWT. */\nexport async function installationToken(creds: AppCredentials): Promise<string> {\n  const key = cacheKey(creds);\n  const cached = cache.get(key);\n  if (cached && cached.expiresAt - TOKEN_REFRESH_MARGIN_MS > Date.now()) {\n    return cached.token;\n  }\n  const pending = inflight.get(key) ?? exchange(creds, key);\n  inflight.set(key, pending);\n  try {\n    return await pending;\n  } finally {\n    inflight.delete(key);\n  }\n}\n\n/** Forget every cached token (tests). */\nexport function clearInstallationTokens(): void {\n  cache.clear();\n  inflight.clear();\n}\n\nasync function exchange(creds: AppCredentials, key: string): Promise<string> {\n  const jwt = signAppJwt(creds, Date.now());\n  const response = await httpJson<{ token?: unknown; expires_at?: unknown }>(\n    `${apiBase()}/app/installations/${encodeURIComponent(creds.installationId)}/access_tokens`,\n    { method: \"POST\", headers: githubHeaders(jwt) },\n  );\n  if (typeof response.token !== \"string\" || typeof response.expires_at !== \"string\") {\n    throw new TypeError(\"GitHub did not return an installation token\");\n  }\n  cache.set(key, { token: response.token, expiresAt: Date.parse(response.expires_at) });\n  return response.token;\n}\n\n/** The cache key never holds the private key itself, only its digest. */\nfunction cacheKey(creds: AppCredentials): string {\n  const digest = createHash(\"sha256\").update(creds.privateKey).digest(\"hex\").slice(0, 16);\n  return `${creds.appId}:${creds.installationId}:${digest}`;\n}\n\n/** An App JWT (RS256), valid for nine minutes; `now` is in milliseconds. */\nexport function signAppJwt(creds: AppCredentials, now: number): string {\n  const seconds = Math.floor(now / 1000);\n  const header = base64url(JSON.stringify({ alg: \"RS256\", typ: \"JWT\" }));\n  // `iat` is backdated a minute to allow for clock drift, as GitHub recommends.\n  const claims = base64url(\n    JSON.stringify({ iat: seconds - 60, exp: seconds + 9 * 60, iss: creds.appId }),\n  );\n  const signature = createSign(\"RSA-SHA256\")\n    .update(`${header}.${claims}`)\n    .sign(creds.privateKey.replaceAll(String.raw`\\n`, \"\\n\"));\n  return `${header}.${claims}.${base64url(signature)}`;\n}\n\nfunction base64url(value: string | Buffer): string {\n  return Buffer.from(value).toString(\"base64url\");\n}\n"],"mappings":";;;;;;;;;;;;AAiBA,MAAa,0BAA0B;AAOvC,MAAM,wBAAQ,IAAI,IAAyB;AAC3C,MAAM,2BAAW,IAAI,IAA6B;;AAGlD,eAAsB,kBAAkB,OAAwC;CAC9E,MAAM,MAAM,SAAS,KAAK;CAC1B,MAAM,SAAS,MAAM,IAAI,GAAG;CAC5B,IAAI,UAAU,OAAO,YAAA,MAAsC,KAAK,IAAI,GAClE,OAAO,OAAO;CAEhB,MAAM,UAAU,SAAS,IAAI,GAAG,KAAK,SAAS,OAAO,GAAG;CACxD,SAAS,IAAI,KAAK,OAAO;CACzB,IAAI;EACF,OAAO,MAAM;CACf,UAAU;EACR,SAAS,OAAO,GAAG;CACrB;AACF;AAQA,eAAe,SAAS,OAAuB,KAA8B;CAC3E,MAAM,MAAM,WAAW,OAAO,KAAK,IAAI,CAAC;CACxC,MAAM,WAAW,MAAM,SACrB,GAAG,QAAQ,EAAE,qBAAqB,mBAAmB,MAAM,cAAc,EAAE,iBAC3E;EAAE,QAAQ;EAAQ,SAAS,cAAc,GAAG;CAAE,CAChD;CACA,IAAI,OAAO,SAAS,UAAU,YAAY,OAAO,SAAS,eAAe,UACvE,MAAM,IAAI,UAAU,6CAA6C;CAEnE,MAAM,IAAI,KAAK;EAAE,OAAO,SAAS;EAAO,WAAW,KAAK,MAAM,SAAS,UAAU;CAAE,CAAC;CACpF,OAAO,SAAS;AAClB;;AAGA,SAAS,SAAS,OAA+B;CAC/C,MAAM,SAAS,WAAW,QAAQ,CAAC,CAAC,OAAO,MAAM,UAAU,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,GAAG,EAAE;CACtF,OAAO,GAAG,MAAM,MAAM,GAAG,MAAM,eAAe,GAAG;AACnD;;AAGA,SAAgB,WAAW,OAAuB,KAAqB;CACrE,MAAM,UAAU,KAAK,MAAM,MAAM,GAAI;CACrC,MAAM,SAAS,UAAU,KAAK,UAAU;EAAE,KAAK;EAAS,KAAK;CAAM,CAAC,CAAC;CAErE,MAAM,SAAS,UACb,KAAK,UAAU;EAAE,KAAK,UAAU;EAAI,KAAK,UAAU;EAAQ,KAAK,MAAM;CAAM,CAAC,CAC/E;CAIA,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,UAHZ,WAAW,YAAY,CAAC,CACvC,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC,CAC7B,KAAK,MAAM,WAAW,WAAW,OAAO,GAAG,MAAM,IAAI,CACR,CAAC;AACnD;AAEA,SAAS,UAAU,OAAgC;CACjD,OAAO,OAAO,KAAK,KAAK,CAAC,CAAC,SAAS,WAAW;AAChD"}

package/dist/github-check-mapper.mjs

@@ -0,0 +1,69 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+/** The `external_id` that keys a check run: the same name always finds the same run. */
+function externalIdOf(context) {
+	return `storyshelf:${context}`;
+}
+/** `pending` is queued or in progress; a final state completes the run; a cancel is `cancelled`. */
+function phaseOf(input) {
+	switch (input.state) {
+		case "pending": return { status: input.progress === "queued" ? "queued" : "in_progress" };
+		case "success": return {
+			status: "completed",
+			conclusion: "success"
+		};
+		case "cancelled": return {
+			status: "completed",
+			conclusion: "cancelled"
+		};
+		default: return {
+			status: "completed",
+			conclusion: input.informational === true ? "neutral" : "failure"
+		};
+	}
+}
+/** The check run to show for a desired status. */
+function checkRunBody(input) {
+	return {
+		name: input.context,
+		external_id: externalIdOf(input.context),
+		...phaseOf(input),
+		...input.url === void 0 ? {} : { details_url: input.url },
+		output: {
+			title: input.description,
+			summary: summaryOf(input)
+		}
+	};
+}
+/** The summary: the description, then the link to the build, then what the annotations leave out. */
+function summaryOf(input) {
+	const lines = [input.description];
+	const omitted = input.omitted ?? 0;
+	if (omitted > 0 && input.url !== void 0) lines.push(`and ${String(omitted)} more changed snapshots: [open the build](${input.url})`);
+	else if (omitted > 0) lines.push(`and ${String(omitted)} more changed snapshots`);
+	else if (input.url !== void 0) lines.push(`[Open the build](${input.url})`);
+	return lines.join("\n\n");
+}
+/** Annotations as batches of at most {@link ANNOTATIONS_PER_REQUEST}, after the `skip` already on the run. */
+function annotationBatches(annotations, skip = 0) {
+	const pending = annotations.slice(skip).map((annotation) => annotationOf(annotation));
+	const batches = [];
+	for (let at = 0; at < pending.length; at += 50) batches.push(pending.slice(at, at + 50));
+	return batches;
+}
+function annotationOf(annotation) {
+	return {
+		path: annotation.path,
+		start_line: 1,
+		end_line: 1,
+		annotation_level: annotation.level,
+		title: annotation.title.slice(0, 255),
+		message: annotation.message,
+		raw_details: annotation.url
+	};
+}
+//#endregion
+export { annotationBatches, checkRunBody, externalIdOf, phaseOf, summaryOf };
+
+//# sourceMappingURL=github-check-mapper.mjs.map

package/dist/github-check-mapper.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-check-mapper.mjs","names":[],"sources":["../src/github-check-mapper.ts"],"sourcesContent":["/** Pure mapping from a desired status to GitHub check-run payloads (never posts anything). */\nimport type { NotifierState, StateAnnotation } from \"@storyshelf/core/adapter/notifier\";\n\n/** GitHub accepts at most this many annotations per request. */\nexport const ANNOTATIONS_PER_REQUEST = 50;\n\n/** What one check run shows. */\nexport interface CheckRunInput {\n  /** Full status name: the check run's name, so a required check keeps its `<prefix>/testing` name. */\n  context: string;\n  state: NotifierState;\n  description: string;\n  /** Absolute link to the build page. */\n  url?: string | undefined;\n  progress?: \"queued\" | \"running\" | undefined;\n  informational?: boolean | undefined;\n  annotations?: readonly StateAnnotation[] | undefined;\n  omitted?: number | undefined;\n}\n\n/** The lifecycle fields of a check run. */\nexport interface CheckRunPhase {\n  status: \"queued\" | \"in_progress\" | \"completed\";\n  conclusion?: \"success\" | \"failure\" | \"cancelled\" | \"neutral\";\n}\n\n/** One annotation as the Checks API takes it. */\nexport interface CheckAnnotation {\n  path: string;\n  start_line: number;\n  end_line: number;\n  annotation_level: \"notice\" | \"warning\" | \"failure\";\n  title: string;\n  message: string;\n  raw_details: string;\n}\n\n/** The body of a create or update of a check run, without the annotations. */\nexport interface CheckRunBody extends CheckRunPhase {\n  name: string;\n  external_id: string;\n  details_url?: string;\n  output: { title: string; summary: string };\n}\n\n/** The `external_id` that keys a check run: the same name always finds the same run. */\nexport function externalIdOf(context: string): string {\n  return `storyshelf:${context}`;\n}\n\n/** `pending` is queued or in progress; a final state completes the run; a cancel is `cancelled`. */\nexport function phaseOf(\n  input: Pick<CheckRunInput, \"state\" | \"progress\" | \"informational\">,\n): CheckRunPhase {\n  switch (input.state) {\n    case \"pending\": {\n      return { status: input.progress === \"queued\" ? \"queued\" : \"in_progress\" };\n    }\n    case \"success\": {\n      return { status: \"completed\", conclusion: \"success\" };\n    }\n    case \"cancelled\": {\n      return { status: \"completed\", conclusion: \"cancelled\" };\n    }\n    default: {\n      return {\n        status: \"completed\",\n        conclusion: input.informational === true ? \"neutral\" : \"failure\",\n      };\n    }\n  }\n}\n\n/** The check run to show for a desired status. */\nexport function checkRunBody(input: CheckRunInput): CheckRunBody {\n  return {\n    name: input.context,\n    external_id: externalIdOf(input.context),\n    ...phaseOf(input),\n    ...(input.url === undefined ? {} : { details_url: input.url }),\n    output: { title: input.description, summary: summaryOf(input) },\n  };\n}\n\n/** The summary: the description, then the link to the build, then what the annotations leave out. */\nexport function summaryOf(input: CheckRunInput): string {\n  const lines = [input.description];\n  const omitted = input.omitted ?? 0;\n  if (omitted > 0 && input.url !== undefined) {\n    lines.push(`and ${String(omitted)} more changed snapshots: [open the build](${input.url})`);\n  } else if (omitted > 0) {\n    lines.push(`and ${String(omitted)} more changed snapshots`);\n  } else if (input.url !== undefined) {\n    lines.push(`[Open the build](${input.url})`);\n  }\n  return lines.join(\"\\n\\n\");\n}\n\n/** Annotations as batches of at most {@link ANNOTATIONS_PER_REQUEST}, after the `skip` already on the run. */\nexport function annotationBatches(\n  annotations: readonly StateAnnotation[],\n  skip = 0,\n): CheckAnnotation[][] {\n  const pending = annotations.slice(skip).map((annotation) => annotationOf(annotation));\n  const batches: CheckAnnotation[][] = [];\n  for (let at = 0; at < pending.length; at += ANNOTATIONS_PER_REQUEST) {\n    batches.push(pending.slice(at, at + ANNOTATIONS_PER_REQUEST));\n  }\n  return batches;\n}\n\nfunction annotationOf(annotation: StateAnnotation): CheckAnnotation {\n  return {\n    path: annotation.path,\n    start_line: 1,\n    end_line: 1,\n    annotation_level: annotation.level,\n    title: annotation.title.slice(0, 255),\n    message: annotation.message,\n    raw_details: annotation.url,\n  };\n}\n"],"mappings":";;;;AA8CA,SAAgB,aAAa,SAAyB;CACpD,OAAO,cAAc;AACvB;;AAGA,SAAgB,QACd,OACe;CACf,QAAQ,MAAM,OAAd;EACE,KAAK,WACH,OAAO,EAAE,QAAQ,MAAM,aAAa,WAAW,WAAW,cAAc;EAE1E,KAAK,WACH,OAAO;GAAE,QAAQ;GAAa,YAAY;EAAU;EAEtD,KAAK,aACH,OAAO;GAAE,QAAQ;GAAa,YAAY;EAAY;EAExD,SACE,OAAO;GACL,QAAQ;GACR,YAAY,MAAM,kBAAkB,OAAO,YAAY;EACzD;CAEJ;AACF;;AAGA,SAAgB,aAAa,OAAoC;CAC/D,OAAO;EACL,MAAM,MAAM;EACZ,aAAa,aAAa,MAAM,OAAO;EACvC,GAAG,QAAQ,KAAK;EAChB,GAAI,MAAM,QAAQ,KAAA,IAAY,CAAC,IAAI,EAAE,aAAa,MAAM,IAAI;EAC5D,QAAQ;GAAE,OAAO,MAAM;GAAa,SAAS,UAAU,KAAK;EAAE;CAChE;AACF;;AAGA,SAAgB,UAAU,OAA8B;CACtD,MAAM,QAAQ,CAAC,MAAM,WAAW;CAChC,MAAM,UAAU,MAAM,WAAW;CACjC,IAAI,UAAU,KAAK,MAAM,QAAQ,KAAA,GAC/B,MAAM,KAAK,OAAO,OAAO,OAAO,EAAE,4CAA4C,MAAM,IAAI,EAAE;MACrF,IAAI,UAAU,GACnB,MAAM,KAAK,OAAO,OAAO,OAAO,EAAE,wBAAwB;MACrD,IAAI,MAAM,QAAQ,KAAA,GACvB,MAAM,KAAK,oBAAoB,MAAM,IAAI,EAAE;CAE7C,OAAO,MAAM,KAAK,MAAM;AAC1B;;AAGA,SAAgB,kBACd,aACA,OAAO,GACc;CACrB,MAAM,UAAU,YAAY,MAAM,IAAI,CAAC,CAAC,KAAK,eAAe,aAAa,UAAU,CAAC;CACpF,MAAM,UAA+B,CAAC;CACtC,KAAK,IAAI,KAAK,GAAG,KAAK,QAAQ,QAAQ,MAAA,IACpC,QAAQ,KAAK,QAAQ,MAAM,IAAI,KAAA,EAA4B,CAAC;CAE9D,OAAO;AACT;AAEA,SAAS,aAAa,YAA8C;CAClE,OAAO;EACL,MAAM,WAAW;EACjB,YAAY;EACZ,UAAU;EACV,kBAAkB,WAAW;EAC7B,OAAO,WAAW,MAAM,MAAM,GAAG,GAAG;EACpC,SAAS,WAAW;EACpB,aAAa,WAAW;CAC1B;AACF"}

package/dist/github-check.mjs

@@ -0,0 +1,86 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { githubHeaders, repoPath } from "./github-api.mjs";
+import { annotationBatches, checkRunBody, externalIdOf } from "./github-check-mapper.mjs";
+import { httpJson } from "@storyshelf/core/utils";
+//#region src/github-check.ts
+/**
+* Show a status as a check run of the commit `sha`: update the run that carries the status's
+* `external_id`, or create it, so a build has one run per name and its lifecycle (queued,
+* in progress, completed) moves that run. The annotations follow in batches of 50; the ones
+* already on the run are skipped, so posting the same state again adds nothing.
+*/
+async function postCheckRun(repo, input) {
+	const body = checkRunBody(input);
+	const existing = await findRun(repo, input);
+	const batches = annotationBatches(input.annotations ?? [], existing?.output?.annotations_count ?? 0);
+	repo.logger?.debug({
+		context: input.context,
+		sha: input.sha,
+		status: body.status
+	}, "posting check run");
+	try {
+		await appendBatches(repo, (existing ? await update(repo, existing.id, withBatch(body, batches[0])) : await create(repo, {
+			...withBatch(body, batches[0]),
+			head_sha: input.sha
+		})).id, {
+			output: body.output,
+			batches: batches.slice(1)
+		});
+	} catch (error) {
+		repo.logger?.error({
+			err: error,
+			context: input.context,
+			sha: input.sha
+		}, "failed to post check run");
+		throw error;
+	}
+}
+function withBatch(body, batch) {
+	return batch === void 0 ? body : {
+		...body,
+		output: {
+			...body.output,
+			annotations: batch
+		}
+	};
+}
+/** The run of this commit that carries the status's `external_id`, if there is one. */
+async function findRun(repo, input) {
+	const url = repoPath(repo.owner, repo.repo, `/commits/${encodeURIComponent(input.sha)}/check-runs?filter=latest&per_page=100&check_name=${encodeURIComponent(input.context)}`);
+	return (await httpJson(url, { headers: githubHeaders(repo.token) })).check_runs?.find((run) => run.external_id === externalIdOf(input.context));
+}
+async function create(repo, body) {
+	return await httpJson(repoPath(repo.owner, repo.repo, "/check-runs"), {
+		method: "POST",
+		headers: githubHeaders(repo.token),
+		json: body,
+		logger: repo.logger
+	});
+}
+async function update(repo, id, body) {
+	return await httpJson(repoPath(repo.owner, repo.repo, `/check-runs/${String(id)}`), {
+		method: "PATCH",
+		headers: githubHeaders(repo.token),
+		json: body,
+		logger: repo.logger
+	});
+}
+/** Append the remaining annotation batches to the run, one request after the other (in order). */
+async function appendBatches(repo, id, rest) {
+	const [next, ...later] = rest.batches;
+	if (next === void 0) return;
+	await update(repo, id, { output: {
+		...rest.output,
+		annotations: next
+	} });
+	await appendBatches(repo, id, {
+		output: rest.output,
+		batches: later
+	});
+}
+//#endregion
+export { postCheckRun };
+
+//# sourceMappingURL=github-check.mjs.map

package/dist/github-check.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-check.mjs","names":[],"sources":["../src/github-check.ts"],"sourcesContent":["import type { Logger } from \"@storyshelf/core/logger\";\nimport { httpJson } from \"@storyshelf/core/utils\";\nimport { githubHeaders, repoPath } from \"./github-api.ts\";\nimport {\n  annotationBatches,\n  checkRunBody,\n  externalIdOf,\n  type CheckAnnotation,\n  type CheckRunBody,\n  type CheckRunInput,\n} from \"./github-check-mapper.ts\";\n\n/** Coordinates and installation token of one repository. */\nexport interface CheckRepo {\n  token: string;\n  owner: string;\n  repo: string;\n  logger?: Logger | undefined;\n}\n\ninterface ExistingRun {\n  id: number;\n  external_id?: string | null;\n  output?: { annotations_count?: number | null } | null;\n}\n\n/**\n * Show a status as a check run of the commit `sha`: update the run that carries the status's\n * `external_id`, or create it, so a build has one run per name and its lifecycle (queued,\n * in progress, completed) moves that run. The annotations follow in batches of 50; the ones\n * already on the run are skipped, so posting the same state again adds nothing.\n */\nexport async function postCheckRun(\n  repo: CheckRepo,\n  input: CheckRunInput & { sha: string },\n): Promise<void> {\n  const body = checkRunBody(input);\n  const existing = await findRun(repo, input);\n  const batches = annotationBatches(\n    input.annotations ?? [],\n    existing?.output?.annotations_count ?? 0,\n  );\n  repo.logger?.debug(\n    { context: input.context, sha: input.sha, status: body.status },\n    \"posting check run\",\n  );\n  try {\n    const run = existing\n      ? await update(repo, existing.id, withBatch(body, batches[0]))\n      : await create(repo, { ...withBatch(body, batches[0]), head_sha: input.sha });\n    await appendBatches(repo, run.id, { output: body.output, batches: batches.slice(1) });\n  } catch (error) {\n    repo.logger?.error(\n      { err: error, context: input.context, sha: input.sha },\n      \"failed to post check run\",\n    );\n    throw error;\n  }\n}\n\ntype WithAnnotations = Omit<CheckRunBody, \"output\"> & {\n  output: CheckRunBody[\"output\"] & { annotations?: CheckAnnotation[] };\n};\n\nfunction withBatch(body: CheckRunBody, batch: CheckAnnotation[] | undefined): WithAnnotations {\n  return batch === undefined ? body : { ...body, output: { ...body.output, annotations: batch } };\n}\n\n/** The run of this commit that carries the status's `external_id`, if there is one. */\nasync function findRun(\n  repo: CheckRepo,\n  input: { sha: string; context: string },\n): Promise<ExistingRun | undefined> {\n  const url = repoPath(\n    repo.owner,\n    repo.repo,\n    `/commits/${encodeURIComponent(input.sha)}/check-runs?filter=latest&per_page=100&check_name=${encodeURIComponent(input.context)}`,\n  );\n  const listed = await httpJson<{ check_runs?: ExistingRun[] }>(url, {\n    headers: githubHeaders(repo.token),\n  });\n  return listed.check_runs?.find((run) => run.external_id === externalIdOf(input.context));\n}\n\nasync function create(repo: CheckRepo, body: unknown): Promise<{ id: number }> {\n  return await httpJson<{ id: number }>(repoPath(repo.owner, repo.repo, \"/check-runs\"), {\n    method: \"POST\",\n    headers: githubHeaders(repo.token),\n    json: body,\n    logger: repo.logger,\n  });\n}\n\nasync function update(repo: CheckRepo, id: number, body: unknown): Promise<{ id: number }> {\n  return await httpJson<{ id: number }>(\n    repoPath(repo.owner, repo.repo, `/check-runs/${String(id)}`),\n    {\n      method: \"PATCH\",\n      headers: githubHeaders(repo.token),\n      json: body,\n      logger: repo.logger,\n    },\n  );\n}\n\n/** Append the remaining annotation batches to the run, one request after the other (in order). */\nasync function appendBatches(\n  repo: CheckRepo,\n  id: number,\n  rest: { output: CheckRunBody[\"output\"]; batches: CheckAnnotation[][] },\n): Promise<void> {\n  const [next, ...later] = rest.batches;\n  if (next === undefined) {\n    return;\n  }\n  await update(repo, id, { output: { ...rest.output, annotations: next } });\n  await appendBatches(repo, id, { output: rest.output, batches: later });\n}\n"],"mappings":";;;;;;;;;;;;;AAgCA,eAAsB,aACpB,MACA,OACe;CACf,MAAM,OAAO,aAAa,KAAK;CAC/B,MAAM,WAAW,MAAM,QAAQ,MAAM,KAAK;CAC1C,MAAM,UAAU,kBACd,MAAM,eAAe,CAAC,GACtB,UAAU,QAAQ,qBAAqB,CACzC;CACA,KAAK,QAAQ,MACX;EAAE,SAAS,MAAM;EAAS,KAAK,MAAM;EAAK,QAAQ,KAAK;CAAO,GAC9D,mBACF;CACA,IAAI;EAIF,MAAM,cAAc,OAHR,WACR,MAAM,OAAO,MAAM,SAAS,IAAI,UAAU,MAAM,QAAQ,EAAE,CAAC,IAC3D,MAAM,OAAO,MAAM;GAAE,GAAG,UAAU,MAAM,QAAQ,EAAE;GAAG,UAAU,MAAM;EAAI,CAAC,EAAA,CAChD,IAAI;GAAE,QAAQ,KAAK;GAAQ,SAAS,QAAQ,MAAM,CAAC;EAAE,CAAC;CACtF,SAAS,OAAO;EACd,KAAK,QAAQ,MACX;GAAE,KAAK;GAAO,SAAS,MAAM;GAAS,KAAK,MAAM;EAAI,GACrD,0BACF;EACA,MAAM;CACR;AACF;AAMA,SAAS,UAAU,MAAoB,OAAuD;CAC5F,OAAO,UAAU,KAAA,IAAY,OAAO;EAAE,GAAG;EAAM,QAAQ;GAAE,GAAG,KAAK;GAAQ,aAAa;EAAM;CAAE;AAChG;;AAGA,eAAe,QACb,MACA,OACkC;CAClC,MAAM,MAAM,SACV,KAAK,OACL,KAAK,MACL,YAAY,mBAAmB,MAAM,GAAG,EAAE,oDAAoD,mBAAmB,MAAM,OAAO,GAChI;CAIA,QAAO,MAHc,SAAyC,KAAK,EACjE,SAAS,cAAc,KAAK,KAAK,EACnC,CAAC,EAAA,CACa,YAAY,MAAM,QAAQ,IAAI,gBAAgB,aAAa,MAAM,OAAO,CAAC;AACzF;AAEA,eAAe,OAAO,MAAiB,MAAwC;CAC7E,OAAO,MAAM,SAAyB,SAAS,KAAK,OAAO,KAAK,MAAM,aAAa,GAAG;EACpF,QAAQ;EACR,SAAS,cAAc,KAAK,KAAK;EACjC,MAAM;EACN,QAAQ,KAAK;CACf,CAAC;AACH;AAEA,eAAe,OAAO,MAAiB,IAAY,MAAwC;CACzF,OAAO,MAAM,SACX,SAAS,KAAK,OAAO,KAAK,MAAM,eAAe,OAAO,EAAE,GAAG,GAC3D;EACE,QAAQ;EACR,SAAS,cAAc,KAAK,KAAK;EACjC,MAAM;EACN,QAAQ,KAAK;CACf,CACF;AACF;;AAGA,eAAe,cACb,MACA,IACA,MACe;CACf,MAAM,CAAC,MAAM,GAAG,SAAS,KAAK;CAC9B,IAAI,SAAS,KAAA,GACX;CAEF,MAAM,OAAO,MAAM,IAAI,EAAE,QAAQ;EAAE,GAAG,KAAK;EAAQ,aAAa;CAAK,EAAE,CAAC;CACxE,MAAM,cAAc,MAAM,IAAI;EAAE,QAAQ,KAAK;EAAQ,SAAS;CAAM,CAAC;AACvE"}

package/dist/github-comment.mjs

@@ -0,0 +1,58 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { githubHeaders, repoPath } from "./github-api.mjs";
+import { findPrNumber } from "./github-pr.mjs";
+import { upsertReviewComment } from "./review-comment.mjs";
+import { httpJson } from "@storyshelf/core/utils";
+//#region src/github-comment.ts
+/** Fetch-backed review thread (comments) for a pull request. */
+function createThread(repo, prNumber) {
+	const threadUrl = repoPath(repo.owner, repo.repo, `/issues/${prNumber}/comments`);
+	const headers = githubHeaders(repo.token);
+	return {
+		list: async () => {
+			return (await httpJson(`${threadUrl}?per_page=100`, { headers })).map((comment) => ({
+				id: comment.id,
+				body: comment.body ?? ""
+			}));
+		},
+		update: async (id, body) => {
+			const updated = await httpJson(repoPath(repo.owner, repo.repo, `/issues/comments/${String(id)}`), {
+				method: "PATCH",
+				headers,
+				json: { body }
+			});
+			return String(updated.id);
+		},
+		create: async (body) => {
+			const created = await httpJson(threadUrl, {
+				method: "POST",
+				headers,
+				json: { body }
+			});
+			return String(created.id);
+		}
+	};
+}
+/** Create or update the StoryShelf review comment on the pull request of a commit. */
+async function upsertPrComment(repo, input) {
+	const { token, owner } = repo;
+	return await upsertReviewComment({
+		url: input.url,
+		markdown: input.markdown,
+		sha: input.sha,
+		logger: input.logger,
+		resolveNumber: async () => await findPrNumber({
+			token,
+			owner,
+			repo: repo.repo,
+			sha: input.sha
+		}),
+		thread: (prNumber) => createThread(repo, prNumber)
+	});
+}
+//#endregion
+export { upsertPrComment };
+
+//# sourceMappingURL=github-comment.mjs.map

package/dist/github-comment.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-comment.mjs","names":[],"sources":["../src/github-comment.ts"],"sourcesContent":["import type { Logger } from \"@storyshelf/core/logger\";\nimport { httpJson } from \"@storyshelf/core/utils\";\nimport { githubHeaders, repoPath } from \"./github-api.ts\";\nimport { findPrNumber } from \"./github-pr.ts\";\nimport type { GitHubRepo } from \"./github-status.ts\";\nimport { upsertReviewComment, type ReviewThread } from \"./review-comment.ts\";\n\ninterface IssueComment {\n  id: number;\n  body?: string | null;\n}\n\n/** Fetch-backed review thread (comments) for a pull request. */\nfunction createThread(repo: GitHubRepo, prNumber: number): ReviewThread {\n  const threadUrl = repoPath(repo.owner, repo.repo, `/issues/${prNumber}/comments`);\n  const headers = githubHeaders(repo.token);\n  return {\n    list: async () => {\n      const comments = await httpJson<IssueComment[]>(`${threadUrl}?per_page=100`, { headers });\n      return comments.map((comment) => ({ id: comment.id, body: comment.body ?? \"\" }));\n    },\n    update: async (id, body) => {\n      const updated = await httpJson<IssueComment>(\n        repoPath(repo.owner, repo.repo, `/issues/comments/${String(id)}`),\n        { method: \"PATCH\", headers, json: { body } },\n      );\n      return String(updated.id);\n    },\n    create: async (body) => {\n      const created = await httpJson<IssueComment>(threadUrl, {\n        method: \"POST\",\n        headers,\n        json: { body },\n      });\n      return String(created.id);\n    },\n  };\n}\n\n/** Create or update the StoryShelf review comment on the pull request of a commit. */\nexport async function upsertPrComment(\n  repo: GitHubRepo,\n  input: { sha: string; url: string; markdown: string; logger?: Logger },\n): Promise<string> {\n  const { token, owner } = repo;\n  return await upsertReviewComment({\n    url: input.url,\n    markdown: input.markdown,\n    sha: input.sha,\n    logger: input.logger,\n    resolveNumber: async () =>\n      await findPrNumber({ token, owner, repo: repo.repo, sha: input.sha }),\n    thread: (prNumber) => createThread(repo, prNumber),\n  });\n}\n"],"mappings":";;;;;;;;;AAaA,SAAS,aAAa,MAAkB,UAAgC;CACtE,MAAM,YAAY,SAAS,KAAK,OAAO,KAAK,MAAM,WAAW,SAAS,UAAU;CAChF,MAAM,UAAU,cAAc,KAAK,KAAK;CACxC,OAAO;EACL,MAAM,YAAY;GAEhB,QAAO,MADgB,SAAyB,GAAG,UAAU,gBAAgB,EAAE,QAAQ,CAAC,EAAA,CACxE,KAAK,aAAa;IAAE,IAAI,QAAQ;IAAI,MAAM,QAAQ,QAAQ;GAAG,EAAE;EACjF;EACA,QAAQ,OAAO,IAAI,SAAS;GAC1B,MAAM,UAAU,MAAM,SACpB,SAAS,KAAK,OAAO,KAAK,MAAM,oBAAoB,OAAO,EAAE,GAAG,GAChE;IAAE,QAAQ;IAAS;IAAS,MAAM,EAAE,KAAK;GAAE,CAC7C;GACA,OAAO,OAAO,QAAQ,EAAE;EAC1B;EACA,QAAQ,OAAO,SAAS;GACtB,MAAM,UAAU,MAAM,SAAuB,WAAW;IACtD,QAAQ;IACR;IACA,MAAM,EAAE,KAAK;GACf,CAAC;GACD,OAAO,OAAO,QAAQ,EAAE;EAC1B;CACF;AACF;;AAGA,eAAsB,gBACpB,MACA,OACiB;CACjB,MAAM,EAAE,OAAO,UAAU;CACzB,OAAO,MAAM,oBAAoB;EAC/B,KAAK,MAAM;EACX,UAAU,MAAM;EAChB,KAAK,MAAM;EACX,QAAQ,MAAM;EACd,eAAe,YACb,MAAM,aAAa;GAAE;GAAO;GAAO,MAAM,KAAK;GAAM,KAAK,MAAM;EAAI,CAAC;EACtE,SAAS,aAAa,aAAa,MAAM,QAAQ;CACnD,CAAC;AACH"}

package/dist/github-config.d.mts

@@ -0,0 +1,24 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { z } from "zod";
+//#region src/github-config.d.ts
+/**
+ * Validation schema for a GitHub channel config: `owner` + `repo`, an optional status `prefix` and
+ * how the build is shown. `statuses` (default) posts commit statuses with a token; `checks` posts
+ * check runs as a GitHub App and needs `appId` and `installationId` (the private key is the
+ * channel's secret).
+ */
+declare const githubConfigSchema: z.ZodObject<{
+  owner: z.ZodString;
+  repo: z.ZodString;
+  prefix: z.ZodOptional<z.ZodString>;
+  mode: z.ZodOptional<z.ZodEnum<{
+    checks: "checks";
+    statuses: "statuses";
+  }>>;
+  appId: z.ZodOptional<z.ZodString>;
+  installationId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+//#endregion
+export { githubConfigSchema };
+//# sourceMappingURL=github-config.d.mts.map

package/dist/github-config.mjs

@@ -0,0 +1,31 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { statusPrefixSchema } from "./prefix.mjs";
+import { z } from "zod";
+//#region src/github-config.ts
+/**
+* Validation schema for a GitHub channel config: `owner` + `repo`, an optional status `prefix` and
+* how the build is shown. `statuses` (default) posts commit statuses with a token; `checks` posts
+* check runs as a GitHub App and needs `appId` and `installationId` (the private key is the
+* channel's secret).
+*/
+const githubConfigSchema = z.object({
+	owner: z.string().min(1),
+	repo: z.string().min(1),
+	prefix: statusPrefixSchema.optional(),
+	mode: z.enum(["statuses", "checks"]).optional(),
+	appId: z.string().regex(/^\d+$/u, "Use the numeric App ID").optional(),
+	installationId: z.string().regex(/^\d+$/u, "Use the numeric installation ID").optional()
+}).superRefine((cfg, ctx) => {
+	if (cfg.mode !== "checks") return;
+	for (const field of ["appId", "installationId"]) if (cfg[field] === void 0) ctx.addIssue({
+		code: "custom",
+		path: [field],
+		message: `Checks mode needs ${field}`
+	});
+});
+//#endregion
+export { githubConfigSchema };
+
+//# sourceMappingURL=github-config.mjs.map

package/dist/github-config.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-config.mjs","names":[],"sources":["../src/github-config.ts"],"sourcesContent":["import { z } from \"zod\";\nimport { statusPrefixSchema } from \"./prefix.ts\";\n\n/**\n * Validation schema for a GitHub channel config: `owner` + `repo`, an optional status `prefix` and\n * how the build is shown. `statuses` (default) posts commit statuses with a token; `checks` posts\n * check runs as a GitHub App and needs `appId` and `installationId` (the private key is the\n * channel's secret).\n */\nexport const githubConfigSchema = z\n  .object({\n    owner: z.string().min(1),\n    repo: z.string().min(1),\n    prefix: statusPrefixSchema.optional(),\n    mode: z.enum([\"statuses\", \"checks\"]).optional(),\n    appId: z.string().regex(/^\\d+$/u, \"Use the numeric App ID\").optional(),\n    installationId: z.string().regex(/^\\d+$/u, \"Use the numeric installation ID\").optional(),\n  })\n  .superRefine((cfg, ctx) => {\n    if (cfg.mode !== \"checks\") {\n      return;\n    }\n    for (const field of [\"appId\", \"installationId\"] as const) {\n      if (cfg[field] === undefined) {\n        ctx.addIssue({ code: \"custom\", path: [field], message: `Checks mode needs ${field}` });\n      }\n    }\n  });\n\n/** The parsed config of a GitHub channel. */\nexport type GitHubConfig = z.infer<typeof githubConfigSchema>;\n"],"mappings":";;;;;;;;;;;;AASA,MAAa,qBAAqB,EAC/B,OAAO;CACN,OAAO,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC;CACvB,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC;CACtB,QAAQ,mBAAmB,SAAS;CACpC,MAAM,EAAE,KAAK,CAAC,YAAY,QAAQ,CAAC,CAAC,CAAC,SAAS;CAC9C,OAAO,EAAE,OAAO,CAAC,CAAC,MAAM,UAAU,wBAAwB,CAAC,CAAC,SAAS;CACrE,gBAAgB,EAAE,OAAO,CAAC,CAAC,MAAM,UAAU,iCAAiC,CAAC,CAAC,SAAS;AACzF,CAAC,CAAC,CACD,aAAa,KAAK,QAAQ;CACzB,IAAI,IAAI,SAAS,UACf;CAEF,KAAK,MAAM,SAAS,CAAC,SAAS,gBAAgB,GAC5C,IAAI,IAAI,WAAW,KAAA,GACjB,IAAI,SAAS;EAAE,MAAM;EAAU,MAAM,CAAC,KAAK;EAAG,SAAS,qBAAqB;CAAQ,CAAC;AAG3F,CAAC"}

package/dist/github-mapper.mjs

@@ -0,0 +1,22 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/github-mapper.ts
+/**
+* GitHub's commit states. It has no cancelled state, so a cancelled build shows `error`, its
+* "did not complete" state.
+*/
+const STATES = {
+	pending: "pending",
+	success: "success",
+	failure: "failure",
+	cancelled: "error"
+};
+/** Map a StoryShelf build state to a GitHub commit state; an unknown state is `error`. */
+function mapState(state) {
+	return STATES[state] ?? "error";
+}
+//#endregion
+export { mapState };
+
+//# sourceMappingURL=github-mapper.mjs.map

package/dist/github-mapper.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-mapper.mjs","names":[],"sources":["../src/github-mapper.ts"],"sourcesContent":["import type { NotifierState } from \"@storyshelf/core/adapter/notifier\";\n\n/**\n * GitHub's commit states. It has no cancelled state, so a cancelled build shows `error`, its\n * \"did not complete\" state.\n */\nconst STATES: Record<NotifierState, \"pending\" | \"success\" | \"failure\" | \"error\"> = {\n  pending: \"pending\",\n  success: \"success\",\n  failure: \"failure\",\n  cancelled: \"error\",\n};\n\n/** Map a StoryShelf build state to a GitHub commit state; an unknown state is `error`. */\nexport function mapState(state: NotifierState): \"pending\" | \"success\" | \"failure\" | \"error\" {\n  return STATES[state] ?? \"error\";\n}\n"],"mappings":";;;;;;;;AAMA,MAAM,SAA6E;CACjF,SAAS;CACT,SAAS;CACT,SAAS;CACT,WAAW;AACb;;AAGA,SAAgB,SAAS,OAAmE;CAC1F,OAAO,OAAO,UAAU;AAC1B"}

package/dist/github-pr.mjs

@@ -0,0 +1,20 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { githubHeaders, repoPath } from "./github-api.mjs";
+import { httpJson } from "@storyshelf/core/utils";
+//#region src/github-pr.ts
+/** Find the pull request number associated with a commit SHA, if any. */
+async function findPrNumber(opts) {
+	try {
+		const [pr] = await httpJson(repoPath(opts.owner, opts.repo, `/commits/${encodeURIComponent(opts.sha)}/pulls`), { headers: githubHeaders(opts.token) });
+		if (pr && typeof pr.number === "number") return pr.number;
+		return;
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { findPrNumber };
+
+//# sourceMappingURL=github-pr.mjs.map

package/dist/github-pr.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-pr.mjs","names":[],"sources":["../src/github-pr.ts"],"sourcesContent":["import { httpJson } from \"@storyshelf/core/utils\";\nimport { githubHeaders, repoPath } from \"./github-api.ts\";\n\ninterface AssociatedPull {\n  number?: unknown;\n}\n\n/** Find the pull request number associated with a commit SHA, if any. */\nexport async function findPrNumber(opts: {\n  token: string;\n  owner: string;\n  repo: string;\n  sha: string;\n}): Promise<number | undefined> {\n  try {\n    const pulls = await httpJson<AssociatedPull[]>(\n      repoPath(opts.owner, opts.repo, `/commits/${encodeURIComponent(opts.sha)}/pulls`),\n      { headers: githubHeaders(opts.token) },\n    );\n    const [pr] = pulls;\n    if (pr && typeof pr.number === \"number\") {\n      return pr.number;\n    }\n    return undefined;\n  } catch {\n    return undefined;\n  }\n}\n"],"mappings":";;;;;;;AAQA,eAAsB,aAAa,MAKH;CAC9B,IAAI;EAKF,MAAM,CAAC,MAAM,MAJO,SAClB,SAAS,KAAK,OAAO,KAAK,MAAM,YAAY,mBAAmB,KAAK,GAAG,EAAE,OAAO,GAChF,EAAE,SAAS,cAAc,KAAK,KAAK,EAAE,CACvC;EAEA,IAAI,MAAM,OAAO,GAAG,WAAW,UAC7B,OAAO,GAAG;EAEZ;CACF,QAAQ;EACN;CACF;AACF"}