@glw907/cairn-cms 0.4.0 → 0.5.0

package/src/lib/components/LoginPage.svelte

@@ -1,13 +1,13 @@
 <script lang="ts">
   // The magic-link sign-in page. Requests a link via the better-auth client (client-side, same
-  // origin). To avoid enumeration the UI shows the SAME neutral copy whether or not the email is
-  // on the allowlist — the server only emails actual editors (see auth/config.ts send gate).
+  // origin). To avoid enumeration the UI shows the same neutral copy whether or not the email is
+  // on the allowlist. The server only emails actual editors (see auth/config.ts send gate).
   import { createAuthClient } from 'better-auth/svelte';
   import { magicLinkClient } from 'better-auth/client/plugins';
 
   // The browser client lives in the one component that needs it (requesting a link). Sign-out
-  // and editor management go through server endpoints, so no shared client module is needed —
-  // and a component-local const keeps better-auth's deep client types out of the packaged .d.ts.
+  // and editor management go through server endpoints, so no shared client module is needed.
+  // A component-local const keeps better-auth's deep client types out of the packaged .d.ts.
   const authClient = createAuthClient({ plugins: [magicLinkClient()] });
 
   interface Props {
@@ -23,7 +23,7 @@
     event.preventDefault();
     busy = true;
     // The magic-link email points at our /admin/auth/confirm page (built in config.ts), not a
-    // GET-verify URL — so the result is the same regardless of allowlist membership.
+    // GET-verify URL, so the result is the same regardless of allowlist membership.
     await authClient.signIn.magicLink({ email });
     busy = false;
     requested = true;

package/src/lib/email.ts

@@ -1,9 +1,9 @@
 // cairn-core: pluggable magic-link email sender.
 //
-// Default adapter is Cloudflare Email Service → Email Sending (transactional, arbitrary
-// recipients) — distinct from Email Routing's recipient-restricted `EmailMessage` flow.
-// It is reached through the same `send_email` binding (configured without a
-// destination_address) but a different call shape: `binding.send({ to, from, ... })`.
+// The default adapter targets Cloudflare Email Service (Email Sending, transactional,
+// arbitrary recipients), distinct from Email Routing's recipient-restricted `EmailMessage`
+// flow. Both share the same `send_email` binding (configured without a destination_address)
+// but use a different call shape: `binding.send({ to, from, ... })`.
 // Resend can slot in behind the same `sendMagicLink` signature if needed.
 
 /** Cloudflare Email Sending binding surface (the object-form `send`, not the MIME form). */

package/src/lib/github.ts

@@ -2,8 +2,8 @@
 //
 // Reads (Pass B) list a collection directory and fetch a file's raw markdown; the token
 // is optional because ecnordic's repo is public. Writes (Pass C) mint a short-lived
-// GitHub App installation token — App JWT (RS256) signed with Web Crypto, no octokit
-// dependency — and commit through the contents API with author = editor, committer = the
+// GitHub App installation token (App JWT, RS256 signed with Web Crypto, no octokit
+// dependency) and commit through the contents API with author = editor, committer = the
 // App (cairn-cms[bot]). The same token also lifts reads to the authenticated rate limit
 // and unlocks private repos (e.g. 907-life).
 
@@ -90,7 +90,7 @@ function derLength(n: number): number[] {
 // AlgorithmIdentifier for rsaEncryption (OID 1.2.840.113549.1.1.1) with NULL parameters.
 const RSA_ALG_ID = [0x30, 0x0d, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x01, 0x05, 0x00];
 
-/** Wrap a PKCS#1 RSAPrivateKey (DER) as PKCS#8 — the only RSA form Web Crypto importKey takes. */
+/** Wrap a PKCS#1 RSAPrivateKey (DER) as PKCS#8 (the only RSA form Web Crypto importKey takes). */
 function pkcs1ToPkcs8(pkcs1: Uint8Array): Uint8Array {
   const octet = [0x04, ...derLength(pkcs1.length), ...pkcs1];
   const body = [0x02, 0x01, 0x00, ...RSA_ALG_ID, ...octet];
@@ -124,7 +124,7 @@ export async function appJwt(appId: string, privateKeyPem: string): Promise<stri
 export interface AppCredentials {
   appId: string;
   installationId: string;
-  /** The stored GITHUB_APP_PRIVATE_KEY_B64 — base64 of the PEM, single line. */
+  /** The stored GITHUB_APP_PRIVATE_KEY_B64: base64 of the PEM, single line. */
   privateKeyB64: string;
 }
 
@@ -139,7 +139,7 @@ export async function installationToken(creds: AppCredentials): Promise<string>
   return ((await res.json()) as { token: string }).token;
 }
 
-/** Standard (padded) base64 of UTF-8 text — the encoding the contents API expects. */
+/** Standard (padded) base64 of UTF-8 text, as the contents API expects. */
 function toBase64(text: string): string {
   return btoa(Array.from(encoder.encode(text), (b) => String.fromCharCode(b)).join(''));
 }
@@ -157,11 +157,24 @@ export interface CommitAuthor {
   email: string;
 }
 
+/**
+ * A concurrent edit lost the SHA race (C3): the file changed between the read and the PUT,
+ * from another editor or the site's own CI. Thrown so callers can fail safe (re-fetch and ask
+ * the editor to reapply) instead of surfacing a raw 409. Defined and caught inside the package
+ * so `instanceof` is reliable (no peer-boundary identity split, unlike kit's `redirect`/`error`).
+ */
+export class CommitConflictError extends Error {
+  constructor(public readonly path: string) {
+    super(`Commit conflict on ${path}: it changed since it was opened`);
+    this.name = 'CommitConflictError';
+  }
+}
+
 /**
  * Commit `content` to `path` on the configured branch via the contents API. Author is the
  * editor; committer is omitted so GitHub attributes it to the App (cairn-cms[bot]). Updates
  * the file in place when it exists (passing its sha), creates it otherwise. Returns the
- * commit sha.
+ * commit sha. A stale-sha 409 (someone committed in between) becomes a `CommitConflictError`.
  */
 export async function commitFile(
   repo: RepoRef,
@@ -183,6 +196,25 @@ export async function commitFile(
       ...(sha ? { sha } : {}),
     }),
   });
