@o-a/cms-agent 0.1.0

package/dist/search/drivers/node-sqlite-driver.js

@@ -0,0 +1,19 @@
+import { DatabaseSync } from 'node:sqlite';
+// A plain string constant, not the raw node:sqlite import itself - safe
+// for the capabilities endpoint (Phase 2 Group A) to import without
+// tripping the G5 grep test, and avoids hardcoding this name a second
+// time as a literal that could drift from the actual active driver.
+export const DRIVER_NAME = 'node:sqlite';
+// The only file in the codebase allowed to import node:sqlite
+// (checklist G5, enforced by a grep test in
+// test/static/static-analysis.test.ts). DatabaseSync's own
+// prepare()/exec()/close() already structurally match SearchDriver,
+// so this is a thin adapter, not a reimplementation.
+export function openNodeSqliteDriver(path) {
+    const db = new DatabaseSync(path);
+    return {
+        exec: (sql) => db.exec(sql),
+        prepare: (sql) => db.prepare(sql),
+        close: () => db.close(),
+    };
+}

package/dist/search/query-index.d.ts

@@ -0,0 +1,5 @@
+export interface SearchResult {
+    url: string;
+    title: string;
+}
+export declare function queryIndex(searchIndexPath: string, term: string): SearchResult[];

package/dist/search/query-index.js

@@ -0,0 +1,21 @@
+import { openNodeSqliteDriver } from "./drivers/node-sqlite-driver.js";
+// Never queued: an in-flight query holding an open handle during a
+// concurrent rebuild's unlink just keeps reading the pre-rebuild inode
+// (stale but consistent, never torn) - queuing a read against the same
+// queue as writes would only add latency for no correctness benefit.
+export function queryIndex(searchIndexPath, term) {
+    const driver = openNodeSqliteDriver(searchIndexPath);
+    try {
+        const rows = driver.prepare('SELECT url, title FROM pages_fts WHERE pages_fts MATCH ?').all(term);
+        // node:sqlite returns rows as [Object: null prototype] instances;
+        // rebuilt here as plain objects so callers (and assert.deepEqual)
+        // never have to know that's a driver implementation detail.
+        return rows.map((row) => {
+            const { url, title } = row;
+            return { url, title };
+        });
+    }
+    finally {
+        driver.close();
+    }
+}

package/dist/search/rebuild-index.d.ts

@@ -0,0 +1,2 @@
+import type { SiteConfig } from '../config.ts';
+export declare function rebuildIndex(config: SiteConfig): Promise<void>;

package/dist/search/rebuild-index.js

