@glw907/cairn-cms 0.56.2 → 0.57.0

package/src/lib/media/naming.ts

@@ -0,0 +1,130 @@
+// cairn-cms: media naming. Media is content-addressed: the sha256 of the bytes names the object, so
+// the same bytes always land at the same key no matter the original filename. This module owns the
+// hash, the ingest slug transform, the R2 object key, and the public delivery path. The slug grammar
+// here matches the one parseMediaToken validates in ./reference.ts, so an ingested filename round
+// trips through the media: token unchanged.
+
+// slugifyFilename output always satisfies parseMediaToken's grammar (lowercase alphanumerics joined
+// by single internal hyphens, no leading or trailing hyphen), or is the literal `file`.
+
+/** Combining marks (Unicode block U+0300 to U+036F), left over after an NFD decompose, stripped to
+ *  fold an accented letter down to its ASCII base. Written as escapes because the literal marks are
+ *  invisible in source. */
+const COMBINING_MARKS = /[\u0300-\u036f]/g;
+
+/** Windows reserved device names. A bare match (case-insensitive) cannot survive as the slug, since
+ *  it names a device rather than a file on that platform. */
+const RESERVED = new Set([
+  'con',
+  'prn',
+  'aux',
+  'nul',
+  'com1',
+  'com2',
+  'com3',
+  'com4',
+  'com5',
+  'com6',
+  'com7',
+  'com8',
+  'com9',
+  'lpt1',
+  'lpt2',
+  'lpt3',
+  'lpt4',
+  'lpt5',
+  'lpt6',
+  'lpt7',
+  'lpt8',
+  'lpt9',
+]);
+
+/** The maximum slug length, applied before the reserved-name and empty fallbacks. */
+const MAX_SLUG = 80;
+
+/** A 16-character lowercase hex content-hash prefix, the bare-hash reference form. A slug that
+ *  matches this shape would collide with `media:<hash>`, so slugifyFilename screens it. */
+const HASH_RE = /^[0-9a-f]{16}$/;
+
+/** A short alphanumeric extension (no dot), the only shape r2Key accepts, for example `webp`. */
+const R2_EXT_RE = /^[a-z0-9]{1,5}$/;
+
+// A Uint8Array's generic buffer type no longer satisfies Web Crypto's BufferSource under strict lib
+// types, since the backing buffer may be a SharedArrayBuffer; slice the bytes into a plain
+// ArrayBuffer to hand digest. Mirrors the buf helper in ../github/signing.ts.
+function asArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+}
+
+/** The full lowercase hex sha256 of the bytes, via Web Crypto, hand-formatted to 64 hex chars. */
+export async function hashBytes(bytes: Uint8Array): Promise<string> {
+  const digest = await crypto.subtle.digest('SHA-256', asArrayBuffer(bytes));
+  return Array.from(new Uint8Array(digest))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/** The first 16 characters of a full hex digest, the content-hash prefix media references commit to. */
+export function shortHash(full: string): string {
+  return full.slice(0, 16);
+}
+
+/** The strict ingest transform from a raw filename to a slug that satisfies the media: slug grammar,
+ *  or the literal `file`. Drops the extension, lowercases, transliterates accents, collapses non-alphanumeric runs
+ *  to a single hyphen, trims, caps at 80 chars, screens Windows reserved names, and falls back to
+ *  `file` when nothing usable is left. */
+export function slugifyFilename(name: string): string {
+  const dot = name.lastIndexOf('.');
+  const stem = dot === -1 ? name : name.slice(0, dot);
+
+  let slug = stem
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(COMBINING_MARKS, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+  if (slug.length > MAX_SLUG) {
+    slug = slug.slice(0, MAX_SLUG).replace(/-+$/, '');
+  }
+
+  if (RESERVED.has(slug)) return `${slug}-file`;
+  if (slug === '') return 'file';
+  // A slug shaped like a bare 16-hex hash would collide with the `media:<hash>` reference form, so
+  // append -img (mirroring the reserved-name -file fallback) to keep the slug and bare-hash forms
+  // disjoint.
+  if (HASH_RE.test(slug)) return `${slug}-img`;
+  return slug;
+}
+
+/** The content-addressed R2 object key `media/<aa>/<shortHash>.<ext>`, fanned out on the first two
+ *  hex chars of the short hash. No leading slash: this is an object key, not a URL. `ext` is bare
+ *  (no dot), for example `webp`. */
+export function r2Key(shortHash: string, ext: string): string {
+  if (!HASH_RE.test(shortHash)) {
+    throw new Error(`r2Key: hash must be 16 lowercase hex chars, got "${shortHash}"`);
+  }
+  if (!R2_EXT_RE.test(ext)) {
+    throw new Error(`r2Key: ext must be 1 to 5 lowercase alphanumerics, got "${ext}"`);
+  }
+  return `media/${shortHash.slice(0, 2)}/${shortHash}.${ext}`;
+}
+
+/** The public delivery URL path, with a leading slash, under the delivery base (`publicBase`,
+ *  default `/media`). The `slug` form is human-readable (`<base>/<slug>.<shortHash>.<ext>`, or
+ *  `<base>/<shortHash>.<ext>` when the slug is null); the `opaque` form mirrors the R2 fan-out
+ *  (`<base>/<aa>/<shortHash>.<ext>`) and ignores the slug. */
+export function publicPath(
+  slug: string | null,
+  shortHash: string,
+  ext: string,
+  urlForm: 'slug' | 'opaque',
+  publicBase = '/media',
+): string {
+  if (urlForm === 'opaque') {
+    return `${publicBase}/${shortHash.slice(0, 2)}/${shortHash}.${ext}`;
+  }
+  return slug === null
+    ? `${publicBase}/${shortHash}.${ext}`
+    : `${publicBase}/${slug}.${shortHash}.${ext}`;
+}

package/src/lib/media/reconcile.ts

@@ -0,0 +1,79 @@
+// cairn-cms: the media reconcile read. Storage is put-first and idempotent, so an upload whose entry
+// is never saved leaves R2 bytes with no manifest row (an orphan), and a manifest row whose bytes
+// were never stored (or were collected) points at nothing. This module reads both directions: the
+// stored R2 keys under the media/ prefix versus the manifest's content-hash keys. It only reads and
+// reports; no path here deletes (destructive collection is deferred to Phase 4). The module is
+// engine-internal and on no public subpath, so the narrow bucket seam below is a local interface, not
+// a re-export of any @cloudflare/workers-types name.
+import type { MediaManifest } from './manifest.js';
+import { log } from '../log/index.js';
+
+/** A stored media object key parses to its short hash via `media/<aa>/<shortHash>.<ext>`. */
+const MEDIA_KEY_RE = /^media\/[0-9a-f]{2}\/([0-9a-f]{16})\.[a-z0-9]{1,5}$/;
+
+/** What a reconcile read found in either direction. `orphanedObjects` are stored R2 keys whose hash
+ *  has no manifest row; `missingObjects` are manifest hashes with no stored object. */
+export interface ReconcileResult {
+  /** Stored keys (full R2 keys) whose content hash is absent from the manifest. */
+  orphanedObjects: string[];
+  /** Manifest content-hash keys with no matching stored object. */
+  missingObjects: string[];
+}
+
+/** The pure core: compare the stored R2 keys against the manifest's content-hash keys and report
+ *  both orphan directions. A stored key that does not match the media-key grammar is ignored, since
+ *  it is not a content-addressed media object this reconcile owns. */
+export function reconcileMedia(storedKeys: string[], manifest: MediaManifest): ReconcileResult {
+  const manifestHashes = new Set(Object.keys(manifest));
+  const storedHashes = new Set<string>();
+  const orphanedObjects: string[] = [];
+  for (const key of storedKeys) {
+    const hash = MEDIA_KEY_RE.exec(key)?.[1];
+    if (hash === undefined) continue;
+    storedHashes.add(hash);
+    if (!manifestHashes.has(hash)) orphanedObjects.push(key);
+  }
+  const missingObjects: string[] = [];
+  for (const hash of manifestHashes) {
+    if (!storedHashes.has(hash)) missingObjects.push(hash);
+  }
+  return { orphanedObjects, missingObjects };
+}
+
+/** One page of an R2 list, the narrow subset the reconcile read consumes. */
+interface ReconcileListPage {
+  objects: { key: string }[];
+  truncated: boolean;
+  cursor?: string;
+}
+
+/** The R2 bucket surface the reconcile read needs: a single prefixed, paginated list. A local
+ *  structural interface so no @cloudflare/workers-types name is imported (the module is internal and
+ *  on no public subpath, but the narrow seam keeps the build self-contained either way). */
+export interface ReconcileBucket {
+  list(opts?: { prefix?: string; cursor?: string }): Promise<ReconcileListPage>;
+}
+
+/** The glue runner: list every stored key under the media/ prefix (paginating through R2's
+ *  cursor/truncated), reconcile against the manifest, log the count summary, and return the result.
+ *  The log record carries counts only, never bytes or a key list; the keys are content hashes and so
+ *  carry no PII, but the count summary is all an operator needs to size the orphan state. */
+export async function runReconcile(
+  bucket: ReconcileBucket,
+  manifest: MediaManifest,
+): Promise<ReconcileResult> {
+  const storedKeys: string[] = [];
+  let cursor: string | undefined;
+  do {
+    const page = await bucket.list({ prefix: 'media/', cursor });
+    for (const object of page.objects) storedKeys.push(object.key);
+    cursor = page.truncated ? page.cursor : undefined;
+  } while (cursor !== undefined);
+
+  const result = reconcileMedia(storedKeys, manifest);
+  log.info('media.orphan_reconcile', {
+    orphaned: result.orphanedObjects.length,
+    missing: result.missingObjects.length,
+  });
+  return result;
+}

package/src/lib/media/reference.ts

@@ -0,0 +1,40 @@
+// cairn-cms: the media: reference token. A media reference is the logical handle that content
+// commits to git, keyed to a content-hash prefix so the same bytes resolve no matter where they
+// are stored or what they are named. The canonical form is `media:<slug>.<hash>`: the hash is a
+// 16-character lowercase hex content-hash prefix that identifies the bytes, and the slug is a
+// cosmetic display name. The bare `media:<hash>` form (no slug) is also valid. This module owns
+// the grammar; it mirrors the cairn: link codec in ../content/links.ts.
+
+/** A resolved reference to a media asset by its content-hash prefix, with an optional display slug. */
+export interface MediaRef {
+  slug: string | null;
+  hash: string;
+}
+
+/** A 16-character lowercase hex content-hash prefix. */
+const HASH_RE = /^[0-9a-f]{16}$/;
+
+/** The slug grammar from the Task 2 slugify transform: lowercase alphanumerics joined by single
+ *  internal hyphens, with no leading or trailing hyphen and no dot (the dot is the slug/hash
+ *  separator). */
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** Parse a `media:<slug>.<hash>` href (or the bare `media:<hash>` form), or null for any other
+ *  href or a malformed token. Splits on the last dot, so a slug that illegally contains a dot fails
+ *  the slug grammar and returns null. */
+export function parseMediaToken(href: string): MediaRef | null {
+  if (!href.startsWith('media:')) return null;
+  const rest = href.slice('media:'.length);
+  const dot = rest.lastIndexOf('.');
+  if (dot === -1) return HASH_RE.test(rest) ? { slug: null, hash: rest } : null;
+  const slug = rest.slice(0, dot);
+  const hash = rest.slice(dot + 1);
+  if (!HASH_RE.test(hash) || !SLUG_RE.test(slug)) return null;
+  return { slug, hash };
+}
+
+/** Write the canonical media: token for a ref. The inverse of parseMediaToken, so a parse then
+ *  write round trip is stable: `media:<slug>.<hash>` when the slug is present, else `media:<hash>`. */
+export function mediaToken(ref: MediaRef): string {
+  return ref.slug === null ? `media:${ref.hash}` : `media:${ref.slug}.${ref.hash}`;
+}

package/src/lib/media/sniff.ts

@@ -0,0 +1,114 @@
+// cairn-cms: content-type sniffing and the engine-level upload deny-list. The upload action trusts no
+// client-declared type: it sniffs the real type from the leading bytes and screens the payload against a
+// deny-list a site cannot override. Both functions are pure and Worker-clean (a plain Uint8Array, no
+// Node Buffer and no stream), so they run unchanged on Cloudflare Workers and under vitest.
+//
+// The sniff is necessary but not sufficient. A polyglot can carry a valid image magic and an HTML tail,
+// and this byte check sees only the magic. The delivery route's response headers (X-Content-Type-Options:
+// nosniff, Content-Disposition: inline, a restrictive Content-Security-Policy) are the real XSS control
+// for the served bytes; sniffing here is the ingest gate, not the served-bytes defense.
+
+/** The leading ASCII whitespace bytes skipped before the deny-list's first-byte-is-`<` check:
+ *  tab (0x09), newline (0x0A), carriage return (0x0D), and space (0x20). */
+const WHITESPACE = new Set([0x09, 0x0a, 0x0d, 0x20]);
+
+/** The single byte `<` (0x3C). A payload whose first non-whitespace byte is `<` is markup (SVG, HTML,
+ *  XML) and is denied regardless of its declared type or any site `allowedTypes`. */
+const LT = 0x3c;
+
+/** Declared content types denied at the engine level, independent of any site `allowedTypes`. SVG and
+ *  the markup types carry active content (script, foreignObject), so they never ingest as media. */
+const DENIED_TYPES = new Set(['image/svg+xml', 'image/svg', 'text/html', 'application/xml']);
+
+/** The ISO-BMFF major-brand codes (at bytes 8..11 of an `ftyp` box) that mean an AVIF image. */
+const AVIF_BRANDS = new Set(['avif', 'avis']);
+
+/** The ISO-BMFF major-brand codes that mean a HEIF/HEIC image. */
+const HEIC_BRANDS = new Set(['heic', 'heix', 'heif', 'hevc', 'hevx', 'mif1', 'msf1']);
+
+/** True when every byte of `magic` matches `bytes` starting at `offset`. False if `bytes` is too
+ *  short to hold the whole magic. */
+function matches(bytes: Uint8Array, offset: number, magic: number[]): boolean {
+  if (bytes.length < offset + magic.length) return false;
+  for (let i = 0; i < magic.length; i++) {
+    if (bytes[offset + i] !== magic[i]) return false;
+  }
+  return true;
+}
+
+/** The four ASCII characters at bytes `offset..offset+3`, or null when the input is too short. Used to
+ *  read an ISO-BMFF brand code as a string. */
+function ascii4(bytes: Uint8Array, offset: number): string | null {
+  if (bytes.length < offset + 4) return null;
+  return String.fromCharCode(bytes[offset], bytes[offset + 1], bytes[offset + 2], bytes[offset + 3]);
+}
+
+/**
+ * Detect the MIME type of an image from its leading magic bytes. Reads only the first ~32 bytes and
+ * returns the recognized type, or null for an unrecognized magic or an input too short for a given
+ * check. This is the server's source of truth for an upload's type; the client-declared type is
+ * advisory. Recognizes JPEG, PNG, GIF, WebP, and the AVIF/HEIC ISO-BMFF brands.
+ */
+export function sniffMediaType(bytes: Uint8Array): string | null {
+  // JPEG: starts FF D8 FF.
+  if (matches(bytes, 0, [0xff, 0xd8, 0xff])) return 'image/jpeg';
+
+  // PNG: the 8-byte signature 89 50 4E 47 0D 0A 1A 0A; the leading 89 50 4E 47 ('.PNG') is enough.
+  if (matches(bytes, 0, [0x89, 0x50, 0x4e, 0x47])) return 'image/png';
+
+  // GIF: 'GIF8' (the 87a and 89a versions share this prefix).
+  if (matches(bytes, 0, [0x47, 0x49, 0x46, 0x38])) return 'image/gif';
+
+  // WebP: a RIFF container ('RIFF' at 0..3) whose form type is 'WEBP' at 8..11.
+  if (matches(bytes, 0, [0x52, 0x49, 0x46, 0x46]) && matches(bytes, 8, [0x57, 0x45, 0x42, 0x50])) {
+    return 'image/webp';
+  }
+
+  // AVIF and HEIC are ISO base media format files: an 'ftyp' box tag at bytes 4..7, then the 4-byte
+  // major brand at bytes 8..11. A truncated box (no brand bytes) or an unknown brand returns null.
+  if (matches(bytes, 4, [0x66, 0x74, 0x79, 0x70])) {
+    const brand = ascii4(bytes, 8);
+    if (brand !== null) {
+      if (AVIF_BRANDS.has(brand)) return 'image/avif';
+      if (HEIC_BRANDS.has(brand)) return 'image/heic';
+    }
+  }
+
+  return null;
+}
+
+/** The bare file extension (no dot) for each sniffed media type the upload path stores. The ext is
+ *  derived from the server-sniffed type, never the client filename, so the stored key and the
+ *  delivery extension allow-list always agree. An unmappable type returns null (the upload 415s). */
+const EXT_BY_TYPE: Record<string, string> = {
+  'image/jpeg': 'jpg',
+  'image/png': 'png',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+  'image/avif': 'avif',
+};
+
+/** The storage extension for a sniffed media type, or null for a type the upload path does not store
+ *  (HEIC, an unknown type). Driven by the sniffed type, so the key's ext is server-owned. */
+export function extForMediaType(type: string): string | null {
+  return EXT_BY_TYPE[type] ?? null;
+}
+
+/**
+ * The engine-level upload deny predicate. Returns true (reject) when the upload is markup a site can
+ * never override: a declared type of image/svg+xml, image/svg, text/html, or application/xml, OR a
+ * payload whose first non-whitespace byte is `<` (an 0x3C after skipping leading ASCII whitespace).
+ * This runs ahead of and independent of any site `allowedTypes`, since SVG and HTML carry active
+ * content. The byte check catches a markup payload sent under a permitted declared type.
+ */
+export function isDeniedUpload(bytes: Uint8Array, declaredType?: string): boolean {
+  if (declaredType !== undefined && DENIED_TYPES.has(declaredType.toLowerCase())) return true;
+
+  for (let i = 0; i < bytes.length; i++) {
+    if (WHITESPACE.has(bytes[i])) continue;
+    return bytes[i] === LT;
+  }
+
+  // An empty or all-whitespace payload has no opening byte to deny here; the type and size gates own it.
+  return false;
+}

package/src/lib/media/store.ts

@@ -0,0 +1,57 @@
+// cairn-cms: the media object store, a thin wrapper over the per-site R2 bucket binding. The media
+// pipeline codes against the narrow MediaStore seam rather than the full R2Bucket API, so the four
+// operations it needs (store, probe, read, remove a content-addressed object) are typed and testable
+// against an in-memory double, and a later storage-backend swap touches this one factory. The bytes
+// are content-addressed, so a put under an existing key is a harmless rewrite of identical bytes.
+import type {
+  R2Bucket,
+  R2Conditional,
+  R2HTTPMetadata,
+  R2Object,
+  R2ObjectBody,
+  R2Range,
+} from '@cloudflare/workers-types';
+
+/** The narrow R2 surface the media pipeline uses. The engine depends on this, not on R2Bucket, so the
+ *  multipart, list, and conditional-read surface R2 also carries never leaks into the media code. */
+export interface MediaStore {
+  /** Store bytes under a content-addressed key, with the response HTTP metadata (the content type)
+   *  and optional custom metadata (the upload stores the full sha256 here, so a short-hash collision
+   *  is detectable on a later dedup probe). */
+  put(
+    key: string,
+    bytes: ArrayBuffer | Uint8Array,
+    httpMetadata?: R2HTTPMetadata,
+    customMetadata?: Record<string, string>,
+  ): Promise<void>;
+  /** The object's metadata, or null when no object lives at the key (the dedup probe). */
+  head(key: string): Promise<R2Object | null>;
+  /** The object body for streaming to a delivery response, or null when the key is absent. The
+   *  delivery route passes `onlyIf` and `range` through for conditional and partial reads: an
+   *  `onlyIf` etag match returns a body-less R2Object (the 304 shape), so the return widens to
+   *  `R2Object` alongside `R2ObjectBody`. */
+  get(
+    key: string,
+    opts?: { range?: R2Range; onlyIf?: R2Conditional },
+  ): Promise<R2ObjectBody | R2Object | null>;
+  /** Remove the object at the key. A delete of an absent key is a no-op, the R2 contract. */
+  delete(key: string): Promise<void>;
+}
+
+/** Wrap an R2 bucket binding as a MediaStore. Each method delegates to the binding; put folds the
+ *  HTTP and custom metadata into R2's options shape and drops the returned R2Object the pipeline does
+ *  not read. */
+export function r2Store(bucket: R2Bucket): MediaStore {
+  return {
+    async put(key, bytes, httpMetadata, customMetadata) {
+      const options =
+        httpMetadata || customMetadata
+          ? { ...(httpMetadata ? { httpMetadata } : {}), ...(customMetadata ? { customMetadata } : {}) }
+          : undefined;
+      await bucket.put(key, bytes, options);
+    },
+    head: (key) => bucket.head(key),
+    get: (key, opts) => bucket.get(key, opts),
+    delete: (key) => bucket.delete(key),
+  };
+}

package/src/lib/media/transform-url.ts

@@ -0,0 +1,58 @@
+// cairn-cms: the Cloudflare Images transform URL. A delivery path names the original bytes; an
+// on-demand variant is that path prefixed with `/cdn-cgi/image/<options>/`, where the options are a
+// comma-joined list of resize and format directives Cloudflare reads at the edge. This module owns
+// the option encoding and the stable option order, so the same spec always builds the same URL and
+// a CDN cache keys on it cleanly. The delivery path is appended unaltered, since it already carries
+// its own leading slash.
+
+/** A single image variant: the resize and format directives Cloudflare Images applies to the
+ *  original bytes. Every field is optional. width, height, quality, and fit are emitted only when
+ *  set; format and gravity always appear, defaulting to auto. */
+export interface VariantSpec {
+  /** Target width in pixels. */
+  width?: number;
+  /** Target height in pixels. */
+  height?: number;
+  /** Output quality, 1 to 100. */
+  quality?: number;
+  /** How the image fits the target box. */
+  fit?: 'scale-down' | 'contain' | 'cover' | 'crop' | 'pad';
+  /** Crop focus, `auto` or `face` or a coordinate string. */
+  gravity?: 'auto' | 'face' | string;
+  /** Output format, `auto` to let Cloudflare negotiate, or a forced codec. */
+  format?: 'auto' | 'webp' | 'avif' | string;
+}
+
+/** Build the on-demand Cloudflare Images transform URL for a delivery path. The options are
+ *  comma-joined in the stable order width, height, quality, fit, format, gravity, with width through
+ *  fit emitted only when the spec sets them and format and gravity always present (defaulting to
+ *  auto). The publicPath is appended unaltered, so the result is `/cdn-cgi/image/<options><publicPath>`. */
+export function variantUrl(publicPath: string, spec: VariantSpec): string {
+  const options: string[] = [];
+  if (spec.width !== undefined) options.push(`width=${spec.width}`);
+  if (spec.height !== undefined) options.push(`height=${spec.height}`);
+  if (spec.quality !== undefined) options.push(`quality=${spec.quality}`);
+  if (spec.fit !== undefined) options.push(`fit=${spec.fit}`);
+  options.push(`format=${spec.format ?? 'auto'}`);
+  options.push(`gravity=${spec.gravity ?? 'auto'}`);
+  // The source must be its own path segment after the options, so it needs a leading slash;
+  // Cloudflare reads a slashless join as a malformed options list. publicPath carries one, but this
+  // guards a caller that passes a relative path from fusing the options and the source.
+  const source = publicPath.startsWith('/') ? publicPath : `/${publicPath}`;
+  return `/cdn-cgi/image/${options.join(',')}${source}`;
+}
+
+/** Build a variant URL from a named preset. Looks up presetName in variants and builds its spec with
+ *  variantUrl. Throws a cairn:-prefixed error naming the unknown preset when the name is absent, so a
+ *  typo in a preset name fails loudly rather than silently rendering an unsized image. */
+export function presetUrl(
+  publicPath: string,
+  presetName: string,
+  variants: Record<string, VariantSpec>,
+): string {
+  const spec = variants[presetName];
+  if (spec === undefined) {
+    throw new Error(`cairn: unknown image variant preset "${presetName}"`);
+  }
+  return variantUrl(publicPath, spec);
+}

package/src/lib/media/usage.ts

@@ -0,0 +1,152 @@
+// cairn-cms: the cross-branch media usage index, the where-used core of the admin Media Library.
+// It answers "which entries reference this asset" for every committed asset, keyed by the content
+// hash (the immutable truth, so a renamed slug never splits a row). The map unions two sources:
+// the published corpus on main and every open cairn/* edit branch, so an asset that is referenced
+// only in an unpublished draft still shows as in use and is not mistaken for an orphan.
+//
+// The main arm reads the content manifest's per-entry mediaRefs (the field manifestEntryFromFile
+// records) and builds the reverse map; it never crawls the files, since the manifest already
+// carries the refs. The branch arm cannot use a manifest (the content manifest is never committed
+// to a branch), so it reconstructs each edited entry's path from the branch name, reads that one
+// file, and runs the extractor directly.
+//
+// A site's published use and an open-branch edit of the SAME entry are distinct origins (decision
+// 4): both rows are kept, and the consumer groups by origin. Within one entry the extractor dedupes
+// by hash, so an asset used twice in one entry is a single row.
+//
+// CAVEAT (carry it to the screen): a reference hidden inside a raw-HTML block (an <img> the markdown
+// parser sees as opaque HTML, not an image node) is undetectable here. The Library's verdict wording
+// is therefore "found in N entries" / "no references found", never a bare "unused": absence of a row
+// means no reference was found, not a proof that none exists.
+import type { ConceptDescriptor } from '../content/types.js';
+import type { RepoRef } from '../github/types.js';
+import type { Manifest } from '../content/manifest.js';
+import { listBranches } from '../github/branches.js';
+import { readRaw } from '../github/repo.js';
+import { PENDING_PREFIX, parsePendingBranch } from '../content/pending.js';
+import { findConcept } from '../content/concepts.js';
+import { isValidId, filenameFromId } from '../content/ids.js';
+import { parseMarkdown } from '../content/frontmatter.js';
+import { extractMediaRefs } from '../content/media-refs.js';
+
+/** Where a reference lives: the published corpus on main, or a named open edit branch. */
+export type UsageOrigin = { kind: 'published' } | { kind: 'branch'; branch: string };
+
+/** One entry that references an asset, in a shape the screen links and groups by. */
+export interface UsageEntry {
+  /** The concept id, e.g. "posts". */
+  concept: string;
+  /** The entry id (its filename stem). */
+  id: string;
+  /** The entry title for display, from the manifest (published) or frontmatter (branch). */
+  title: string;
+  /** The public permalink, present for a published entry (carried from the manifest). */
+  permalink?: string;
+  /** Published vs the cairn/* branch the edit lives on. */
+  origin: UsageOrigin;
+}
+
+/** Content hash to the distinct entries that reference it. A hash with no row is "no references
+ *  found" (see the raw-HTML caveat above), never a proven orphan. */
+export type UsageIndex = Map<string, UsageEntry[]>;
+
+/** Build options. `branches` lets a caller that already listed the open cairn/* branches pass them
+ *  in so the index does not list them a second time (the load path lists once for the media-union).
+ *  `strict` flips the per-branch read from degrade-and-skip to fail-closed: a delete gate must not
+ *  treat a transient branch-read failure as an absent reference, so it rethrows instead. */
+export interface BuildUsageOptions {
+  /** The open cairn/* branch names, already listed. When present the index skips its own listing. */
+  branches?: string[];
+  /** When true a branch read that throws rejects the whole build, so the caller can fail closed. */
+  strict?: boolean;
+}
+
+/** Append a row under its hash, creating the bucket on first use. */
+function push(index: UsageIndex, hash: string, entry: UsageEntry): void {
+  const rows = index.get(hash);
+  if (rows) rows.push(entry);
+  else index.set(hash, [entry]);
+}
+
+/**
+ * Build the hash-keyed usage index over main (from the manifest's per-entry mediaRefs) plus every
+ * open cairn/* branch (parsed from its edited markdown).
+ *
+ * By default a single branch read that throws degrades that one branch and is skipped, the way the
+ * admin loaders degrade a failed read, rather than sinking the whole screen. That tolerance is right
+ * for the Library DISPLAY, but wrong for the delete gate: a transient branch-read failure would make
+ * a still-referenced asset look orphaned. Pass `strict: true` (the delete path) to rethrow a branch
+ * failure so the caller fails closed. Pass `branches` to reuse a branch list the caller already has
+ * (the load path lists once for the media-union) rather than listing them a second time.
+ */
+export async function buildUsageIndex(
+  repo: RepoRef,
+  token: string,
+  concepts: ConceptDescriptor[],
+  manifest: Manifest,
+  opts: BuildUsageOptions = {},
+): Promise<UsageIndex> {
+  const index: UsageIndex = new Map();
+
+  // The main arm: the manifest already carries each entry's mediaRefs, so this is a pure reverse
+  // map with no per-file read.
+  for (const entry of manifest.entries) {
+    for (const hash of entry.mediaRefs ?? []) {
+      push(index, hash, {
+        concept: entry.concept,
+        id: entry.id,
+        title: entry.title,
+        permalink: entry.permalink,
+        origin: { kind: 'published' },
+      });
+    }
+  }
+
+  // The branch arm: read each open cairn/* branch's one edited file. The path is derivable from the
+  // branch name, so no tree-listing is needed. The branch list is reused when the caller passes it.
+  const names = opts.branches ?? (await listBranches(repo, PENDING_PREFIX, token));
+  // Read the branches in parallel rather than one at a time, so the latency floor is one round trip
+  // instead of N. workerd self-throttles to 6 simultaneous outbound connections, so this batch and
+  // the load path's media-union batch each stay under the limit; do NOT merge the two into one
+  // wider Promise.all, since the combined fan-out would queue behind that throttle.
+  const perBranch = await Promise.all(
+    names.map(async (name): Promise<{ hash: string; entry: UsageEntry }[]> => {
+      // Resolve the branch name to a configured entry with the same guard the branch tooling uses: a
+      // malformed name, an id that fails the slug rule (entry paths are built from it, so this is the
+      // path confinement), or a concept this site does not configure is skipped, no read attempted.
+      const ref = parsePendingBranch(name);
+      if (!ref || !isValidId(ref.id)) return [];
+      const concept = findConcept(concepts, ref.concept);
+      if (!concept) return [];
+
+      const path = `${concept.dir}/${filenameFromId(ref.id)}`;
+      try {
+        const raw = await readRaw({ ...repo, branch: name }, path, token);
+        if (raw === null) return []; // The file is absent on the branch: nothing to extract.
+        const { frontmatter, body } = parseMarkdown(raw);
+        const fmTitle = frontmatter.title;
+        const title = typeof fmTitle === 'string' && fmTitle.trim() ? fmTitle : ref.id;
+        const rows: { hash: string; entry: UsageEntry }[] = [];
+        for (const hash of extractMediaRefs(frontmatter, body, concept.fields)) {
+          rows.push({
+            hash,
+            entry: { concept: concept.id, id: ref.id, title, origin: { kind: 'branch', branch: name } },
+          });
+        }
+        return rows;
+      } catch (err) {
+        // In strict mode a branch failure fails the whole build so the delete gate can fail closed;
+        // otherwise degrade this one branch rather than sinking the screen.
+        if (opts.strict) throw err;
+        return [];
+      }
+    }),
+  );
+
+  // Fold the per-branch rows back in, preserving the branch order so the index reads stably.
+  for (const rows of perBranch) {
+    for (const { hash, entry } of rows) push(index, hash, entry);
+  }
+
+  return index;
+}