+  // 409 = the blob sha we read is no longer current. Fail safe: the caller re-fetches and the
+  // editor reapplies. (Full three-way merge stays out of scope; see ARCHITECTURE §5.)
+  if (res.status === 409) throw new CommitConflictError(path);
   if (!res.ok) throw new Error(`GitHub commit ${path} failed: ${res.status} ${await res.text()}`);
   return ((await res.json()) as { commit: { sha: string } }).commit.sha;
 }
+
+/**
+ * Deploy-time self-test for the GitHub App signer (M2): sign a dummy JWT with the configured
+ * private key. Exercises the brittle PKCS#1→PKCS#8 conversion + Web Crypto import/sign without
+ * any network call or secret in the result, so `/admin/healthz` catches a bad/rotated key
+ * before an editor's save fails. Returns `{ ok: false, detail }` rather than throwing.
+ */
+export async function signingSelfTest(appId: string, privateKeyB64: string): Promise<{ ok: boolean; detail?: string }> {
+  try {
+    const jwt = await appJwt(appId, atob(privateKeyB64));
+    if (jwt.split('.').length !== 3) return { ok: false, detail: 'malformed JWT' };
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, detail: err instanceof Error ? err.message : 'sign failed' };
+  }
+}

package/src/lib/index.ts

@@ -5,3 +5,4 @@ export * from './github';
 export * from './carta';
 export * from './content';
 export * from './adapter';
+export * from './render';

package/src/lib/render/glyph.ts

@@ -0,0 +1,14 @@
+import { s } from 'hastscript';
+import type { Element } from 'hast';
+
+/** A glyph name → SVG path-data map (the site owns the icon set). */
+export type IconSet = Record<string, string>;
+
+/** Inline SVG glyph as a real hast node: class ec-glyph, 256 viewBox, currentColor fill. */
+export function glyph(name: string, icons: IconSet): Element {
+	return s(
+		'svg',
+		{ className: ['ec-glyph'], viewBox: '0 0 256 256', fill: 'currentColor', ariaHidden: 'true' },
+		[s('path', { d: icons[name] })],
+	);
+}

package/src/lib/render/index.ts

@@ -0,0 +1,8 @@
+// cairn-cms render engine: a directive-driven markdown → HTML pipeline whose
+// component vocabulary is supplied by a site's component registry. The site owns the
+// component builders, class names, icon set, and CSS; the engine owns the machinery.
+export * from './registry';
+export * from './glyph';
+export * from './remark-directives';
+export * from './rehype-dispatch';
+export * from './pipeline';

package/src/lib/render/pipeline.ts