@@ -0,0 +1,111 @@
+import { mkdirSync, readFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { listFilesRecursively } from "../services/fs-walk.js";
+import { postPathToUrl } from "../services/post-urls.js";
+import { pagePathToUrl } from "../services/urls.js";
+import { enqueue } from "../services/write-queue.js";
+import { openNodeSqliteDriver } from "./drivers/node-sqlite-driver.js";
+function collectStrings(value, out) {
+    if (typeof value === 'string') {
+        out.push(value);
+    }
+    else if (Array.isArray(value)) {
+        for (const item of value) {
+            collectStrings(item, out);
+        }
+    }
+    else if (value !== null && typeof value === 'object') {
+        for (const nested of Object.values(value)) {
+            collectStrings(nested, out);
+        }
+    }
+}
+// Recursively collects every string value out of each section's
+// settings and any nested blocks' settings (instance.schema.json's
+// blocks is self-referential, so this covers arbitrarily deep
+// nesting). Only settings values, not id/type, so the indexed body is
+// actual authored content, not structural metadata.
+function extractBody(instances) {
+    const strings = [];
+    const walk = (list) => {
+        if (!list) {
+            return;
+        }
+        for (const instance of list) {
+            collectStrings(instance.settings, strings);
+            walk(instance.blocks);
+        }
+    };
+    walk(instances);
+    return strings.join(' ');
+}
+async function rebuildIndexJob(config) {
+    mkdirSync(config.dataRoot, { recursive: true });
+    // Delete-then-recreate, not existsSync-then-unlinkSync (a TOCTOU
+    // gap): this makes every rebuild start from a genuinely clean file,
+    // which is also what makes "delete the index and rebuild produces
+    // equivalent results" (G2) a structural consequence rather than a
+    // special case.
+    try {
+        unlinkSync(config.searchIndexPath);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    const driver = openNodeSqliteDriver(config.searchIndexPath);
+    try {
+        driver.exec('CREATE VIRTUAL TABLE pages_fts USING fts5(url UNINDEXED, title, body)');
+        const insert = driver.prepare('INSERT INTO pages_fts (url, title, body) VALUES (?, ?, ?)');
+        // Posts are genuinely public, URL-addressable content search
+        // should cover, same as pages - only the root and the URL mapping
+        // differ. Menus are deliberately never walked here at all: they
+        // have no public URL to point a search result at.
+        const collections = [
+            { root: config.pagesRoot, toUrl: pagePathToUrl },
+            { root: config.postsRoot, toUrl: postPathToUrl },
+        ];
+        driver.exec('BEGIN');
+        for (const { root, toUrl } of collections) {
+            for (const relativePath of listFilesRecursively(root, root, '.json')) {
+                let page;
+                try {
+                    page = JSON.parse(readFileSync(join(root, relativePath), 'utf-8'));
+                }
+                catch {
+                    // A malformed individual file is skipped, not an all-or-nothing
+                    // abort: the index is explicitly disposable/best-effort, and
+                    // aborting the whole rebuild over one bad file would leave no
+                    // working index at all - strictly worse than skipping one page.
+                    continue;
+                }
+                // Never walks draftsRoot at all, and skips unpublished content
+                // here - both halves of "drafts and unpublished content are
+                // absent from the index" (G3) are true by construction, not by
+                // a filter that could be gotten wrong.
+                if (page.published === false) {
+                    continue;
+                }
+                const url = toUrl(relativePath);
+                const title = typeof page.title === 'string' ? page.title : '';
+                const body = extractBody(page.sections);
+                insert.run(url, title, body);
+            }
+        }
+        driver.exec('COMMIT');
+    }
+    finally {
+        driver.close();
+    }
+}
+// Queued via enqueue(), not because constraint 6 literally demands it
+// for a non-authoritative index, but because of a same-process race
+// specific to this delete-then-recreate design: two concurrent
+// rebuilds can interleave so one's unlink races another's open+CREATE,
+// or one can unlink the file out from under another's in-progress
+// transaction. enqueue() is a generic, domain-agnostic primitive, so
+// reusing it for self-exclusion costs nothing.
+export function rebuildIndex(config) {
+    return enqueue(() => rebuildIndexJob(config));
+}

package/dist/server-config.d.ts

@@ -0,0 +1,22 @@
+export type Scope = 'content' | 'theme' | 'media';
+export interface TokenEntry {
+    hash: string;
+    scopes: Scope[];
+}
+export interface RateLimitConfig {
+    max: number;
+    windowMs: number;
+}
+export interface MediaConfig {
+    maxUploadBytes: number;
+}
+export interface ServerConfig {
+    port: number;
+    tokens: TokenEntry[];
+    rateLimit: RateLimitConfig;
+    trustProxy: boolean;
+    ipAllowlist: string[];
+    checkpointIntervalMs: number;
+    media: MediaConfig;
+}
+export declare function loadServerConfig(siteRoot: string): ServerConfig;

package/dist/server-config.js

@@ -0,0 +1,196 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { VHOST_DIR_NAME } from "./config.js";
+import { StartupCheckError } from "./services/startup-checks.js";
+const DEFAULT_PORT = 3000;
+const DEFAULT_RATE_LIMIT = { max: 60, windowMs: 60000 };
+// 10MB (docs/cms-build-plan.md's own suggested default) - comfortably
+// above a properly web-optimised image, well below an unoptimised raw
+// camera export.
+const DEFAULT_MEDIA_MAX_UPLOAD_BYTES = 10 * 1024 * 1024;
+// The build plan's own literal example ("every 30 minutes"), adopted
+// as-is rather than re-litigated - its own [REVIEW] flag was about
+// whether checkpoints belong on main vs a dedicated branch (resolved:
+// main), not this number specifically.
+const DEFAULT_CHECKPOINT_INTERVAL_MS = 1_800_000;
+const VALID_SCOPES = new Set(['content', 'theme', 'media']);
+// sha256 digest, hex-encoded: exactly 64 lowercase hex characters.
+const HEX64_PATTERN = /^[0-9a-f]{64}$/;
+// A loose IPv4/IPv6-shaped typo-catcher, not a real IP parser -
+// exact-IP-only is a deliberate scope reduction (see ip-allowlist.ts),
+// so this doesn't need to be exhaustive either.
+const IP_SHAPE_PATTERN = /^[0-9a-fA-F:.]+$/;
+function parseTokens(value) {
+    if (value === undefined) {
+        // Absent entirely -> no configured tokens -> every scope check
+        // fails closed (401 on everything). The safe default, not an
+        // incidental side effect - see server-config.test.ts's explicit
+        // "no tokens configured" case.
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new StartupCheckError('invalid-token-config', 'site.config.json\'s "tokens" must be an array');
+    }
+    const seenHashes = new Set();
+    const tokens = [];
+    value.forEach((entry, index) => {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+            throw new StartupCheckError('invalid-token-config', `tokens[${index}] must be an object`);
+        }
+        const record = entry;
+        const hash = record.hash;
+        if (typeof hash !== 'string' || !HEX64_PATTERN.test(hash)) {
+            throw new StartupCheckError('invalid-token-config', `tokens[${index}].hash must be a 64-character hex-encoded sha256 digest`);
+        }
+        if (seenHashes.has(hash)) {
+            throw new StartupCheckError('invalid-token-config', `tokens[${index}].hash duplicates an earlier entry`);
+        }
+        seenHashes.add(hash);
+        const scopesValue = record.scopes;
+        if (!Array.isArray(scopesValue) || scopesValue.length === 0) {
+            throw new StartupCheckError('invalid-token-config', `tokens[${index}].scopes must be a non-empty array`);
+        }
+        const scopes = scopesValue.map((scope) => {
+            if (typeof scope !== 'string' || !VALID_SCOPES.has(scope)) {
+                throw new StartupCheckError('invalid-token-config', `tokens[${index}].scopes contains an unknown scope: ${JSON.stringify(scope)}`);
+            }
+            return scope;
+        });
+        tokens.push({ hash, scopes });
+    });
+    return tokens;
+}
+function parseRateLimit(value) {
+    if (value === undefined) {
+        // Absent entirely -> the default limit applies - matches tokens'/
+        // port's own "absence is not an error" philosophy.
+        return DEFAULT_RATE_LIMIT;
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new StartupCheckError('invalid-site-config', 'site.config.json\'s "rateLimit" must be an object');
+    }
+    const record = value;
+    const max = record.max;
+    if (typeof max !== 'number' || !Number.isInteger(max) || max < 1) {
+        throw new StartupCheckError('invalid-site-config', `site.config.json's "rateLimit.max" must be a positive integer, got ${JSON.stringify(max)}`);
+    }
+    const windowMs = record.windowMs;
+    if (typeof windowMs !== 'number' || !Number.isInteger(windowMs) || windowMs < 1) {
+        throw new StartupCheckError('invalid-site-config', `site.config.json's "rateLimit.windowMs" must be a positive integer, got ${JSON.stringify(windowMs)}`);
+    }
+    return { max, windowMs };
+}
+function parseMedia(value) {
+    if (value === undefined) {
+        // Absent entirely -> the default limit applies, matching every
+        // other optional-object field's own "absence is not an error"
+        // philosophy.
+        return { maxUploadBytes: DEFAULT_MEDIA_MAX_UPLOAD_BYTES };
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new StartupCheckError('invalid-site-config', 'site.config.json\'s "media" must be an object');
+    }
+    const record = value;
+    const maxUploadBytes = record.maxUploadBytes;
+    if (maxUploadBytes === undefined) {
+        return { maxUploadBytes: DEFAULT_MEDIA_MAX_UPLOAD_BYTES };
+    }
+    if (typeof maxUploadBytes !== 'number' || !Number.isInteger(maxUploadBytes) || maxUploadBytes < 1) {
+        throw new StartupCheckError('invalid-site-config', `site.config.json's "media.maxUploadBytes" must be a positive integer, got ${JSON.stringify(maxUploadBytes)}`);
+    }
+    return { maxUploadBytes };
+}
+function parseTrustProxy(value) {
+    if (value === undefined) {
+        // Absent -> false, matching a bare single-process, no-reverse-
+        // proxy deployment assumption unless an operator explicitly opts
+        // in.
+        return false;
+    }
+    if (typeof value !== 'boolean') {
+        throw new StartupCheckError('invalid-site-config', `site.config.json's "trustProxy" must be a boolean, got ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+function parseIpAllowlist(value) {
+    if (value === undefined) {
+        // Absent -> [] -> a no-op (checklist H3), not "nothing is
+        // allowed" - see ip-allowlist.ts's isIpAllowed.
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new StartupCheckError('invalid-site-config', 'site.config.json\'s "ipAllowlist" must be an array');
+    }
+    value.forEach((entry, index) => {
+        if (typeof entry !== 'string' || entry.length === 0 || !IP_SHAPE_PATTERN.test(entry)) {
+            throw new StartupCheckError('invalid-site-config', `ipAllowlist[${index}] must be a non-empty IP-address-shaped string, got ${JSON.stringify(entry)}`);
+        }
+    });
+    return value;
+}
+function parseCheckpointIntervalMs(value) {
+    if (value === undefined) {
+        return DEFAULT_CHECKPOINT_INTERVAL_MS;
+    }
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+        throw new StartupCheckError('invalid-site-config', `site.config.json's "checkpointIntervalMs" must be a positive integer, got ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+// Kept separate from SiteConfig (src/config.ts, pure filesystem paths)
+// and from BootedSite (src/boot.ts): this is site.config.json's
+// non-path settings. Later groups add fields here without needing to
+// restructure this module or its callers - the "media" field below is
+// exactly that: the max-upload-size setting anticipated here since
+// Phase 2 planning, now landed as Phase 4's local-storage foundation.
+//
+// Two different failure classes: the file being entirely absent is
+// not an error (defaults silently) - the whole Phase 1 test estate
+// has no site.config.json and shouldn't need one invented just to
+// boot. The file existing but being malformed IS an error (the
+// operator wrote it and got it wrong), consistent with
+// startup-checks.ts's fail-fast discipline. Token rotation requires a
+// restart, since this loads once at boot - matches the existing
+// "agent upgrade = restart" story already established for schema
+// migrations, a deliberate decision, not an accident.
+export function loadServerConfig(siteRoot) {
+    const configPath = join(siteRoot, VHOST_DIR_NAME, 'site.config.json');
+    let raw;
+    try {
+        raw = readFileSync(configPath, 'utf-8');
+    }
+    catch {
+        return {
+            port: DEFAULT_PORT,
+            tokens: [],
+            rateLimit: DEFAULT_RATE_LIMIT,
+            trustProxy: false,
+            ipAllowlist: [],
+            checkpointIntervalMs: DEFAULT_CHECKPOINT_INTERVAL_MS,
+            media: { maxUploadBytes: DEFAULT_MEDIA_MAX_UPLOAD_BYTES },
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new StartupCheckError('invalid-site-config', `site.config.json is not valid JSON: ${detail}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new StartupCheckError('invalid-site-config', 'site.config.json must be a JSON object');
+    }
+    const record = parsed;
+    const port = record.port ?? DEFAULT_PORT;
+    if (typeof port !== 'number' || !Number.isInteger(port) || port < 0) {
+        throw new StartupCheckError('invalid-site-config', `site.config.json's "port" must be a non-negative integer, got ${JSON.stringify(record.port)}`);
+    }
+    const tokens = parseTokens(record.tokens);
+    const rateLimit = parseRateLimit(record.rateLimit);
+    const trustProxy = parseTrustProxy(record.trustProxy);
+    const ipAllowlist = parseIpAllowlist(record.ipAllowlist);
+    const checkpointIntervalMs = parseCheckpointIntervalMs(record.checkpointIntervalMs);
+    const media = parseMedia(record.media);
+    return { port, tokens, rateLimit, trustProxy, ipAllowlist, checkpointIntervalMs, media };
+}

package/dist/server.d.ts

@@ -0,0 +1,13 @@
+import { type FastifyInstance } from 'fastify';
+import type { BootedSite } from './boot.ts';
+import type { ServerConfig } from './server-config.ts';
+import type { DevTunnel } from './services/dev-tunnel.ts';
+export interface BuildServerOptions {
+    logger?: boolean;
+}
+export interface StartServerOptions extends BuildServerOptions {
+    tunnel?: boolean;
+    startTunnel?: (port: number) => Promise<DevTunnel>;
+}
+export declare function buildServer(booted: BootedSite, serverConfig: ServerConfig, options?: BuildServerOptions): FastifyInstance;
+export declare function startServer(siteRoot: string, options?: StartServerOptions): Promise<FastifyInstance>;

package/dist/server.js

@@ -0,0 +1,163 @@
+import rateLimitPlugin from '@fastify/rate-limit';
+import Fastify, {} from 'fastify';
+import { bootSite } from "./boot.js";
+import { loadServerConfig } from "./server-config.js";
+import { assetsRoutes } from "./routes/assets.js";
+import { v1Routes } from "./routes/index.js";
+import { mediaPublicRoutes } from "./routes/media-public.js";
+import { publicRoutes } from "./routes/public.js";
+import { sitemapRoutes } from "./routes/sitemap.js";
+import { CHECKPOINT_AUTHOR, runCheckpoint } from "./services/checkpoint.js";
+import { startDevTunnel } from "./services/dev-tunnel.js";
+import { startIntervalJob } from "./services/interval-job.js";
+// Never wrap v1Routes (or any route-group plugin it registers) with
+// fastify-plugin (fp()): plain app.register() gives each file its own
+// encapsulation scope by default, which Group B's auth preHandler
+// hooks depend on. Wrapping would silently hoist decorators/hooks to
+// the parent scope and break that later.
+export function buildServer(booted, serverConfig, options = {}) {
+    const app = Fastify({ logger: options.logger ?? false, trustProxy: serverConfig.trustProxy });
+    // global: false - only routes that explicitly opt in via a
+    // config: { rateLimit: {...} } marker on their own route options
+    // (see src/services/rate-limit-config.ts) are ever limited. The
+    // max/timeWindow set here are the configured (or defaulted)
+    // site.config.json values - an opting-in route's own empty
+    // { rateLimit: {} } marker inherits these, verified empirically.
+    // Registered once here, on the root app (an ancestor of v1Routes and
+    // everything it nests), so no individual route file needs to import
+    // this plugin itself. Its own 429 response body shape
+    // ({statusCode, error, message}) already matches this project's own
+    // error-JSON convention exactly - verified empirically before relying
+    // on it, no errorResponseBuilder override needed.
+    app.register(rateLimitPlugin, {
+        global: false,
+        max: serverConfig.rateLimit.max,
+        timeWindow: serverConfig.rateLimit.windowMs,
+    });
+    // Fastify's own default 500 body leaks the raw thrown Error.message
+    // to the client verbatim - confirmed empirically before this was
+    // written. Anything below 500 (e.g. a future route's schema-
+    // validation failure) already carries a safe, specific message and
+    // is passed through unchanged; only 500-and-above gets sanitised.
+    app.setErrorHandler((error, request, reply) => {
+        const statusCode = error.statusCode ?? 500;
+        if (statusCode >= 500) {
+            request.log.error(error);
+            reply.code(statusCode).send({
+                statusCode,
+                error: 'Internal Server Error',
+                message: 'Internal Server Error',
+            });
+            return;
+        }
+        reply.code(statusCode).send({ statusCode, error: error.name || 'Bad Request', message: error.message });
+    });
+    app.register(v1Routes, {
+        prefix: '/v1',
+        config: booted.config,
+        themeSchemas: booted.themeSchemas,
+        pageTemplates: booted.pageTemplates,
+        themeTemplates: booted.themeTemplates,
+        layouts: booted.layouts,
+        engine: booted.engine,
+        tokens: serverConfig.tokens,
+        ipAllowlist: serverConfig.ipAllowlist,
+        maxUploadBytes: serverConfig.media.maxUploadBytes,
+    });
+    // Registered without a /v1 prefix, alongside v1Routes: this is the
+    // site's own public website, not part of the site agent API. Order
+    // relative to v1Routes is not load-bearing - Fastify's router
+    // prefers exact/prefixed matches over this route's wildcard
+    // regardless of registration order (verified empirically). What
+    // actually protects unmatched /v1/* paths from being swallowed as
+    // page lookups is the explicit guard inside publicRoutes itself.
+    app.register(publicRoutes, {
+        config: booted.config,
+        themeTemplates: booted.themeTemplates,
+        layouts: booted.layouts,
+        engine: booted.engine,
+    });
+    // A more specific static-prefixed route than the public catch-all's
+    // own /* wildcard - Fastify prefers it regardless of registration
+    // order (verified empirically), so no guard is needed here the way
+    // publicRoutes needs one against /v1/*.
+    app.register(assetsRoutes, { config: booted.config });
+    // Same "more specific than the public catch-all" reasoning as
+    // assetsRoutes above. Deliberately not registered inside v1Routes
+    // (media.ts's own authenticated /v1/media CRUD routes are what live
+    // there) - this is the public, unauthenticated read side, matching
+    // assetsRoutes/publicRoutes' own placement.
+    //
+    // @fastify/multipart itself is NOT registered here, only inside
+    // media.ts's own plugin scope - see that file's comment for why
+    // (confining it to media routes only, leaving every other route
+    // file's default JSON body parsing untouched).
+    app.register(mediaPublicRoutes, { config: booted.config });
+    // Same "more specific than the public catch-all" reasoning again -
+    // this exact path always wins over publicRoutes' /* wildcard, and
+    // also always wins over a same-named static file under
+    // theme/root/sitemap.xml (see routes/public.ts's root-mirror check).
+    app.register(sitemapRoutes, { config: booted.config });
+    return app;
+}
+// Neither a recurring timer nor process signal handling exists
+// anywhere else in this codebase - this is genuinely new machinery for
+// the low-frequency draft-checkpoint background job (checklist H4).
+// Wired only here, never in buildServer: every existing route test
+// uses buildServer + .inject() directly and must stay completely
+// unaffected by any of this.
+export async function startServer(siteRoot, options = {}) {
+    const booted = bootSite(siteRoot);
+    const serverConfig = loadServerConfig(siteRoot);
+    const app = buildServer(booted, serverConfig, options);
+    const doCheckpoint = () => runCheckpoint(booted.config, CHECKPOINT_AUTHOR);
+    const scheduler = startIntervalJob(doCheckpoint, serverConfig.checkpointIntervalMs, (error) => {
+        app.log.error(error, 'background draft checkpoint failed');
+    });
+    let tunnel;
+    // Node's default action for an unhandled SIGTERM/SIGINT is immediate
+    // process termination, bypassing all JS-level cleanup - without
+    // this, a real kill/Ctrl-C would never run the final checkpoint
+    // (build plan: "and on graceful shutdown"). process.once (not .on)
+    // self-removes after firing, and is explicitly removed again inside
+    // onClose below, so a test calling app.close() leaves zero global
+    // process-level listeners behind across the many startServer/
+    // buildServer calls the suite makes.
+    const shutdown = () => {
+        app.close().catch((error) => app.log.error(error, 'error during shutdown'));
+    };
+    process.once('SIGTERM', shutdown);
+    process.once('SIGINT', shutdown);
+    app.addHook('onClose', async () => {
+        tunnel?.close();
+        scheduler.stop();
+        process.removeListener('SIGTERM', shutdown);
+        process.removeListener('SIGINT', shutdown);
+        try {
+            await doCheckpoint();
+        }
+        catch (error) {
+            app.log.error(error, 'final draft checkpoint on shutdown failed');
+        }
+    });
+    // host: '0.0.0.0' - Fastify's own default binds 127.0.0.1 only,
+    // which is unreachable from outside any container or remote host.
+    await app.listen({ port: serverConfig.port, host: '0.0.0.0' });
+    if (options.tunnel) {
+        try {
+            tunnel = await (options.startTunnel ?? startDevTunnel)(serverConfig.port);
+            console.log(`Tunnel open: ${tunnel.url}`);
+            console.log('This URL is publicly reachable for as long as this process runs - anyone with it (and a valid API token) can reach this site. Do not leave it running unattended.');
+        }
+        catch (error) {
+            // The site itself is already up and correctly serving locally -
+            // a failed tunnel is not a reason to fail the whole boot.
+            app.log.error(error, 'failed to start dev tunnel');
+            console.error('Failed to start the dev tunnel - the site is still running locally.');
+        }
+    }
+    else {
+        console.log('Tip: run with --tunnel to expose this site publicly for testing against a hosted admin.');
+    }
+    return app;
+}

package/dist/services/batch.d.ts

@@ -0,0 +1,35 @@
+import type { SiteConfig } from '../config.ts';
+import type { CommitAuthor } from './git.ts';
+import type { ThemeSchemas } from './validation.ts';
+export type BatchOperation = {
+    type: 'draft-write';
+    path: string;
+    content: unknown;
+    expectedEtag: string;
+} | {
+    type: 'draft-discard';
+    path: string;
+} | {
+    type: 'content-delete';
+    path: string;
+    redirectTo?: string;
+} | {
+    type: 'move';
+    from: string;
+    to: string;
+};
+export interface BatchPublish {
+    relativePaths: string[];
+}
+export type BatchReason = 'validation-failed' | 'conflict' | 'page-not-found' | 'has-children' | 'redirect-cycle' | 'invalid-redirect-target' | 'source-not-found' | 'destination-exists' | 'draft-not-found' | 'duplicate-path' | 'write-failed' | 'commit-failed' | 'rollback-failed';
+export declare class BatchError extends Error {
+    readonly reason: BatchReason;
+    readonly stage?: 'operation' | 'publish';
+    readonly operationIndex?: number;
+    constructor(reason: BatchReason, message: string, options?: {
+        cause?: unknown;
+        stage?: 'operation' | 'publish';
+        operationIndex?: number;
+    });
+}
+export declare function runBatch(config: SiteConfig, themeSchemas: ThemeSchemas, operations: BatchOperation[], publish: BatchPublish | undefined, message: string, author: CommitAuthor): Promise<void>;