@glw907/cairn-cms 0.60.1 → 0.62.2

package/src/lib/content/types.ts

@@ -22,6 +22,11 @@ interface FieldBase {
   label: string;
   /** A required field fails validation when empty (spec §7.4). */
   required?: boolean;
+  /**
+   * One author-facing sentence shown under the field in the editor, in plain end-user language.
+   * Optional; render nothing when absent. Not a validation rule.
+   */
+  description?: string;
 }
 
 /** A single-line text input. */
@@ -33,8 +38,10 @@ export interface TextField extends FieldBase {
   max?: number;
   /** Exact required character length. */
   length?: number;
-  /** A regular-expression source string the value must match. Stored as a string so the field
-   *  list stays plain serializable data; the validator compiles it. */
+  /**
+   * A regular-expression source string the value must match. Stored as a string so the field
+   *  list stays plain serializable data; the validator compiles it.
+   */
   pattern?: string;
 }
 /** A multi-line text input. */
@@ -103,8 +110,10 @@ export type FrontmatterField =
   | FreeTagsField
   | ImageField;
 
-/** The stored value of an `image` field: a `media:` reference, a screen-reader description, and an
- *  optional caption. */
+/**
+ * The stored value of an `image` field: a `media:` reference, a screen-reader description, and an
+ *  optional caption.
+ */
 export interface ImageValue {
   src: string;
   alt: string;
@@ -138,8 +147,10 @@ export interface ConceptConfig<S extends ConceptSchema = ConceptSchema> {
   singular?: string;
   /** The concept's schema: the form projection, the generated validator, and the inferred type. */
   schema: S;
-  /** Frontmatter keys to surface on each `ContentSummary.fields`, so a list card reads an authored
-   *  field without a per-entry detail read. Each key should also be declared in `schema`. */
+  /**
+   * Frontmatter keys to surface on each `ContentSummary.fields`, so a list card reads an authored
+   *  field without a per-entry detail read. Each key should also be declared in `schema`.
+   */
   summaryFields?: string[];
 }
 
@@ -191,28 +202,38 @@ export interface NavMenuConfig {
  * stylesheet.
  */
 export interface PreviewConfig {
-  /** Absolute or root-relative URLs of the site's compiled stylesheets, linked inside the
-   *  preview document. A Vite `?url` import of the site's CSS resolves the hashed asset URL. */
+  /**
+   * Absolute or root-relative URLs of the site's compiled stylesheets, linked inside the
+   *  preview document. A Vite `?url` import of the site's CSS resolves the hashed asset URL.
+   */
   stylesheets: string[];
   /** Class list applied to the preview document's body, for theme or typography roots. */
   bodyClass?: string;
-  /** Class list for a wrapper element around the rendered content, reproducing the site's
-   *  content container (a prose or measure class). Omitted renders the content bare. */
+  /**
+   * Class list for a wrapper element around the rendered content, reproducing the site's
+   *  content container (a prose or measure class). Omitted renders the content bare.
+   */
   containerClass?: string;
-  /** Per-concept overrides of bodyClass and containerClass, keyed by concept id. An entry's
+  /**
+   * Per-concept overrides of bodyClass and containerClass, keyed by concept id. An entry's
    *  preview resolves the override for its concept over the top-level values; stylesheets are
-   *  always shared. */
+   *  always shared.
+   */
   byConcept?: Record<string, { bodyClass?: string; containerClass?: string }>;
 }
 
-/** The flat preview shape `editLoad` ships to the edit page: the top-level `PreviewConfig`
- *  values with the entry's concept override applied, and no `byConcept` map. */
+/**
+ * The flat preview shape `editLoad` ships to the edit page: the top-level `PreviewConfig`
+ *  values with the entry's concept override applied, and no `byConcept` map.
+ */
 export type ResolvedPreview = Omit<PreviewConfig, 'byConcept'>;
 
-/** A site's media configuration (seam 4). A site sets this to turn on R2-backed media: uploads,
+/**
+ * A site's media configuration (seam 4). A site sets this to turn on R2-backed media: uploads,
  *  content-addressed storage, and Cloudflare Images variants. Omitting it leaves media off. The
  *  engine normalizes this into a `ResolvedAssetConfig` and merges the named variants over the
- *  built-in thumb, inline, card, and hero presets. */
+ *  built-in thumb, inline, card, and hero presets.
+ */
 export interface AssetConfig {
   /** The R2 bucket binding name on the Worker, e.g. "MEDIA_BUCKET". Required when a site declares media. */
   bucketBinding: string;
@@ -226,10 +247,12 @@ export interface AssetConfig {
   allowedTypes?: string[];
   /** Named transform presets, merged over the built-in thumb/inline/card/hero presets. */
   variants?: Record<string, VariantSpec>;
-  /** Whether Cloudflare Image Transformations are enabled for the zone (default false). The feature
+  /**
+   * Whether Cloudflare Image Transformations are enabled for the zone (default false). The feature
    *  is a per-zone setting that the dashboard or API turns on; it cannot be flipped from a Worker. With
    *  it off, the media resolver serves the bare full-size delivery path and ignores any preset, so
-   *  thumbnails stay correct (full-size-but-correct) rather than pointing at a dead /cdn-cgi/image URL. */
+   *  thumbnails stay correct (full-size-but-correct) rather than pointing at a dead /cdn-cgi/image URL.
+   */
   transformations?: boolean;
 }
 
@@ -246,10 +269,18 @@ export interface CairnAdapter {
   };
   backend: BackendConfig;
   sender: SenderConfig;
-  /** The site's one renderer: the editor preview and every public page call it (design decision 4).
+  /**
+   * Optional contact a stuck editor is pointed to from the in-admin help (an email address, a URL,
+   *  or a name and instruction). The help renders the hand-off only when this is set. Plain string,
+   *  passed through verbatim.
+   */
+  supportContact?: string;
+  /**
+   * The site's one renderer: the editor preview and every public page call it (design decision 4).
    *  `resolve` rewrites cairn: links to live permalinks; the build passes a site-resolver-backed
    *  one, the preview a manifest one. The trailing `resolveMedia` is additive and optional: the build
-   *  passes a site-resolver-backed media resolver, the preview a manifest-backed one. */
+   *  passes a site-resolver-backed media resolver, the preview a manifest-backed one.
+   */
   render(
     md: string,
     opts?: {
@@ -258,24 +289,32 @@ export interface CairnAdapter {
       resolveMedia?: import('../render/resolve-media.js').MediaResolve;
     },
   ): string | Promise<string>;
-  /** Repo-relative path to the committed content manifest. Defaults to src/content/.cairn/index.json
-   *  in composeRuntime. It sits outside any concept directory, so content enumeration never globs it. */
+  /**
+   * Repo-relative path to the committed content manifest. Defaults to src/content/.cairn/index.json
+   *  in composeRuntime. It sits outside any concept directory, so content enumeration never globs it.
+   */
   manifestPath?: string;
-  /** Repo-relative path to the committed media manifest. Defaults to src/content/.cairn/media.json,
-   *  applied in composeRuntime. Sits outside any concept directory, like the content manifest. */
+  /**
+   * Repo-relative path to the committed media manifest. Defaults to src/content/.cairn/media.json,
+   *  applied in composeRuntime. Sits outside any concept directory, like the content manifest.
+   */
   mediaManifestPath?: string;
-  /** Repo-relative path to the committed personal dictionary file. Defaults to
+  /**
+   * Repo-relative path to the committed personal dictionary file. Defaults to
    *  src/content/.cairn/dictionary.txt, applied in composeRuntime: the same `.cairn/` content root the
    *  manifests use, so the spec's `content/.cairn/dictionary.txt` resolves the same configurable way the
-   *  manifest paths do. One word per line, sorted, comment lines allowed (see site-dictionary.ts). */
+   *  manifest paths do. One word per line, sorted, comment lines allowed (see site-dictionary.ts).
+   */
   dictionaryPath?: string;
   /** Directive component registry; the renderer and the future palette derive from it (seam 3). */
   registry?: ComponentRegistry;
   /** The site's glyph name to SVG path-data map, for the admin icon picker and the renderer. */
   icons?: IconSet;
   navMenu?: NavMenuConfig;
-  /** The live site's content styling for the preview frame. The admin's chrome isolation keeps
-   *  the site's CSS out of the admin document, so the preview frame links these instead. */
+  /**
+   * The live site's content styling for the preview frame. The admin's chrome isolation keeps
+   *  the site's CSS out of the admin document, so the preview frame links these instead.
+   */
   preview?: PreviewConfig;
   assets?: AssetConfig;
 }
@@ -301,8 +340,10 @@ export interface ConceptDescriptor {
   /** Concept id, the key under `content`, e.g. "posts". */
   id: string;
   label: string;
-  /** The singular noun for the create affordances ("New post"); resolved from `ConceptConfig.singular`,
-   *  defaulting to `label` when the config omits it. */
+  /**
+   * The singular noun for the create affordances ("New post"); resolved from `ConceptConfig.singular`,
+   *  defaulting to `label` when the config omits it.
+   */
   singular: string;
   dir: string;
   routing: RoutingRule;
@@ -311,8 +352,10 @@ export interface ConceptDescriptor {
   /** Filename date-prefix granularity for a dated concept; resolved by `normalizeConcepts`. */
   datePrefix: DatePrefix;
   fields: FrontmatterField[];
-  /** Frontmatter keys the index copies onto each summary's `fields` record. `normalizeConcepts`
-   *  resolves it to `[]` when a concept omits `summaryFields`. */
+  /**
+   * Frontmatter keys the index copies onto each summary's `fields` record. `normalizeConcepts`
+   *  resolves it to `[]` when a concept omits `summaryFields`.
+   */
   summaryFields: string[];
   validate(frontmatter: Record<string, unknown>, body: string): ValidationResult;
 }
@@ -371,9 +414,13 @@ export interface CairnRuntime {
   concepts: ConceptDescriptor[];
   backend: BackendConfig;
   sender: SenderConfig;
-  /** The site's one renderer: the editor preview and every public page call it (design decision 4).
+  /** The support contact passed through from the adapter; the in-admin help reads it. Optional. */
+  supportContact?: string;
+  /**
+   * The site's one renderer: the editor preview and every public page call it (design decision 4).
    *  The trailing `resolveMedia` is additive and optional: the build passes a site-resolver-backed
-   *  media resolver, the preview a manifest-backed one. */
+   *  media resolver, the preview a manifest-backed one.
+   */
   render(
     md: string,
     opts?: {
@@ -385,15 +432,19 @@ export interface CairnRuntime {
   manifestPath: string;
   /** The repo-relative path to the committed media manifest, defaulted in composeRuntime. */
   mediaManifestPath: string;
-  /** The repo-relative path to the committed personal dictionary file (one word per line, sorted),
+  /**
+   * The repo-relative path to the committed personal dictionary file (one word per line, sorted),
    *  defaulted in composeRuntime to src/content/.cairn/dictionary.txt: the same `.cairn/` content root
    *  the manifests use. The edit load reads it and threads its words onto EditData; the
    *  addDictionaryWord action reads, merges, and commits it. Optional on the runtime so a hand-built
    *  runtime need not set it; composeRuntime always fills it, and the edit load and the action default
-   *  a missing value to the same content-root path. */
+   *  a missing value to the same content-root path.
+   */
   dictionaryPath?: string;
-  /** The adapter's asset config resolved once at compose: `{ enabled: false }` for a no-media site,
-   *  otherwise the filled config the upload, storage, delivery, and resolver paths read. */
+  /**
+   * The adapter's asset config resolved once at compose: `{ enabled: false }` for a no-media site,
+   *  otherwise the filled config the upload, storage, delivery, and resolver paths read.
+   */
   resolvedAssets: import('../media/config.js').ResolvedAssetConfig;
   registry?: ComponentRegistry;
   /** The site's glyph name to SVG path-data map, for the admin icon picker and the renderer. */
@@ -402,18 +453,22 @@ export interface CairnRuntime {
   /** The live site's content styling for the preview frame; passed through from the adapter. */
   preview?: PreviewConfig;
   assets?: AssetConfig;
-  /** The editor's spellcheck dictionary file, resolved once at compose from the site config's
+  /**
+   * The editor's spellcheck dictionary file, resolved once at compose from the site config's
    *  `spellcheck.dialect` (defaulting to US English). The edit load threads it onto EditData and the
    *  editor resolves it to a real asset URL on the main thread, so the Worker receives the URL and
    *  never reads config. Just the filename, e.g. "dictionary-en-us.txt". Optional on the runtime so a
    *  hand-built runtime need not set it; composeRuntime always fills it, and the edit load defaults a
-   *  missing value to the US English dictionary. */
+   *  missing value to the US English dictionary.
+   */
   spellcheckDictionary?: string;
-  /** The editor tidy (LLM copy-edit) settings, passed through from the site config. Optional on the
+  /**
+   * The editor tidy (LLM copy-edit) settings, passed through from the site config. Optional on the
    *  runtime so a hand-built runtime need not set it; composeRuntime threads it from
    *  `siteConfig.tidy`. The tidy action reads `enabled` and `model` at call time, and builds its prompt
    *  from `conventions`. Absent (or `enabled` false) means tidy is off, and the action refuses with a
-   *  fail(503) before any model call. */
+   *  fail(503) before any model call.
+   */
   tidy?: import('../nav/site-config.js').TidyConfig;
   /** Admin panels contributed by extensions (Mode 2). Empty until Plan 09 wires the dispatch route. */
   adminPanels?: AdminPanel[];

package/src/lib/delivery/content-index.ts

@@ -15,8 +15,10 @@ export interface RawFile {
 
 /** The cheap, plain-data view of one entry, for lists, feeds, and the sitemap. */
 export interface ContentSummary {
-  /** The descriptor id this entry belongs to, e.g. "posts". Lets a list or page branch per
-   *  concept without re-deriving it from a proxy like `entry.date`. */
+  /**
+   * The descriptor id this entry belongs to, e.g. "posts". Lets a list or page branch per
+   *  concept without re-deriving it from a proxy like `entry.date`.
+   */
   concept: string;
   id: string;
   slug: string;
@@ -24,23 +26,29 @@ export interface ContentSummary {
   title: string;
   date?: string;
   updated?: string;
-  /** The entry's tags, always present as an array and empty when the file declares none. This is the
+  /**
+   * The entry's tags, always present as an array and empty when the file declares none. This is the
    *  read-model normalization. It differs on purpose from the validated `frontmatter.tags`, which the
    *  validator omits when empty, so a published file carries no `tags: []` noise. Read `tags` here for
-   *  a list; read `frontmatter.tags` only when you need the validated, possibly-absent value. */
+   *  a list; read `frontmatter.tags` only when you need the validated, possibly-absent value.
+   */
   tags: string[];
   excerpt: string;
   wordCount: number;
   draft: boolean;
-  /** The frontmatter keys the descriptor nominated via `summaryFields`, read off the validated,
+  /**
+   * The frontmatter keys the descriptor nominated via `summaryFields`, read off the validated,
    *  normalized frontmatter. Held in a separate record so a nominated key cannot collide with a
-   *  typed summary field. Empty when the concept declares no `summaryFields`. */
+   *  typed summary field. Empty when the concept declares no `summaryFields`.
+   */
   fields: Record<string, unknown>;
 }
 
-/** The detail view: a summary plus the frontmatter and the body to render. The frontmatter
+/**
+ * The detail view: a summary plus the frontmatter and the body to render. The frontmatter
  *  type defaults to `Record<string, unknown>`; the typed-reads pass infers it from the concept
- *  fields. Generic now so that change does not break this signature. */
+ *  fields. Generic now so that change does not break this signature.
+ */
 export interface ContentEntry<F = Record<string, unknown>> extends ContentSummary {
   frontmatter: F;
   body: string;

package/src/lib/delivery/feeds.ts

@@ -30,8 +30,10 @@ function cdataSafe(value: string): string {
   return value.replace(/]]>/g, ']]]]><![CDATA[>');
 }
 
-/** Parse a YYYY-MM-DD (or ISO) string as a UTC instant. Returns undefined for an absent or
- *  unparseable date, so a feed omits the date field rather than emit Invalid Date or throw. */
+/**
+ * Parse a YYYY-MM-DD (or ISO) string as a UTC instant. Returns undefined for an absent or
+ *  unparseable date, so a feed omits the date field rather than emit Invalid Date or throw.
+ */
 function parseFeedDate(date?: string): Date | undefined {
   if (!date) return undefined;
   const at = new Date(`${date.slice(0, 10)}T00:00:00.000Z`);

package/src/lib/delivery/json-ld.ts

@@ -5,6 +5,9 @@
 // The line separator U+2028 and paragraph separator U+2029 get the same treatment: they are
 // legal inside a JSON string but unsafe in inline script text, where some parsers read them as
 // line terminators, so an author pasting one into frontmatter would corrupt the JSON-LD block.
+/**
+ *
+ */
 export function jsonLdScript(data: Record<string, unknown>): string {
   const json = JSON.stringify(data)
     .replace(/</g, '\\u003c')

package/src/lib/delivery/manifest.ts

@@ -11,8 +11,10 @@ import type { SiteConfig } from '../nav/site-config.js';
 import type { CairnAdapter } from '../content/types.js';
 import type { SiteGlobs } from './site-indexes.js';
 
-/** Build the whole-corpus manifest from a site's adapter, config, and per-concept globs. Drafts are
- *  included and flagged, so the admin picker and the guards see the full graph. */
+/**
+ * Build the whole-corpus manifest from a site's adapter, config, and per-concept globs. Drafts are
+ *  included and flagged, so the admin picker and the guards see the full graph.
+ */
 export function buildSiteManifest<A extends CairnAdapter>(adapter: A, config: SiteConfig, globs: SiteGlobs<A>): Manifest {
   const globRecord = globs as Record<string, Record<string, string> | undefined>;
   const manifest = emptyManifest();

package/src/lib/delivery/public-routes.ts

@@ -25,12 +25,16 @@ export interface PublicRoutesDeps {
   description: string;
   /** Absolute feed URLs for the head's autodiscovery links. */
   feeds?: { rss?: string; json?: string };
-  /** A site-wide default OG image, used when an entry declares none. Resolved to absolute like the
-   *  canonical URL, so a relative path such as "/og/default.png" works. */
+  /**
+   * A site-wide default OG image, used when an entry declares none. Resolved to absolute like the
+   *  canonical URL, so a relative path such as "/og/default.png" works.
+   */
   defaultImage?: string;
-  /** Resolve a frontmatter `media:` hero reference to its delivery path. The site builds this from its
+  /**
+   * Resolve a frontmatter `media:` hero reference to its delivery path. The site builds this from its
    *  committed `media.json` exactly as it builds the body resolver (`makeMediaResolver`). When absent,
-   *  media is off and no `heroImage` projection is derived. */
+   *  media is off and no `heroImage` projection is derived.
+   */
   resolveMedia?: MediaResolve;
 }
 
@@ -58,11 +62,13 @@ export interface EntryData {
   seo: SeoMeta;
   newer?: ContentSummary;
   older?: ContentSummary;
-  /** The resolved hero image, a derived projection of the frontmatter `image` field. `url` is the
+  /**
+   * The resolved hero image, a derived projection of the frontmatter `image` field. `url` is the
    *  root-relative delivery path for an `<img>`, `absoluteUrl` the origin-anchored form for the
    *  og:image, and `alt`/`caption` carry from the stored object. The canonical token is untouched:
    *  `entry.frontmatter.image.src` stays the `media:` token. Undefined when no hero is set, media is
-   *  off, the reference does not parse, or the resolver finds no asset. */
+   *  off, the reference does not parse, or the resolver finds no asset.
+   */
   heroImage?: { url: string; absoluteUrl?: string; alt: string; caption?: string };
 }
 
@@ -70,7 +76,8 @@ export interface EntryData {
 export function createPublicRoutes(deps: PublicRoutesDeps) {
   const { site, render, origin, siteName, description, feeds, defaultImage, resolveMedia } = deps;
 
-  /** Derive the hero projection from an entry's frontmatter, without mutating it (locked decision 5).
+  /**
+   * Derive the hero projection from an entry's frontmatter, without mutating it (locked decision 5).
    *  The hero lives at the conventional `image` key as the validated nested object `{ src, alt, caption }`;
    *  only an image field's validate arm produces an object-with-string-`src` shape, so detecting that
    *  structure is enough (a text field stores a string, a tags field an array). Returns undefined when
@@ -81,7 +88,8 @@ export function createPublicRoutes(deps: PublicRoutesDeps) {
    *  and renders in the editor, but its delivery resolution is not wired here yet, since the field
    *  declarations are not reachable in the delivery read path. Honoring a renamed `seo`-flagged field
    *  (and a second image field per concept) at delivery is a carried follow-up; every consumer today
-   *  uses `image`. */
+   *  uses `image`.
+   */
   function deriveHeroImage(frontmatter: Record<string, unknown>): EntryData['heroImage'] {
     if (!resolveMedia) return undefined;
     const value = frontmatter.image;

package/src/lib/delivery/seo-fields.ts

@@ -3,9 +3,11 @@
 // typed Record<string, unknown>; this reads the known head fields by name and coerces. Kept apart
 // from seo.ts (the head builder) so reading frontmatter and building the head stay distinct concerns.
 
-/** The head fields a concept can carry in frontmatter. Each is optional and omitted when absent.
+/**
+ * The head fields a concept can carry in frontmatter. Each is optional and omitted when absent.
  *  `author` is article-scoped downstream: the head builder emits `article:author` only for a dated
- *  entry, so an `author` on an undated Page is read here but not rendered. */
+ *  entry, so an `author` on an undated Page is read here but not rendered.
+ */
 export interface SeoFields {
   description?: string;
   image?: string;
@@ -15,11 +17,13 @@ export interface SeoFields {
 
 const KEYS = ['description', 'image', 'robots', 'author'] as const;
 
-/** Read the known SEO head fields off an entry's normalized frontmatter. Keeps a present string,
+/**
+ * Read the known SEO head fields off an entry's normalized frontmatter. Keeps a present string,
  *  trimmed, and omits an absent, empty, or non-string value. Trimming the stored value keeps a stray
  *  `robots: "  noindex  "` from reaching the head tag with surrounding whitespace. The field must be
  *  declared in the concept's schema to survive the validate-once read; an undeclared key is not on the
- *  normalized frontmatter. */
+ *  normalized frontmatter.
+ */
 export function readSeoFields(frontmatter: Record<string, unknown>): SeoFields {
   const fields: SeoFields = {};
   for (const key of KEYS) {
@@ -29,11 +33,13 @@ export function readSeoFields(frontmatter: Record<string, unknown>): SeoFields {
   return fields;
 }
 
-/** Resolve an author-supplied image path to an absolute URL against the site origin. An absolute or
+/**
+ * Resolve an author-supplied image path to an absolute URL against the site origin. An absolute or
  *  protocol-relative URL passes through; a root-relative path anchors to the origin; a malformed
  *  string returns undefined rather than throwing at build. The sites use a bare-domain origin, so a
  *  bare path also anchors to the origin root; against a sub-path origin it would resolve relative to
- *  that path, per the WHATWG URL rules. */
+ *  that path, per the WHATWG URL rules.
+ */
 export function resolveImageUrl(image: string, origin: string): string | undefined {
   try {
     const url = new URL(image, origin);

package/src/lib/delivery/site-indexes.ts

@@ -18,8 +18,10 @@ export type SiteGlobs<A extends CairnAdapter> = {
   [K in keyof A['content']]?: Record<string, string>;
 };
 
-/** The typed per-concept indexes plus the cross-concept `site` resolver. A concept literally named
- *  `site` is not supported, since `site` is the reserved resolver key. */
+/**
+ * The typed per-concept indexes plus the cross-concept `site` resolver. A concept literally named
+ *  `site` is not supported, since `site` is the reserved resolver key.
+ */
 export type SiteIndexes<A extends CairnAdapter> = {
   [K in keyof A['content']]: ContentIndex<
     NonNullable<A['content'][K]> extends ConceptConfig<infer S> ? Infer<S> : Record<string, unknown>

package/src/lib/delivery/site-resolver.ts

@@ -93,8 +93,10 @@ export function createSiteResolver(concepts: ConceptIndex[], opts: { validate?:
   };
 }
 
-/** A resolver backed by the site resolver, for the build. A miss throws, so a dangling cairn: token
- *  fails the prerender (the build backstop). The preview uses manifestLinkResolver, which marks. */
+/**
+ * A resolver backed by the site resolver, for the build. A miss throws, so a dangling cairn: token
+ *  fails the prerender (the build backstop). The preview uses manifestLinkResolver, which marks.
+ */
 export function buildLinkResolver(site: SiteResolver): LinkResolve {
   return (ref) => {
     const url = site.concept(ref.concept)?.byId(ref.id)?.permalink;

package/src/lib/doctor/cloudflare-api.ts

@@ -17,12 +17,18 @@ export const NO_ACCOUNT: CheckResult = skip(
 	'set CLOUDFLARE_API_TOKEN, and CLOUDFLARE_ACCOUNT_ID or a wrangler account_id, to run this check'
 );
 
+/**
+ *
+ */
 export function cfGet(ctx: DoctorContext, path: string): Promise<Response> {
 	return ctx.fetch(`${CF_API}${path}`, {
 		headers: { authorization: `Bearer ${ctx.cfToken}` },
 	});
 }
 
+/**
+ *
+ */
 export function cfPost(ctx: DoctorContext, path: string, body: unknown): Promise<Response> {
 	return ctx.fetch(`${CF_API}${path}`, {
 		method: 'POST',

package/src/lib/doctor/index.ts

@@ -25,8 +25,10 @@ export interface DoctorArgs {
 	from?: string;
 	repo?: string;
 	sendTest?: string;
-	/** The live admin probe: a URL when --probe carried one, true for the bare flag (probe the
-	 *  PUBLIC_ORIGIN input), absent when the flag never appeared (the probe does not run). */
+	/**
+	 * The live admin probe: a URL when --probe carried one, true for the bare flag (probe the
+	 *  PUBLIC_ORIGIN input), absent when the flag never appeared (the probe does not run).
+	 */
 	probe?: string | true;
 }
 
@@ -91,12 +93,16 @@ export function contextFromEnv(
 	};
 }
 
-/** The lazy derivation sources the bin wires up: the adapter read through the consumer's own
+/**
+ * The lazy derivation sources the bin wires up: the adapter read through the consumer's own
  *  Vite resolution and the wrangler config's account_id. Each runs only when an input it feeds
- *  is still missing, so a doctor run with full flags touches neither. */
+ *  is still missing, so a doctor run with full flags touches neither.
+ */
 export interface DerivationSources {
-	/** Returns { owner, repo, from, mediaBucketBinding } off the adapter, or null when nothing is
-	 *  derivable. */
+	/**
+	 * Returns `{ owner, repo, from, mediaBucketBinding }` off the adapter, or null when nothing is
+	 *  derivable.
+	 */
 	adapterFacts: () => Promise<{
 		owner?: string;
 		repo?: string;

package/src/lib/doctor/report.ts

@@ -11,6 +11,9 @@ const TAG: Record<CheckResult['status'], string> = {
 	skip: 'SKIP',
 };
 
+/**
+ *
+ */
 export function formatReport(results: { check: DoctorCheck; result: CheckResult }[]): string {
 	const lines = results.map(
 		({ check, result }) => `${TAG[result.status]}  ${check.title}: ${result.detail}`

package/src/lib/doctor/run.ts

@@ -3,6 +3,9 @@
 import { fail } from './types.js';
 import type { CheckResult, DoctorCheck, DoctorContext } from './types.js';
 
+/**
+ *
+ */
 export async function runDoctor(
 	checks: DoctorCheck[],
 	ctx: DoctorContext

package/src/lib/doctor/types.ts

@@ -14,10 +14,16 @@ export function pass(detail: string): CheckResult {
 	return { status: 'pass', detail };
 }
 
+/**
+ *
+ */
 export function fail(detail: string): CheckResult {
 	return { status: 'fail', detail };
 }
 
+/**
+ *
+ */
 export function skip(detail: string): CheckResult {
 	return { status: 'skip', detail };
 }
@@ -45,8 +51,10 @@ export interface DoctorContext {
 	cfAccountId?: string;
 	/** PUBLIC_ORIGIN, the env fallback when the wrangler vars carry none. */
 	publicOrigin?: string;
-	/** The adapter's media bucket binding (cairn.assets.bucketBinding), derived off the adapter.
-	 *  Undefined when the site declares no media assets; the media-bucket check skips in that case. */
+	/**
+	 * The adapter's media bucket binding (cairn.assets.bucketBinding), derived off the adapter.
+	 *  Undefined when the site declares no media assets; the media-bucket check skips in that case.
+	 */
 	mediaBucketBinding?: string;
 	/** GITHUB_APP_ID / GITHUB_APP_INSTALLATION_ID / GITHUB_APP_PRIVATE_KEY_B64. */
 	github?: { appId: string; installationId: string; privateKeyB64: string };

package/src/lib/doctor/wrangler-config.ts

@@ -16,11 +16,16 @@ export interface WranglerFacts {
 	publicOrigin?: string;
 	/** The top-level account_id, when declared; a fallback for CLOUDFLARE_ACCOUNT_ID. */
 	accountId?: string;
-	/** The declared r2_buckets binding names; the conditional media check matches the adapter's
-	 *  bucketBinding against this. Not part of the hard config.bindings check (decision 9). */
+	/**
+	 * The declared r2_buckets binding names; the conditional media check matches the adapter's
+	 *  bucketBinding against this. Not part of the hard config.bindings check (decision 9).
+	 */
 	r2Buckets: string[];
 }
 
+/**
+ *
+ */
 export async function readWranglerConfig(
 	readFile: DoctorContext['readFile']
 ): Promise<WranglerFacts | null> {

package/src/lib/email.ts

@@ -23,9 +23,11 @@ export interface AuthBranding {
   replyTo?: string;
 }
 
-/** The injected send. Production uses `cloudflareSend`; tests pass a sink. A thrown error's
+/**
+ * The injected send. Production uses `cloudflareSend`; tests pass a sink. A thrown error's
  *  text reaches the structured log (scrubbed and truncated), so a custom sender must not embed
- *  the message body or the magic link in what it throws. */
+ *  the message body or the magic link in what it throws.
+ */
 export type SendMagicLink = (env: AuthEnv, message: MagicLinkMessage) => Promise<void>;
 
 /** Build the confirmation email. The link is the only action; the copy stays plain. */