@o-a/cms-agent 0.1.0

package/dist/services/git.js

@@ -0,0 +1,127 @@
+import { execFileSync } from 'node:child_process';
+export class GitOperationError extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.name = 'GitOperationError';
+        this.reason = reason;
+    }
+}
+const CONTROL_CHAR_PATTERN = /[\r\n]/;
+// The route layer's shape check for a caller-supplied author before it
+// ever reaches `git commit --author` below. execFileSync (not a shell)
+// already rules out command injection, but a name/email containing a
+// literal newline could still smuggle a malformed or multi-line author
+// string into git history - this is the first place in the codebase a
+// caller-supplied identity reaches a real commit (saveDraft/discardDraft
+// never take an author at all), so this check is new, necessary
+// surface, not a repeat of an existing one.
+export function isValidCommitAuthor(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const { name, email } = value;
+    return (typeof name === 'string' &&
+        name.length > 0 &&
+        !CONTROL_CHAR_PATTERN.test(name) &&
+        typeof email === 'string' &&
+        email.length > 0 &&
+        !CONTROL_CHAR_PATTERN.test(email));
+}
+// Author identity always comes from the caller, never host config
+// (constraint: commit authorship passthrough, checklist C5). Passing
+// GIT_AUTHOR_*/GIT_COMMITTER_* explicitly means this never depends on
+// ~/.gitconfig or any host identity being configured at all, which also
+// retires the "usable identity config" startup prerequisite entirely
+// rather than merely deferring it.
+function authorEnv(author) {
+    return {
+        ...process.env,
+        GIT_AUTHOR_NAME: author.name,
+        GIT_AUTHOR_EMAIL: author.email,
+        GIT_COMMITTER_NAME: author.name,
+        GIT_COMMITTER_EMAIL: author.email,
+    };
+}
+// Guarantees its own all-or-nothing contract: either fully committed,
+// or nothing left staged. Callers (publish.ts) therefore only ever need
+// to reason about filesystem state on failure, never git staging state.
+export function commitPaths(cwd, paths, message, author) {
+    try {
+        execFileSync('git', ['add', '--', ...paths], { cwd, stdio: 'ignore' });
+    }
+    catch (error) {
+        throw new GitOperationError('add-failed', `git add failed in ${cwd}`, { cause: error });
+    }
+    try {
+        execFileSync('git', ['commit', '-m', message, '--author', `${author.name} <${author.email}>`], {
+            cwd,
+            env: authorEnv(author),
+            stdio: 'ignore',
+        });
+    }
+    catch (error) {
+        try {
+            execFileSync('git', ['reset', '--', ...paths], { cwd, stdio: 'ignore' });
+        }
+        catch (resetError) {
+            throw new GitOperationError('reset-failed', `git commit failed in ${cwd} and unstaging afterwards also failed; index may be inconsistent`, { cause: resetError });
+        }
+        throw new GitOperationError('commit-failed', `git commit failed in ${cwd}`, { cause: error });
+    }
+}
+export function resetPaths(cwd, paths) {
+    try {
+        execFileSync('git', ['reset', '--', ...paths], { cwd, stdio: 'ignore' });
+    }
+    catch (error) {
+        throw new GitOperationError('reset-failed', `git reset failed in ${cwd}`, { cause: error });
+    }
+}
+// Allowlist, not a denylist of "dangerous" characters - the same
+// reject-on-ambiguity posture sanitisePath itself uses for paths. A
+// denylist (reject leading '-', reject whitespace) is exactly the
+// shape of check that's easy to get subtly wrong one case at a time
+// (reflog @{...} syntax, ^{...} suffixes, unicode whitespace); this
+// closes all of that in one line instead of enumerating each dangerous
+// case as it's discovered.
+const REF_PATTERN = /^[A-Za-z0-9._/-]+$/;
+export function isValidGitRef(value) {
+    return value.length > 0 && !value.startsWith('-') && !value.includes('..') && REF_PATTERN.test(value);
+}
+// The escape hatch (checklist G5): stages and commits literally
+// everything currently changed in the working tree, deliberately
+// unscoped - a path-scoped variant would defeat the entire point of
+// "out-of-band changes the API doesn't otherwise know about" (build
+// plan wording). Respects .gitignore like any git invocation, so
+// data/ stays excluded per existing convention.
+export function commitWorkingTree(cwd, message, author) {
+    const status = execFileSync('git', ['status', '--porcelain'], { cwd }).toString('utf-8');
+    if (status.trim().length === 0) {
+        // Nothing to stage - matches batch.ts's empty-commit lesson
+        // (git commit with nothing staged exits non-zero), simpler here
+        // since there's no path list to check, just the whole tree.
+        return 'clean';
+    }
+    try {
+        execFileSync('git', ['add', '-A'], { cwd, stdio: 'ignore' });
+    }
+    catch (error) {
+        throw new GitOperationError('add-failed', `git add -A failed in ${cwd}`, { cause: error });
+    }
+    try {
+        execFileSync('git', ['commit', '-m', message, '--author', `${author.name} <${author.email}>`], { cwd, env: authorEnv(author), stdio: 'ignore' });
+    }
+    catch (error) {
+        try {
+            // Bare reset (no path list): unstages everything just added,
+            // mirroring commitPaths's own rollback shape.
+            execFileSync('git', ['reset'], { cwd, stdio: 'ignore' });
+        }
+        catch (resetError) {
+            throw new GitOperationError('reset-failed', `git commit failed in ${cwd} and unstaging afterwards also failed; index may be inconsistent`, { cause: resetError });
+        }
+        throw new GitOperationError('commit-failed', `git commit failed in ${cwd}`, { cause: error });
+    }
+    return 'committed';
+}

