@minamocms/framework 0.0.0-stage → 0.10.1

package/dist/services/post-urls.js

@@ -0,0 +1,27 @@
+// Pure, filesystem-free mapping between a /blog/<slug> URL and a
+// post's path relative to postsRoot. Unlike pages' arbitrary nested
+// paths (about.json beside a sibling about/ directory), posts are
+// flat only - a URL with more than one segment after /blog/ is never
+// a valid post URL, enforced here rather than left to sanitisePath.
+const BLOG_PREFIX = '/blog/';
+// /blog is a permanently reserved namespace: both "/blog" itself (no
+// slug) and every "/blog/..." URL are recognised here, so a caller can
+// route the whole namespace to post resolution before ever checking
+// for a page, matching the confirmed reserved-namespace decision.
+export function isBlogUrl(url) {
+    return url === '/blog' || url.startsWith(BLOG_PREFIX);
+}
+export function urlToPostPath(url) {
+    if (!url.startsWith(BLOG_PREFIX)) {
+        return null;
+    }
+    const slug = url.slice(BLOG_PREFIX.length);
+    if (slug === '' || slug.includes('/')) {
+        return null;
+    }
+    return `${slug}.json`;
+}
+export function postPathToUrl(relativePostPath) {
+    const withoutExtension = relativePostPath.replace(/\.json$/, '');
+    return `${BLOG_PREFIX}${withoutExtension}`;
+}

package/dist/services/prepared-operation.d.ts

@@ -0,0 +1,4 @@
+export interface PreparedOperation {
+    paths: string[];
+    undo: () => unknown[];
+}

package/dist/services/prepared-operation.js

@@ -0,0 +1 @@
+export {};

package/dist/services/publish.d.ts