@@ -0,0 +1,37 @@
+import { unified, type PluggableList } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import remarkDirective from 'remark-directive';
+import remarkRehype from 'remark-rehype';
+import rehypeRaw from 'rehype-raw';
+import rehypeSlug from 'rehype-slug';
+import rehypeStringify from 'rehype-stringify';
+import { remarkDirectiveStamp } from './remark-directives';
+import { rehypeDispatch } from './rehype-dispatch';
+import type { ComponentRegistry } from './registry';
+
+export interface RendererOptions {
+	/** A site's per-index motion formula for the top-level rise stagger
+	 *  (e.g. ecnordic's `(i) => '--rise:' + …`). Omit for no stagger. */
+	rise?: (idx: number) => string;
+}
+
+/** Compose a site's render pipeline from its component registry: directive syntax →
+ *  stamped markers → registry-built hast. Returns `renderMarkdown` plus the remark/
+ *  rehype plugin arrays (so the Carta editor preview can reuse the exact same set). */
+export function createRenderer(registry: ComponentRegistry, options: RendererOptions = {}) {
+	const remarkPlugins: PluggableList = [remarkDirective, [remarkDirectiveStamp, registry]];
+	const rehypePlugins: PluggableList = [rehypeRaw, [rehypeDispatch, registry, options.rise], rehypeSlug];
+	const processor = unified()
+		.use(remarkParse)
+		.use(remarkGfm)
+		.use(remarkPlugins)
+		.use(remarkRehype, { allowDangerousHtml: true })
+		.use(rehypePlugins)
+		.use(rehypeStringify);
+	return {
+		remarkPlugins,
+		rehypePlugins,
+		renderMarkdown: async (content: string): Promise<string> => String(await processor.process(content)),
+	};
+}

package/src/lib/render/registry.ts

@@ -0,0 +1,36 @@
+import type { Element } from 'hast';
+
+/** A site component: how it inserts (editor) and how it renders (rehype). */
+export interface ComponentDef {
+	/** Directive name, e.g. 'card' (matches `:::card`). */
+	name: string;
+	/** Palette label. */
+	label: string;
+	/** Palette description. */
+	description: string;
+	/** Markdown scaffold inserted at the cursor by the editor palette. */
+	insertTemplate: string;
+	/** Build the final hast element from the stamped directive element. */
+	build: (node: Element, rise?: string) => Element;
+	/** Optional role→default-icon (e.g. `{ caution: 'warning' }`). */
+	defaultIconByRole?: Record<string, string>;
+}
+
+export interface ComponentRegistry {
+	defs: ComponentDef[];
+	names: string[];
+	get(name: string): ComponentDef | undefined;
+	defaultIcon(name: string, role?: string): string | undefined;
+}
+
+/** Build a registry from a site's component definitions. The single source the
+ *  render pipeline (directive stamp + rehype dispatch) and the editor palette read. */
+export function defineRegistry(input: { components: ComponentDef[] }): ComponentRegistry {
+	const byName = new Map(input.components.map((c) => [c.name, c]));
+	return {
+		defs: input.components,
+		names: input.components.map((c) => c.name),
+		get: (name) => byName.get(name),
+		defaultIcon: (name, role) => (role ? byName.get(name)?.defaultIconByRole?.[role] : undefined),
+	};
+}

package/src/lib/render/rehype-dispatch.ts