package/dist/services/interval-job.d.ts

@@ -0,0 +1,4 @@
+export interface IntervalJobHandle {
+    stop: () => void;
+}
+export declare function startIntervalJob(job: () => Promise<unknown>, intervalMs: number, onError: (error: unknown) => void): IntervalJobHandle;

package/dist/services/interval-job.js

@@ -0,0 +1,9 @@
+export function startIntervalJob(job, intervalMs, onError) {
+    const timer = setInterval(() => {
+        job().catch(onError);
+    }, intervalMs);
+    // Must not itself keep a process (or a test) alive - the listening
+    // socket is what should be process-life-sustaining, not this timer.
+    timer.unref();
+    return { stop: () => clearInterval(timer) };
+}

package/dist/services/ip-allowlist.d.ts

@@ -0,0 +1,7 @@
+import type { FastifyRequest } from 'fastify';
+export declare class IpAllowlistError extends Error {
+    readonly statusCode = 403;
+    constructor();
+}
+export declare function isIpAllowed(allowlist: string[], ip: string): boolean;
+export declare function ipAllowlistGuard(allowlist: string[]): (request: FastifyRequest) => Promise<void>;

package/dist/services/ip-allowlist.js

@@ -0,0 +1,31 @@
+// Mirrors token-auth.ts's AuthError shape: statusCode set explicitly
+// in the constructor so the existing global error handler passes this
+// through with its real message intact, never sanitising it as a
+// generic 500.
+export class IpAllowlistError extends Error {
+    statusCode = 403;
+    constructor() {
+        super('This IP address is not permitted to access this API');
+        this.name = 'IpAllowlistError';
+    }
+}
+// An empty allowlist is a no-op (checklist H3), not "nothing is
+// allowed" - exact-IP-only for this pass, no CIDR ranges: IP
+// allowlisting is "optional, not the backbone" per the build plan, a
+// deliberate scope reduction rather than an oversight.
+export function isIpAllowed(allowlist, ip) {
+    return allowlist.length === 0 || allowlist.includes(ip);
+}
+// Applied as a whole-file addHook('onRequest', ...) inside v1Routes's
+// own plugin body (routes/index.ts), not a per-route preHandler like
+// requireScope - an IP allowlist is a coarse "is this client's network
+// address allowed to talk to the API at all" gate, orthogonal to
+// token-scope exemption, so it applies to the entire /v1 surface
+// uniformly, including capabilities.ts and every GET route.
+export function ipAllowlistGuard(allowlist) {
+    return async function guard(request) {
+        if (!isIpAllowed(allowlist, request.ip)) {
+            throw new IpAllowlistError();
+        }
+    };
+}

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

@@ -0,0 +1,10 @@
+import type { SiteConfig } from '../config.ts';
+import type { CommitAuthor } from './git.ts';
+export type ManageMenuReason = 'validation-failed' | '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>;

package/dist/services/manage-menus.js

@@ -0,0 +1,84 @@
+import { existsSync, mkdirSync, readFileSync, 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 { 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));
+}

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,166 @@
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { commitPaths } from "./git.js";
+import { sanitisePath } from "./path-safety.js";
+import { isBlogUrl, urlToPostPath } from "./post-urls.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/resolve-blog-url.ts
+// already guarantee 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));
+    if (existsSync(pageFile)) {
+        return true;
+    }
+    if (isBlogUrl(url) && existsSync(config.postsRoot)) {
+        const postRelative = urlToPostPath(url);
+        if (postRelative !== null && existsSync(sanitisePath(config.postsRoot, postRelative))) {
+            return true;
+        }
+    }
+    return false;
+}
+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/menus.d.ts

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

package/dist/services/menus.js