@@ -0,0 +1,15 @@
+import type { SiteConfig } from '../config.ts';
+import type { CommitAuthor } from './git.ts';
+import type { PreparedOperation } from './prepared-operation.ts';
+import type { ThemeSchemas } from './validation.ts';
+export type PublishReason = 'validation-failed' | 'draft-not-found' | 'page-not-found' | 'duplicate-path' | 'write-failed' | 'commit-failed' | 'rollback-failed';
+export declare class PublishError extends Error {
+    readonly reason: PublishReason;
+    constructor(reason: PublishReason, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare function preparePublishDrafts(config: SiteConfig, themeSchemas: ThemeSchemas, relativePaths: string[]): PreparedOperation;
+export declare function publishDrafts(config: SiteConfig, themeSchemas: ThemeSchemas, relativePaths: string[], message: string, author: CommitAuthor): Promise<void>;
+export declare function unpublishPage(config: SiteConfig, relativePath: string, message: string, author: CommitAuthor): Promise<void>;
+export declare function publishPage(config: SiteConfig, relativePath: string, message: string, author: CommitAuthor): Promise<void>;

package/dist/services/publish.js

@@ -0,0 +1,313 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { GitOperationError, commitPaths } from "./git.js";
+import { sanitisePath } from "./path-safety.js";
+import { loadRedirects, removeRedirectForPath, serialiseRedirects } from "./redirects.js";
+import { pagePathToUrl } from "./urls.js";
+import { validateContent } from "./validation.js";
+import { enqueue } from "./write-queue.js";
+import { reindexInBackground } from "./reindex-on-write.js";
+const PAGES_PREFIX = 'pages/';
+// Mirrors delete-content.ts's urlForDeletedEntry - a tiny duplicated
+// helper, not a shared abstraction. Returns null for anything else
+// (menus have no public URL, so redirect semantics don't apply).
+function urlForPublishedEntry(relativePath) {
+    if (relativePath.startsWith(PAGES_PREFIX)) {
+        return pagePathToUrl(relativePath.slice(PAGES_PREFIX.length));
+    }
+    return null;
+}
+export class PublishError extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.name = 'PublishError';
+        this.reason = reason;
+    }
+}
+// Hand-rolled fs snapshot/restore, not a database transaction
+// (deliberate, given the minimal-dependency policy). Attempts every
+// restore even if one fails, rather than aborting on the first error,
+// and reports every failure to the caller: a filesystem cannot give a
+// true atomicity guarantee (disk full, permissions changing mid-flight
+// are real residual risks), so the honest contract is "restores
+// everything it can, and is loud if it can't" rather than a silent
+// best-effort.
+function rollback(snapshots, redirects) {
+    const failures = [];
+    for (const snapshot of snapshots) {
+        try {
+            if (snapshot.liveExisted) {
+                writeFileSync(snapshot.livePath, snapshot.liveOriginal);
+            }
+            else if (existsSync(snapshot.livePath)) {
+                unlinkSync(snapshot.livePath);
+            }
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        try {
+            mkdirSync(dirname(snapshot.draftPath), { recursive: true });
+            writeFileSync(snapshot.draftPath, snapshot.draftOriginal);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    if (redirects) {
+        try {
+            if (redirects.existed) {
+                writeFileSync(redirects.path, redirects.original);
+            }
+            else if (existsSync(redirects.path)) {
+                unlinkSync(redirects.path);
+            }
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    return failures;
+}
+function rollbackOrRethrow(snapshots, cause, redirects) {
+    const failures = rollback(snapshots, redirects);
+    if (failures.length > 0) {
+        throw new PublishError('rollback-failed', 'Publish failed and rolling back afterwards also failed; the working tree may be inconsistent and needs manual inspection', { cause });
+    }
+    const reason = cause instanceof GitOperationError ? 'commit-failed' : 'write-failed';
+    const message = cause instanceof Error ? cause.message : String(cause);
+    throw new PublishError(reason, `Publish failed: ${message}`, { cause });
+}
+// Validates and writes everything a publish needs, stopping short of
+// the commit itself - used both by the standalone publishDraftsJob
+// (which commits immediately after) and by batch.ts (which accumulates
+// this alongside other operations and commits once for the whole
+// batch). A write-phase failure is caught and rolled back here,
+// inside prepare itself - never left for the caller to discover -
+// so prepare either fully succeeds or fully undoes itself before
+// throwing.
+export function preparePublishDrafts(config, themeSchemas, relativePaths) {
+    // Reject duplicates up front: without this, a repeated path's live-
+    // file snapshot would capture already-overwritten state instead of
+    // the true original, corrupting any later rollback.
+    const seen = new Set();
+    for (const relativePath of relativePaths) {
+        if (seen.has(relativePath)) {
+            throw new PublishError('duplicate-path', `Duplicate path in publish request: "${relativePath}"`);
+        }
+        seen.add(relativePath);
+    }
+    // Validate every path before writing anything. Nothing is written
+    // during this pass, so "no files change and no commit is created" on
+    // any failure (C6) falls out of ordering, not cleanup logic. Safe
+    // because the write queue serialises everything: no other job can
+    // interleave and change a draft between this pass and the write pass.
+    const entries = [];
+    for (const relativePath of relativePaths) {
+        const draftPath = sanitisePath(config.draftsRoot, relativePath);
+        const livePath = sanitisePath(config.contentRoot, relativePath);
+        let draftContent;
+        try {
+            draftContent = readFileSync(draftPath);
+        }
+        catch {
+            throw new PublishError('draft-not-found', `No draft found at "${relativePath}"`);
+        }
+        const parsed = JSON.parse(draftContent.toString('utf-8'));
+        const result = validateContent(relativePath, parsed, themeSchemas);
+        if (!result.valid) {
+            throw new PublishError('validation-failed', `Draft at "${relativePath}" failed validation: ${JSON.stringify(result.errors)}`);
+        }
+        entries.push({ relativePath, draftPath, livePath, draftContent });
+    }
+    const snapshots = [];
+    let redirectsSnapshot;
+    try {
+        for (const entry of entries) {
+            let liveExisted = false;
+            let liveOriginal;
+            try {
+                liveOriginal = readFileSync(entry.livePath);
+                liveExisted = true;
+            }
+            catch {
+                liveExisted = false;
+            }
+            snapshots.push({
+                livePath: entry.livePath,
+                liveExisted,
+                liveOriginal,
+                draftPath: entry.draftPath,
+                draftOriginal: entry.draftContent,
+            });
+            mkdirSync(dirname(entry.livePath), { recursive: true });
+            writeFileSync(entry.livePath, entry.draftContent);
+            unlinkSync(entry.draftPath);
+        }
+        // E5 (publish half): a brand-new live page may supersede a stale
+        // redirect recorded at its own URL (checklist wording: "creating a
+        // page at a path that has a redirect entry"). Only applies to page
+        // content - redirect semantics aren't defined for menus (no public
+        // URL), so anything else is skipped silently via
+        // urlForPublishedEntry's null return.
+        const qualifyingUrls = entries
+            .map((entry) => urlForPublishedEntry(entry.relativePath))
+            .filter((url) => url !== null);
+        if (qualifyingUrls.length > 0) {
+            const existed = existsSync(config.redirectsPath);
+            const original = existed ? readFileSync(config.redirectsPath, 'utf-8') : '';
+            let entriesAfterRemoval = loadRedirects(config).entries;
+            for (const url of qualifyingUrls) {
+                entriesAfterRemoval = removeRedirectForPath(entriesAfterRemoval, url);
+            }
+            const updated = serialiseRedirects(entriesAfterRemoval);
+            if (updated !== (existed ? original : '')) {
+                writeFileSync(config.redirectsPath, updated);
+                redirectsSnapshot = { path: config.redirectsPath, existed, original };
+            }
+        }
+    }
+    catch (error) {
+        // A write-phase failure: roll back immediately, inside prepare
+        // itself. cause here can never be a GitOperationError (commitPaths
+        // hasn't been called yet), so rollbackOrRethrow's own
+        // instanceof-based classification correctly resolves to
+        // 'write-failed', never 'commit-failed'.
+        rollbackOrRethrow(snapshots, error, redirectsSnapshot);
+    }
+    // Only the live paths (and redirects.json, if it changed) are ever
+    // staged: drafts are never git-tracked in the first place (saves
+    // don't commit, per C2), so a draft's deletion has no git-visible
+    // effect at all. Including it in the commit would fail outright,
+    // since `git add` on a path that is both absent from disk and was
+    // never tracked is a hard error ("pathspec did not match any
+    // files"), not a silent no-op.
+    const paths = entries.map((entry) => entry.livePath);
+    if (redirectsSnapshot) {
+        paths.push(redirectsSnapshot.path);
+    }
+    return { paths, undo: () => rollback(snapshots, redirectsSnapshot) };
+}
+async function publishDraftsJob(config, themeSchemas, relativePaths, message, author) {
+    const { paths, undo } = preparePublishDrafts(config, themeSchemas, relativePaths);
+    try {
+        // commitPaths gives its own all-or-nothing contract for git staging,
+        // so a failure here only ever leaves filesystem state for this
+        // catch block to worry about, never git index state.
+        commitPaths(config.siteRoot, paths, message, author);
+    }
+    catch (error) {
+        const failures = undo();
+        if (failures.length > 0) {
+            throw new PublishError('rollback-failed', 'Publish failed and rolling back afterwards also failed; the working tree may be inconsistent and needs manual inspection', { cause: error });
+        }
+        // Always commit-failed here, structurally: prepare already
+        // succeeded (no write-phase error), so anything caught in this try
+        // can only have come from commitPaths itself.
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new PublishError('commit-failed', `Publish failed: ${errorMessage}`, { cause: error });
+    }
+}
+async function unpublishPageJob(config, relativePath, message, author) {
+    const livePath = sanitisePath(config.contentRoot, relativePath);
+    let original;
+    try {
+        original = readFileSync(livePath);
+    }
+    catch {
+        throw new PublishError('page-not-found', `No live page found at "${relativePath}"`);
+    }
+    const parsed = JSON.parse(original.toString('utf-8'));
+    parsed.published = false;
+    const updated = Buffer.from(JSON.stringify(parsed, null, 2));
+    // Unpublish only ever touches one file and never a draft, so it gets
+    // its own minimal inline restore rather than routing through the
+    // two-file publish rollback() above, which would need an unused
+    // draft slot to fit the same shape for no benefit.
+    try {
+        writeFileSync(livePath, updated);
+        commitPaths(config.siteRoot, [livePath], message, author);
+    }
+    catch (error) {
+        try {
+            writeFileSync(livePath, original);
+        }
+        catch {
+            throw new PublishError('rollback-failed', 'Unpublish failed and rolling back afterwards also failed; the working tree may be inconsistent and needs manual inspection', { cause: error });
+        }
+        const reason = error instanceof GitOperationError ? 'commit-failed' : 'write-failed';
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new PublishError(reason, `Unpublish failed: ${errorMessage}`, { cause: error });
+    }
+}
+// The exact twin of unpublishPageJob above, flipping the same flag the
+// other way: reads the live file, sets published true, commits. Kept as
+// its own job rather than a parameterised shared one - the two read
+// identically but say opposite things, and a boolean argument at every
+// call site ("publishPage(config, path, true)") reads far worse than
+// two named functions.
+//
+// Deliberately does NOT validate against the theme schemas, matching
+// unpublish rather than publishDrafts: this only ever touches content
+// that is already live, and was therefore already validated when it was
+// published in the first place. publishDrafts validates because it
+// promotes a draft, which may never have been checked before.
+//
+// Like unpublish, never touches a draft. A page with unpublished edits
+// pending keeps them, and this only changes whether what is already
+// live is publicly visible.
+async function publishPageJob(config, relativePath, message, author) {
+    const livePath = sanitisePath(config.contentRoot, relativePath);
+    let original;
+    try {
+        original = readFileSync(livePath);
+    }
+    catch {
+        throw new PublishError('page-not-found', `No live page found at "${relativePath}"`);
+    }
+    const parsed = JSON.parse(original.toString('utf-8'));
+    parsed.published = true;
+    const updated = Buffer.from(JSON.stringify(parsed, null, 2));
+    // Same minimal inline restore unpublishPageJob uses, and for the same
+    // reason - one file, no draft, so the two-file publish rollback()
+    // above would need an unused draft slot for no benefit.
+    try {
+        writeFileSync(livePath, updated);
+        commitPaths(config.siteRoot, [livePath], message, author);
+    }
+    catch (error) {
+        try {
+            writeFileSync(livePath, original);
+        }
+        catch {
+            throw new PublishError('rollback-failed', 'Publishing this page failed and rolling back afterwards also failed; the working tree may be inconsistent and needs manual inspection', { cause: error });
+        }
+        const reason = error instanceof GitOperationError ? 'commit-failed' : 'write-failed';
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new PublishError(reason, `Publishing this page failed: ${errorMessage}`, { cause: error });
+    }
+}
+export function publishDrafts(config, themeSchemas, relativePaths, message, author) {
+    const result = enqueue(() => publishDraftsJob(config, themeSchemas, relativePaths, message, author));
+    // Only on success - a failed publish changed nothing, so there's
+    // nothing to reindex. Chained onto `result` rather than awaited here:
+    // by the time this callback runs, the write-queue's own tail has
+    // already advanced past this job, so reindexInBackground's own
+    // enqueue()d rebuild queues cleanly behind it (see that function's
+    // own comment on why calling it any earlier would deadlock).
+    result.then(() => reindexInBackground(config), () => undefined);
+    return result;
+}
+export function unpublishPage(config, relativePath, message, author) {
+    const result = enqueue(() => unpublishPageJob(config, relativePath, message, author));
+    result.then(() => reindexInBackground(config), () => undefined);
+    return result;
+}
+// Twin of unpublishPage - same queue, same background reindex (a page
+// becoming visible changes the index exactly as much as one leaving it).
+export function publishPage(config, relativePath, message, author) {
+    const result = enqueue(() => publishPageJob(config, relativePath, message, author));
+    result.then(() => reindexInBackground(config), () => undefined);
+    return result;
+}

package/dist/services/rate-limit-config.d.ts

@@ -0,0 +1,9 @@
+export declare const WRITE_ROUTE_RATE_LIMIT: {
+    rateLimit: {};
+};
+export declare const NO_AUTH_ROUTE_RATE_LIMIT: {
+    rateLimit: {
+        max: number;
+        timeWindow: number;
+    };
+};

package/dist/services/rate-limit-config.js

@@ -0,0 +1,22 @@
+// Shared rate-limit config markers for route options objects
+// (Fastify's config: { rateLimit: {...} } opt-in shape, consumed by
+// @fastify/rate-limit registered with global: false in server.ts).
+// One constant per tier, not ad-hoc literals at each of the ~10 call
+// sites, both for DRYness and so the structural test
+// (test/static/static-analysis.test.ts) has something unambiguous to
+// grep for.
+// An empty per-route override: @fastify/rate-limit (registered with
+// global: false in server.ts) still requires each route to opt in via
+// this marker, but an empty {} inherits the plugin's own registration-
+// level max/timeWindow - which server.ts sets from serverConfig.rateLimit
+// (site.config.json-configurable, defaulting to 60/min - see
+// server-config.ts). Verified empirically before relying on it: a
+// route's own config.rateLimit only needs *something* present to opt
+// in, not a duplicated copy of the numbers.
+export const WRITE_ROUTE_RATE_LIMIT = { rateLimit: {} };
+// Generous defense-in-depth against basic scanning/abuse of the
+// endpoints reachable with zero credentials (GET /v1/capabilities,
+// GET /v1/search), not a meaningful throttle on legitimate use - a
+// real front-end calling search on every keystroke of a live search
+// box should never realistically hit this.
+export const NO_AUTH_ROUTE_RATE_LIMIT = { rateLimit: { max: 300, timeWindow: 60000 } };

package/dist/services/redirects.d.ts

@@ -0,0 +1,27 @@
+import type { SiteConfig } from '../config.ts';
+export type RedirectReason = 'redirect-cycle' | 'malformed-file' | 'invalid-target';
+export declare class RedirectError extends Error {
+    readonly reason: RedirectReason;
+    constructor(reason: RedirectReason, message: string);
+}
+export interface RedirectEntry {
+    from: string;
+    to: string;
+    note?: string;
+}
+export interface Redirects {
+    schemaVersion: number;
+    entries: RedirectEntry[];
+}
+export declare const CURRENT_REDIRECTS_SCHEMA_VERSION = 1;
+export declare function loadRedirects(config: SiteConfig): Redirects;
+export declare function loadRedirectsStrict(config: SiteConfig): Redirects;
+export declare function serialiseRedirects(entries: RedirectEntry[]): string;
+export declare function buildRedirectLookup(entries: RedirectEntry[]): Map<string, string>;
+export interface AddRedirectResult {
+    entries: RedirectEntry[];
+    retargeted: RedirectEntry[];
+}
+export declare function addRedirect(entries: RedirectEntry[], from: string, to: string, note?: string): AddRedirectResult;
+export declare function removeRedirectForPath(entries: RedirectEntry[], url: string): RedirectEntry[];
+export declare function isValidRedirectTarget(value: string): boolean;

package/dist/services/redirects.js

@@ -0,0 +1,175 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { validateRedirects } from "./validation.js";
+export class RedirectError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'RedirectError';
+        this.reason = reason;
+    }
+}
+export const CURRENT_REDIRECTS_SCHEMA_VERSION = 1;
+const EMPTY_REDIRECTS = { schemaVersion: CURRENT_REDIRECTS_SCHEMA_VERSION, entries: [] };
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// The old shape (pre-Group M) was a flat { from: to } map, with no
+// schemaVersion or entries key at all. Identified purely by the
+// ABSENCE of both new-shape keys - a file that has an `entries` key is
+// always treated as new-shape from here on, even if malformed, so a
+// corrupt new-shape file is never silently reinterpreted as an empty
+// old-shape map (which would look like "no redirects" and risk a
+// write-time caller clobbering real data - see loadRedirectsStrict).
+function isOldFlatShape(value) {
+    return !('schemaVersion' in value) && !('entries' in value);
+}
+function upgradeOldFlatShape(value) {
+    const entries = Object.entries(value)
+        .filter((pair) => typeof pair[1] === 'string')
+        .map(([from, to]) => ({ from, to }));
+    return { schemaVersion: CURRENT_REDIRECTS_SCHEMA_VERSION, entries };
+}
+// Read-time loader, used by public request handling (resolve-url.ts,
+// resolve-blog-url.ts) as well as by write paths before they call
+// loadRedirectsStrict for the extra guarantee. Graceful-empty on any
+// failure - including a malformed new-shape file - matching
+// theme-schemas.ts's established pattern: a corrupt redirects.json
+// must never crash public page serving, it should just mean redirects
+// don't resolve until the file is fixed.
+export function loadRedirects(config) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(config.redirectsPath, 'utf-8'));
+    }
+    catch {
+        return EMPTY_REDIRECTS;
+    }
+    if (!isPlainObject(raw)) {
+        return EMPTY_REDIRECTS;
+    }
+    if (isOldFlatShape(raw)) {
+        return upgradeOldFlatShape(raw);
+    }
+    const result = validateRedirects(raw);
+    if (!result.valid) {
+        return EMPTY_REDIRECTS;
+    }
+    return raw;
+}
+// Stricter sibling of loadRedirects, for write paths only (manage-
+// redirects.ts, and any other future direct redirect writer). Unlike
+// the graceful read-time loader, this throws on a malformed new-shape
+// file instead of silently treating it as empty - a write that follows
+// an incorrectly-"empty" load would overwrite and destroy whatever
+// real entries the file actually held, which is a much worse outcome
+// for a write than for a page render.
+export function loadRedirectsStrict(config) {
+    if (!existsSync(config.redirectsPath)) {
+        return EMPTY_REDIRECTS;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(config.redirectsPath, 'utf-8'));
+    }
+    catch {
+        throw new RedirectError('malformed-file', 'redirects.json exists but is not valid JSON; refusing to write until it is fixed');
+    }
+    if (!isPlainObject(raw)) {
+        throw new RedirectError('malformed-file', 'redirects.json exists but is not a JSON object');
+    }
+    if (isOldFlatShape(raw)) {
+        return upgradeOldFlatShape(raw);
+    }
+    const result = validateRedirects(raw);
+    if (!result.valid) {
+        throw new RedirectError('malformed-file', `redirects.json exists but does not match the expected shape: ${result.errors.map((e) => e.message).join(', ')}`);
+    }
+    return raw;
+}
+export function serialiseRedirects(entries) {
+    const redirects = { schemaVersion: CURRENT_REDIRECTS_SCHEMA_VERSION, entries };
+    return JSON.stringify(redirects, null, 2);
+}
+export function buildRedirectLookup(entries) {
+    return new Map(entries.map((entry) => [entry.from, entry.to]));
+}
+// Collapses chains at write time. Walks `to` forward through any
+// existing chain to its final destination (not just one hop), then
+// rewrites every existing entry that pointed at the just-added `from`
+// to point at that final destination too, so old entries stay
+// collapsed alongside the new one. Also handles updating an existing
+// entry in place: if `from` already has an entry, it is replaced.
+export function addRedirect(entries, from, to, note) {
+    const byFrom = new Map(entries.map((entry) => [entry.from, entry]));
+    let target = to;
+    const visited = new Set();
+    for (;;) {
+        const next = byFrom.get(target)?.to;
+        if (next === undefined) {
+            break;
+        }
+        if (visited.has(target)) {
+            throw new RedirectError('redirect-cycle', `redirects.json already contains a cycle reachable from "${to}"`);
+        }
+        visited.add(target);
+        target = next;
+    }
+    // The walk above only detects a cycle among *pre-existing* entries.
+    // A walk that terminates normally can still resolve back to `from`
+    // itself (e.g. adding "/b" -> "/a" when "/a" -> "/b" already exists:
+    // the walk hits "/b", which has no further mapping, and stops without
+    // revisiting anything) - that's a self-referential redirect, checked
+    // separately here.
+    if (target === from) {
+        throw new RedirectError('redirect-cycle', `Adding redirect "${from}" -> "${to}" would create a cycle (resolves back to "${from}")`);
+    }
+    const retargeted = [];
+    const updated = [];
+    for (const entry of entries) {
+        if (entry.from === from) {
+            continue;
+        }
+        if (entry.to === from) {
+            const rewritten = { ...entry, to: target };
+            retargeted.push(rewritten);
+            updated.push(rewritten);
+            continue;
+        }
+        updated.push(entry);
+    }
+    const newEntry = note !== undefined ? { from, to: target, note } : { from, to: target };
+    updated.push(newEntry);
+    return { entries: updated, retargeted };
+}
+export function removeRedirectForPath(entries, url) {
+    if (!entries.some((entry) => entry.from === url)) {
+        return entries;
+    }
+    return entries.filter((entry) => entry.from !== url);
+}
+// Checked by char code rather than a regex control-character class, to
+// avoid embedding literal control characters in source.
+function hasControlCharacter(value) {
+    for (let i = 0; i < value.length; i += 1) {
+        const code = value.charCodeAt(i);
+        if (code <= 0x1f || code === 0x7f) {
+            return true;
+        }
+    }
+    return false;
+}
+// Shared by manage-redirects.ts (POST/PUT /v1/redirects) and the
+// retroactive fix to delete-content.ts's client-supplied redirectTo -
+// both must enforce the same rule on a redirect target, or the two
+// write paths would silently disagree on what's allowed into the same
+// file. Internal-only: must start with a single "/", never a scheme,
+// host, or protocol-relative "//" - closes an open-redirect vector.
+// Control characters are rejected regardless of the internal/external
+// question, since public.ts writes this value directly into the
+// Location response header.
+export function isValidRedirectTarget(value) {
+    if (value.length === 0 || hasControlCharacter(value)) {
+        return false;
+    }
+    return value.startsWith('/') && !value.startsWith('//');
+}

