@minamocms/framework 0.0.0-stage → 0.10.2

package/dist/renderer/engine.js

@@ -0,0 +1,48 @@
+import { Liquid } from 'liquidjs';
+// Called exactly once, inside bootSite - never a setter invoked again
+// mid-process. This is what keeps "every theme file read once at
+// boot" a structural guarantee rather than a convention: a mutable
+// singleton with a snippets setter would let a future caller silently
+// reload snippets without a restart, exactly what this design exists
+// to avoid.
+//
+// Nothing beyond these constructor options is ever configured: no
+// registerTag, no registerFilter, no plugin() - ever (constraint: no
+// dynamically registered Liquid tags or filters). fs and
+// relativeReference are stock constructor options, not registered
+// tags/filters - confirmed empirically that the built-in `render` tag
+// resolves purely against the in-memory `snippets` map below, with no
+// disk access at all, and that a snippet rendered this way is still
+// bounded by renderLimit (see test/renderer/engine.test.ts, D8, and
+// test/renderer/snippets.test.ts).
+//
+// outputEscape: 'escape' makes {{ value }} escape HTML by default (a
+// stock constructor option, not a registered filter/tag), with an
+// explicit `| raw` as the only opt-out - used for pre-rendered block
+// HTML that was already safely rendered by an earlier parseAndRender
+// call (see render-page.ts), and for content_for_layout in a layout
+// template for the same reason.
+//
+// renderLimit: 50 (ms) is the only reliable defence against a runaway
+// template: an external Promise.race/setTimeout wrapper cannot abort a
+// synchronous-only render (LiquidJS's drive loop only yields to the
+// event loop when it awaits an actual Promise), confirmed empirically.
+// This bounds a single parseAndRender call, not a whole page: a page
+// with many sections/blocks each individually finishing just under
+// budget has no aggregate ceiling. A page-level wall-clock guard is a
+// Phase 2 route-handler concern, once there is an actual request to
+// bound - not solved here.
+export function createEngine(snippets) {
+    return new Liquid({
+        outputEscape: 'escape',
+        renderLimit: 50,
+        relativeReference: false,
+        fs: {
+            exists: async (file) => file in snippets,
+            existsSync: (file) => file in snippets,
+            readFile: async (file) => snippets[file],
+            readFileSync: (file) => snippets[file],
+            resolve: (_root, file) => file,
+        },
+    });
+}

package/dist/renderer/render-cache.d.ts

@@ -0,0 +1,11 @@
+export interface RenderCacheEntry {
+    html: string;
+    pageMtimeMs: number;
+    menusMtimeMs: number;
+    themeGeneration: number;
+}
+export interface RenderCache {
+    get(renderPath: string): RenderCacheEntry | undefined;
+    set(renderPath: string, entry: RenderCacheEntry): void;
+}
+export declare function createRenderCache(): RenderCache;

package/dist/renderer/render-cache.js

@@ -0,0 +1,11 @@
+export function createRenderCache() {
+    const map = new Map();
+    return {
+        get(renderPath) {
+            return map.get(renderPath);
+        },
+        set(renderPath, entry) {
+            map.set(renderPath, entry);
+        },
+    };
+}

package/dist/renderer/render-page.d.ts

