@o-a/cms-agent 0.1.0

package/dist/services/mime-types.d.ts

@@ -0,0 +1,3 @@
+export declare const MIME_TYPES: Record<string, string>;
+export declare const DEFAULT_MIME_TYPE = "application/octet-stream";
+export declare function mimeTypeFor(path: string): string;

package/dist/services/mime-types.js

@@ -0,0 +1,36 @@
+import { extname } from 'node:path';
+// A small hand-rolled lookup, not a dependency (@fastify/static would
+// be the obvious ecosystem package, but this is a handful of lines and
+// matches this codebase's existing minimal-dependency posture). Only
+// the common web asset types - nothing here needs to be exhaustive.
+//
+// Shared by both routes/assets.ts (theme CSS/JS/images/fonts) and
+// routes/public.ts's theme/root/ mirror (robots.txt, .well-known/*,
+// site-verification HTML files) via services/static-file.ts - the
+// text/xml/html entries below exist specifically for that second,
+// broader use case. Found live: robots.txt fell back to
+// DEFAULT_MIME_TYPE (application/octet-stream), which every browser
+// treats as "download this" rather than displaying it inline, even
+// though the actual content is plain text.
+export const MIME_TYPES = {
+    '.css': 'text/css; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+    '.webp': 'image/webp',
+    '.ico': 'image/x-icon',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.txt': 'text/plain; charset=utf-8',
+    '.xml': 'application/xml; charset=utf-8',
+    '.html': 'text/html; charset=utf-8',
+    '.htm': 'text/html; charset=utf-8',
+};
+export const DEFAULT_MIME_TYPE = 'application/octet-stream';
+export function mimeTypeFor(path) {
+    return MIME_TYPES[extname(path).toLowerCase()] ?? DEFAULT_MIME_TYPE;
+}

package/dist/services/move.d.ts