@@ -0,0 +1,97 @@
+import type { Root, Element, ElementContent, Properties } from 'hast';
+import { h } from 'hastscript';
+import type { ComponentRegistry } from './registry';
+
+export function isElement(node: ElementContent | undefined): node is Element {
+	return !!node && node.type === 'element';
+}
+
+// hast Properties values are PropertyValue (string | number | boolean | array | null).
+// Directive markers (dataIcon/dataRole/dataPrimitive) are always stamped as strings;
+// this reads them back with that guarantee instead of casting at each call site.
+export function strProp(node: Element, name: string): string | undefined {
+	const value = node.properties?.[name];
+	return typeof value === 'string' ? value : undefined;
+}
+
+/** Wrap a pre-built glyph in an ec-icon span; secondary role adds the modifier. */
+export function iconSpan(glyphEl: Element, role?: string): Element {
+	const className = role === 'secondary' ? ['ec-icon', 'ec-icon-secondary'] : ['ec-icon'];
+	return h('span', { className }, [glyphEl]);
+}
+
+/** A site's icon factory: turn a stamped icon name + role into a hast element. */
+export type MakeIcon = (name: string, role?: string) => Element;
+
+// Pull the section's <h2> out, retag it .card-title, and build the .ec-head row
+// (optional icon + heading). Returns the head plus the remaining body children.
+// `makeIcon` (site-supplied) turns the stamped data-icon into an element; omit it
+// for a head with no icon.
+export function splitHead(node: Element, makeIcon?: MakeIcon): { head: Element; rest: ElementContent[] } {
+	const children = node.children as ElementContent[];
+	const i = children.findIndex((c) => isElement(c) && c.tagName === 'h2');
+	const h2 = children[i] as Element;
+	h2.properties = { ...h2.properties, className: ['card-title'] };
+	const rest = children.filter((_, j) => j !== i);
+	const icon = strProp(node, 'dataIcon');
+	const role = strProp(node, 'dataRole');
+	const headKids: ElementContent[] = [];
+	if (makeIcon && icon) headKids.push(makeIcon(icon, role));
+	headKids.push(h2);
+	return { head: h('div', { className: ['ec-head'] }, headKids), rest };
+}
+
+/** Section wrapper: `<section class=…><div class="card-body">…</div></section>`,
+ *  with an optional inline rise style. */
+export function cardShell(classes: string[], rise: string | undefined, body: ElementContent[]): Element {
+	const properties: Properties = { className: classes };
+	if (rise) properties.style = rise;
+	return h('section', properties, [h('div', { className: ['card-body'] }, body)]);
+}
+
+/** Tag the first <ul> among children with `ec-grid` and strip its whitespace-only
+ *  text nodes so the bare list serializes without newlines. Returns that <ul>. */
+export function markFirstList(children: ElementContent[]): Element | undefined {
+	const ul = children.find((c) => isElement(c) && c.tagName === 'ul') as Element | undefined;
+	if (ul) {
+		ul.properties = { ...ul.properties, className: ['ec-grid'] };
+		ul.children = (ul.children as ElementContent[]).filter(
+			(c) => !(c.type === 'text' && /^\s*$/.test(c.value)),
+		);
+	}
+	return ul;
+}
+
+// Recurse into a node's children, transforming any nested primitive sections
+// (a grid inside a card, panels inside a split) WITHOUT a rise stagger.
+function transformChildren(children: ElementContent[], registry: ComponentRegistry): ElementContent[] {
+	return children.map((c) => {
+		if (isElement(c) && c.properties?.dataPrimitive) return transformNode(c, registry);
+		if (isElement(c)) c.children = transformChildren(c.children as ElementContent[], registry);
+		return c;
+	});
+}
+
+function transformNode(node: Element, registry: ComponentRegistry, rise?: string): Element {
+	node.children = transformChildren(node.children as ElementContent[], registry);
+	const name = strProp(node, 'dataPrimitive');
+	const def = name ? registry.get(name) : undefined;
+	return def ? def.build(node, rise) : node;
+}
+
+/** Rehype transformer: dispatch each stamped element through its registry `build`
+ *  fn. Top-level primitives get a document-order rise stagger when `rise` is
+ *  supplied (a site's per-index motion formula); nested ones don't. Non-primitive
+ *  content (lede, intro paragraphs, the page-toc nav) passes through untouched. */
+export function rehypeDispatch(registry: ComponentRegistry, rise?: (idx: number) => string) {
+	return (tree: Root) => {
+		let idx = 0;
+		tree.children = (tree.children as ElementContent[]).map((child) => {
+			if (isElement(child) && child.properties?.dataPrimitive) {
+				return transformNode(child, registry, rise ? rise(idx++) : undefined);
+			}
+			if (isElement(child)) child.children = transformChildren(child.children as ElementContent[], registry);
+			return child;
+		});
+	};
+}

package/src/lib/render/remark-directives.ts

