@glw907/cairn-cms 0.58.0 → 0.60.0

package/dist/sveltekit/content-routes.js

@@ -10,13 +10,22 @@ import { deriveExcerpt } from '../content/excerpt.js';
 import { asString } from '../content/identity.js';
 import { isValidId, slugify, filenameFromId, composeDatedId, slugFromId, renameId } from '../content/ids.js';
 import { appCredentials } from '../github/credentials.js';
-import { listMarkdown, readRaw, commitFiles } from '../github/repo.js';
+import { listMarkdown, readRaw, commitFile, commitFiles } from '../github/repo.js';
 import { branchHeadSha, createBranch, deleteBranch, listBranches } from '../github/branches.js';
 import { PENDING_PREFIX, pendingBranch, parsePendingBranch } from '../content/pending.js';
 import { cachedInstallationToken } from '../github/signing.js';
 import { emptyManifest, manifestEntryFromFile, parseManifest, serializeManifest, upsertEntry, removeEntry, inboundLinks } from '../content/manifest.js';
 import { isConflict } from '../github/types.js';
 import { log } from '../log/index.js';
+import { dictionaryFileForDialect, DEFAULT_TIDY_MODEL, resolveTidyConventions, parseSiteConfig, setTidy, validateTidyConventions, TidyConventionsError } from '../nav/site-config.js';
+import { buildTidyPrompt } from './tidy-prompt.js';
+// Server-only: the Anthropic SDK ships the API-key path and never reaches a browser bundle. It is
+// imported only here (a Worker module no component imports statically), and the server-only-deps test
+// guards that boundary. The default export is the Anthropic client class; the structural TidyClient
+// type below keeps the action's surface small and the test seam injectable, so the SDK's deep types
+// never leak into a public signature.
+import Anthropic from '@anthropic-ai/sdk';
+import { parseDictionary, mergeDictionaryWords, serializeDictionary, isValidDictionaryWord } from '../content/site-dictionary.js';
 import { issueCsrfToken, validateCsrfHeader } from './csrf.js';
 import { requireSession } from './guard.js';
 import { sniffMediaType, isDeniedUpload, extForMediaType } from '../media/sniff.js';
@@ -26,8 +35,37 @@ import { r2Store } from '../media/store.js';
 import { parseMediaEntries, parseMediaManifest, upsertMediaEntry, removeMediaEntry, serializeMediaManifest } from '../media/manifest.js';
 import { mediaLibraryEntry } from '../media/library-entry.js';
 import { buildUsageIndex } from '../media/usage.js';
+import { runReconcile, MEDIA_KEY_RE } from '../media/reconcile.js';
+import { buildOrphanScan } from '../media/orphan-scan.js';
 import { repointMediaRef, fillAltForHash } from '../content/media-rewrite.js';
 import { planMediaRewrite } from '../media/rewrite-plan.js';
+import { planBulkDelete } from '../media/bulk-delete-plan.js';
+/** The Worker-side request deadline for the tidy model call: 30 seconds. A tidy call to Sonnet on a
+ *  full entry can run many seconds, so the action bounds it with an AbortSignal and maps the overrun to
+ *  a retryable fail(502). This sits well under Cloudflare's per-request wall-clock ceiling (a Worker
+ *  invocation can run far longer, but a single subrequest left open near that ceiling would surface as a
+ *  platform timeout the action could not shape into a clean retry). 30s comfortably covers a proofread
+ *  of the bounded input (see MAX_TIDY_CHARS) while leaving headroom under the platform limit. */
+const DEFAULT_TIDY_TIMEOUT_MS = 30_000;
+/** The fallback site-config path when no nav menu names one: the convention every scaffolded site
+ *  uses. The settings save edits the same committed YAML the nav editor does, so it resolves the path
+ *  from the configured nav menu first and falls back to this default. */
+const DEFAULT_SITE_CONFIG_PATH = 'src/lib/site.config.yaml';
+/** Plain-language labels for the known tidy models, so the read-only model fact reads as a name rather
+ *  than a bare id. An unknown id falls back to itself. */
+const TIDY_MODEL_LABELS = {
+    'claude-sonnet-4-6': 'Claude Sonnet',
+    'claude-haiku-4-5': 'Claude Haiku',
+};
+/** The display label for a tidy model id, falling back to the raw id for an unknown model. */
+function tidyModelLabel(model) {
+    return TIDY_MODEL_LABELS[model] ?? model;
+}
+/** The input cap for a single tidy request: 24000 characters (~6k input tokens). A proofread runs at
+ *  roughly input length, so this stays comfortably inside the 30s deadline; a longer entry refuses with
+ *  fail(413) and the author tidies a selection instead. The cap is enforced BEFORE the model call, so an
+ *  over-long body never spends a token or risks the deadline. */
+const MAX_TIDY_CHARS = 24_000;
 /** Resolve the effective preview for one concept: its `byConcept` override wins per key, with
  *  nullish coalescing so an override key that is present but undefined keeps the top-level value.
  *  Stylesheets are always shared, and the `byConcept` map never reaches the client. */