@@ -0,0 +1,34 @@
+import type { Liquid } from 'liquidjs';
+import type { SiteConfig } from '../config.ts';
+import type { ThemeTemplates } from './theme-templates.ts';
+import { type SiteSettings } from '../services/site-settings.ts';
+export type PageRenderReason = 'page-not-found' | 'missing-section-type' | 'missing-block-type' | 'missing-layout' | 'template-error';
+export declare class PageRenderError extends Error {
+    readonly reason: PageRenderReason;
+    constructor(reason: PageRenderReason, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface SectionOrBlockInstance {
+    id: string;
+    type: string;
+    settings: Record<string, unknown>;
+    blocks?: SectionOrBlockInstance[];
+}
+export interface PageContent {
+    schemaVersion: number;
+    title: string;
+    published: boolean;
+    layout: string;
+    sections: SectionOrBlockInstance[];
+    author?: string;
+    publishDate?: string;
+    tags?: string[];
+}
+export declare function renderSections(page: PageContent, themeTemplates: ThemeTemplates, engine: Liquid, siteSettings?: SiteSettings): Promise<string>;
+export type RenderMode = 'public' | 'preview';
+export declare function parsePageContent(raw: string): PageContent;
+export declare function renderLoadedPage(page: PageContent, config: SiteConfig, themeTemplates: ThemeTemplates, layouts: Record<string, string>, engine: Liquid, siteSettings?: SiteSettings): Promise<string>;
+export declare function renderPage(config: SiteConfig, themeTemplates: ThemeTemplates, layouts: Record<string, string>, engine: Liquid, relativePath: string, mode: RenderMode, siteSettings?: SiteSettings): Promise<string>;
+export declare function getPageMtimeMs(config: SiteConfig, relativePath: string): number | null;
+export declare function getMenusMtimeMs(config: SiteConfig): number;

package/dist/renderer/render-page.js

@@ -0,0 +1,209 @@
+import { readFileSync, statSync } from 'node:fs';
+import { listFilesRecursively } from "../services/fs-walk.js";
+import { loadMenus } from "../services/menus.js";
+import { sanitisePath } from "../services/path-safety.js";
+import { siteSettingsMtimeMs } from "../services/site-settings.js";
+export class PageRenderError extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.name = 'PageRenderError';
+        this.reason = reason;
+    }
+}
+function pageEnvelope(page) {
+    return { title: page.title, author: page.author, publishDate: page.publishDate, tags: page.tags };
+}
+// Renders one section or block, recursively rendering any nested blocks
+// first (instance.schema.json is self-referential, so a block can carry
+// its own nested blocks). Never uses {% include %}/{% render %}: block
+// HTML is pre-rendered here in JS and handed to the parent template as
+// a plain array, which sidesteps LiquidJS's own filesystem include
+// resolution entirely.
+// Site settings reach every template in a render - layout, sections,
+// blocks, and snippets pulled in with {% render %} (which otherwise sees
+// only what it is passed) - as `settings`, via Liquid's per-render
+// globals. Shopify's name for the same thing; no clash with
+// section.settings/block.settings, which are nested.
+function settingsGlobals(siteSettings) {
+    return { globals: { settings: siteSettings } };
+}
+async function renderInstance(instance, kind, themeTemplates, engine, page, siteSettings) {
+    const templates = kind === 'section' ? themeTemplates.sections : themeTemplates.blocks;
+    const template = templates[instance.type];
+    if (!template) {
+        throw new PageRenderError(kind === 'section' ? 'missing-section-type' : 'missing-block-type', `${kind === 'section' ? 'Section' : 'Block'} type "${instance.type}" is missing from the theme (${kind} id: "${instance.id}")`);
+    }
+    const blocksHtml = [];
+    for (const block of instance.blocks ?? []) {
+        blocksHtml.push(await renderInstance(block, 'block', themeTemplates, engine, page, siteSettings));
+    }
+    // Shopify-style scope shape: settings nested under the instance, not
+    // flattened, so templates read section.settings.x / block.settings.x.
+    // `page` is the same built-in envelope a layout gets (title plus the
+    // optional author/publishDate/tags fields) - lets a section print a
+    // byline/date without duplicating it into a settings field.
+    const scope = kind === 'section'
+        ? { section: { id: instance.id, type: instance.type, settings: instance.settings }, blocksHtml, page }
+        : { block: { id: instance.id, type: instance.type, settings: instance.settings }, blocksHtml, page };
+    try {
+        return (await engine.parseAndRender(template, scope, settingsGlobals(siteSettings)));
+    }
+    catch (error) {
+        if (error instanceof PageRenderError) {
+            throw error;
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new PageRenderError('template-error', `Failed to render ${kind} "${instance.id}" (type "${instance.type}"): ${detail}`, { cause: error });
+    }
+}
+// Renders a page's top-level sections, in declared order, concatenated.
+// No page-level layout/wrapper concept in Phase 1 - this is the whole
+// output.
+export async function renderSections(page, themeTemplates, engine, siteSettings = {}) {
+    const envelope = pageEnvelope(page);
+    const html = [];
+    for (const section of page.sections) {
+        html.push(await renderInstance(section, 'section', themeTemplates, engine, envelope, siteSettings));
+    }
+    return html.join('');
+}
+// The layout a page with no layout field (or an invalid one) gets
+// defaulted to. boot.ts never auto-migrates content, so a real site
+// can have pre-existing pages that predate this field entirely - this
+// default must match migrateV3ToV4's own default exactly, so render
+// behaviour is identical whether or not a site has ever run its
+// migrations (content-read.ts established this same defensive-read
+// pattern for the "type" field).
+const DEFAULT_LAYOUT = 'theme';
+// Throws on invalid JSON rather than swallowing to null - callers reading
+// a specific historical revision (preview-revision.ts) want to know "the
+// JSON at this ref is broken" as a distinct, reportable case, whereas
+// tryReadPage's null return means "nothing here, try the next root".
+export function parsePageContent(raw) {
+    const parsed = JSON.parse(raw);
+    const layout = typeof parsed.layout === 'string' && parsed.layout.length > 0 ? parsed.layout : DEFAULT_LAYOUT;
+    return { ...parsed, layout };
+}
+function tryReadPage(root, relativePath) {
+    const fullPath = sanitisePath(root, relativePath);
+    try {
+        return parsePageContent(readFileSync(fullPath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+// Public mode reads /content/ only, and treats published: false the same
+// as "doesn't exist" - this is what makes unpublish actually take a
+// page offline (checklist C8: the renderer skips unpublished pages).
+// Preview mode overlays /drafts/ over /content/, falling back to live
+// when no draft exists, and deliberately does NOT filter on published:
+// an editor needs to see a currently-unpublished page to review it
+// before republishing.
+function loadPageForRender(config, relativePath, mode) {
+    if (mode === 'preview') {
+        const draft = tryReadPage(config.draftsRoot, relativePath);
+        if (draft) {
+            return draft;
+        }
+        const live = tryReadPage(config.contentRoot, relativePath);
+        if (live) {
+            return live;
+        }
+        throw new PageRenderError('page-not-found', `No page found at "${relativePath}"`);
+    }
+    const live = tryReadPage(config.contentRoot, relativePath);
+    if (!live || live.published === false) {
+        throw new PageRenderError('page-not-found', `No publicly reachable page found at "${relativePath}"`);
+    }
+    return live;
+}
+// The shared back half of rendering: takes a page already loaded from
+// wherever (current draft/live disk state via loadPageForRender, or a
+// historical git blob via readFileAtRevision + parsePageContent) and runs
+// it through the identical layout/section/menu pipeline - so "render
+// what's on disk" and "render this specific historical revision" never
+// duplicate this logic.
+export async function renderLoadedPage(page, config, themeTemplates, layouts, engine, siteSettings = {}) {
+    // Checked before rendering any sections, matching the fail-fast
+    // ordering missing-section-type/missing-block-type already
+    // establish - no point rendering a page's whole body just to
+    // discover its layout doesn't exist.
+    const layoutTemplate = layouts[page.layout];
+    if (!layoutTemplate) {
+        throw new PageRenderError('missing-layout', `Layout "${page.layout}" is missing from the theme`);
+    }
+    const bodyHtml = await renderSections(page, themeTemplates, engine, siteSettings);
+    // Menus are content, not theme data - loaded fresh here rather than
+    // once at boot, same freshness guarantee as the page itself. Scoped
+    // to the layout only (not threaded into renderSections/renderInstance
+    // above), matching the confirmed requirement: a layout renders nav,
+    // sections/blocks don't need it in this pass. No mode distinction:
+    // menus have no draft state (Group N), always the live file. This
+    // also means a historical page preview always shows today's menus,
+    // never a menu as it existed at that revision - an accepted limitation.
+    const menus = loadMenus(config);
+    // content_for_layout is already-rendered, already-safe HTML (like
+    // blocksHtml handed to a section template) - the layout template
+    // itself must use `{{ content_for_layout | raw }}`, or engine.ts's
+    // outputEscape: 'escape' double-escapes it into literal text.
+    return (await engine.parseAndRender(layoutTemplate, {
+        content_for_layout: bodyHtml,
+        page: pageEnvelope(page),
+        menus,
+    }, settingsGlobals(siteSettings)));
+}
+export async function renderPage(config, themeTemplates, layouts, engine, relativePath, mode, siteSettings = {}) {
+    const page = loadPageForRender(config, relativePath, mode);
+    return renderLoadedPage(page, config, themeTemplates, layouts, engine, siteSettings);
+}
+// For public.ts's render cache: the page's own current mtime, so a
+// cached render can be validated against real filesystem state rather
+// than needing every write path (publish/unpublish/delete/move/batch)
+// to remember to invalidate something. null means "not cacheable this
+// time" (the file vanished between resolveUrl confirming it exists and
+// this call - vanishingly unlikely, not a hard failure) rather than
+// throwing, since a cache-freshness check is never the place to
+// surface a real error - the ordinary render path below still will.
+export function getPageMtimeMs(config, relativePath) {
+    try {
+        return statSync(sanitisePath(config.contentRoot, relativePath)).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+// A menu edit affects every page's rendered nav, not just one page, so
+// the cache's freshness check needs one value covering all menus
+// together rather than per-page tracking. The max mtime across every
+// menu file covers an edit. It does not cover a menu being renamed (a
+// handle change keeps the file's mtime) or deleted (removes one), so
+// the menus directory's own mtime is included too: that changes
+// whenever an entry is added, renamed or removed. Menus are flat, so
+// the one directory is enough. 0 (never stale relative to anything)
+// when there are no menus at all, matching listFilesRecursively's own
+// "missing directory returns []" behaviour.
+export function getMenusMtimeMs(config) {
+    // Site settings too: like menus, they feed every page.
+    let max = siteSettingsMtimeMs(config);
+    try {
+        max = Math.max(max, statSync(config.menusRoot).mtimeMs);
+    }
+    catch {
+        // No content/menus/ at all - nothing to track.
+    }
+    for (const relativePath of listFilesRecursively(config.menusRoot, config.menusRoot, '.json')) {
+        try {
+            const { mtimeMs } = statSync(sanitisePath(config.menusRoot, relativePath));
+            if (mtimeMs > max) {
+                max = mtimeMs;
+            }
+        }
+        catch {
+            // Vanished between the directory walk and this stat (e.g. a
+            // concurrent delete) - doesn't contribute, not fatal.
+        }
+    }
+    return max;
+}

package/dist/renderer/theme-templates.d.ts

@@ -0,0 +1,7 @@
+export interface ThemeTemplates {
+    sections: Record<string, string>;
+    blocks: Record<string, string>;
+}
+export declare function loadThemeTemplates(themeRoot: string): ThemeTemplates;
+export declare function loadSnippets(themeRoot: string): Record<string, string>;
+export declare function loadLayouts(themeRoot: string): Record<string, string>;

package/dist/renderer/theme-templates.js

@@ -0,0 +1,82 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseThemeComponentFile } from "../services/theme-component-file.js";
+// themeRoot is agent configuration (the configured site's theme
+// directory), not a request-supplied :path parameter. This walk is
+// deliberately NOT the Group B path-sanitisation helper and must
+// never be reused for untrusted request paths.
+//
+// Flat *.liquid files, one per type, named directly (e.g. hero.liquid,
+// media-text.liquid) - no subfolder per type, no separate schema.json.
+// Mirrors loadFlatTemplates below exactly, extended to strip the
+// embedded {% schema %} block (via theme-component-file.ts's shared
+// parser - the same parse theme-schemas.ts uses for the other half of
+// the same file) before handing the remaining markup to the Liquid
+// engine, since {% schema %} is never a real, live Liquid tag.
+function loadTypeTemplates(typesDir) {
+    const templates = {};
+    let entries;
+    try {
+        entries = readdirSync(typesDir, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && entry.name.endsWith('.liquid'))
+            .map((entry) => entry.name);
+    }
+    catch {
+        return templates;
+    }
+    for (const fileName of entries) {
+        const type = fileName.slice(0, -'.liquid'.length);
+        let source;
+        try {
+            source = readFileSync(join(typesDir, fileName), 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const parsed = parseThemeComponentFile(source);
+        if (!parsed) {
+            continue;
+        }
+        templates[type] = parsed.markup;
+    }
+    return templates;
+}
+export function loadThemeTemplates(themeRoot) {
+    return {
+        sections: loadTypeTemplates(join(themeRoot, 'sections')),
+        blocks: loadTypeTemplates(join(themeRoot, 'blocks')),
+    };
+}
+// Flat *.liquid files, one per name, no subdirectory-per-name and no
+// co-located schema.json - unlike sections/blocks, snippets and
+// layouts are theme-author code with no user-facing settings to
+// declare, matching Shopify's own flat snippets/layouts convention.
+// Same agent-configuration-not-request-path caveat as loadTypeTemplates.
+function loadFlatTemplates(dir) {
+    const templates = {};
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && entry.name.endsWith('.liquid'))
+            .map((entry) => entry.name);
+    }
+    catch {
+        return templates;
+    }
+    for (const fileName of entries) {
+        const name = fileName.slice(0, -'.liquid'.length);
+        try {
+            templates[name] = readFileSync(join(dir, fileName), 'utf-8');
+        }
+        catch {
+            continue;
+        }
+    }
+    return templates;
+}
+export function loadSnippets(themeRoot) {
+    return loadFlatTemplates(join(themeRoot, 'snippets'));
+}
+export function loadLayouts(themeRoot) {
+    return loadFlatTemplates(join(themeRoot, 'layouts'));
+}

package/dist/routes/admin-redirect.d.ts

@@ -0,0 +1,5 @@
+import type { FastifyPluginAsync } from 'fastify';
+export interface AdminRedirectRouteOptions {
+    adminBaseUrl: string;
+}
+export declare const adminRedirectRoutes: FastifyPluginAsync<AdminRedirectRouteOptions>;

package/dist/routes/admin-redirect.js

@@ -0,0 +1,26 @@
+import { NO_AUTH_ROUTE_RATE_LIMIT } from "../services/rate-limit-config.js";
+// Only ever registered by server.ts when serverConfig.adminBaseUrl is
+// actually set - that's what makes this genuinely opt-in, not a
+// reserved namespace like /media or /assets. A site that hasn't
+// configured this can still use "admin" as an ordinary page path,
+// same reasoning as GET /search.json over reserving all of /search.
+//
+// Redirects to adminBaseUrl with the requesting host appended as
+// ?site=, never a deep link with a site ID baked in - keeps this
+// agent completely decoupled from any particular admin app's own URL
+// scheme, so a self-hoster running a different admin frontend just
+// points adminBaseUrl at it. request.host (not request.hostname,
+// which strips the port - same reasoning sitemap.ts already
+// documents) so the admin side can match it directly against
+// new URL(registeredSiteUrl).host.
+//
+// Deliberately unauthenticated: this is a discovery aid an operator
+// (or anyone) can hit before they have a token, same class of
+// zero-credential route as GET /v1/capabilities and GET /search.json.
+export const adminRedirectRoutes = async (fastify, opts) => {
+    fastify.get('/admin', { config: NO_AUTH_ROUTE_RATE_LIMIT }, async (request, reply) => {
+        const target = new URL(opts.adminBaseUrl);
+        target.searchParams.set('site', request.host);
+        reply.code(302).header('location', target.toString()).send();
+    });
+};

package/dist/routes/assets.d.ts

@@ -0,0 +1,6 @@
+import type { FastifyPluginAsync } from 'fastify';
+import type { SiteConfig } from '../config.ts';
+export interface AssetsRouteOptions {
+    config: SiteConfig;
+}
+export declare const assetsRoutes: FastifyPluginAsync<AssetsRouteOptions>;

package/dist/routes/assets.js

@@ -0,0 +1,30 @@
+import { findStaticFile, sendStaticFile } from "../services/static-file.js";
+async function handleAssetRequest(request, reply, config) {
+    const relativePath = request.params['*'];
+    const match = findStaticFile(config.assetsRoot, relativePath);
+    if (!match) {
+        reply.code(404).send({ statusCode: 404, error: 'Not Found', message: `No asset at "${relativePath}"` });
+        return;
+    }
+    // A synchronous buffered read, not a stream: reply.send(stream) was
+    // verified empirically to produce an empty body in this Fastify
+    // version (confirmed both via .inject() and a real socket, isolated
+    // down to a minimal repro) - a real, environment-specific problem,
+    // not a mistake in this route's own logic. No Range/If-Range support
+    // in this pass either way (nothing has asked for large-file
+    // streaming yet), so buffering the whole file is not a meaningful
+    // regression. sendStaticFile (services/static-file.ts) does this
+    // read, shared with routes/public.ts's root-mirror check.
+    sendStaticFile(reply, match);
+}
+// Deliberately and permanently unauthenticated: static assets (CSS/JS/
+// images) must be fetchable by any visitor's browser without a token,
+// same as the public website itself. Registered without a /v1 prefix,
+// directly on app in server.ts, alongside publicRoutes. No guard
+// against the public catch-all's own /* wildcard is needed here - this
+// is the more specific static-prefixed route winning cleanly (verified
+// empirically), not the reverse case that needed public.ts's /v1/*
+// guard.
+export const assetsRoutes = async (fastify, opts) => {
+    fastify.get('/assets/*', async (request, reply) => handleAssetRequest(request, reply, opts.config));
+};

package/dist/routes/batch.d.ts

@@ -0,0 +1,10 @@
+import type { FastifyPluginAsync } from 'fastify';
+import type { SiteConfig } from '../config.ts';
+import type { ThemeState } from '../theme-state.ts';
+import type { TokenEntry } from '../server-config.ts';
+export interface BatchRouteOptions {
+    config: SiteConfig;
+    theme: ThemeState;
+    tokens: TokenEntry[];
+}
+export declare const batchRoutes: FastifyPluginAsync<BatchRouteOptions>;

package/dist/routes/batch.js

@@ -0,0 +1,148 @@
+import { BatchError, runBatch } from "../services/batch.js";
+import { isValidCommitAuthor } from "../services/git.js";
+import { PathSafetyError } from "../services/path-safety.js";
+import { WRITE_ROUTE_RATE_LIMIT } from "../services/rate-limit-config.js";
+import { requireScope } from "../services/token-auth.js";
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+function parseOperation(value) {
+    if (!isPlainObject(value)) {
+        return null;
+    }
+    const { type } = value;
+    switch (type) {
+        case 'draft-write': {
+            const { path, content, expectedEtag } = value;
+            if (!isNonEmptyString(path) || !isPlainObject(content) || !isNonEmptyString(expectedEtag)) {
+                return null;
+            }
+            return { type, path, content, expectedEtag };
+        }
+        case 'draft-discard': {
+            const { path } = value;
+            if (!isNonEmptyString(path)) {
+                return null;
+            }
+            return { type, path };
+        }
+        case 'content-delete': {
+            const { path, redirectTo } = value;
+            if (!isNonEmptyString(path) || (redirectTo !== undefined && !isNonEmptyString(redirectTo))) {
+                return null;
+            }
+            return { type, path, redirectTo };
+        }
+        case 'move': {
+            const { from, to } = value;
+            if (!isNonEmptyString(from) || !isNonEmptyString(to)) {
+                return null;
+            }
+            return { type, from, to };
+        }
+        default:
+            return null;
+    }
+}
+function parsePublish(value) {
+    if (!isPlainObject(value)) {
+        return null;
+    }
+    const { paths } = value;
+    if (!Array.isArray(paths) || paths.length === 0 || !paths.every(isNonEmptyString)) {
+        return null;
+    }
+    return { relativePaths: paths };
+}
+const BATCH_BODY_SHAPE = 'Expected { operations: BatchOperation[], publish?: { paths: string[] }, message: string, author: { name, email } }';
+function parseBatchBody(body) {
+    if (!isPlainObject(body)) {
+        return null;
+    }
+    const { operations, publish, message, author } = body;
+    if (!Array.isArray(operations)) {
+        return null;
+    }
+    const parsedOperations = [];
+    for (const raw of operations) {
+        const operation = parseOperation(raw);
+        if (!operation) {
+            return null;
+        }
+        parsedOperations.push(operation);
+    }
+    let parsedPublish;
+    if (publish !== undefined) {
+        const result = parsePublish(publish);
+        if (!result) {
+            return null;
+        }
+        parsedPublish = result;
+    }
+    if (!isNonEmptyString(message) || !isValidCommitAuthor(author)) {
+        return null;
+    }
+    return { operations: parsedOperations, publish: parsedPublish, message, author };
+}
+// Maps every BatchReason to a status code, mirroring the same mapping
+// each originating service's own route already applies (publish.ts's
+// replyForPublishError, content.ts's move/delete handlers, drafts.ts's
+// conflict/validation-failed handling) - kept as one switch here since
+// batch.ts's BatchReason is a superset drawn from all four services.
+function replyForBatchError(reply, error) {
+    switch (error.reason) {
+        case 'conflict':
+            reply.code(409).send({ statusCode: 409, error: 'Conflict', message: error.message });
+            return;
+        case 'destination-exists':
+            reply.code(409).send({ statusCode: 409, error: 'Conflict', message: error.message });
+            return;
+        case 'has-children':
+            reply.code(409).send({ statusCode: 409, error: 'Conflict', message: error.message });
+            return;
+        case 'validation-failed':
+        case 'duplicate-path':
+        case 'redirect-cycle':
+            reply.code(400).send({ statusCode: 400, error: 'Bad Request', message: error.message });
+            return;
+        case 'page-not-found':
+        case 'source-not-found':
+        case 'draft-not-found':
+            reply.code(404).send({ statusCode: 404, error: 'Not Found', message: error.message });
+            return;
+        default:
+            // write-failed / commit-failed / rollback-failed: no client-side
+            // fix applies, fall through to the global handler's sanitised 500.
+            throw error;
+    }
+}
+export const batchRoutes = async (fastify, opts) => {
+    fastify.post('/batch', { preHandler: requireScope(opts.tokens, 'content'), config: WRITE_ROUTE_RATE_LIMIT }, async (request, reply) => {
+        const parsed = parseBatchBody(request.body);
+        if (!parsed) {
+            reply.code(400).send({ statusCode: 400, error: 'Bad Request', message: BATCH_BODY_SHAPE });
+            return;
+        }
+        try {
+            await runBatch(opts.config, opts.theme.current.themeSchemas, parsed.operations, parsed.publish, parsed.message, parsed.author);
+            reply.send({ ok: true });
+        }
+        catch (error) {
+            // PathSafetyError has no .statusCode - left uncaught it falls
+            // through to the global handler's sanitised 500, the same gap
+            // every other route touching a :path already guards against.
+            if (error instanceof PathSafetyError) {
+                reply.code(404).send({ statusCode: 404, error: 'Not Found', message: 'No content at that path' });
+                return;
+            }
+            if (error instanceof BatchError) {
+                replyForBatchError(reply, error);
+                return;
+            }
+            throw error;
+        }
+    });
+};

package/dist/routes/capabilities.d.ts

@@ -0,0 +1,6 @@
+import type { FastifyPluginAsync } from 'fastify';
+export declare function readAgentVersion(): string;
+export interface CapabilitiesRouteOptions {
+    maxUploadBytes: number;
+}
+export declare const capabilitiesRoutes: FastifyPluginAsync<CapabilitiesRouteOptions>;