@o-a/cms-agent 0.1.6 → 0.2.0

package/dist/boot.d.ts

@@ -1,5 +1,6 @@
 import type { Liquid } from 'liquidjs';
 import type { SiteConfig } from './config.ts';
+import type { RenderCache } from './renderer/render-cache.ts';
 import type { ThemeTemplates } from './renderer/theme-templates.ts';
 import type { StartupCheckOptions } from './services/startup-checks.ts';
 import type { ThemeSchemas } from './services/validation.ts';
@@ -11,5 +12,6 @@ export interface BootedSite {
     layouts: Record<string, string>;
     pageTemplates: PageTemplate[];
     engine: Liquid;
+    renderCache: RenderCache;
 }
 export declare function bootSite(siteRoot: string, options?: StartupCheckOptions): BootedSite;

package/dist/boot.js

@@ -1,5 +1,6 @@
 import { loadSiteConfig } from "./config.js";
 import { createEngine } from "./renderer/engine.js";
+import { createRenderCache } from "./renderer/render-cache.js";
 import { loadLayouts, loadSnippets, loadThemeTemplates } from "./renderer/theme-templates.js";
 import { runStartupChecks } from "./services/startup-checks.js";
 import { loadThemeSchemas } from "./services/theme-schemas.js";
@@ -29,5 +30,6 @@ export function bootSite(siteRoot, options) {
     // page.
     const pageTemplates = loadPageTemplates(config.templatesRoot, themeSchemas);
     const engine = createEngine(snippets);
-    return { config, themeSchemas, themeTemplates, layouts, pageTemplates, engine };
+    const renderCache = createRenderCache();
+    return { config, themeSchemas, themeTemplates, layouts, pageTemplates, engine, renderCache };
 }

package/dist/config.d.ts