@@ -0,0 +1,42 @@
+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;
+        }
+        return { items: parsed.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,13 @@
+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 declare function runMigrations(config: SiteConfig, themeSchemas: ThemeSchemas, migrations: MigrationMap, currentVersion: number, author: CommitAuthor): Promise<void>;

package/dist/services/migration-runner.js

@@ -0,0 +1,123 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { listFilesRecursively } from "./fs-walk.js";
+import { GitOperationError, commitPaths } from "./git.js";
+import { validateContent } from "./validation.js";
+import { enqueue } from "./write-queue.js";
+export class MigrationError extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.name = 'MigrationError';
+        this.reason = reason;
+    }
+}
+// Walks the migration chain one step at a time until currentVersion is
+// reached. Throws if a step is missing, or if a migration doesn't
+// actually advance the version (a defensive check against a broken
+// migration function).
+function applyMigrationChain(content, migrations, currentVersion, path) {
+    let current = content;
+    const initialVersion = current.schemaVersion;
+    if (typeof initialVersion !== 'number') {
+        throw new MigrationError('migration-failed', `"${path}" has no numeric schemaVersion`);
+    }
+    let version = initialVersion;
+    while (version < currentVersion) {
+        const migrate = migrations[version];
+        if (!migrate) {
+            throw new MigrationError('migration-failed', `No migration registered for schemaVersion ${version} ("${path}")`);
+        }
+        const next = migrate(current);
+        const nextVersion = next.schemaVersion;
+        if (typeof nextVersion !== 'number' || nextVersion <= version) {
+            throw new MigrationError('migration-failed', `Migration from schemaVersion ${version} did not advance schemaVersion ("${path}")`);
+        }
+        current = next;
+        version = nextVersion;
+    }
+    return current;
+}
+// Hand-rolled fs snapshot/restore, matching publish.ts's established
+// shape - but simpler: every file the write phase touches already
+// existed with real prior bytes (F3's skip logic guarantees this), so
+// there is no "did this file exist before" branch to carry.
+function rollback(files) {
+    const failures = [];
+    for (const file of files) {
+        try {
+            writeFileSync(file.path, file.originalBytes);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    return failures;
+}
+async function runMigrationsJob(config, themeSchemas, migrations, currentVersion, author) {
+    // Three named walks (pages/posts/menus), not one broad walk of
+    // contentRoot - see content-read.ts's listContent for the identical
+    // reasoning (Group N nested draftsRoot/redirectsPath inside
+    // contentRoot; a broad walk would double-migrate drafts and try to
+    // validate redirects.json as a page). base stays config.contentRoot
+    // for all three so relativePath matches what validateContent expects.
+    const files = [
+        ...listFilesRecursively(config.pagesRoot, config.contentRoot, '.json').map((rel) => ({
+            path: join(config.contentRoot, rel),
+            relativePath: rel,
+        })),
+        ...listFilesRecursively(config.postsRoot, config.contentRoot, '.json').map((rel) => ({
+            path: join(config.contentRoot, rel),
+            relativePath: rel,
+        })),
+        ...listFilesRecursively(config.menusRoot, config.contentRoot, '.json').map((rel) => ({
+            path: join(config.contentRoot, rel),
+            relativePath: rel,
+        })),
+        ...listFilesRecursively(config.draftsRoot, config.draftsRoot, '.json').map((rel) => ({
+            path: join(config.draftsRoot, rel),
+            relativePath: rel,
+        })),
+    ];
+    // Compute every migration before writing anything. If any file's
+    // migration or validation throws, everything computed for other
+    // files so far is simply discarded - a mid-list failure aborts with
+    // literally zero writes having happened (F4's primary scenario).
+    const toMigrate = [];
+    for (const { path, relativePath } of files) {
+        const originalBytes = readFileSync(path);
+        const parsed = JSON.parse(originalBytes.toString('utf-8'));
+        const schemaVersion = parsed.schemaVersion;
+        if (typeof schemaVersion === 'number' && schemaVersion >= currentVersion) {
+            continue;
+        }
+        const migrated = applyMigrationChain(parsed, migrations, currentVersion, path);
+        const result = validateContent(relativePath, migrated, themeSchemas);
+        if (!result.valid) {
+            throw new MigrationError('validation-failed', `Migrated content at "${path}" failed validation: ${JSON.stringify(result.errors)}`);
+        }
+        const migratedBytes = Buffer.from(JSON.stringify(migrated, null, 2));
+        toMigrate.push({ path, originalBytes, migratedBytes });
+    }
+    if (toMigrate.length === 0) {
+        return;
+    }
+    try {
+        for (const file of toMigrate) {
+            writeFileSync(file.path, file.migratedBytes);
+        }
+        commitPaths(config.siteRoot, toMigrate.map((file) => file.path), `chore: migrate content to schema version ${currentVersion}`, author);
+    }
+    catch (error) {
+        const failures = rollback(toMigrate);
+        if (failures.length > 0) {
+            throw new MigrationError('rollback-failed', 'Migration run 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 detail = error instanceof Error ? error.message : String(error);
+        throw new MigrationError(reason, `Migration run failed: ${detail}`, { cause: error });
+    }
+}
+export function runMigrations(config, themeSchemas, migrations, currentVersion, author) {
+    return enqueue(() => runMigrationsJob(config, themeSchemas, migrations, currentVersion, author));
+}