@@ -0,0 +1,71 @@
+import type { Paragraph, PhrasingContent, Root, Text } from 'mdast';
+import type { ContainerDirective, LeafDirective, TextDirective } from 'mdast-util-directive';
+import { visit } from 'unist-util-visit';
+import type { ComponentRegistry } from './registry';
+
+// Reconstruct a directive's authored attribute block (`{#id .class key="value"}`).
+// Accidental prose directives carry none, so this is almost always empty.
+function serializeAttributes(attributes?: Record<string, string | null | undefined> | null): string {
+	if (!attributes) return '';
+	const tokens: string[] = [];
+	for (const [key, value] of Object.entries(attributes)) {
+		if (value == null) tokens.push(key);
+		else if (key === 'id') tokens.push(`#${value}`);
+		else if (key === 'class') for (const c of value.split(/\s+/).filter(Boolean)) tokens.push(`.${c}`);
+		else tokens.push(`${key}="${value}"`);
+	}
+	return tokens.length ? `{${tokens.join(' ')}}` : '';
+}
+
+// The vocabulary is container-only (`:::name`). A text directive (`:name`) or
+// leaf directive (`::name`) is therefore always an accidental colon in prose
+// ("4:00", "9:30", "ratio 16:9") that micromark tokenized as a directive.
+// Restore it to its literal source text so prose renders verbatim.
+function restoreLiteral(node: TextDirective | LeafDirective): PhrasingContent[] {
+	const marker = node.type === 'leafDirective' ? '::' : ':';
+	const attrs = serializeAttributes(node.attributes);
+	if (node.children.length === 0) {
+		return [{ type: 'text', value: marker + node.name + attrs }];
+	}
+	const open: Text = { type: 'text', value: `${marker}${node.name}[` };
+	const close: Text = { type: 'text', value: `]${attrs}` };
+	return [open, ...(node.children as PhrasingContent[]), close];
+}
+
+// Stamp each registered container directive with data-* markers carrying its
+// component name, icon, and role. No structure is built here; the rehype
+// dispatcher rewrites the marked elements once their children are hast.
+// Text and leaf directives are restored to literal text (accidental prose colons).
+export function remarkDirectiveStamp(registry: ComponentRegistry) {
+	const known = new Set(registry.names);
+	return (tree: Root) => {
+		visit(tree, 'containerDirective', (node: ContainerDirective) => {
+			if (!known.has(node.name)) return;
+			const attrs = node.attributes ?? {};
+			const role = attrs.role || undefined;
+			let icon = attrs.icon || undefined;
+			if (!icon && role) icon = registry.defaultIcon(node.name, role);
+
+			const properties: Record<string, string> = { dataPrimitive: node.name };
+			if (icon) properties.dataIcon = icon;
+			if (role) properties.dataRole = role;
+
+			const data = node.data ?? (node.data = {});
+			data.hName = 'div';
+			data.hProperties = properties;
+		});
+
+		visit(tree, ['textDirective', 'leafDirective'], (node, index, parent) => {
+			if (!parent || index == null) return;
+			const literal = restoreLiteral(node as TextDirective | LeafDirective);
+			if (node.type === 'leafDirective') {
+				// Leaf directives sit at block level; wrap the restored text in a paragraph.
+				const paragraph: Paragraph = { type: 'paragraph', children: literal };
+				parent.children.splice(index, 1, paragraph);
+			} else {
+				parent.children.splice(index, 1, ...literal);
+			}
+			return index;
+		});
+	};
+}

package/src/lib/sveltekit/index.ts

@@ -2,20 +2,28 @@
 // route files are thin shims (`export const load = (event) => editLoad(event, cairn)`).
 //
 // SvelteKit's filesystem routing requires the route *files* to live in each site's
-// `src/routes/`, but their bodies are identical across sites — only the adapter differs.
+// `src/routes/`, but their bodies are identical across sites. Only the adapter differs.
 // These functions take the SvelteKit event (typed structurally, to avoid depending on the
 // site-generated `App.*` ambient types) plus the site `CairnAdapter`, and throw
 // `redirect`/`error` from `@sveltejs/kit` (a peer dependency, so the thrown objects share
-// class identity with the host's runtime — else the redirect 500s). Auth/session/manage-editors
+// class identity with the host's runtime; otherwise the redirect 500s). Auth/session/manage-editors
 // logic lives under `@glw907/cairn-cms/auth`; this module is content-only (list/edit/save).
 import { redirect, error } from '@sveltejs/kit';
 import matter from 'gray-matter';
 import type { CairnUser } from '../auth/guard';
-import { listMarkdown, readRaw, commitFile, installationToken, type RepoFile } from '../github';
+import {
+  listMarkdown,
+  readRaw,
+  commitFile,
+  installationToken,
+  signingSelfTest,
+  CommitConflictError,
+  type RepoFile,
+} from '../github';
 import { serializeMarkdown } from '../content';
 import { findCollection, frontmatterFromForm, type CairnAdapter, type CairnField } from '../adapter';
 