package/dist/services/reindex-on-write.d.ts

@@ -0,0 +1,3 @@
+import type { SiteConfig } from '../config.ts';
+export declare function reindexInBackground(config: SiteConfig): void;
+export declare function reindexOnBootIfMissing(config: SiteConfig): void;

package/dist/services/reindex-on-write.js

@@ -0,0 +1,30 @@
+import { rebuildIndex, rebuildIndexIfMissing } from "../search/rebuild-index.js";
+// Search is a derived, disposable index (constraint 3) - previously
+// nothing ever rebuilt it except a caller manually hitting
+// POST /v1/search/rebuild, so GET /search.json stayed empty forever on
+// a fresh site and stale forever after a real edit. This is the one
+// place that closes that gap: called after a content-affecting write's
+// own enqueue()d promise has already resolved.
+//
+// Deliberately fire-and-forget, never awaited by the caller: rebuildIndex
+// is itself enqueue()d internally (search/rebuild-index.ts) - awaiting it
+// from inside the very job whose own completion is what let this run
+// would deadlock (routes/search.ts's own comment describes the same
+// hazard for a second, nested enqueue() call). A failed reindex must
+// also never surface as a failure of the write that triggered it - the
+// write already succeeded, and the index is rebuildable from content at
+// any time, so a logged-and-swallowed failure here is the correct
+// severity, not a thrown error.
+export function reindexInBackground(config) {
+    void rebuildIndex(config).catch((error) => {
+        console.error('Background search reindex failed:', error);
+    });
+}
+// startServer's own boot-time call - see rebuildIndexIfMissing's own
+// comment for why this is conditional (existsSync), unlike the
+// unconditional reindexInBackground above.
+export function reindexOnBootIfMissing(config) {
+    void rebuildIndexIfMissing(config).catch((error) => {
+        console.error('Background search reindex failed:', error);
+    });
+}

package/dist/services/resolve-blog-url.d.ts

@@ -0,0 +1,11 @@
+import type { SiteConfig } from '../config.ts';
+export type ResolvedBlogUrl = {
+    kind: 'post';
+    relativePath: string;
+} | {
+    kind: 'redirect';
+    to: string;
+} | {
+    kind: 'not-found';
+};
+export declare function resolveBlogUrl(config: SiteConfig, url: string): ResolvedBlogUrl;