@@ -8,7 +8,6 @@ export interface SiteConfig {
     rootMirrorRoot: string;
     templatesRoot: string;
     pagesRoot: string;
-    postsRoot: string;
     menusRoot: string;
     redirectsPath: string;
     vhostRoot: string;

package/dist/config.js

@@ -33,7 +33,6 @@ export function loadSiteConfig(siteRoot) {
         rootMirrorRoot: join(themeRoot, 'root'),
         templatesRoot: join(themeRoot, 'templates'),
         pagesRoot: join(contentRoot, 'pages'),
-        postsRoot: join(contentRoot, 'posts'),
         menusRoot: join(contentRoot, 'menus'),
         // Also nested inside contentRoot, for the same reason.
         redirectsPath: join(contentRoot, 'redirects.json'),

package/dist/media/filename.js

@@ -27,5 +27,8 @@ export function buildMediaFilename(originalFilename, bytes) {
     const cleaned = base.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
     const slug = cleaned.length > 0 ? cleaned : 'file';
     const extension = extname(originalFilename).toLowerCase();
-    return `${hash}-${slug}${extension}`;
+    // Slug first, hash last (requested directly) - the readable part of
+    // the filename sorts and scans first in a directory listing/URL,
+    // with the hash as a suffix rather than something to read past.
+    return `${slug}-${hash}${extension}`;
 }

package/dist/migrations/index.d.ts

@@ -1,3 +1,3 @@
 import type { MigrationMap } from '../services/migration-runner.ts';
-export declare const CURRENT_SCHEMA_VERSION = 5;
+export declare const CURRENT_SCHEMA_VERSION = 6;
 export declare const migrations: MigrationMap;

package/dist/migrations/index.js

@@ -1,7 +1,7 @@
 // The current content schema version. Bumping this and adding a new
 // migrations[N] entry is the only way a content shape may change
 // (constraint 4) - never a manual edit convention.
-export const CURRENT_SCHEMA_VERSION = 5;
+export const CURRENT_SCHEMA_VERSION = 6;
 // A trivial identity migration, proving the mechanism (per the build
 // plan's Phase 1 scope): no shape change, only the version bump. Safe
 // against page.schema.json's schemaVersion: { minimum: 1 } (not an
@@ -41,9 +41,32 @@ function migrateV4ToV5(content) {
     const title = typeof content.title === 'string' ? content.title : '';
     return { ...content, schemaVersion: 5, name: title };
 }
+// Folds the distinct "post" content type into "page" - author,
+// publishDate, and tags become optional fields any page may carry
+// (page.schema.json), and the post-only schema (which required them,
+// but had no "name" field at all) is retired. Ordinary pages already
+// at v5 already have "name"; this is only ever a genuine backfill for
+// a legacy content/posts/*.json file, which never had one. Mirrors the
+// admin's own backfillPageName (derivePageLabel.ts) precisely: fills
+// name from title only when name is genuinely absent, never overwrites
+// an existing one (a page's name may deliberately differ from its
+// title - migrateV4ToV5's own unconditional set was safe only because
+// no content reaching it could already have a name).
+// migration-runner.ts's runMigrationsJob is what physically relocates
+// a legacy content/posts/<slug>.json file to content/pages/blog/<slug>.json
+// alongside this shape change - this function only ever transforms
+// content, never a path.
+function migrateV5ToV6(content) {
+    if ('name' in content) {
+        return { ...content, schemaVersion: 6 };
+    }
+    const title = typeof content.title === 'string' ? content.title : '';
+    return { ...content, schemaVersion: 6, name: title };
+}
 export const migrations = {
     1: migrateV1ToV2,
     2: migrateV2ToV3,
     3: migrateV3ToV4,
     4: migrateV4ToV5,
+    5: migrateV5ToV6,
 };

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

@@ -0,0 +1,10 @@
+export interface RenderCacheEntry {
+    html: string;
+    pageMtimeMs: number;
+    menusMtimeMs: 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

@@ -26,3 +26,5 @@ 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): Promise<string>;
 export declare function renderPage(config: SiteConfig, themeTemplates: ThemeTemplates, layouts: Record<string, string>, engine: Liquid, relativePath: string, mode: RenderMode): 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

@@ -1,4 +1,5 @@
-import { readFileSync } from 'node:fs';
+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";
 export class PageRenderError extends Error {
@@ -141,3 +142,41 @@ export async function renderPage(config, themeTemplates, layouts, engine, relati
     const page = loadPageForRender(config, relativePath, mode);
     return renderLoadedPage(page, config, themeTemplates, layouts, engine);
 }
+// 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 serves that - any single menu changing bumps it. 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) {
+    let max = 0;
+    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/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/capabilities.js

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { CURRENT_SCHEMA_VERSION } from "../migrations/index.js";
-import { CAPABILITIES_RATE_LIMIT } from "../services/rate-limit-config.js";
+import { NO_AUTH_ROUTE_RATE_LIMIT } from "../services/rate-limit-config.js";
 import { DRIVER_NAME } from "../search/drivers/node-sqlite-driver.js";
 // The agent's own bundled package.json, not site data - the same
 // import.meta.dirname-relative pattern already established in
@@ -12,7 +12,7 @@ function readAgentVersion() {
     return packageJson.version ?? '0.0.0';
 }
 export const capabilitiesRoutes = async (fastify, opts) => {
-    fastify.get('/capabilities', { config: CAPABILITIES_RATE_LIMIT }, async () => ({
+    fastify.get('/capabilities', { config: NO_AUTH_ROUTE_RATE_LIMIT }, async () => ({
         agentVersion: readAgentVersion(),
         contentSchemaVersion: CURRENT_SCHEMA_VERSION,
         sqliteDriver: DRIVER_NAME,

package/dist/routes/media-public.js

@@ -25,9 +25,15 @@ async function handleMediaRequest(request, reply, config) {
     // <base href> fix), making genuinely cross-origin browser requests
     // for what looks like a same-origin path. Consistent with this
     // route already being deliberately unauthenticated and public.
+    //
+    // Cache-Control: immutable, a full year - safe unconditionally
+    // because filenames are content-addressed (a hash of the file's own
+    // bytes, see media/filename.ts): a given URL's content can never
+    // change, so there is no invalidation case to ever design for here.
     reply
         .header('X-Content-Type-Options', 'nosniff')
         .header('Access-Control-Allow-Origin', '*')
+        .header('Cache-Control', 'public, max-age=31536000, immutable')
         .type(mimeTypeFor(relativePath))
         .send(bytes);
 }

package/dist/routes/preview-revision.js

@@ -3,7 +3,6 @@ import { PageRenderError, parsePageContent, renderLoadedPage } from "../renderer
 import { GitShowError, readFileAtRevision } from "../services/git-history.js";
 import { isValidGitRef } from "../services/git.js";
 import { PathSafetyError } from "../services/path-safety.js";
-import { isBlogUrl, urlToPostPath } from "../services/post-urls.js";
 import { requireScope } from "../services/token-auth.js";
 import { urlToPagePath } from "../services/urls.js";
 // A dedicated top-level route rather than nesting under /preview/*
@@ -20,14 +19,11 @@ import { urlToPagePath } from "../services/urls.js";
 // readFileAtRevision resolves paths relative to config.siteRoot, not
 // config.contentRoot (confirmed by git-history.ts/git.test.ts's own
 // "content/pages/about.json" usage) - so unlike preview.ts's
-// toRenderPath/toPostsRenderPath (contentRoot-relative), the path
-// built here is prefixed with "content/".
+// toRenderPath (contentRoot-relative), the path built here is prefixed
+// with "content/".
 function toRevisionPath(pagesRelativePath) {
     return join('content', 'pages', pagesRelativePath);
 }
-function toPostsRevisionPath(postsRelativePath) {
-    return join('content', 'posts', postsRelativePath);
-}
 async function handlePreviewRevisionRequest(request, reply, config, themeTemplates, layouts, engine) {
     const { ref } = request.params;
     const url = `/${request.params['*']}`;
@@ -36,19 +32,7 @@ async function handlePreviewRevisionRequest(request, reply, config, themeTemplat
         return;
     }
     try {
-        const isPost = isBlogUrl(url);
-        let repoRelativePath;
-        if (isPost) {
-            const relativePath = urlToPostPath(url);
-            if (relativePath === null) {
-                reply.code(404).send({ statusCode: 404, error: 'Not Found', message: `No page at "${url}"` });
-                return;
-            }
-            repoRelativePath = toPostsRevisionPath(relativePath);
-        }
-        else {
-            repoRelativePath = toRevisionPath(urlToPagePath(url));
-        }
+        const repoRelativePath = toRevisionPath(urlToPagePath(url));
         const raw = readFileAtRevision(config, ref, repoRelativePath);
         const page = parsePageContent(raw.toString('utf-8'));
         const html = await renderLoadedPage(page, config, themeTemplates, layouts, engine);

package/dist/routes/preview.js

@@ -1,7 +1,6 @@
 import { join } from 'node:path';
 import { PageRenderError, renderPage } from "../renderer/render-page.js";
 import { PathSafetyError } from "../services/path-safety.js";
-import { isBlogUrl, urlToPostPath } from "../services/post-urls.js";
 import { requireScope } from "../services/token-auth.js";
 import { urlToPagePath } from "../services/urls.js";
 // Same pagesRoot/contentRoot seam as public.ts - see that file's
@@ -11,26 +10,9 @@ import { urlToPagePath } from "../services/urls.js";
 function toRenderPath(pagesRelativePath) {
     return join('pages', pagesRelativePath);
 }
-// Same seam as toRenderPath above, for posts.
-function toPostsRenderPath(postsRelativePath) {
-    return join('posts', postsRelativePath);
-}
 async function handlePreviewRequest(request, reply, config, themeTemplates, layouts, engine) {
     const url = `/${request.params['*']}`;
     try {
-        // /blog is a permanently reserved namespace, same as public.ts -
-        // no redirects.json fallback here either way (preview never
-        // consults it, per this file's own established comment above).
-        if (isBlogUrl(url)) {
-            const relativePath = urlToPostPath(url);
-            if (relativePath === null) {
-                reply.code(404).send({ statusCode: 404, error: 'Not Found', message: `No page at "${url}"` });
-                return;
-            }
-            const html = await renderPage(config, themeTemplates, layouts, engine, toPostsRenderPath(relativePath), 'preview');
-            reply.type('text/html; charset=utf-8').send(html);
-            return;
-        }
         const relativePath = urlToPagePath(url);
         const html = await renderPage(config, themeTemplates, layouts, engine, toRenderPath(relativePath), 'preview');
         reply.type('text/html; charset=utf-8').send(html);

package/dist/routes/public.d.ts

@@ -1,11 +1,13 @@
 import type { FastifyPluginAsync } from 'fastify';
 import type { Liquid } from 'liquidjs';
 import type { SiteConfig } from '../config.ts';
+import type { RenderCache } from '../renderer/render-cache.ts';
 import type { ThemeTemplates } from '../renderer/theme-templates.ts';
 export interface PublicRouteOptions {
     config: SiteConfig;
     themeTemplates: ThemeTemplates;
     layouts: Record<string, string>;
     engine: Liquid;
+    renderCache: RenderCache;
 }
 export declare const publicRoutes: FastifyPluginAsync<PublicRouteOptions>;

package/dist/routes/public.js

@@ -1,8 +1,6 @@
 import { join } from 'node:path';
-import { PageRenderError, renderPage } from "../renderer/render-page.js";
+import { getMenusMtimeMs, getPageMtimeMs, PageRenderError, renderPage } from "../renderer/render-page.js";
 import { PathSafetyError } from "../services/path-safety.js";
-import { isBlogUrl } from "../services/post-urls.js";
-import { resolveBlogUrl } from "../services/resolve-blog-url.js";
 import { resolveUrl } from "../services/resolve-url.js";
 import { findStaticFile, sendStaticFile } from "../services/static-file.js";
 // resolveUrl's relativePath is relative to pagesRoot (e.g. "about.json"),
@@ -13,12 +11,6 @@ import { findStaticFile, sendStaticFile } from "../services/static-file.js";
 function toRenderPath(pagesRelativePath) {
     return join('pages', pagesRelativePath);
 }
-// Same seam as toRenderPath above, for posts: resolveBlogUrl's
-// relativePath is relative to postsRoot, renderPage's is relative to
-// contentRoot/draftsRoot directly.
-function toPostsRenderPath(postsRelativePath) {
-    return join('posts', postsRelativePath);
-}
 // A themed 404: content/pages/404.json, if it exists and is published,
 // is rendered through the ordinary public renderPage pipeline (layout +
 // sections + blocks, same as any other page) - no special-casing in
@@ -37,7 +29,7 @@ async function sendNotFound(reply, config, themeTemplates, layouts, engine, url)
         reply.code(404).send({ statusCode: 404, error: 'Not Found', message: `No page at "${url}"` });
     }
 }
-async function handlePublicRequest(request, reply, config, themeTemplates, layouts, engine) {
+async function handlePublicRequest(request, reply, config, themeTemplates, layouts, engine, renderCache) {
     // The public catch-all is registered without a /v1 prefix alongside
     // v1Routes (which has its own exact/prefixed routes). Fastify's
     // router already prefers exact matches over this wildcard regardless
@@ -63,24 +55,6 @@ async function handlePublicRequest(request, reply, config, themeTemplates, layou
     }
     const url = `/${request.params['*']}`;
     try {
-        // /blog is a permanently reserved namespace (confirmed design
-        // decision): checked first, and never falls through to page
-        // resolution even on a miss - a page manually placed at
-        // content/pages/blog/x.json is deliberately unreachable.
-        if (isBlogUrl(url)) {
-            const resolved = resolveBlogUrl(config, url);
-            if (resolved.kind === 'not-found') {
-                await sendNotFound(reply, config, themeTemplates, layouts, engine, url);
-                return;
-            }
-            if (resolved.kind === 'redirect') {
-                reply.code(301).header('location', resolved.to).send();
-                return;
-            }
-            const html = await renderPage(config, themeTemplates, layouts, engine, toPostsRenderPath(resolved.relativePath), 'public');
-            reply.type('text/html; charset=utf-8').send(html);
-            return;
-        }
         const resolved = resolveUrl(config, url);
         if (resolved.kind === 'not-found') {
             await sendNotFound(reply, config, themeTemplates, layouts, engine, url);
@@ -90,7 +64,28 @@ async function handlePublicRequest(request, reply, config, themeTemplates, layou
             reply.code(301).header('location', resolved.to).send();
             return;
         }
-        const html = await renderPage(config, themeTemplates, layouts, engine, toRenderPath(resolved.relativePath), 'public');
+        const renderPath = toRenderPath(resolved.relativePath);
+        // Validated against real filesystem state, not invalidated by
+        // hooking every write path (publish/unpublish/delete/move/batch) -
+        // see render-cache.ts's own comment for why. pageMtimeMs is null
+        // only if the file vanished between resolveUrl confirming it
+        // exists and this check (vanishingly unlikely) - falls through to
+        // an ordinary uncached render rather than treating that as
+        // fatal.
+        const pageMtimeMs = getPageMtimeMs(config, renderPath);
+        if (pageMtimeMs !== null) {
+            const menusMtimeMs = getMenusMtimeMs(config);
+            const cached = renderCache.get(renderPath);
+            if (cached && cached.pageMtimeMs === pageMtimeMs && cached.menusMtimeMs === menusMtimeMs) {
+                reply.type('text/html; charset=utf-8').send(cached.html);
+                return;
+            }
+            const html = await renderPage(config, themeTemplates, layouts, engine, renderPath, 'public');
+            renderCache.set(renderPath, { html, pageMtimeMs, menusMtimeMs });
+            reply.type('text/html; charset=utf-8').send(html);
+            return;
+        }
+        const html = await renderPage(config, themeTemplates, layouts, engine, renderPath, 'public');
         reply.type('text/html; charset=utf-8').send(html);
     }
     catch (error) {
@@ -113,5 +108,5 @@ async function handlePublicRequest(request, reply, config, themeTemplates, layou
     }
 }
 export const publicRoutes = async (fastify, opts) => {
-    fastify.get('/*', async (request, reply) => handlePublicRequest(request, reply, opts.config, opts.themeTemplates, opts.layouts, opts.engine));
+    fastify.get('/*', async (request, reply) => handlePublicRequest(request, reply, opts.config, opts.themeTemplates, opts.layouts, opts.engine, opts.renderCache));
 };

package/dist/routes/search-public.d.ts

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

package/dist/routes/search-public.js

@@ -0,0 +1,104 @@
+import { queryContent } from "../search/query-content.js";
+import { NO_AUTH_ROUTE_RATE_LIMIT } from "../services/rate-limit-config.js";
+const FIELD_OPS = ['eq', 'gt', 'gte', 'lt', 'lte'];
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+function badRequest(reply, message) {
+    reply.code(400).send({ statusCode: 400, error: 'Bad Request', message });
+}
+// field:value (op implied "eq") or field:op:value. Split on the FIRST
+// colon, then check whether the next segment up to a second colon is
+// one of the known op words - a value that itself contains a colon
+// (unlikely for the fields this targets, but not impossible) still
+// parses correctly either way, since only a genuine, recognised op
+// token is ever treated as one.
+function parseFilter(raw) {
+    const firstColon = raw.indexOf(':');
+    if (firstColon <= 0) {
+        return undefined;
+    }
+    const field = raw.slice(0, firstColon);
+    const rest = raw.slice(firstColon + 1);
+    const secondColon = rest.indexOf(':');
+    if (secondColon !== -1) {
+        const maybeOp = rest.slice(0, secondColon);
+        if (FIELD_OPS.includes(maybeOp)) {
+            const value = rest.slice(secondColon + 1);
+            return value === '' ? undefined : { field, op: maybeOp, value };
+        }
+    }
+    return rest === '' ? undefined : { field, op: 'eq', value: rest };
+}
+function parseSort(raw) {
+    return raw.startsWith('-') ? { field: raw.slice(1), direction: 'desc' } : { field: raw, direction: 'asc' };
+}
+function parseLimit(raw) {
+    if (raw === undefined) {
+        return DEFAULT_LIMIT;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed < 1) {
+        return DEFAULT_LIMIT;
+    }
+    return Math.min(parsed, MAX_LIMIT);
+}
+function parseOffset(raw) {
+    if (raw === undefined) {
+        return 0;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0;
+}
+async function handleSearch(request, reply, config) {
+    const { q, pageType, sort } = request.query;
+    const rawFilters = request.query.filter;
+    const filterStrings = rawFilters === undefined ? [] : Array.isArray(rawFilters) ? rawFilters : [rawFilters];
+    const filters = [];
+    for (const raw of filterStrings) {
+        const parsed = parseFilter(raw);
+        if (!parsed) {
+            badRequest(reply, `invalid filter "${raw}" - expected field:value or field:op:value`);
+            return;
+        }
+        if (parsed.op !== 'eq' && !Number.isFinite(Number(parsed.value))) {
+            badRequest(reply, `value must be numeric for op "${parsed.op}" (filter "${raw}")`);
+            return;
+        }
+        filters.push(parsed);
+    }
+    const response = queryContent(config.searchIndexPath, {
+        q,
+        pageType,
+        filters,
+        sort: sort ? parseSort(sort) : undefined,
+        limit: parseLimit(request.query.limit),
+        offset: parseOffset(request.query.offset),
+    });
+    reply.send(response);
+}
+// The one public query surface - full-text (q), structured filters,
+// sort, and pagination all in one endpoint (query-content.ts's own
+// queryContent), rather than three narrow ones. Deliberately no
+// requireScope, unlike every other route in this codebase: it's
+// read-only and can only ever surface already-published data
+// (rebuild-index.ts never indexes drafts or unpublished content), so
+// there's nothing here a site visitor couldn't already see by
+// browsing the live site directly - the whole point of this route is
+// that a theme's own front-end JS can call it directly, which a
+// token requirement would rule out entirely (a bearer token embedded
+// in public client-side JS is not a secret - anyone's dev tools can
+// read it straight back out, and this agent's tokens all carry real
+// write scopes, not just search). NO_AUTH_ROUTE_RATE_LIMIT, the same
+// defense-in-depth GET /v1/capabilities already has.
+//
+// GET /search.json, not GET /v1/search: this is a stable, public,
+// front-end-facing contract, not part of the versioned admin/
+// integration surface under /v1 - registered without a prefix in
+// server.ts, alongside mediaPublicRoutes/assetsRoutes/sitemapRoutes.
+// A single reserved path, not a whole prefix (unlike /media/* or
+// /assets/*): a site's own content page can still live at the bare
+// /search URL (see granite-starter/theme/sections/search-demo.liquid,
+// which does exactly that) - only this one exact path is claimed.
+export const searchPublicRoutes = async (fastify, opts) => {
+    fastify.get('/search.json', { config: NO_AUTH_ROUTE_RATE_LIMIT }, async (request, reply) => handleSearch(request, reply, opts.config));
+};

package/dist/routes/search.js

@@ -1,6 +1,10 @@
 import { rebuildIndex } from "../search/rebuild-index.js";
 import { WRITE_ROUTE_RATE_LIMIT } from "../services/rate-limit-config.js";
 import { requireScope } from "../services/token-auth.js";
+// The read side (GET /search.json) lives in routes/search-public.ts,
+// registered separately, unprefixed, in server.ts - this file only
+// ever holds the authenticated write side, matching media.ts (write,
+// under /v1) vs media-public.ts (public read, unprefixed).
 export const searchRoutes = async (fastify, opts) => {
     fastify.post('/search/rebuild', { preHandler: requireScope(opts.tokens, 'content'), config: WRITE_ROUTE_RATE_LIMIT }, async (_request, reply) => {
         // rebuildIndex is already self-enqueue()d (search/rebuild-index.ts) -

package/dist/routes/sitemap.js

@@ -1,15 +1,14 @@
 import { join } from 'node:path';
 import { readContentFile } from "../services/content-read.js";
 import { listFilesRecursively } from "../services/fs-walk.js";
-import { postPathToUrl } from "../services/post-urls.js";
 import { pagePathToUrl } from "../services/urls.js";
 // Reads through readContentFile/listFilesRecursively (both already
 // gated behind sanitisePath/agent-configured roots - see their own
 // files) rather than touching fs directly, so this route needs no
 // allowlist entry of its own (docs/phase-1-checklist.md Group B).
-function isPublished(contentRoot, subdir, relativePath) {
+function isPublished(contentRoot, relativePath) {
     try {
-        const { bytes } = readContentFile(contentRoot, join(subdir, relativePath));
+        const { bytes } = readContentFile(contentRoot, join('pages', relativePath));
         const parsed = JSON.parse(bytes.toString('utf-8'));
         return parsed.published === true;
     }
@@ -34,15 +33,10 @@ function buildSitemapUrls(config) {
         if (relativePath === '404.json') {
             continue;
         }
-        if (isPublished(config.contentRoot, 'pages', relativePath)) {
+        if (isPublished(config.contentRoot, relativePath)) {
             urls.push(pagePathToUrl(relativePath));
         }
     }
-    for (const relativePath of listFilesRecursively(config.postsRoot, config.postsRoot, '.json')) {
-        if (isPublished(config.contentRoot, 'posts', relativePath)) {
-            urls.push(postPathToUrl(relativePath));
-        }
-    }
     return urls;
 }
 function escapeXml(value) {

package/dist/schemas/page.schema.json

@@ -12,6 +12,12 @@
     "type": { "type": "string", "minLength": 1 },
     "layout": { "type": "string", "minLength": 1 },
     "published": { "type": "boolean" },
+    "author": { "type": "string", "minLength": 1 },
+    "publishDate": { "type": "string", "minLength": 1 },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
     "sections": {
       "type": "array",
       "items": { "$ref": "instance.schema.json" }

package/dist/search/drivers/node-sqlite-driver.d.ts

@@ -1,3 +1,7 @@
 import type { SearchDriver } from './driver.ts';
 export declare const DRIVER_NAME = "node:sqlite";
-export declare function openNodeSqliteDriver(path: string): SearchDriver;
+export interface OpenDriverOptions {
+    readOnly?: boolean;
+    timeout?: number;
+}
+export declare function openNodeSqliteDriver(path: string, options?: OpenDriverOptions): SearchDriver;