@@ -50,6 +88,11 @@ function conceptOf(runtime, params) {
 }
 export function createContentRoutes(runtime, deps = {}) {
     const mintToken = deps.mintToken ?? ((env) => cachedInstallationToken(appCredentials(runtime.backend, env)));
+    // The default Anthropic factory builds the real SDK client from the resolved key. Tests inject a fake
+    // (deps.anthropic) so messages.create is stubbed and no network call or real key is ever needed. The
+    // SDK client satisfies TidyClient structurally; the cast names that to the compiler.
+    const anthropicClient = deps.anthropic ?? ((opts) => new Anthropic({ apiKey: opts.apiKey }));
+    const tidyTimeoutMs = deps.tidyTimeoutMs ?? DEFAULT_TIDY_TIMEOUT_MS;
     /** Main's manifest, parsed. A missing file starts empty (a fresh repo before the first commit).
      *  Always read from main: pending branches carry no manifest copy. */
     async function readManifest(token) {
@@ -233,6 +276,10 @@ export function createContentRoutes(runtime, deps = {}) {
             flash = 'replaced';
         else if (event.url.searchParams.get('altPropagated') === '1')
             flash = 'altPropagated';
+        else if (event.url.searchParams.get('bulkDeleted') === '1')
+            flash = 'bulkDeleted';
+        else if (event.url.searchParams.get('orphansPurged') === '1')
+            flash = 'orphansPurged';
         const flashError = event.url.searchParams.get('error');
         let token;
         try {
@@ -361,13 +408,17 @@ export function createContentRoutes(runtime, deps = {}) {
         // The media manifest joins the concurrent batch only when media is on, read from the default
         // branch (pending branches carry no copy). A rejected media read degrades to null so the edit
         // never throws on a missing or unreadable media.json; the projection below treats null as empty.
-        const [headSha, mainRaw, manifestRaw, mediaRaw] = await Promise.all([
+        // The committed personal dictionary joins the concurrent batch, read from the default branch. A
+        // rejected read degrades to null so the edit never throws on a missing or unreadable dictionary;
+        // the projection below treats null as an empty word list (the editor falls back to dialect-only).
+        const [headSha, mainRaw, manifestRaw, mediaRaw, dictionaryRaw] = await Promise.all([
             branchHeadSha(runtime.backend, branch, token),
             readRaw(runtime.backend, path, token),
             readRaw(runtime.backend, runtime.manifestPath, token),
             runtime.resolvedAssets.enabled
                 ? readRaw(runtime.backend, runtime.mediaManifestPath, token).catch(() => null)
                 : Promise.resolve(null),
+            readRaw(runtime.backend, dictionaryFilePath(), token).catch(() => null),
         ]);
         const pending = headSha !== null;
         const raw = pending ? await readRaw({ ...runtime.backend, branch }, path, token) : mainRaw;
@@ -421,8 +472,28 @@ export function createContentRoutes(runtime, deps = {}) {
             publishedFlash: event.url.searchParams.get('published') === '1',
             discardedFlash: event.url.searchParams.get('discarded') === '1',
             preview: resolvePreview(runtime.preview, concept.id),
+            // composeRuntime always resolves this from the site config's dialect; default a hand-built
+            // runtime that omits it to the US English dictionary so the editor always has a real filename.
+            spellcheckDictionary: runtime.spellcheckDictionary ?? dictionaryFileForDialect(undefined),
+            // The committed personal-dictionary words, normalized to the canonical sorted, deduplicated set
+            // so the editor seeds the Worker's personal layer with a clean list. A missing or unreadable file
+            // is an empty list (the dialect-only fallback).
+            siteDictionary: mergeDictionaryWords(parseDictionary(dictionaryRaw), []),
+            // The editor-tier tidy facts: the master switch, the model (for the head pill), and the resolved
+            // conventions (the because-line and category inference read only these). The API key is never
+            // exposed here. A site with no tidy block reads disabled with the default conventions.
+            tidy: {
+                enabled: runtime.tidy?.enabled ?? false,
+                model: runtime.tidy?.model || DEFAULT_TIDY_MODEL,
+                conventions: resolveTidyConventions(runtime.tidy?.conventions),
+            },
         };
     }
+    /** The repo-relative personal-dictionary path, defaulting a hand-built runtime that omits it to the
+     *  same `.cairn/` content root the manifests use. composeRuntime always fills `dictionaryPath`. */
+    function dictionaryFilePath() {
+        return runtime.dictionaryPath ?? 'src/content/.cairn/dictionary.txt';
+    }
     /** Log a failed commit: a conflict is the expected last-writer-wins outcome, so it warns with a
      *  reason; any other error is unexpected and logs at error with the stringified cause. Publish
      *  failures carry the same shape under their own event name. */
@@ -1073,6 +1144,245 @@ export function createContentRoutes(runtime, deps = {}) {
         log.info('media.deleted', { editor: editor.email, hash });
         throw redirect(303, '/admin/media?deleted=1');
     }
+    /** Bulk safe-delete a multi-select of committed media assets. This is mediaDeleteAction extended to
+     *  many items, with the same safety primitives and one rule that defines the batch: the gate is ONE
+     *  shared strict cross-branch usage index built per batch, never N per-item reads (N strict reads
+     *  would blow the workerd connection budget at many open branches). The fail-closed posture is for
+     *  the WHOLE batch: if that single strict index cannot complete, the action refuses everything and
+     *  commits nothing, rather than risk deleting bytes a branch still references.
+     *
+     *  Skip-and-report, never force: the pure planBulkDelete partitions the selection against the strict
+     *  index into deletable (no usage row, a committed manifest row exists), skipped-still-referenced (a
+     *  usage row, carried for the where-used), and skipped-uncommitted (no manifest row). An in-use item
+     *  is skipped and reported, never bulk-force-deleted; forced in-use deletion stays the single-item
+     *  typed-slug path.
+     *
+     *  The order is load-bearing, mirroring single delete: ONE atomic commit removes every deletable row
+     *  FIRST, then the R2 objects are deleted (commit-row-then-delete-R2). A failure after the commit
+     *  leaves bytes with no row (a benign orphan) rather than a row pointing at deleted bytes. Each R2
+     *  delete is best-effort and batch-resilient: a per-object error is reported in `failed` and never
+     *  aborts the rest of the batch. The result is an itemized 207-style summary the component renders
+     *  (deleted / skipped with reasons / failed); there is no success redirect. */
+    async function mediaBulkDelete(event) {
+        const editor = requireSession(event);
+        const token = await mintToken(event.platform?.env ?? {});
+        // Read the selected hashes from the form. Accept the repeated `hash` field, falling back to a JSON
+        // `hashes` array. Each value must match the 16-hex content-hash grammar; a malformed value is
+        // dropped silently rather than surfaced as a skip (it was never a real selection).
+        const form = await event.request.formData();
+        let raw = form.getAll('hash').map(String);
+        if (raw.length === 0) {
+            const json = form.get('hashes');
+            if (typeof json === 'string') {
+                try {
+                    const parsed = JSON.parse(json);
+                    if (Array.isArray(parsed))
+                        raw = parsed.map(String);
+                }
+                catch {
+                    raw = [];
+                }
+            }
+        }
+        const selected = raw.filter((h) => MEDIA_HASH_RE.test(h));
+        // Read the fresh media manifest (the deletable rows come from here, by hash).
+        const manifest = parseMediaManifest(parseMediaJson(await readRaw(runtime.backend, runtime.mediaManifestPath, token)));
+        // Resolve the R2 bucket before any write, so a media-off site or a missing binding refuses before
+        // the commit, exactly like single delete.
+        const resolved = runtime.resolvedAssets;
+        if (!resolved.enabled) {
+            return fail(503, { error: 'Media is not enabled for this site.' });
+        }
+        const platformEnv = event.platform?.env ?? {};
+        const rawBucket = platformEnv[resolved.bucketBinding];
+        if (!rawBucket) {
+            return fail(503, { error: 'The media bucket is not bound.' });
+        }
+        const store = r2Store(rawBucket);
+        // THE fail-closed gate for the whole batch: one shared strict usage index. STRICT mode rethrows a
+        // branch-read failure, so a transient branch read failing refuses the whole batch rather than
+        // mistaking a still-referenced asset for an orphan. Build exactly one index, never one per item.
+        let index;
+        try {
+            index = await buildUsageIndex(runtime.backend, token, runtime.concepts, await readManifest(token), { strict: true });
+        }
+        catch {
+            return fail(503, { error: 'Could not verify where these assets are used. Try again.' });
+        }
+        // The pure partition: membership in the fresh strict index is the gate, never the display count.
+        const plan = planBulkDelete(selected, index, manifest);
+        // An all-skipped or empty batch is a no-op success: nothing committed, nothing deleted.
+        if (plan.deletable.length === 0) {
+            return { deleted: [], skipped: plan.skipped, failed: [] };
+        }
+        // ONE atomic commit removing EVERY deletable row, folded over removeMediaEntry.
+        let next = manifest;
+        for (const hash of plan.deletable)
+            next = removeMediaEntry(next, hash);
+        const commitFields = { concept: 'media', id: 'bulk', editor: editor.email };
+        try {
+            await commitFiles(runtime.backend, [{ path: runtime.mediaManifestPath, content: serializeMediaManifest(next) }], { message: `Delete ${plan.deletable.length} media assets`, author: { name: editor.displayName, email: editor.email } }, token);
+            log.info('commit.succeeded', commitFields);
+        }
+        catch (err) {
+            commitFailure(commitFields, err, '/admin/media', 'The media manifest changed since you opened it. Reload and try again.');
+        }
+        // THEN delete each deletable hash's R2 object (the load-bearing order, see the docstring). Best
+        // effort and batch-resilient: a thrown key derivation or a delete error is reported in `failed`
+        // and the loop continues. An absent object is a no-op (the R2 contract).
+        const deleted = [];
+        const failed = [];
+        for (const hash of plan.deletable) {
+            try {
+                const row = manifest[hash];
+                await store.delete(r2Key(row.hash, row.ext));
+                deleted.push(hash);
+            }
+            catch (err) {
+                failed.push({ hash, error: err instanceof Error ? err.message : String(err) });
+            }
+        }
+        log.info('media.bulk_deleted', { editor: editor.email, deleted: deleted.length, skipped: plan.skipped.length });
+        return { deleted, skipped: plan.skipped, failed };
+    }
+    /** The on-demand orphan scan: a read-only reconcile of stored R2 bytes against the manifest, joined
+     *  with one strict cross-branch usage index for the broken-reference where-used. It runs only when
+     *  requested, never on the loaded index, because it is heavier than the load path: a full R2 list
+     *  plus a reconcile pass on top of the strict usage build.
+     *
+     *  Detection-time fail-closed: BOTH the reconcile and the strict usage build run inside one
+     *  try/catch, and any throw refuses the whole scan with fail(503) rather than returning a partial
+     *  result. The reconcile must not run on a half-listed bucket: a truncated R2 list would call
+     *  still-stored bytes orphaned. The strict usage build must not run on a half-read branch set: an
+     *  unread branch would make a branch-referenced asset look orphaned. A wrong orphan verdict here
+     *  feeds the irreversible purge, so the scan refuses rather than risk it.
+     *
+     *  The result is the OrphanScan projection: orphanedBytes (stored keys with no manifest row, the
+     *  purge surface) and brokenRefs (manifest rows whose bytes are gone, read-only, shown with their
+     *  where-used so an operator can re-ingest rather than purge a still-referenced record). */
+    async function mediaOrphanScan(event) {
+        requireSession(event);
+        const token = await mintToken(event.platform?.env ?? {});
+        // Resolve the R2 binding. The reconcile lists the raw bucket directly, so keep the raw binding;
+        // the MediaStore seam carries no list. A media-off site or a missing binding refuses the scan.
+        const resolved = runtime.resolvedAssets;
+        if (!resolved.enabled) {
+            return fail(503, { error: 'Media is not enabled for this site.' });
+        }
+        const platformEnv = event.platform?.env ?? {};
+        const rawBucket = platformEnv[resolved.bucketBinding];
+        if (!rawBucket) {
+            return fail(503, { error: 'The media bucket is not bound.' });
+        }
+        // Read the fresh media manifest for the reconcile's manifest side.
+        const manifest = parseMediaManifest(parseMediaJson(await readRaw(runtime.backend, runtime.mediaManifestPath, token)));
+        // THE detection-time fail-closed surface. The reconcile (an R2 list that must complete in full)
+        // and the strict usage build (a branch read that must complete in full) are both unsafe to use
+        // partially, so either throwing refuses the scan. A wrong orphan verdict from a partial read here
+        // would feed the irreversible purge.
+        let reconcile;
+        let index;
+        try {
+            reconcile = await runReconcile(rawBucket, manifest);
+            index = await buildUsageIndex(runtime.backend, token, runtime.concepts, await readManifest(token), { strict: true });
+        }
+        catch {
+            return fail(503, { error: 'Could not check where files are used, so the scan was not run. Try again.' });
+        }
+        return buildOrphanScan(reconcile, manifest, index);
+    }
+    /** Purge orphaned R2 bytes: the one IRREVERSIBLE media action. Raw object bytes live only in R2, not
+     *  in git, so a purged orphan cannot be recovered the way a deleted manifest row can be reverted in
+     *  history. The whole action is built around that fact.
+     *
+     *  The typed-count confirm is the never-bypassable gate, the analogue of single delete's typed-slug
+     *  check. The form's `confirm` must equal the count of selected keys (the approved rev.2 mockup's
+     *  "Type N to purge these files for good"); an empty selection or a mismatched count deletes nothing.
+     *
+     *  Re-derive fresh is the safety crux. The selection came from an earlier scan, so the action does
+     *  NOT trust it: the purge keys are client-posted, so the server cannot assume they came from a fresh
+     *  scan. It reads the current media manifest AND rebuilds ONE strict cross-branch usage index, then
+     *  for each selected key parses the hash from the key grammar. A key that does not match the grammar
+     *  was never a real orphan key and is dropped silently. A key whose hash now has a manifest row OR is
+     *  referenced on any open cairn/* branch survived the scan window (it was claimed by a row, or a
+     *  draft started referencing those bytes), so it is skipped into skippedClaimed and its bytes survive.
+     *  Only a key whose hash is STILL absent from both is purged. This closes the TOCTOU between scan and
+     *  purge that could otherwise irreversibly delete a live draft's bytes.
+     *
+     *  Like the scan and the bulk delete, the strict index build is the fail-closed gate: a branch read
+     *  that throws refuses the whole batch with fail(503) rather than mistaking an unverifiable reference
+     *  for an absent one. The index is built exactly once for the batch, never once per key.
+     *
+     *  There is no commit. An orphan by definition has no manifest row to remove, so the purge deletes
+     *  the R2 object directly. Each delete is best-effort and batch-resilient: a per-object error is
+     *  reported in `failed` and the loop continues; an absent object is a no-op (the R2 contract). */
+    async function mediaPurgeOrphans(event) {
+        const editor = requireSession(event);
+        const token = await mintToken(event.platform?.env ?? {});
+        // Resolve the R2 binding, the same media-off / missing-binding refusals as the scan. The purge
+        // deletes through the MediaStore seam, so wrap the raw binding.
+        const resolved = runtime.resolvedAssets;
+        if (!resolved.enabled) {
+            return fail(503, { error: 'Media is not enabled for this site.' });
+        }
+        const platformEnv = event.platform?.env ?? {};
+        const rawBucket = platformEnv[resolved.bucketBinding];
+        if (!rawBucket) {
+            return fail(503, { error: 'The media bucket is not bound.' });
+        }
+        const store = r2Store(rawBucket);
+        // Read the selected R2 keys and the typed confirm.
+        const form = await event.request.formData();
+        const keys = form.getAll('key').map(String);
+        const confirm = String(form.get('confirm') ?? '');
+        // The irreversible gate: the confirm must equal the selected count, and the set must be non-empty.
+        // A mismatch or an empty set refuses and deletes NOTHING.
+        if (keys.length === 0 || confirm !== String(keys.length)) {
+            return fail(400, { error: 'Type the number of files to confirm the purge.' });
+        }
+        // Re-derive fresh against the current manifest, so a key claimed since the scan is never purged.
+        const manifest = parseMediaManifest(parseMediaJson(await readRaw(runtime.backend, runtime.mediaManifestPath, token)));
+        // THE fail-closed gate for the whole batch: one shared strict cross-branch usage index, symmetric
+        // with the scan and the bulk delete. STRICT mode rethrows a branch-read failure, so a transient
+        // branch read refuses the irreversible purge rather than letting a possibly-referenced byte be
+        // treated as a true orphan. Build exactly one index, never one per key.
+        let index;
+        try {
+            index = await buildUsageIndex(runtime.backend, token, runtime.concepts, await readManifest(token), { strict: true });
+        }
+        catch {
+            return fail(503, { error: 'Could not verify where these files are used. Try again.' });
+        }
+        const purged = [];
+        const skippedClaimed = [];
+        const failed = [];
+        for (const key of keys) {
+            const hash = MEDIA_KEY_RE.exec(key)?.[1];
+            // A key that does not match the grammar was never a real orphan key: drop it silently.
+            if (hash === undefined)
+                continue;
+            // A hash that now has a manifest row was claimed since the scan: its bytes are a live asset now.
+            if (manifest[hash]) {
+                skippedClaimed.push(key);
+                continue;
+            }
+            // A hash referenced on any open cairn/* branch backs an in-progress draft: skip it claimed too.
+            if (index.has(hash)) {
+                skippedClaimed.push(key);
+                continue;
+            }
+            // Still orphaned: delete the object directly. No commit, there is no manifest row.
+            try {
+                await store.delete(key);
+                purged.push(key);
+            }
+            catch (err) {
+                failed.push({ key, error: err instanceof Error ? err.message : String(err) });
+            }
+        }
+        log.info('media.orphans_purged', { editor: editor.email, purged: purged.length });
+        return { purged, skippedClaimed, failed };
+    }
     /** Edit a committed asset's metadata: its display name, slug, and default alt. A single media.json
      *  row commit, with NO reference rewrite: the resolver and the delivery route key on the hash, so a
      *  rename never breaks an existing `media:` reference. The default alt is the asset's value for the
@@ -1425,7 +1735,291 @@ export function createContentRoutes(runtime, deps = {}) {
         }
         throw redirect(303, '/admin/media?altPropagated=1');
     }
-    return { layoutLoad, indexRedirect, listLoad, mediaLibraryLoad, createAction, editLoad, saveAction, publishAction, publishAllAction, discardAction, deleteAction, listDeleteAction, renameAction, uploadAction, mediaDeleteAction, mediaUpdateAction, mediaReplacePreview, mediaReplaceApply, mediaAltPreview, mediaAltApply, mintToken };
+    /** The cap on a personal-dictionary word, matched by isValidDictionaryWord. A word is one line, so
+     *  this bounds an abusive input; the real authority is the per-character validation, which rejects
+     *  whitespace and control bytes so a body can never inject an extra line into the committed file. */
+    const MAX_DICTIONARY_WORD = 64;
+    /** The cap on the words a single add request carries: an editor adds a handful at save time, never
+     *  a flood. Past this the body is treated as abusive and the surplus is dropped. */
+    const MAX_DICTIONARY_BATCH = 100;
+    /** Read the committed personal dictionary, merge the validated additions in sorted order, and commit
+     *  the canonical file back. Shared by the first attempt and the post-conflict retry, so both re-read
+     *  the head and re-merge the same additions; the merge is order-independent, so a concurrent editor's
+     *  word that already landed is preserved and the result is the same sorted set regardless of order.
+     *  Returns the merged word list. Throws CommitConflictError (via commitFiles) when the branch moves
+     *  under the commit, which the caller catches to retry once. */
+    async function mergeAndCommitDictionary(token, additions, editor) {
+        const path = dictionaryFilePath();
+        // The existing file as its canonical sorted set, so a no-op add is detected against the same
+        // normalization the commit would write (an already-sorted file never re-commits just to reorder).
+        const canonicalExisting = mergeDictionaryWords(parseDictionary(await readRaw(runtime.backend, path, token)), []);
+        const merged = mergeDictionaryWords(canonicalExisting, additions);
+        // Nothing new (every addition was already present): skip the commit so an idempotent add never
+        // pushes an empty commit that would redeploy the site. The merged set is still returned so the
+        // client reconciles its pending additions away.
+        if (merged.length === canonicalExisting.length)
+            return merged;
+        await commitFiles(runtime.backend, [{ path, content: serializeDictionary(merged) }], { message: `Add to dictionary: ${additions.join(', ')}`, author: { name: editor.displayName, email: editor.email } }, token);
+        return merged;
+    }
+    /** The repo-relative site-config path the settings save reads and commits. It is the same committed
+     *  YAML the nav editor edits, so it comes from the configured nav menu first and falls back to the
+     *  scaffold default when no menu is configured. */
+    function siteConfigPath() {
+        return runtime.navMenu?.configPath ?? DEFAULT_SITE_CONFIG_PATH;
+    }
+    /** Read whether the Anthropic API key secret is present in the load's env. A presence flag for the
+     *  truthful visibility gate, never the key itself: the key is a Worker secret, so this only reports
+     *  that a non-empty `ANTHROPIC_API_KEY` exists and the value never leaves the server. */
+    function keyConfigured(event) {
+        const env = (event.platform?.env ?? {});
+        return typeof env.ANTHROPIC_API_KEY === 'string' && env.ANTHROPIC_API_KEY.length > 0;
+    }
+    /** Load the two-tier tidy settings (spec 2.8, Task 15). The developer tier (enabled, key, model) is
+     *  read-only; the editor tier is the resolved conventions block. The visibility gate is truthful: the
+     *  `enabled` flag is true only when `tidy.enabled` is set AND the key is present, so the screen renders
+     *  the convention list only then and the honest gate note otherwise. No secret is returned: only a
+     *  presence flag for the key. The conventions come straight from the runtime config (the same source
+     *  the tidy action's prompt reads), so the screen and the prompt can never diverge. */
+    function settingsLoad(event) {
+        requireSession(event);
+        const tidy = runtime.tidy;
+        const tidyEnabled = tidy?.enabled === true;
+        const keyPresent = keyConfigured(event);
+        const model = tidy?.model || DEFAULT_TIDY_MODEL;
+        return {
+            enabled: tidyEnabled && keyPresent,
+            tidyEnabled,
+            keyConfigured: keyPresent,
+            model,
+            modelLabel: tidyModelLabel(model),
+            conventions: resolveTidyConventions(tidy?.conventions),
+            saved: event.url.searchParams.get('saved') === '1',
+            error: event.url.searchParams.get('error'),
+        };
+    }
+    /** Save the editor-tier tidy conventions: validate the posted block, then read-modify-commit it into
+     *  the same committed YAML the nav editor writes, with the session editor as author. The transport is
+     *  the nav save's exactly: a form POST carrying the conventions JSON, the read-modify-commit through
+     *  `commitFile`, and a stale-SHA `isConflict` bounced back as a reload prompt. Only the conventions
+     *  block is written (setTidy leaves `tidy.enabled` and `tidy.model` untouched), so an editor's save can
+     *  never flip the developer-tier deploy facts. The save refuses before any commit when tidy is not
+     *  enabled, so the gate state's absent editor tier can never be saved past. */
+    async function settingsSave(event) {
+        const editor = requireSession(event);
+        // The editor tier does not exist when tidy is off, so a save in that state is a 404 (no editable
+        // surface to commit), the server half of the truthful gate.
+        if (runtime.tidy?.enabled !== true)
+            throw error(404, 'Tidy is not enabled for this site');
+        const form = await event.request.formData();
+        let conventions;
+        try {
+            conventions = validateTidyConventions(JSON.parse(String(form.get('conventions') ?? '{}')));
+        }
+        catch (err) {
+            const message = err instanceof TidyConventionsError ? err.message : 'Invalid tidy settings';
+            throw redirect(303, `/admin/settings?error=${encodeURIComponent(message)}`);
+        }
+        const path = siteConfigPath();
+        const token = await mintToken(event.platform?.env ?? {});
+        const raw = await readRaw(runtime.backend, path, token);
+        if (raw === null)
+            throw error(404, 'Site config not found');
+        // Parse first so a malformed file fails before the write rather than committing onto a broken base.
+        parseSiteConfig(raw);
+        const commitFields = { concept: 'settings', id: 'tidy', editor: editor.email };
+        try {
+            await commitFile(runtime.backend, path, setTidy(raw, conventions), { message: 'Update tidy settings', author: { name: editor.displayName, email: editor.email } }, token);
+            log.info('commit.succeeded', commitFields);
+        }
+        catch (err) {
+            if (isConflict(err)) {
+                log.warn('commit.failed', { ...commitFields, reason: 'conflict' });
+                const message = 'The site config changed since you opened it. Reload and reapply your edits.';
+                throw redirect(303, `/admin/settings?error=${encodeURIComponent(message)}`);
+            }
+            log.error('commit.failed', { ...commitFields, error: String(err) });
+            throw err;
+        }
+        throw redirect(303, '/admin/settings?saved=1');
+    }
+    /** Add a word (or batch) to the git-committed personal dictionary (spec 1.6). The transport mirrors
+     *  the media raw-body actions exactly: a `text/plain` POST, the CSRF token in `X-Cairn-CSRF` validated
+     *  by validateCsrfHeader (CSRF first, then the session), and a small JSON body `{ word }` or
+     *  `{ words }`. It reads the current file from the default branch, inserts the validated words in
+     *  sorted order if absent (idempotent), and commits through the GitHub-App pipeline.
+     *
+     *  The commit is SHA-guarded with commit-and-retry: commitFiles throws CommitConflictError when the
+     *  branch moved under it, which is caught here to re-read the new head, re-merge the same additions
+     *  (the sorted insert is order-independent, so a concurrent editor's word is preserved), and retry
+     *  once. The response is the merged word list, so the client drops the now-committed words from its
+     *  pending set; a refusal rides a `fail` envelope the client reads by `type`/`status`.
+     *
+     *  Input validation is load-bearing here: this commits to the repo from request input, so every word
+     *  is length-bounded and rejected if it carries whitespace or control characters (a word is one
+     *  line), and the batch is capped. A body that yields no valid word refuses with a 400 and commits
+     *  nothing, so the committed file can never gain an injected or empty line. */
+    async function addDictionaryWord(event) {
+        // CSRF first: a raw-body (JSON) POST, so the header witness is the authority, like the upload and
+        // media actions. A failed check refuses before the session read or any GitHub call.
+        if (!event.cookies || !validateCsrfHeader({ url: event.url, request: event.request, cookies: event.cookies })) {
+            return fail(403, { error: 'csrf' });
+        }
+        const editor = requireSession(event);
+        let payload;
+        try {
+            payload = JSON.parse(await event.request.text());
+        }
+        catch {
+            return fail(400, { error: 'Could not read the dictionary request.' });
+        }
+        // Collect the candidate words from `word` and/or `words`, keep only the strings, validate each
+        // against the one-line word grammar, dedupe, and cap the batch. A body with no valid word refuses.
+        const raw = [
+            ...(typeof payload.word === 'string' ? [payload.word] : []),
+            ...(Array.isArray(payload.words) ? payload.words.filter((w) => typeof w === 'string') : []),
+        ];
+        const additions = [...new Set(raw.filter((w) => isValidDictionaryWord(w, MAX_DICTIONARY_WORD)))].slice(0, MAX_DICTIONARY_BATCH);
+        if (additions.length === 0) {
+            return fail(400, { error: 'No valid word to add to the dictionary.' });
+        }
+        const token = await mintToken(event.platform?.env ?? {});
+        const commitFields = { concept: 'dictionary', id: additions[0], editor: editor.email };
+        try {
+            const words = await mergeAndCommitDictionary(token, additions, editor);
+            log.info('dictionary.added', { editor: editor.email, words: additions });
+            return { words };
+        }
+        catch (err) {
+            if (!isConflict(err))
+                throw err;
+            // The branch moved under the commit. Re-read the new head and re-merge the same additions, then
+            // retry once. The merge is order-independent, so a concurrent editor's word that landed in the
+            // window is preserved and the two adds converge on the same sorted set.
+            try {
+                const words = await mergeAndCommitDictionary(token, additions, editor);
+                log.info('dictionary.added', { editor: editor.email, words: additions, retried: true });
+                return { words };
+            }
+            catch (retryErr) {
+                if (!isConflict(retryErr))
+                    throw retryErr;
+                // A second conflict: give up rather than loop. The client keeps the words in its pending set
+                // for the session and re-attempts on the next save, so the word is never silently dropped.
+                log.warn('dictionary.add_conflict', { editor: editor.email, words: additions });
+                return fail(409, { error: 'The dictionary changed while saving. It will retry on the next save.' });
+            }
+        }
+    }
+    /** Tidy: a light LLM copy-edit of the author's markdown (spec 2.1). The first remote model call in
+     *  the library, so this is the highest-blast-radius server action: untrusted content and the Anthropic
+     *  API key. The transport mirrors the media raw-body actions (a `text/plain` POST carrying JSON
+     *  `{ text, scope }`, the CSRF token in `X-Cairn-CSRF`, the response deserialized by the client), with
+     *  abort/timeout/deadline the media calls did not need: a tidy call to Sonnet on a full entry can run
+     *  many seconds.
+     *
+     *  Gate order (every refusal happens before the next step, so a refused request spends nothing):
+     *    1. validateCsrfHeader FIRST (the header witness is the authority for a raw-body POST).
+     *    2. requireSession (an expired session throws the manual-redirect 303 the client reads as status-0).
+     *    3. Read the key and config; refuse fail(503) if tidy is disabled or the key is missing.
+     *    4. Parse and bound the body; refuse fail(400) on malformed JSON, fail(413) on an over-long text.
+     *    5. Only then build the prompt and call the model, bounded by the Worker deadline.
+     *
+     *  The untrusted text rides as the user message, never interpolated into the system prompt; the
+     *  prompt's injection framing (Task 10) treats it as data. The API key never leaves the action: it is
+     *  not returned and not logged, and the log line carries no content. The action commits NOTHING, so a
+     *  failed, aborted, or refused tidy can never corrupt the entry; the diff is computed on the client
+     *  (Task 12), so the server stays a thin model-call boundary. */
+    async function tidyAction(event) {
+        // CSRF first: a raw-body (JSON) POST, so the header witness is the authority. A failed check refuses
+        // before the session read and before any model call.
+        if (!event.cookies || !validateCsrfHeader({ url: event.url, request: event.request, cookies: event.cookies })) {
+            return fail(403, { error: 'csrf' });
+        }
+        const editor = requireSession(event);
+        // Fail-fast: refuse before any model call if tidy is off or the key is missing. The model is read
+        // from config (a stated fact in this tier); a missing key is the "not enabled" refusal. No secret is
+        // ever returned or logged.
+        const tidy = runtime.tidy;
+        if (!tidy?.enabled) {
+            return fail(503, { error: 'Tidy is not enabled for this site.' });
+        }
+        const env = (event.platform?.env ?? {});
+        const apiKey = typeof env.ANTHROPIC_API_KEY === 'string' ? env.ANTHROPIC_API_KEY : '';
+        if (!apiKey) {
+            return fail(503, { error: 'Tidy is not configured: the Anthropic API key is missing.' });
+        }
+        // Parse and bound the body before the call. A malformed body refuses 400; an over-long text refuses
+        // 413 (tidy a selection instead), so no over-long input ever spends a token or risks the deadline.
+        let payload;
+        try {
+            payload = JSON.parse(await event.request.text());
+        }
+        catch {
+            return fail(400, { error: 'Could not read the tidy request.' });
+        }
+        const text = typeof payload.text === 'string' ? payload.text : '';
+        if (text.length === 0) {
+            return fail(400, { error: 'No text to tidy.' });
+        }
+        if (text.length > MAX_TIDY_CHARS) {
+            return fail(413, { error: 'This is too long to tidy at once. Select a passage and tidy that instead.' });
+        }
+        // Build the system prompt from the resolved conventions (Task 10). The prompt is built from config,
+        // never from the author's text, so the untrusted text cannot reshape the instructions.
+        const system = buildTidyPrompt(resolveTidyConventions(tidy.conventions));
+        const model = tidy.model || DEFAULT_TIDY_MODEL;
+        // max_tokens sized to comfortably exceed the input token count: a proofread runs at roughly input
+        // length, never lowballed. The character cap is ~6k input tokens, so this leaves generous headroom.
+        const maxTokens = 16_000;
+        // Bound the model call with the Worker's own deadline (shorter than the platform limit), so a slow
+        // call becomes a retryable fail(502) rather than a platform timeout. The client also drives its own
+        // AbortController (Cancel + a bounded timeout, Task 14); this action accepts an aborted request
+        // cleanly by mapping any abort to the same fail(502).
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), tidyTimeoutMs);
+        let message;
+        try {
+            const client = anthropicClient({ apiKey });
+            message = await client.messages.create({
+                model,
+                max_tokens: maxTokens,
+                system,
+                messages: [{ role: 'user', content: text }],
+            }, 
+            // The signal rides the request options, so the deadline timer above actually cancels the call.
+            { signal: controller.signal });
+        }
+        catch (err) {
+            // A deadline overrun, a client abort, or a model error (rate limit, overload, 5xx) all map to the
+            // retryable fail(502). The error string is not surfaced to the client (it may carry internal
+            // detail); the log line carries the editor and the kind, never the key or the content.
+            log.warn('tidy.error', { editor: editor.email, model, aborted: controller.signal.aborted });
+            return fail(502, { error: 'Tidy could not finish. Try again.' });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        // A model refusal (the streaming-classifier intervention) is a clean fail(422): the author's text is
+        // untouched, so the editor can leave it as-is.
+        if (message.stop_reason === 'refusal') {
+            log.warn('tidy.refused', { editor: editor.email, model });
+            return fail(422, { error: 'Tidy declined to edit this text.' });
+        }
+        // Read the output as plain text: concatenate the text blocks (a normal response is one). An empty
+        // result is treated as a model error rather than silently returning an empty document.
+        const corrected = message.content
+            .filter((block) => block.type === 'text' && typeof block.text === 'string')
+            .map((block) => block.text ?? '')
+            .join('');
+        if (corrected.length === 0) {
+            log.warn('tidy.empty', { editor: editor.email, model });
+            return fail(502, { error: 'Tidy returned nothing. Try again.' });
+        }
+        log.info('tidy.done', { editor: editor.email, model: message.model, usage: message.usage });
+        return { corrected, model: message.model, usage: message.usage };
+    }
+    return { layoutLoad, indexRedirect, listLoad, mediaLibraryLoad, settingsLoad, settingsSave, createAction, editLoad, saveAction, publishAction, publishAllAction, discardAction, deleteAction, listDeleteAction, renameAction, uploadAction, mediaDeleteAction, mediaBulkDelete, mediaOrphanScan, mediaPurgeOrphans, mediaUpdateAction, mediaReplacePreview, mediaReplaceApply, mediaAltPreview, mediaAltApply, addDictionaryWord, tidyAction, mintToken };
 }
 /** The cap, in characters, on the stored alt text. The human fields are display copy, not content,
  *  so a generous cap rejects only abuse-scale input. */