@glw907/cairn-cms 0.58.0 → 0.60.0

package/dist/components/tidy-validate.js

@@ -0,0 +1,174 @@
+// The tidy output validation: the safety backstop that proves a tidy result is a proofread and not
+// a restructure (spec 2.6) or a successful prompt injection (spec 2.3.3). A pure module taking the
+// captured original and the model's corrected string and returning either the validated change set
+// (the Task 12 diff) or a typed rejection reason. A rejected result is discarded by the caller with
+// an honest message and the document is left untouched; nothing here mutates the buffer.
+//
+// Four of the five checks are EXACT and are the real structural backstop: the directive structure,
+// the heading count and levels, the fenced-code-block count, the byte-for-byte frontmatter, the
+// media-hash multiset, and every code span and fenced block. The fifth, the divergence bound, is
+// the only fuzzy one, and it is a rewrite/injection backstop only, never a voice safeguard. The
+// config-driven prompt is what protects voice.
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import { visit } from 'unist-util-visit';
+import { fenceScan, frontmatterSpan } from './markdown-directives.js';
+import { parseMediaToken } from '../media/reference.js';
+import { diffTokens, diffChanges } from './tidy-diff.js';
+/** The honest author-facing message a rejection maps to. The same message for every reason, by
+ *  design: an author does not need the validator's internal taxonomy, only that the result was
+ *  discarded and their text is safe. */
+export const TIDY_REJECTION_MESSAGE = 'Tidy returned a result that changed more than the wording, so it was discarded. Your text is unchanged.';
+// The divergence bound. The floor allows a fixed number of changed tokens regardless of fraction so
+// a legitimate heavy proofread of a SHORT input is not penalized: a short paragraph with a typo in
+// nearly every word is a real proofread, not a rewrite. The fraction catches a wholesale rewrite of
+// a LONG input, where a large absolute count is past any honest copy-edit. A result is rejected only
+// when it exceeds BOTH the floor and the fraction, so a short input rides the floor and a long input
+// rides the fraction. The values are deliberate: 60 tokens of change covers a dense proofread of a
+// few short paragraphs, and 0.5 of the total tokens marks the point where more than half the text
+// changed, which no proofread does but a rewrite or a successful injection always does.
+const DIVERGENCE_TOKEN_FLOOR = 60;
+const DIVERGENCE_FRACTION = 0.5;
+// Every `media:` token anywhere in the text, hash and slug forms alike. The validator scans the raw
+// text rather than going through extractMediaRefs for two reasons. First, a true MULTISET is the
+// invariant a backstop wants: extractMediaRefs dedups by hash, so a doubled token collapsing to one
+// would read as equal, and the validator must catch a dropped duplicate. Second, the raw scan covers
+// the whole text including frontmatter without threading the concept's FrontmatterField[] to the call
+// site, which the validator otherwise has no reason to know. A token mangled inside a code fence is
+// caught here too, redundantly with the code check, which is the right posture for a backstop.
+const MEDIA_TOKEN = /media:[A-Za-z0-9.-]+/g;
+/** The sorted multiset of valid media hashes in the text. Each `media:` occurrence is parsed; a
+ *  malformed token (a broken hash, an illegal slug) parses to null and is dropped, so a tidy that
+ *  CORRUPTED a hash drops it from the multiset and the comparison fails. Sorted so two multisets
+ *  compare by value, order-independent. */
+function mediaHashes(text) {
+    const hashes = [];
+    for (const m of text.matchAll(MEDIA_TOKEN)) {
+        const ref = parseMediaToken(m[0]);
+        if (ref)
+            hashes.push(ref.hash);
+    }
+    return hashes.sort();
+}
+/** The directive structure signature: each opener or closer in document order, paired with the depth
+ *  the fence scan assigned it. Two texts share a directive structure when these signatures are equal,
+ *  so an added, removed, or relevelled container fails the comparison. A fence-shaped line inside a
+ *  code block is already disowned by the scan (its role is null), so a documented `:::` example does
+ *  not enter the signature. */
+function directiveSignature(text) {
+    const { depths, roles } = fenceScan(text.split('\n'));
+    const parts = [];
+    for (let i = 0; i < roles.length; i++) {
+        if (roles[i] !== null)
+            parts.push(`${roles[i]}@${depths[i]}`);
+    }
+    return parts.join(',');
+}
+/** The heading signature: every ATX heading's level in document order. Parsed as mdast so a `#`
+ *  inside a code block or an escaped one is never counted, and the level is the parser's own depth.
+ *  Two texts share a heading structure when these are equal, so an added, removed, or relevelled
+ *  heading fails the comparison. */
+function headingSignature(text) {
+    const tree = unified().use(remarkParse).use(remarkGfm).parse(text);
+    const levels = [];
+    visit(tree, 'heading', (node) => {
+        if (typeof node.depth === 'number')
+            levels.push(node.depth);
+    });
+    return levels.join(',');
+}
+/** Every code span and fenced or indented code block in the text, as a sorted multiset of values.
+ *  Parsed as mdast so the comparison sees exactly what the parser treats as code, the same authority
+ *  the media body scan uses. Sorted so the comparison is order-independent: the divergence and
+ *  structure checks own ordering, this check owns the contents. A `code` node is a block, an
+ *  `inlineCode` node is a span. */
+function codeContents(text) {
+    const tree = unified().use(remarkParse).use(remarkGfm).parse(text);
+    const values = [];
+    visit(tree, (node) => {
+        if ((node.type === 'code' || node.type === 'inlineCode') && typeof node.value === 'string') {
+            values.push(`${node.type}:${node.value}`);
+        }
+    });
+    return values.sort();
+}
+/** True when two string multisets are equal: same length and same sorted contents. */
+function multisetEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+// The changed token amount: the count of tokens the diff marked inserted or deleted, against the
+// total tokens in the original. An equal run contributes nothing; an inserted or deleted run counts
+// its own tokens. This is the rewrite measure, deliberately coarse, since the structure/token/code
+// checks are the exact backstop and this only catches a wholesale rewrite that slipped past them.
+function divergence(original, corrected) {
+    const runs = diffTokens(original, corrected);
+    // Count tokens by splitting each run's text on the same word/non-word boundary the diff uses; a
+    // run's token count is its number of word-or-nonword matches. The original's total is the equal
+    // plus deleted token count.
+    const countTokens = (s) => (s.match(/[A-Za-z0-9_]+(?:['’][A-Za-z0-9_]+)*|[^A-Za-z0-9_]+/g) ?? []).length;
+    let changed = 0;
+    let total = 0;
+    for (const run of runs) {
+        const tokens = countTokens(run.text);
+        if (run.kind === 'inserted' || run.kind === 'deleted')
+            changed += tokens;
+        if (run.kind === 'equal' || run.kind === 'deleted')
+            total += tokens;
+    }
+    return { changed, total };
+}
+/**
+ * Validate a tidy result against the captured original. Runs the exact structural checks first (a
+ * restructure or a token or code edit is a hard reject regardless of how little else changed), then
+ * the length-aware divergence bound. On success returns the Task 12 change set for the review
+ * surface; on failure returns the typed reason and the one honest message.
+ *
+ * The checks, in order: the directive opener/closer sequence and depths, the ATX heading count and
+ * levels, the fenced-code-block count (folded into the code-contents multiset), the byte-for-byte
+ * frontmatter via the shared frontmatterSpan helper, the media-hash multiset, the code-span and
+ * code-block contents, and finally the divergence bound. A pure function: it reads the two strings
+ * and nothing else, and it never mutates the buffer.
+ */
+export function validateTidy(original, corrected) {
+    // Directive structure: the opener/closer sequence and depths must match exactly.
+    if (directiveSignature(original) !== directiveSignature(corrected)) {
+        return { ok: false, reason: 'structure', message: TIDY_REJECTION_MESSAGE };
+    }
+    // Headings: the same ATX headings at the same levels, in order.
+    if (headingSignature(original) !== headingSignature(corrected)) {
+        return { ok: false, reason: 'structure', message: TIDY_REJECTION_MESSAGE };
+    }
+    // Frontmatter: byte-for-byte equal, via the same helper the spellcheck skip uses. A null span
+    // (no frontmatter) on both sides slices to the empty string on both, so a body-only document
+    // passes; a span on one side and not the other diverges.
+    const fmOriginal = frontmatterSpan(original);
+    const fmCorrected = frontmatterSpan(corrected);
+    const fmTextOriginal = fmOriginal ? original.slice(fmOriginal.from, fmOriginal.to) : '';
+    const fmTextCorrected = fmCorrected ? corrected.slice(fmCorrected.from, fmCorrected.to) : '';
+    if (fmTextOriginal !== fmTextCorrected) {
+        return { ok: false, reason: 'frontmatter', message: TIDY_REJECTION_MESSAGE };
+    }
+    // Media: the exact same multiset of hashes across the whole text.
+    if (!multisetEqual(mediaHashes(original), mediaHashes(corrected))) {
+        return { ok: false, reason: 'media', message: TIDY_REJECTION_MESSAGE };
+    }
+    // Code: every code span and fenced or indented block identical. The block count is folded in
+    // here: a multiset of block-and-span values that differs in count or contents fails.
+    if (!multisetEqual(codeContents(original), codeContents(corrected))) {
+        return { ok: false, reason: 'code', message: TIDY_REJECTION_MESSAGE };
+    }
+    // Divergence: rejected only when the changed amount exceeds BOTH the absolute floor and the
+    // fraction of the total. A short input rides the floor; a long input rides the fraction.
+    const { changed, total } = divergence(original, corrected);
+    if (changed > DIVERGENCE_TOKEN_FLOOR && changed > total * DIVERGENCE_FRACTION) {
+        return { ok: false, reason: 'divergence', message: TIDY_REJECTION_MESSAGE };
+    }
+    return { ok: true, changes: diffChanges(original, corrected) };
+}

package/dist/content/compose.d.ts

@@ -1,5 +1,5 @@
 import type { CairnAdapter, CairnExtension, CairnRuntime } from './types.js';
-import type { SiteConfig } from '../nav/site-config.js';
+import { type SiteConfig } from '../nav/site-config.js';
 /** The input to {@link composeRuntime}. `siteConfig` is required so the per-concept URL policy is
  *  always derived from one source and can never be silently dropped. `extensions` fold in after the
  *  adapter's concepts. */

package/dist/content/compose.js

@@ -1,5 +1,6 @@
 import { resolveConcepts } from './concepts.js';
 import { normalizeAssets } from '../media/config.js';
+import { dictionaryFileForDialect } from '../nav/site-config.js';
 /**
  * Fold an adapter and any extensions into the composed runtime (seam 2). The per-concept URL policy
  * is derived from the site config, the same source the delivery path uses, so the runtime and
@@ -36,6 +37,16 @@ export function composeRuntime({ adapter, siteConfig, extensions = [] }) {
         assets: adapter.assets,
         resolvedAssets: normalizeAssets(adapter.assets),
         mediaManifestPath: adapter.mediaManifestPath ?? 'src/content/.cairn/media.json',
+        // The personal dictionary sits beside the manifests under the same `.cairn/` content root, so the
+        // spec's `content/.cairn/dictionary.txt` resolves the same configurable way the manifest paths do.
+        dictionaryPath: adapter.dictionaryPath ?? 'src/content/.cairn/dictionary.txt',
+        // The spellcheck dictionary is resolved once here from the site config's dialect (default US),
+        // so the runtime and the editor never re-derive it. The site config is the one home for the
+        // dialect; the editor resolves this filename to a real asset URL on the main thread.
+        spellcheckDictionary: dictionaryFileForDialect(siteConfig.spellcheck?.dialect),
+        // The tidy block passes through from the site config; the tidy action reads enabled/model at call
+        // time and builds its prompt from conventions. Absent means tidy is off.
+        tidy: siteConfig.tidy,
         adminPanels,
         fieldTypes,
     };

package/dist/content/site-dictionary.d.ts

@@ -0,0 +1,31 @@
+/** True when a word is a single valid dictionary line (no whitespace, no control characters, non-empty
+ *  and within the length bound). A leading "#" is rejected: parseDictionary re-reads such a line as a
+ *  comment, so committing it would silently drop the word on the next read. The action uses this to
+ *  reject untrusted input before the merge, so a newline or a control byte can never inject an extra
+ *  line into the committed file. */
+export declare function isValidDictionaryWord(word: string, maxLength?: number): boolean;
+/**
+ * Parse the committed dictionary file text into its word list. Comment lines (a `#` after optional
+ * leading whitespace) and blank lines are dropped; every other line is trimmed and kept. A null or
+ * empty file yields an empty list. The result preserves the file's order and is not deduplicated or
+ * sorted here, so a caller can see exactly what the file held; `mergeDictionaryWords` is the path that
+ * normalizes to the sorted, deduplicated set.
+ */
+export declare function parseDictionary(text: string | null): string[];
+/**
+ * Merge `additions` into the `existing` word list, returning the canonical sorted, deduplicated set.
+ * The merge is case-insensitive (a duplicate add of an existing word, in any case, collapses) and
+ * order-independent: the inputs are unioned by lowercased key and sorted, so re-merging the same
+ * additions at a moved head produces the same set. The first-seen casing of each word wins, so an
+ * existing "Cairn" is kept over a later "cairn". Invalid additions (whitespace, control characters,
+ * empty) are skipped here as a backstop; the action validates before this is reached.
+ */
+export declare function mergeDictionaryWords(existing: readonly string[], additions: readonly string[]): string[];
+/**
+ * Serialize a word list to the canonical committed file text: the header comment, then one word per
+ * line sorted case-insensitively, with a trailing newline. The input is run through the same dedup
+ * and sort as the merge, so serializing an unsorted or duplicate-bearing list still yields the
+ * canonical form. An empty word list serializes to just the header (so the file stays a valid,
+ * recognizable dictionary rather than vanishing).
+ */
+export declare function serializeDictionary(words: readonly string[]): string;

package/dist/content/site-dictionary.js

@@ -0,0 +1,82 @@
+// cairn-cms: the git-committed per-site personal dictionary (spec 1.6). One word per line,
+// sorted, with comment lines (starting with #) and blank lines tolerated on read. This module is
+// pure: it parses the committed file text, inserts words in sorted order, and serializes the
+// canonical form. The insert is order-independent, so the action's commit-and-retry can re-merge
+// the pending additions at a new head and reach the same sorted set regardless of insertion order.
+//
+// The canonical serialization keeps a single leading header comment and one sorted word per line.
+// An inbound file's other comment lines are dropped on serialize (the header is regenerated), so the
+// committed file stays a clean, diffable, sorted word list; a maintainer who wants a richer comment
+// edits it in git, and the next add through here normalizes it back to the header.
+/** The header comment the canonical serialization writes above the sorted words. */
+const HEADER = '# cairn personal dictionary: one word per line, sorted, kept in git.';
+// A dictionary word: a single line carrying no whitespace and no ASCII control characters, so it can
+// never inject an extra line into the committed file. Hyphens and apostrophes are allowed, since real
+// words carry them ("well-known", "O'Brien"); a non-ASCII surname or place name validates too, since
+// the test is for whitespace and control bytes rather than an allow-list of letters. The action runs
+// inbound words through this before a merge.
+const WORD_RE = /^[^\s\p{Cc}]+$/u;
+/** True when a word is a single valid dictionary line (no whitespace, no control characters, non-empty
+ *  and within the length bound). A leading "#" is rejected: parseDictionary re-reads such a line as a
+ *  comment, so committing it would silently drop the word on the next read. The action uses this to
+ *  reject untrusted input before the merge, so a newline or a control byte can never inject an extra
+ *  line into the committed file. */
+export function isValidDictionaryWord(word, maxLength = 64) {
+    if (word.startsWith('#'))
+        return false;
+    return word.length > 0 && word.length <= maxLength && WORD_RE.test(word);
+}
+/**
+ * Parse the committed dictionary file text into its word list. Comment lines (a `#` after optional
+ * leading whitespace) and blank lines are dropped; every other line is trimmed and kept. A null or
+ * empty file yields an empty list. The result preserves the file's order and is not deduplicated or
+ * sorted here, so a caller can see exactly what the file held; `mergeDictionaryWords` is the path that
+ * normalizes to the sorted, deduplicated set.
+ */
+export function parseDictionary(text) {
+    if (!text)
+        return [];
+    const words = [];
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '' || trimmed.startsWith('#'))
+            continue;
+        words.push(trimmed);
+    }
+    return words;
+}
+/** Case-insensitive, locale-stable comparator for the canonical sort. Words are compared lowercased
+ *  so "Cairn" and "cairn" collapse to one entry, the same case-folding the Worker's merged set uses. */
+function byWord(a, b) {
+    return a.toLowerCase().localeCompare(b.toLowerCase());
+}
+/**
+ * Merge `additions` into the `existing` word list, returning the canonical sorted, deduplicated set.
+ * The merge is case-insensitive (a duplicate add of an existing word, in any case, collapses) and
+ * order-independent: the inputs are unioned by lowercased key and sorted, so re-merging the same
+ * additions at a moved head produces the same set. The first-seen casing of each word wins, so an
+ * existing "Cairn" is kept over a later "cairn". Invalid additions (whitespace, control characters,
+ * empty) are skipped here as a backstop; the action validates before this is reached.
+ */
+export function mergeDictionaryWords(existing, additions) {
+    const byKey = new Map();
+    for (const word of [...existing, ...additions]) {
+        if (!isValidDictionaryWord(word))
+            continue;
+        const key = word.toLowerCase();
+        if (!byKey.has(key))
+            byKey.set(key, word);
+    }
+    return [...byKey.values()].sort(byWord);
+}
+/**
+ * Serialize a word list to the canonical committed file text: the header comment, then one word per
+ * line sorted case-insensitively, with a trailing newline. The input is run through the same dedup
+ * and sort as the merge, so serializing an unsorted or duplicate-bearing list still yields the
+ * canonical form. An empty word list serializes to just the header (so the file stays a valid,
+ * recognizable dictionary rather than vanishing).
+ */
+export function serializeDictionary(words) {
+    const sorted = mergeDictionaryWords(words, []);
+    return [HEADER, ...sorted].join('\n') + '\n';
+}

package/dist/content/types.d.ts

@@ -238,6 +238,11 @@ export interface CairnAdapter {
     /** 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
+     *  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). */
+    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. */
@@ -345,6 +350,13 @@ 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),
+     *  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. */
+    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. */
     resolvedAssets: import('../media/config.js').ResolvedAssetConfig;
@@ -355,6 +367,19 @@ 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
+     *  `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. */
+    spellcheckDictionary?: string;
+    /** 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. */
+    tidy?: import('../nav/site-config.js').TidyConfig;
     /** Admin panels contributed by extensions (Mode 2). Empty until Plan 09 wires the dispatch route. */
     adminPanels?: AdminPanel[];
     /** Field types contributed by extensions (Mode 2). Empty until Plan 09 wires the form dispatch. */

package/dist/doctor/checks-local.d.ts

@@ -5,3 +5,4 @@ export declare const configObservability: DoctorCheck;
 export declare const configCsrfDisable: DoctorCheck;
 export declare const configPublicOrigin: DoctorCheck;
 export declare const configSiteConfig: DoctorCheck;
+export declare const configTidyKey: DoctorCheck;

package/dist/doctor/checks-local.js

@@ -129,17 +129,21 @@ export const configPublicOrigin = {
 // evaluate, so the check probes the conventional spots instead (the repo root and the two
 // src locations the production sites use).
 const SITE_CONFIG_PATHS = ['site.config.yaml', 'src/lib/site.config.yaml', 'src/site.config.yaml'];
+// Read the first site.config.yaml that exists in a conventional spot, or null when none does.
+async function readSiteConfigText(ctx) {
+    for (const path of SITE_CONFIG_PATHS) {
+        const text = await ctx.readFile(path);
+        if (text !== null)
+            return text;
+    }
+    return null;
+}
 export const configSiteConfig = {
     id: 'config.site-config',
     conditionId: 'config.site-config-invalid',
     title: 'Site config',
     async run(ctx) {
-        let text = null;
-        for (const path of SITE_CONFIG_PATHS) {
-            text = await ctx.readFile(path);
-            if (text !== null)
-                break;
-        }
+        const text = await readSiteConfigText(ctx);
         if (text === null)
             return skip(`no site.config.yaml found (looked in ${SITE_CONFIG_PATHS.join(', ')})`);
         try {
@@ -157,3 +161,48 @@ export const configSiteConfig = {
         }
     },
 };
+// A site enables tidy with `tidy.enabled: true` in the committed config; ignore a config the rest of
+// the doctor reports through configSiteConfig, so a parse error here just skips rather than doubling
+// the failure.
+function tidyEnabled(text) {
+    let config;
+    try {
+        config = parseSiteConfig(text);
+    }
+    catch {
+        return false;
+    }
+    return config.tidy?.enabled === true;
+}
+// The Anthropic key is a Worker secret, so the doctor cannot prove it is unset (it is in neither the
+// committed wrangler config nor anything readFile reaches). It CAN read the two spots a key would also
+// appear if set as a plain var: the wrangler config text and .dev.vars. A bare presence-by-name read
+// is enough for the heuristic; the runtime fail(503) and --probe are the real truth checks.
+function keyAppearsIn(text) {
+    return text !== null && text.includes('ANTHROPIC_API_KEY');
+}
+// The tidy secret heuristic. It reuses the config.bindings-missing condition rather than registering a
+// new one, so the readiness count holds (the same pattern configMediaBucket uses). A warn here is not a
+// definitive unset claim: it asks the operator to verify the secret, since a wrangler secret is
+// invisible to the CLI.
+export const configTidyKey = {
+    id: 'config.tidy-key',
+    conditionId: 'config.bindings-missing',
+    title: 'Tidy API key',
+    async run(ctx) {
+        const text = await readSiteConfigText(ctx);
+        if (text === null)
+            return skip('no site.config.yaml found, so tidy enablement is unknown');
+        if (!tidyEnabled(text))
+            return skip('tidy is not enabled in the site config');
+        const wrangler = (await ctx.readFile('wrangler.jsonc')) ?? (await ctx.readFile('wrangler.toml'));
+        if (keyAppearsIn(wrangler)) {
+            return pass('ANTHROPIC_API_KEY appears in the wrangler vars (verify it is the real key, not a placeholder)');
+        }
+        const devVars = await ctx.readFile('.dev.vars');
+        if (keyAppearsIn(devVars)) {
+            return pass('ANTHROPIC_API_KEY appears in .dev.vars (the local override; verify the Worker secret is set for production)');
+        }
+        return fail('tidy is enabled but ANTHROPIC_API_KEY is in neither the wrangler vars nor .dev.vars; verify the secret is configured with wrangler secret put ANTHROPIC_API_KEY');
+    },
+};

package/dist/doctor/index.js

@@ -1,4 +1,4 @@
-import { configBindings, configMediaBucket, configObservability, configCsrfDisable, configSiteConfig, configPublicOrigin, } from './checks-local.js';
+import { configBindings, configMediaBucket, configObservability, configCsrfDisable, configSiteConfig, configPublicOrigin, configTidyKey, } from './checks-local.js';
 import { configDependencyFloors } from './check-floors.js';
 import { emailSenderOnboarded, edgeHttpsForced, edgeHsts, authStore } from './checks-cloudflare.js';
 import { githubApp } from './checks-github.js';
@@ -108,6 +108,7 @@ export function defaultChecks() {
         configCsrfDisable,
         configSiteConfig,
         configPublicOrigin,
+        configTidyKey,
         configDependencyFloors,
         emailSenderOnboarded,
         edgeHttpsForced,

package/dist/log/events.d.ts

@@ -1 +1 @@
-export type CairnLogEvent = 'auth.link.requested' | 'auth.link.send_failed' | 'auth.token.minted' | 'auth.token.confirmed' | 'auth.session.created' | 'auth.session.destroyed' | 'commit.succeeded' | 'commit.failed' | 'config.invalid' | 'entry.published' | 'entry.discarded' | 'publish.failed' | 'github.unreachable' | 'guard.rejected' | 'media.uploaded' | 'media.upload_failed' | 'media.delivery_failed' | 'media.orphan_reconcile' | 'media.resolve_missing' | 'media.deleted' | 'media.delete_blocked' | 'media.replaced' | 'media.replace_blocked' | 'media.alt_propagated';
+export type CairnLogEvent = 'auth.link.requested' | 'auth.link.send_failed' | 'auth.token.minted' | 'auth.token.confirmed' | 'auth.session.created' | 'auth.session.destroyed' | 'commit.succeeded' | 'commit.failed' | 'config.invalid' | 'entry.published' | 'entry.discarded' | 'publish.failed' | 'github.unreachable' | 'guard.rejected' | 'media.uploaded' | 'media.upload_failed' | 'media.delivery_failed' | 'media.orphan_reconcile' | 'media.resolve_missing' | 'media.deleted' | 'media.delete_blocked' | 'media.bulk_deleted' | 'media.orphans_purged' | 'media.replaced' | 'media.replace_blocked' | 'media.alt_propagated' | 'dictionary.added' | 'dictionary.add_conflict' | 'tidy.done' | 'tidy.error' | 'tidy.refused' | 'tidy.empty';

package/dist/media/bulk-delete-plan.d.ts

@@ -0,0 +1,24 @@
+import type { UsageEntry, UsageIndex } from './usage.js';
+import type { MediaManifest } from './manifest.js';
+/** One selected hash that is not deleted, with why and (for the where-used) its usage rows. The rows
+ *  are present only for 'still-referenced'; an 'uncommitted' skip carries an empty list. */
+export interface BulkDeleteSkip {
+    hash: string;
+    reason: 'still-referenced' | 'uncommitted';
+    usage: UsageEntry[];
+}
+/** The partitioned selection: the hashes safe to purge and the hashes held back. Both arrays keep the
+ *  input order of `selected` so the screen reports them in the order the user picked. */
+export interface BulkDeletePlan {
+    deletable: string[];
+    skipped: BulkDeleteSkip[];
+}
+/**
+ * Partition `selected` against a strict usage index and the media manifest.
+ *
+ * A hash with one or more usage rows is skipped 'still-referenced', carrying those rows for the
+ * where-used. A hash with no usage row and no committed manifest row is skipped 'uncommitted', since
+ * there is nothing committed to delete. A hash with no usage row and a committed manifest row is
+ * deletable. The input order of `selected` is preserved in both output arrays.
+ */
+export declare function planBulkDelete(selected: string[], index: UsageIndex, manifest: MediaManifest): BulkDeletePlan;

package/dist/media/bulk-delete-plan.js

@@ -0,0 +1,25 @@
+/**
+ * Partition `selected` against a strict usage index and the media manifest.
+ *
+ * A hash with one or more usage rows is skipped 'still-referenced', carrying those rows for the
+ * where-used. A hash with no usage row and no committed manifest row is skipped 'uncommitted', since
+ * there is nothing committed to delete. A hash with no usage row and a committed manifest row is
+ * deletable. The input order of `selected` is preserved in both output arrays.
+ */
+export function planBulkDelete(selected, index, manifest) {
+    const deletable = [];
+    const skipped = [];
+    for (const hash of selected) {
+        const usage = index.get(hash);
+        if (usage && usage.length > 0) {
+            skipped.push({ hash, reason: 'still-referenced', usage });
+        }
+        else if (manifest[hash]) {
+            deletable.push(hash);
+        }
+        else {
+            skipped.push({ hash, reason: 'uncommitted', usage: [] });
+        }
+    }
+    return { deletable, skipped };
+}

package/dist/media/orphan-scan.d.ts

@@ -0,0 +1,37 @@
+import { type ReconcileResult } from './reconcile.js';
+import type { MediaManifest } from './manifest.js';
+import type { UsageEntry, UsageIndex } from './usage.js';
+/** A purgeable orphan: a stored R2 key with no manifest row, plus the 16-hex hash parsed from it. */
+export interface OrphanByteRow {
+    /** The full R2 object key, e.g. "media/ff/ffffffffffffffff.webp". */
+    key: string;
+    /** The 16-hex content hash parsed from the key. */
+    hash: string;
+}
+/** A broken reference: a manifest row whose bytes are gone. Read-only, since purging it would drop a
+ *  still-referenced asset's record; the screen shows where it is used so an operator can re-ingest. */
+export interface BrokenRefRow {
+    /** The 16-hex content hash of the manifest row whose bytes are missing. */
+    hash: string;
+    /** The manifest row's display slug, or '' when the row is somehow absent. */
+    slug: string;
+    /** Where the asset is referenced, from the usage index. Empty when no reference was found. */
+    usage: UsageEntry[];
+}
+/** The scan surface model: the two row sets the Library renders. */
+export interface OrphanScan {
+    orphanedBytes: OrphanByteRow[];
+    brokenRefs: BrokenRefRow[];
+}
+/**
+ * Project a reconcile read plus the usage index into the scan surface model.
+ *
+ * `orphanedBytes` come from `reconcile.orphanedObjects`: each key is parsed to its hash via the
+ * shared media-key grammar, and a key that does not match (so it is not a content-addressed media
+ * object) is skipped. A key whose hash the usage index references is also skipped: it is referenced
+ * on main or some open branch, so its bytes are in use, not orphaned. `brokenRefs` come from
+ * `reconcile.missingObjects`: each hash carries its
+ * manifest slug (falling back to '' when the row is absent) and its where-used rows from the index
+ * (an empty list when no reference was found). Both directions keep their input order.
+ */
+export declare function buildOrphanScan(reconcile: ReconcileResult, manifest: MediaManifest, index: UsageIndex): OrphanScan;

package/dist/media/orphan-scan.js

@@ -0,0 +1,42 @@
+// cairn-cms: the orphan-scan projection, the pure model behind the admin Media Library's scan
+// surface. It folds reconcileMedia's two directions together with the usage index into the two rows
+// the screen renders: the purgeable byte-rows and the read-only broken-reference rows (manifest rows
+// whose bytes are gone). It only projects; no path here reads R2, the manifest, or git. The module
+// is engine-internal and on no public subpath.
+//
+// An orphaned byte is a stored R2 object whose hash has NO manifest row AND appears in NO usage row,
+// so it is referenced nowhere across main and every open branch. Reconcile only checks main's
+// manifest, so a branch-only upload (bytes in R2, manifest row only on the open cairn/* branch) gets
+// flagged as an orphaned object even though a colleague's in-progress draft references it. The byte
+// purge is irreversible, so we intersect reconcile's verdict with the strict cross-branch usage
+// index here: any hash the index references is in use and is dropped from orphanedBytes, which keeps
+// a live draft's bytes from ever reaching the purge surface.
+import { MEDIA_KEY_RE } from './reconcile.js';
+/**
+ * Project a reconcile read plus the usage index into the scan surface model.
+ *
+ * `orphanedBytes` come from `reconcile.orphanedObjects`: each key is parsed to its hash via the
+ * shared media-key grammar, and a key that does not match (so it is not a content-addressed media
+ * object) is skipped. A key whose hash the usage index references is also skipped: it is referenced
+ * on main or some open branch, so its bytes are in use, not orphaned. `brokenRefs` come from
+ * `reconcile.missingObjects`: each hash carries its
+ * manifest slug (falling back to '' when the row is absent) and its where-used rows from the index
+ * (an empty list when no reference was found). Both directions keep their input order.
+ */
+export function buildOrphanScan(reconcile, manifest, index) {
+    const orphanedBytes = [];
+    for (const key of reconcile.orphanedObjects) {
+        const hash = MEDIA_KEY_RE.exec(key)?.[1];
+        if (hash === undefined)
+            continue;
+        if (index.has(hash))
+            continue;
+        orphanedBytes.push({ key, hash });
+    }
+    const brokenRefs = reconcile.missingObjects.map((hash) => ({
+        hash,
+        slug: manifest[hash]?.slug ?? '',
+        usage: index.get(hash) ?? [],
+    }));
+    return { orphanedBytes, brokenRefs };
+}

package/dist/media/reconcile.d.ts

@@ -1,4 +1,7 @@
 import type { MediaManifest } from './manifest.js';
+/** A stored media object key parses to its short hash via `media/<aa>/<shortHash>.<ext>`. Exported so
+ *  the orphan-scan projection derives the same hash from an orphaned key without a second grammar. */
+export declare const MEDIA_KEY_RE: RegExp;
 /** 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 {

package/dist/media/reconcile.js

@@ -1,6 +1,7 @@
 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}$/;
+/** A stored media object key parses to its short hash via `media/<aa>/<shortHash>.<ext>`. Exported so
+ *  the orphan-scan projection derives the same hash from an orphaned key without a second grammar. */
+export const MEDIA_KEY_RE = /^media\/[0-9a-f]{2}\/([0-9a-f]{16})\.[a-z0-9]{1,5}$/;
 /** 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. */