@minamocms/framework 0.0.0-stage → 0.10.2

package/dist/services/links.js

@@ -0,0 +1,169 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { listFilesRecursively } from "./fs-walk.js";
+import { sanitisePath } from "./path-safety.js";
+import { siteSettingsPath } from "./site-settings.js";
+import { pagePathToUrl } from "./urls.js";
+// Internal links: where content points at the site's own pages, found
+// and rewritten without the theme's schemas. A link is any text value
+// that is wholly a site path ("/about", "/about#team") - what a link
+// field, a menu item or a setting stores - and any href="..." inside a
+// longer text value, which is how rich text stores one. Keeping links
+// as plain paths was the owner's choice over permanent page IDs, so
+// content stays readable; this is what keeps those paths correct.
+// The page a link points at: its path without ?query or #fragment, and
+// without a trailing slash (except the home page's "/"). null for
+// anything that isn't a link to a page here - an external address,
+// mailto:/tel:, a bare #anchor, protocol-relative //host, a media or
+// theme asset, or a file such as /robots.txt.
+export function linkTarget(href) {
+    const trimmed = href.trim();
+    if (!trimmed.startsWith('/') || trimmed.startsWith('//') || /\s/.test(trimmed)) {
+        return null;
+    }
+    const path = trimmed.replace(/[?#].*$/, '');
+    if (path.startsWith('/media/') || path.startsWith('/assets/') || /\.[A-Za-z0-9]+$/.test(path)) {
+        return null;
+    }
+    return path.length > 1 ? path.replace(/\/+$/, '') : path;
+}
+const HREF = /(href\s*=\s*)(["'])(.*?)\2/gi;
+// Every link in a piece of content, as written (not yet reduced to a
+// target), in document order.
+export function collectLinks(value) {
+    const links = [];
+    const visit = (node) => {
+        if (typeof node === 'string') {
+            if (linkTarget(node) !== null) {
+                links.push(node);
+            }
+            else if (node.includes('href')) {
+                for (const match of node.matchAll(HREF)) {
+                    links.push(match[3]);
+                }
+            }
+        }
+        else if (Array.isArray(node)) {
+            node.forEach(visit);
+        }
+        else if (node !== null && typeof node === 'object') {
+            Object.values(node).forEach(visit);
+        }
+    };
+    visit(value);
+    return links;
+}
+// A link moved from one page path to another: the page itself, or
+// anything under it (a child page), keeping whatever followed the path
+// (?query, #fragment, a trailing slash). null when the link isn't to a
+// moved page.
+function moveLink(href, from, to) {
+    const target = linkTarget(href);
+    if (target === null || (target !== from && !target.startsWith(`${from}/`))) {
+        return null;
+    }
+    const leading = href.length - href.trimStart().length;
+    const start = href.indexOf(target, leading);
+    return href.slice(0, start) + to + href.slice(start + from.length);
+}
+// A copy of some content with every link to `from` (or a page under it)
+// pointing at `to` instead, and whether anything changed.
+export function rewriteLinks(value, from, to) {
+    let changed = false;
+    const visit = (node) => {
+        if (typeof node === 'string') {
+            const moved = moveLink(node, from, to);
+            if (moved !== null) {
+                changed = true;
+                return moved;
+            }
+            if (!node.includes('href')) {
+                return node;
+            }
+            return node.replace(HREF, (whole, prefix, quote, href) => {
+                const next = moveLink(href, from, to);
+                if (next === null) {
+                    return whole;
+                }
+                changed = true;
+                return `${prefix}${quote}${next}${quote}`;
+            });
+        }
+        if (Array.isArray(node)) {
+            return node.map(visit);
+        }
+        if (node !== null && typeof node === 'object') {
+            return Object.fromEntries(Object.entries(node).map(([key, child]) => [key, visit(child)]));
+        }
+        return node;
+    };
+    const next = visit(value);
+    return { value: next, changed };
+}
+// Every file whose links matter: live pages, drafts, menus and the site
+// settings. Each file is sanitisePath'd under its agent-configured root.
+export function linkSources(config) {
+    const sources = [];
+    const add = (kind, root, relativeTo, prefix) => {
+        if (!existsSync(root)) {
+            return;
+        }
+        for (const relative of listFilesRecursively(root, relativeTo, '.json')) {
+            sources.push({ kind, path: `${prefix}${relative}`, file: sanitisePath(relativeTo, relative) });
+        }
+    };
+    add('page', config.pagesRoot, config.contentRoot, '');
+    add('draft', config.draftsRoot, config.draftsRoot, 'drafts/');
+    add('menu', config.menusRoot, config.contentRoot, '');
+    const settings = siteSettingsPath(config);
+    if (existsSync(settings)) {
+        sources.push({ kind: 'settings', path: 'settings.json', file: settings });
+    }
+    return sources;
+}
+function readJson(file) {
+    try {
+        return JSON.parse(readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+function labelOf(source, content) {
+    if (source.kind === 'settings') {
+        return 'Site settings';
+    }
+    const { title, name } = (content ?? {});
+    if (typeof title === 'string' && title.trim() !== '') {
+        return title;
+    }
+    if (typeof name === 'string' && name.trim() !== '') {
+        return name;
+    }
+    return source.path;
+}
+function pageUrlOf(source) {
+    const relative = source.kind === 'page' ? source.path : source.kind === 'draft' ? source.path.slice('drafts/'.length) : null;
+    return relative !== null && relative.startsWith('pages/') ? pagePathToUrl(relative.slice('pages/'.length)) : undefined;
+}
+// Everything that links to one page (exactly that page, not ones under
+// it): what the admin lists before a delete. A page's own links to
+// itself don't count.
+export function findReferences(config, to) {
+    const target = linkTarget(to);
+    if (target === null) {
+        return [];
+    }
+    const references = [];
+    for (const source of linkSources(config)) {
+        const url = pageUrlOf(source);
+        if (url === target) {
+            continue;
+        }
+        const content = readJson(source.file);
+        const hrefs = collectLinks(content).filter((href) => linkTarget(href) === target);
+        if (hrefs.length > 0) {
+            references.push({ kind: source.kind, path: source.path, label: labelOf(source, content), ...(url ? { url } : {}), hrefs });
+        }
+    }
+    return references;
+}

package/dist/services/manage-menus.d.ts

@@ -0,0 +1,15 @@
+import type { SiteConfig } from '../config.ts';
+import type { CommitAuthor } from './git.ts';
+export type ManageMenuReason = 'validation-failed' | 'not-found' | 'conflict' | 'write-failed' | 'commit-failed' | 'rollback-failed';
+export declare class ManageMenuError extends Error {
+    readonly reason: ManageMenuReason;
+    constructor(reason: ManageMenuReason, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare function saveMenu(config: SiteConfig, relativePath: string, content: unknown, expectedEtag: string, message: string, author: CommitAuthor): Promise<string>;
+export interface RenameMenuResult {
+    etag: string;
+    staleThemeReferences: string[];
+}
+export declare function renameMenu(config: SiteConfig, from: string, to: string, expectedEtag: string, message: string, author: CommitAuthor): Promise<RenameMenuResult>;

package/dist/services/manage-menus.js

@@ -0,0 +1,138 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { ContentReadError, readContentFile } from "./content-read.js";
+import { computeEtag, etagsMatch } from "./etag.js";
+import { commitPaths } from "./git.js";
+import { findMenuReferences, isValidMenuHandle } from "./menu-references.js";
+import { sanitisePath } from "./path-safety.js";
+import { validateMenu } from "./validation.js";
+import { enqueue } from "./write-queue.js";
+export class ManageMenuError extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.name = 'ManageMenuError';
+        this.reason = reason;
+    }
+}
+// Mirrors drafts.ts's readCurrentEtag, narrowed to a single root since
+// menus have no draft state to prefer over live.
+function readCurrentEtag(config, relativePath) {
+    try {
+        return readContentFile(config.menusRoot, relativePath).etag;
+    }
+    catch (error) {
+        if (!(error instanceof ContentReadError) || error.reason !== 'not-found') {
+            throw error;
+        }
+        return null;
+    }
+}
+async function saveMenuJob(config, relativePath, content, expectedEtag, message, author) {
+    // menusRoot is optional, unlike pagesRoot - a site that has never
+    // had a menu has no content/menus/ at all. sanitisePath unconditionally
+    // realpaths its root argument, so it must exist before the very
+    // first menu is ever created, or a legitimate first-write crashes
+    // with a raw ENOENT instead of just creating the directory.
+    mkdirSync(config.menusRoot, { recursive: true });
+    const menuPath = sanitisePath(config.menusRoot, relativePath);
+    // The If-Match check happens here, inside the queued job, never at
+    // the route layer before enqueuing - same TOCTOU reasoning as
+    // drafts.ts's saveDraftJob (a route-layer check-then-enqueue has a
+    // real, empirically-verified gap; the same check run inside the job
+    // does not).
+    const currentEtag = readCurrentEtag(config, relativePath);
+    if (currentEtag !== null && !etagsMatch(currentEtag, expectedEtag)) {
+        throw new ManageMenuError('conflict', `If-Match "${expectedEtag}" does not match the current ETag for "${relativePath}"`);
+    }
+    // currentEtag === null means no menu exists yet at this path (a
+    // brand-new menu) - matches saveDraftJob's own precedent of skipping
+    // the comparison for a wholly new resource.
+    const result = validateMenu(content);
+    if (!result.valid) {
+        throw new ManageMenuError('validation-failed', `Menu at "${relativePath}" failed validation: ${JSON.stringify(result.errors)}`);
+    }
+    const existedBefore = existsSync(menuPath);
+    const originalBytes = existedBefore ? readFileSync(menuPath) : null;
+    mkdirSync(dirname(menuPath), { recursive: true });
+    const bytes = Buffer.from(JSON.stringify(content, null, 2));
+    writeFileSync(menuPath, bytes);
+    // No draft state (Group N: menus behave like redirects.json) -
+    // commits immediately, mirroring manage-redirects.ts's shape, rather
+    // than drafts.ts's write-with-no-commit.
+    try {
+        commitPaths(config.siteRoot, [menuPath], message, author);
+    }
+    catch (error) {
+        try {
+            if (existedBefore) {
+                writeFileSync(menuPath, originalBytes);
+            }
+            else {
+                unlinkSync(menuPath);
+            }
+        }
+        catch (rollbackError) {
+            throw new ManageMenuError('rollback-failed', 'Menu save failed and rolling back afterwards also failed; the working tree may be inconsistent and needs manual inspection', { cause: rollbackError });
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new ManageMenuError('commit-failed', `Menu save failed: ${detail}`, { cause: error });
+    }
+    return computeEtag(bytes);
+}
+export function saveMenu(config, relativePath, content, expectedEtag, message, author) {
+    return enqueue(() => saveMenuJob(config, relativePath, content, expectedEtag, message, author));
+}
+// Changes a menu's handle: moves content/menus/<from>.json to
+// <to>.json in one commit. Contents are untouched, so the returned
+// etag is the same one the menu already had. Refuses rather than
+// overwriting when <to> is taken, and checks If-Match against <from>
+// like every other menu write, so a rename made from a stale view is
+// refused rather than applied.
+async function renameMenuJob(config, from, to, expectedEtag, message, author) {
+    if (!isValidMenuHandle(from) || !isValidMenuHandle(to)) {
+        throw new ManageMenuError('validation-failed', 'A menu handle may only contain letters, numbers, hyphens and underscores');
+    }
+    if (from === to) {
+        throw new ManageMenuError('validation-failed', `The menu is already called "${to}"`);
+    }
+    mkdirSync(config.menusRoot, { recursive: true });
+    const fromPath = sanitisePath(config.menusRoot, `${from}.json`);
+    const toPath = sanitisePath(config.menusRoot, `${to}.json`);
+    const currentEtag = readCurrentEtag(config, `${from}.json`);
+    if (currentEtag === null) {
+        throw new ManageMenuError('not-found', `No menu with the handle "${from}"`);
+    }
+    if (!etagsMatch(currentEtag, expectedEtag)) {
+        throw new ManageMenuError('conflict', `If-Match "${expectedEtag}" does not match the current ETag for "${from}.json"`);
+    }
+    // existsSync is case-insensitive on a case-insensitive filesystem
+    // (macOS by default), so "main" -> "Main" is refused there rather
+    // than risking a rename onto itself. Harmless: pick another handle.
+    if (existsSync(toPath)) {
+        throw new ManageMenuError('conflict', `A menu with the handle "${to}" already exists`);
+    }
+    try {
+        renameSync(fromPath, toPath);
+    }
+    catch (error) {
+        throw new ManageMenuError('write-failed', `Could not rename "${from}" to "${to}"`, { cause: error });
+    }
+    try {
+        commitPaths(config.siteRoot, [fromPath, toPath], message, author);
+    }
+    catch (error) {
+        try {
+            renameSync(toPath, fromPath);
+        }
+        catch (rollbackError) {
+            throw new ManageMenuError('rollback-failed', 'Menu rename failed and rolling back afterwards also failed; the working tree may be inconsistent and needs manual inspection', { cause: rollbackError });
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new ManageMenuError('commit-failed', `Menu rename failed: ${detail}`, { cause: error });
+    }
+    return { etag: currentEtag, staleThemeReferences: findMenuReferences(config, from) };
+}
+export function renameMenu(config, from, to, expectedEtag, message, author) {
+    return enqueue(() => renameMenuJob(config, from, to, expectedEtag, message, author));
+}

package/dist/services/manage-redirects.d.ts

@@ -0,0 +1,25 @@
+import type { SiteConfig } from '../config.ts';
+import type { CommitAuthor } from './git.ts';
+import type { PreparedOperation } from './prepared-operation.ts';
+import type { RedirectEntry } from './redirects.ts';
+export type ManageRedirectReason = 'invalid-from' | 'invalid-target' | 'already-exists' | 'not-found' | 'live-content-exists' | 'redirect-cycle' | 'malformed-file' | 'write-failed' | 'commit-failed' | 'rollback-failed';
+export declare class ManageRedirectError extends Error {
+    readonly reason: ManageRedirectReason;
+    constructor(reason: ManageRedirectReason, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface RedirectMutationResult {
+    entry: RedirectEntry;
+    retargeted: RedirectEntry[];
+}
+export declare function prepareCreateRedirect(config: SiteConfig, from: string, to: string, note: string | undefined): PreparedOperation & {
+    result: RedirectMutationResult;
+};
+export declare function prepareUpdateRedirect(config: SiteConfig, from: string, to: string, note: string | undefined): PreparedOperation & {
+    result: RedirectMutationResult;
+};
+export declare function prepareDeleteRedirect(config: SiteConfig, from: string): PreparedOperation;
+export declare function createRedirect(config: SiteConfig, from: string, to: string, note: string | undefined, message: string, author: CommitAuthor): Promise<RedirectMutationResult | undefined>;
+export declare function updateRedirect(config: SiteConfig, from: string, to: string, note: string | undefined, message: string, author: CommitAuthor): Promise<RedirectMutationResult | undefined>;
+export declare function deleteRedirect(config: SiteConfig, from: string, message: string, author: CommitAuthor): Promise<undefined>;

package/dist/services/manage-redirects.js

@@ -0,0 +1,156 @@
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { commitPaths } from "./git.js";
+import { sanitisePath } from "./path-safety.js";
+import { RedirectError, addRedirect, isValidRedirectTarget, loadRedirectsStrict, removeRedirectForPath, serialiseRedirects, } from "./redirects.js";
+import { urlToPagePath } from "./urls.js";
+import { enqueue } from "./write-queue.js";
+export class ManageRedirectError extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.name = 'ManageRedirectError';
+        this.reason = reason;
+    }
+}
+// Not required for correctness (resolve-url.ts already guarantees live
+// content always wins over a redirect at the same URL), but rejecting
+// here avoids a marketing manager creating a redirect that would
+// silently never fire.
+function liveContentExistsAt(config, url) {
+    const pageFile = sanitisePath(config.pagesRoot, urlToPagePath(url));
+    return existsSync(pageFile);
+}
+function validateFromAndTo(from, to) {
+    if (!isValidRedirectTarget(from)) {
+        throw new ManageRedirectError('invalid-from', `"from" must be an internal path starting with "/", got "${from}"`);
+    }
+    if (!isValidRedirectTarget(to)) {
+        throw new ManageRedirectError('invalid-target', `"to" must be an internal path starting with "/", got "${to}"`);
+    }
+}
+function readRedirectsSnapshot(config) {
+    const existed = existsSync(config.redirectsPath);
+    return { existed, original: existed ? readFileSync(config.redirectsPath, 'utf-8') : '' };
+}
+function undoRedirectsWrite(config, snapshot) {
+    const failures = [];
+    try {
+        if (snapshot.existed) {
+            writeFileSync(config.redirectsPath, snapshot.original);
+        }
+        else {
+            rmSync(config.redirectsPath, { force: true });
+        }
+    }
+    catch (error) {
+        failures.push(error);
+    }
+    return failures;
+}
+function loadEntriesOrThrow(config) {
+    try {
+        return loadRedirectsStrict(config).entries;
+    }
+    catch (error) {
+        if (error instanceof RedirectError) {
+            throw new ManageRedirectError('malformed-file', error.message, { cause: error });
+        }
+        throw error;
+    }
+}
+export function prepareCreateRedirect(config, from, to, note) {
+    validateFromAndTo(from, to);
+    const entries = loadEntriesOrThrow(config);
+    if (entries.some((entry) => entry.from === from)) {
+        throw new ManageRedirectError('already-exists', `A redirect already exists for "${from}"`);
+    }
+    if (liveContentExistsAt(config, from)) {
+        throw new ManageRedirectError('live-content-exists', `"${from}" already has live content; a redirect there would never take effect`);
+    }
+    const snapshot = readRedirectsSnapshot(config);
+    let addResult;
+    try {
+        addResult = addRedirect(entries, from, to, note);
+    }
+    catch (error) {
+        if (error instanceof RedirectError) {
+            throw new ManageRedirectError('redirect-cycle', error.message, { cause: error });
+        }
+        throw error;
+    }
+    writeFileSync(config.redirectsPath, serialiseRedirects(addResult.entries));
+    const createdEntry = addResult.entries.find((entry) => entry.from === from);
+    if (!createdEntry) {
+        throw new Error('addRedirect did not produce the expected entry - this is a bug');
+    }
+    return {
+        paths: [config.redirectsPath],
+        undo: () => undoRedirectsWrite(config, snapshot),
+        result: { entry: createdEntry, retargeted: addResult.retargeted },
+    };
+}
+export function prepareUpdateRedirect(config, from, to, note) {
+    validateFromAndTo(from, to);
+    const entries = loadEntriesOrThrow(config);
+    if (!entries.some((entry) => entry.from === from)) {
+        throw new ManageRedirectError('not-found', `No redirect exists for "${from}"`);
+    }
+    const snapshot = readRedirectsSnapshot(config);
+    let addResult;
+    try {
+        addResult = addRedirect(entries, from, to, note);
+    }
+    catch (error) {
+        if (error instanceof RedirectError) {
+            throw new ManageRedirectError('redirect-cycle', error.message, { cause: error });
+        }
+        throw error;
+    }
+    writeFileSync(config.redirectsPath, serialiseRedirects(addResult.entries));
+    const updatedEntry = addResult.entries.find((entry) => entry.from === from);
+    if (!updatedEntry) {
+        throw new Error('addRedirect did not produce the expected entry - this is a bug');
+    }
+    return {
+        paths: [config.redirectsPath],
+        undo: () => undoRedirectsWrite(config, snapshot),
+        result: { entry: updatedEntry, retargeted: addResult.retargeted },
+    };
+}
+export function prepareDeleteRedirect(config, from) {
+    const entries = loadEntriesOrThrow(config);
+    if (!entries.some((entry) => entry.from === from)) {
+        throw new ManageRedirectError('not-found', `No redirect exists for "${from}"`);
+    }
+    const snapshot = readRedirectsSnapshot(config);
+    const updated = removeRedirectForPath(entries, from);
+    writeFileSync(config.redirectsPath, serialiseRedirects(updated));
+    return {
+        paths: [config.redirectsPath],
+        undo: () => undoRedirectsWrite(config, snapshot),
+    };
+}
+async function runRedirectJob(config, prepare, message, author) {
+    const prepared = prepare();
+    try {
+        commitPaths(config.siteRoot, prepared.paths, message, author);
+    }
+    catch (error) {
+        const failures = prepared.undo();
+        if (failures.length > 0) {
+            throw new ManageRedirectError('rollback-failed', 'Redirect write failed and rolling back afterwards also failed; the working tree may be inconsistent and needs manual inspection', { cause: error });
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new ManageRedirectError('commit-failed', `Redirect write failed: ${detail}`, { cause: error });
+    }
+    return prepared.result;
+}
+export function createRedirect(config, from, to, note, message, author) {
+    return enqueue(() => runRedirectJob(config, () => prepareCreateRedirect(config, from, to, note), message, author));
+}
+export function updateRedirect(config, from, to, note, message, author) {
+    return enqueue(() => runRedirectJob(config, () => prepareUpdateRedirect(config, from, to, note), message, author));
+}
+export function deleteRedirect(config, from, message, author) {
+    return enqueue(() => runRedirectJob(config, () => prepareDeleteRedirect(config, from), message, author));
+}

package/dist/services/menu-references.d.ts

@@ -0,0 +1,3 @@
+import type { SiteConfig } from '../config.ts';
+export declare function isValidMenuHandle(handle: string): boolean;
+export declare function findMenuReferences(config: SiteConfig, handle: string): string[];

package/dist/services/menu-references.js

@@ -0,0 +1,38 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { listFilesRecursively } from "./fs-walk.js";
+// A menu's handle is its filename without .json - what a layout writes
+// as menus.<handle>.items. Menus are flat (no subfolders), and these
+// are the only characters a Liquid dot-lookup reads as one name.
+const MENU_HANDLE = /^[A-Za-z0-9_-]+$/;
+export function isValidMenuHandle(handle) {
+    return MENU_HANDLE.test(handle);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+// Which theme files mention a menu by handle, as site-relative paths
+// (e.g. "theme/layouts/theme.liquid"). Read-only and advisory: it lets
+// the admin warn before a rename or delete leaves a nav empty. Matches
+// both menus.<handle> and menus['<handle>'] / menus["<handle>"], and
+// the dot form only as a whole name, so "main" never matches
+// menus.mainFooter. A handle built at runtime ({% assign m = ... %})
+// can't be seen here, which is why this only ever informs a warning,
+// never blocks anything.
+export function findMenuReferences(config, handle) {
+    if (!isValidMenuHandle(handle)) {
+        return [];
+    }
+    const escaped = escapeRegExp(handle);
+    const pattern = new RegExp(`menus(?:\\.${escaped}(?![A-Za-z0-9_-])|\\[\\s*(['"])${escaped}\\1\\s*\\])`);
+    return listFilesRecursively(config.themeRoot, config.siteRoot, '.liquid')
+        .filter((relativePath) => {
+        try {
+            return pattern.test(readFileSync(join(config.siteRoot, relativePath), 'utf-8'));
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort();
+}

package/dist/services/menus.d.ts

@@ -0,0 +1,9 @@
+import type { SiteConfig } from '../config.ts';
+export interface MenuContent {
+    name?: string;
+    items: Array<{
+        label: string;
+        url: string;
+    }>;
+}
+export declare function loadMenus(config: SiteConfig): Record<string, MenuContent>;

package/dist/services/menus.js

@@ -0,0 +1,43 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { listFilesRecursively } from "./fs-walk.js";
+function tryReadMenu(fullPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(fullPath, 'utf-8'));
+        if (!Array.isArray(parsed.items)) {
+            return null;
+        }
+        const items = parsed.items;
+        return typeof parsed.name === 'string' ? { name: parsed.name, items } : { items };
+    }
+    catch {
+        // One malformed menu file is skipped individually, not fatal to
+        // the whole render - a broken menu shouldn't take down every page
+        // on the site (matches rebuild-index.ts's best-effort-skip
+        // precedent for pages).
+        return null;
+    }
+}
+function loadMenusFrom(root) {
+    const menus = {};
+    // listFilesRecursively already returns [] for a missing directory -
+    // a site that has never used menus has no content/menus/ at all, and
+    // that resolves to {} gracefully, no existsSync guard needed here.
+    for (const relativePath of listFilesRecursively(root, root, '.json')) {
+        const name = relativePath.replace(/\.json$/, '');
+        const menu = tryReadMenu(join(root, relativePath));
+        if (menu) {
+            menus[name] = menu;
+        }
+    }
+    return menus;
+}
+// Menus are content (git-tracked), but unlike pages/posts they have no
+// draft/publish state at all (Group N) - direct-write with an
+// immediate commit, same as redirects.json. Always the live file,
+// identically in public and preview mode - there is no draft to
+// overlay. Loaded fresh on every render call, not once at boot like
+// theme templates/layouts/snippets.
+export function loadMenus(config) {
+    return loadMenusFrom(config.menusRoot);
+}

package/dist/services/migration-runner.d.ts

@@ -0,0 +1,16 @@
+import type { SiteConfig } from '../config.ts';
+import type { CommitAuthor } from './git.ts';
+import type { ThemeSchemas } from './validation.ts';
+export type MigrationFunction = (content: Record<string, unknown>) => Record<string, unknown>;
+export type MigrationMap = Record<number, MigrationFunction>;
+export type MigrationReason = 'migration-failed' | 'validation-failed' | 'write-failed' | 'commit-failed' | 'rollback-failed';
+export declare class MigrationError extends Error {
+    readonly reason: MigrationReason;
+    constructor(reason: MigrationReason, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface RunMigrationsOptions {
+    commit?: boolean;
+}
+export declare function runMigrations(config: SiteConfig, themeSchemas: ThemeSchemas, migrations: MigrationMap, currentVersion: number, author: CommitAuthor, options?: RunMigrationsOptions): Promise<string[]>;