-/** The `platform.env` bindings the content routes read. All optional — the handlers guard. */
+/** The `platform.env` bindings the content routes read. All optional; the handlers guard. */
 export interface AdminEnv {
   GITHUB_APP_ID?: string;
   GITHUB_APP_INSTALLATION_ID?: string;
@@ -30,7 +38,7 @@ interface PlatformEvent {
  * Mint a GitHub App installation token for *reads* when the App is configured, else undefined
  * (reads then fall back to anonymous). Authenticated reads get the 5000/hr limit; anonymous
  * reads share GitHub's 60/hr-per-IP budget across Cloudflare's egress IPs, so they 403 in prod.
- * A mint failure degrades gracefully to anonymous rather than 500ing — unlike the commit path,
+ * A mint failure degrades gracefully to anonymous rather than 500ing. Unlike the commit path,
  * where a missing App is fatal, a read can still succeed unauthenticated.
  */
 async function readToken(env: AdminEnv | undefined): Promise<string | undefined> {
@@ -59,7 +67,7 @@ export interface AdminLayoutData {
 
 /**
  * Branding + session for every admin page. `siteName` flows from the adapter without pulling
- * its plugin graph into client bundles — the import stays server-side in the layout load.
+ * its plugin graph into client bundles; the import stays server-side in the layout load.
  * `pathname` lets the shared shell highlight the active nav item without a `$app/*` import
  * (those kit virtual modules have no types outside a kit app, so they can't live in the
  * package); reading `event.url` here also opts the layout load into rerunning on navigation.
@@ -182,13 +190,46 @@ export async function saveCommit(
     privateKeyB64: env.GITHUB_APP_PRIVATE_KEY_B64,
   });
 
-  await commitFile(
-    adapter.backend,
-    `${collection.dir}/${id}.md`,
-    markdown,
-    { message: `Update ${collection.label.toLowerCase()}: ${id}`, author: { name: user.name, email: user.email } },
-    token,
-  );
+  try {
+    await commitFile(
+      adapter.backend,
+      `${collection.dir}/${id}.md`,
+      markdown,
+      { message: `Update ${collection.label.toLowerCase()}: ${id}`, author: { name: user.name, email: user.email } },
+      token,
+    );
+  } catch (err) {
+    // Concurrent-edit 409 (C3): fail safe. Bounce back with a reload prompt; the editor reloads
+    // the current version and reapplies. Any other error is unexpected, so rethrow.
+    if (err instanceof CommitConflictError) {
+      const message = 'This file changed since you opened it. Reload and reapply your edits.';
+      throw redirect(303, `/admin/edit/${type}/${id}?error=${encodeURIComponent(message)}`);
+    }
+    throw err;
+  }
 
   throw redirect(303, `/admin/edit/${type}/${id}?saved=1`);
 }
+
+// ── /admin/healthz (GET) ──────────────────────────────────────────────────────
+
+export interface HealthData {
+  ok: boolean;
+  checks: { githubAppSigning: { ok: boolean; detail?: string } };
+}
+
+/**
+ * Deploy-time health check (M2): signs a dummy App JWT to prove the GitHub App key loads and
+ * the PKCS#1→PKCS#8 conversion still works, before an editor hits it on save. Behind the
+ * `/admin` guard (signed-in editors only); returns ok/fail with no secret in the body.
+ */
+export async function healthLoad(event: PlatformEvent): Promise<HealthData> {
+  const env = event.platform?.env;
+  let githubAppSigning: { ok: boolean; detail?: string };
+  if (env?.GITHUB_APP_ID && env.GITHUB_APP_PRIVATE_KEY_B64) {
+    githubAppSigning = await signingSelfTest(env.GITHUB_APP_ID, env.GITHUB_APP_PRIVATE_KEY_B64);
+  } else {
+    githubAppSigning = { ok: false, detail: 'GitHub App not configured' };
+  }
+  return { ok: githubAppSigning.ok, checks: { githubAppSigning } };
+}

package/src/lib/utils.ts

@@ -1,11 +1,11 @@
 // cairn-core: internal encoding helpers shared across modules.
 //
-// Deliberately NOT re-exported from index.ts — these are implementation details of the
+// Deliberately NOT re-exported from index.ts. These are implementation details of the
 // auth/github crypto, not part of the public API (auth.ts signs tokens, github.ts builds
 // the App JWT; both need base64url). Keeping them here stops bytesToB64url leaking through
 // the `export *` barrel.
 
-/** Encode bytes as unpadded base64url (RFC 4648 §5) — the JWT/token wire format. */
+/** Encode bytes as unpadded base64url (RFC 4648 §5), the JWT/token wire format. */
 export function bytesToB64url(bytes: Uint8Array): string {
   const binary = Array.from(bytes, (b) => String.fromCharCode(b)).join('');
   return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');