@@ -0,0 +1,16 @@
+import type { SiteConfig } from '../config.ts';
+import type { CommitAuthor } from './git.ts';
+import type { PreparedOperation } from './prepared-operation.ts';
+export type MoveReason = 'source-not-found' | 'destination-exists' | 'write-failed' | 'commit-failed' | 'rollback-failed';
+export declare class MoveError extends Error {
+    readonly reason: MoveReason;
+    constructor(reason: MoveReason, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare function prepareMovePage(config: SiteConfig, fromUrl: string, toUrl: string, options?: {
+    createRedirect?: boolean;
+}): PreparedOperation;
+export declare function movePage(config: SiteConfig, fromUrl: string, toUrl: string, message: string, author: CommitAuthor, options?: {
+    createRedirect?: boolean;
+}): Promise<void>;

package/dist/services/move.js

@@ -0,0 +1,175 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { listFilesRecursively } from "./fs-walk.js";
+import { commitPaths } from "./git.js";
+import { sanitisePath } from "./path-safety.js";
+import { addRedirect, loadRedirects, removeRedirectForPath, serialiseRedirects } from "./redirects.js";
+import { pagePathToUrl, urlToPagePath } from "./urls.js";
+import { enqueue } from "./write-queue.js";
+export class MoveError extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.name = 'MoveError';
+        this.reason = reason;
+    }
+}
+// Validates and writes everything a move needs, stopping short of the
+// commit itself - used both by the standalone movePageJob (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, so prepare either fully succeeds or fully undoes itself
+// before throwing.
+//
+// options.createRedirect defaults true - existing callers (and
+// batch.ts) keep today's behaviour unchanged. false skips only
+// addRedirect (the "old URL now redirects to the new one" step);
+// removeRedirectForPath still always runs regardless, since that's a
+// correctness cleanup (the destination URL can't stay claimed by a
+// stale redirect once a real page exists there), not a new redirect
+// being created.
+export function prepareMovePage(config, fromUrl, toUrl, options = {}) {
+    const createRedirect = options.createRedirect ?? true;
+    const fromRelative = urlToPagePath(fromUrl);
+    const toRelative = urlToPagePath(toUrl);
+    const fromPageFile = sanitisePath(config.pagesRoot, fromRelative);
+    const toPageFile = sanitisePath(config.pagesRoot, toRelative);
+    if (!existsSync(fromPageFile)) {
+        throw new MoveError('source-not-found', `No page found at "${fromUrl}"`);
+    }
+    if (existsSync(toPageFile)) {
+        throw new MoveError('destination-exists', `A page already exists at "${toUrl}"`);
+    }
+    const fromDirRelative = fromRelative.replace(/\.json$/, '');
+    const toDirRelative = toRelative.replace(/\.json$/, '');
+    const fromDir = sanitisePath(config.pagesRoot, fromDirRelative);
+    const toDir = sanitisePath(config.pagesRoot, toDirRelative);
+    const fromDirExists = existsSync(fromDir) && statSync(fromDir).isDirectory();
+    if (fromDirExists && existsSync(toDir)) {
+        throw new MoveError('destination-exists', `A directory already exists at the destination for "${toUrl}"`);
+    }
+    // Enumerate every affected page (the page itself, plus every
+    // descendant if it has any) before touching disk. This list drives
+    // both the redirect entries (E3: one per affected page) and the git
+    // staging list.
+    const affected = [
+        { oldRelativePath: fromRelative, newRelativePath: toRelative, oldUrl: fromUrl, newUrl: toUrl },
+    ];
+    if (fromDirExists) {
+        for (const rel of listFilesRecursively(fromDir, fromDir, '.json')) {
+            const oldRelativePath = join(fromDirRelative, rel);
+            const newRelativePath = join(toDirRelative, rel);
+            affected.push({
+                oldRelativePath,
+                newRelativePath,
+                oldUrl: pagePathToUrl(oldRelativePath),
+                newUrl: pagePathToUrl(newRelativePath),
+            });
+        }
+    }
+    const performedRenames = [];
+    let redirectsBefore = null;
+    let redirectsChanged = false;
+    // Reverses every rename (in reverse order) and restores/removes
+    // redirects.json. Attempts everything even if one step fails,
+    // reporting every failure - matches publish.ts's rollback()
+    // philosophy exactly (a filesystem cannot give a true atomicity
+    // guarantee, so the honest contract is "restores everything it can,
+    // and is loud if it can't").
+    function undoMoveWrites() {
+        const restoreFailures = [];
+        for (const rename of [...performedRenames].reverse()) {
+            try {
+                renameSync(rename.to, rename.from);
+            }
+            catch (restoreError) {
+                restoreFailures.push(restoreError);
+            }
+        }
+        if (redirectsChanged) {
+            try {
+                if (redirectsBefore === null) {
+                    rmSync(config.redirectsPath, { force: true });
+                }
+                else {
+                    writeFileSync(config.redirectsPath, redirectsBefore);
+                }
+            }
+            catch (restoreError) {
+                restoreFailures.push(restoreError);
+            }
+        }
+        return restoreFailures;
+    }
+    try {
+        mkdirSync(dirname(toPageFile), { recursive: true });
+        renameSync(fromPageFile, toPageFile);
+        performedRenames.push({ from: fromPageFile, to: toPageFile });
+        if (fromDirExists) {
+            mkdirSync(dirname(toDir), { recursive: true });
+            renameSync(fromDir, toDir);
+            performedRenames.push({ from: fromDir, to: toDir });
+        }
+        redirectsBefore = existsSync(config.redirectsPath)
+            ? readFileSync(config.redirectsPath, 'utf-8')
+            : null;
+        let entries = loadRedirects(config).entries;
+        for (const page of affected) {
+            // E5 (move half) must run BEFORE addRedirect, not after: if the
+            // destination held a stale redirect (page.newUrl was itself a
+            // key), addRedirect's chain-walk would otherwise treat it as a
+            // legitimate hop and silently collapse straight through it,
+            // rather than the new page superseding it.
+            entries = removeRedirectForPath(entries, page.newUrl);
+            if (createRedirect) {
+                entries = addRedirect(entries, page.oldUrl, page.newUrl).entries;
+            }
+        }
+        const redirectsAfter = serialiseRedirects(entries);
+        if (redirectsAfter !== (redirectsBefore ?? '')) {
+            writeFileSync(config.redirectsPath, redirectsAfter);
+            redirectsChanged = true;
+        }
+    }
+    catch (error) {
+        // A write-phase failure: roll back immediately, inside prepare
+        // itself, and always classify as write-failed - commitPaths hasn't
+        // been called yet, so this can never be a GitOperationError.
+        const failures = undoMoveWrites();
+        if (failures.length > 0) {
+            throw new MoveError('rollback-failed', 'Move 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 MoveError('write-failed', `Move failed: ${detail}`, { cause: error });
+    }
+    const paths = [];
+    for (const page of affected) {
+        paths.push(sanitisePath(config.pagesRoot, page.oldRelativePath));
+        paths.push(sanitisePath(config.pagesRoot, page.newRelativePath));
+    }
+    if (redirectsChanged) {
+        paths.push(config.redirectsPath);
+    }
+    return { paths, undo: undoMoveWrites };
+}
+async function movePageJob(config, fromUrl, toUrl, message, author, options = {}) {
+    const { paths, undo } = prepareMovePage(config, fromUrl, toUrl, options);
+    try {
+        commitPaths(config.siteRoot, paths, message, author);
+    }
+    catch (error) {
+        const failures = undo();
+        if (failures.length > 0) {
+            throw new MoveError('rollback-failed', 'Move 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, so anything caught in this try can only have come
+        // from commitPaths itself.
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new MoveError('commit-failed', `Move failed: ${detail}`, { cause: error });
+    }
+}
+export function movePage(config, fromUrl, toUrl, message, author, options = {}) {
+    return enqueue(() => movePageJob(config, fromUrl, toUrl, message, author, options));
+}

package/dist/services/path-safety.d.ts

@@ -0,0 +1,6 @@
+export type PathSafetyReason = 'absolute-path' | 'traversal-segment' | 'malformed-encoding' | 'outside-root' | 'resolves-to-root' | 'symlink-escape' | 'invalid-path';
+export declare class PathSafetyError extends Error {
+    readonly reason: PathSafetyReason;
+    constructor(reason: PathSafetyReason, message: string);
+}
+export declare function sanitisePath(root: string, requestedPath: string): string;

package/dist/services/path-safety.js

@@ -0,0 +1,112 @@
+import { realpathSync } from 'node:fs';
+import { dirname, isAbsolute, resolve, sep } from 'node:path';
+export class PathSafetyError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'PathSafetyError';
+        this.reason = reason;
+    }
+}
+function isWithin(root, candidate) {
+    return candidate === root || candidate.startsWith(root + sep);
+}
+// Only existing path segments can be symlinks, so for a target that
+// doesn't exist yet (e.g. a new draft being written for the first time)
+// it is sufficient to realpath the nearest existing ancestor and confirm
+// that stays within the root; segments that don't exist can't smuggle a
+// symlink escape.
+function realpathOfNearestExisting(candidate) {
+    let current = candidate;
+    for (;;) {
+        try {
+            return realpathSync(current);
+        }
+        catch (error) {
+            const code = error.code;
+            // ENOENT/ENOTDIR mean only "this segment doesn't exist yet" -
+            // walk up to the nearest ancestor that does, per this function's
+            // own doc comment. Any other failure (ENAMETOOLONG for an
+            // over-length segment, ERR_INVALID_ARG_VALUE for an embedded null
+            // byte, etc. - verified empirically, not an exhaustive enum by
+            // design) means the path itself is malformed, not merely absent.
+            // Rejecting it here as a PathSafetyError is required, not
+            // optional: left as a raw rethrow, it would escape every route
+            // handler's `instanceof PathSafetyError` check and surface as an
+            // unsanitised 500, the exact failure mode this file exists to
+            // prevent (CLAUDE.md's #1 security concern).
+            if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+                throw new PathSafetyError('invalid-path', `Path could not be resolved: "${candidate}"`);
+            }
+            const parent = dirname(current);
+            if (parent === current) {
+                throw new PathSafetyError('invalid-path', `Path could not be resolved: "${candidate}"`);
+            }
+            current = parent;
+        }
+    }
+}
+// The single shared path-sanitisation helper. Every fs-touching code
+// path that handles a request-supplied :path parameter must resolve it
+// through this function before touching disk (enforced by a grep test,
+// see test/static/static-analysis.test.ts).
+export function sanitisePath(root, requestedPath) {
+    const normalisedRoot = resolve(root);
+    // Step 1: reject a raw absolute path before any decoding.
+    if (isAbsolute(requestedPath)) {
+        throw new PathSafetyError('absolute-path', `Path must be relative, got "${requestedPath}"`);
+    }
+    // Step 2: percent-decode. Decoding before splitting into segments (not
+    // decoding each segment independently) is what's actually required to
+    // catch an encoded slash disguising a segment boundary, e.g.
+    // "a%2f..%2fetc" decodes to "a/../etc" and is then caught by the
+    // segment scan below; decoding per-segment would miss it. Malformed
+    // encoding is rejected outright rather than passed through: this will
+    // also reject a benign filename containing a literal unencoded "%",
+    // which is an acceptable reject-on-ambiguity trade-off, not a bug.
+    let decoded;
+    try {
+        decoded = decodeURIComponent(requestedPath);
+    }
+    catch {
+        throw new PathSafetyError('malformed-encoding', `Path contains malformed percent-encoding: "${requestedPath}"`);
+    }
+    // Step 3: an encoded absolute path (e.g. "%2fetc%2fpasswd") doesn't
+    // look absolute in raw form, so check again after decoding.
+    if (isAbsolute(decoded)) {
+        throw new PathSafetyError('absolute-path', `Path must be relative, got "${requestedPath}"`);
+    }
+    // Step 4: reject any ".." segment, covering both plain and encoded
+    // traversal now that decoding has already happened.
+    if (decoded.split('/').includes('..')) {
+        throw new PathSafetyError('traversal-segment', `Path must not contain ".." segments: "${requestedPath}"`);
+    }
+    // Step 5: string-only containment check, still no fs call.
+    const resolved = resolve(normalisedRoot, decoded);
+    if (!isWithin(normalisedRoot, resolved)) {
+        throw new PathSafetyError('outside-root', `Path resolves outside the allowed root: "${requestedPath}"`);
+    }
+    // Step 6: deliberate hardening beyond the literal B3-B6 wording. A
+    // request that resolves to exactly the root (e.g. "", ".") must not be
+    // handed to a caller expecting a single file path.
+    if (resolved === normalisedRoot) {
+        throw new PathSafetyError('resolves-to-root', `Path must not resolve to the root itself: "${requestedPath}"`);
+    }
+    // Step 7: only now touch the filesystem, to catch a symlink inside the
+    // tree pointing outside the root.
+    const realRoot = realpathSync(normalisedRoot);
+    const realResolved = realpathOfNearestExisting(resolved);
+    if (!isWithin(realRoot, realResolved)) {
+        throw new PathSafetyError('symlink-escape', `Path escapes the allowed root via a symlink: "${requestedPath}"`);
+    }
+    // Accepted residual risk, not a structural gap: the symlink check
+    // above and the fs operation a caller performs with the returned
+    // path are not atomic, so a symlink swapped in between could in
+    // principle slip through (TOCTOU). Given the actual threat model -
+    // a single-operator site, all writes serialised through one queue,
+    // no concurrent untrusted filesystem access - this is low realistic
+    // risk. Flagged by plan-reviewer's Phase 1 audit; noted rather than
+    // solved, the same way other accepted trade-offs in this codebase
+    // are (see publish.ts's rollback() comment).
+    return resolved;
+}

package/dist/services/post-urls.d.ts

@@ -0,0 +1,3 @@
+export declare function isBlogUrl(url: string): boolean;
+export declare function urlToPostPath(url: string): string | null;
+export declare function postPathToUrl(relativePostPath: string): string;

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,14 @@
+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>;

package/dist/services/publish.js

@@ -0,0 +1,254 @@
+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 { postPathToUrl } from "./post-urls.js";
+import { loadRedirects, removeRedirectForPath, serialiseRedirects } from "./redirects.js";
+import { pagePathToUrl } from "./urls.js";
+import { validateContent } from "./validation.js";
+import { enqueue } from "./write-queue.js";
+const PAGES_PREFIX = 'pages/';
+const POSTS_PREFIX = 'posts/';
+// Mirrors delete-content.ts's urlForDeletedEntry - a tiny duplicated
+// helper, not a shared abstraction. Widens the stale-redirect-clearing
+// block below to posts alongside pages; 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));
+    }
+    if (relativePath.startsWith(POSTS_PREFIX)) {
+        return postPathToUrl(relativePath.slice(POSTS_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 or post 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 pages/posts 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 });
+    }
+}
+export function publishDrafts(config, themeSchemas, relativePaths, message, author) {
+    return enqueue(() => publishDraftsJob(config, themeSchemas, relativePaths, message, author));
+}
+export function unpublishPage(config, relativePath, message, author) {
+    return enqueue(() => unpublishPageJob(config, relativePath, message, author));
+}