@o-a/cms-agent 0.1.7 → 0.2.1

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;
     }
@@ -30,19 +29,14 @@ function buildSitemapUrls(config) {
     for (const relativePath of listFilesRecursively(config.pagesRoot, config.pagesRoot, '.json')) {
         // The 404 page must never be listed as a real crawlable URL,
         // regardless of its own published flag - it's a fallback
-        // convention (docs/content-authoring-guide.md), not real content.
+        // convention (docs/guide-content-authoring.md), not real content.
         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;

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

@@ -9,8 +9,8 @@ export const DRIVER_NAME = 'node:sqlite';
 // 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);
+export function openNodeSqliteDriver(path, options = {}) {
+    const db = new DatabaseSync(path, options);
     return {
         exec: (sql) => db.exec(sql),
         prepare: (sql) => db.prepare(sql),

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

@@ -0,0 +1,32 @@
+export type FieldOp = 'eq' | 'gt' | 'gte' | 'lt' | 'lte';
+export interface FieldFilter {
+    field: string;
+    op: FieldOp;
+    value: string;
+}
+export interface SortParam {
+    field: string;
+    direction: 'asc' | 'desc';
+}
+export interface SearchParams {
+    q?: string;
+    pageType?: string;
+    filters: FieldFilter[];
+    sort?: SortParam;
+    limit: number;
+    offset: number;
+}
+export type FieldValue = string | number | boolean;
+export interface SearchResultItem {
+    url: string;
+    title: string;
+    pageType: string;
+    fields: Record<string, FieldValue | FieldValue[]>;
+}
+export interface SearchResponse {
+    results: SearchResultItem[];
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+}
+export declare function queryContent(searchIndexPath: string, params: SearchParams): SearchResponse;

package/dist/search/query-content.js

@@ -0,0 +1,207 @@
+import { existsSync } from 'node:fs';
+import { openNodeSqliteDriver } from "./drivers/node-sqlite-driver.js";
+function toFiniteNumber(raw) {
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+const COMPARATORS = {
+    gt: '>',
+    gte: '>=',
+    lt: '<',
+    lte: '<=',
+};
+// Never passes raw user input straight into FTS5 MATCH - a public
+// search box gets real, messy input (unbalanced quotes, a lone
+// trailing "-", a word FTS5 treats as an operator like "AND" or "NOT")
+// which throws a syntax error against a bare MATCH ? (the previous
+// query-index.ts never guarded this at all). Each whitespace-separated
+// token becomes its own quoted, prefix-matched literal - "hello world"
+// becomes "hello"* AND "world"*, embedded quotes doubled per FTS5's own
+// escaping rule - so the constructed expression can never be
+// misinterpreted as an operator, regardless of what the user typed.
+function buildMatchExpression(q) {
+    const tokens = q
+        .split(/\s+/)
+        .map((token) => token.trim())
+        .filter((token) => token.length > 0);
+    if (tokens.length === 0) {
+        return undefined;
+    }
+    return tokens.map((token) => `"${token.replace(/"/g, '""')}"*`).join(' AND ');
+}
+// One INNER JOIN per filter - a page must satisfy every filter to
+// appear at all, so a page missing that field entirely (or with a
+// non-matching value) is correctly excluded, not just left with a
+// null comparison. Same typed-column branch logic query-fields.ts
+// (now retired) already proved out for a single filter.
+function buildFilterJoin(alias, filter) {
+    const args = [filter.field];
+    if (filter.op === 'eq') {
+        const branches = [`${alias}.value_text = ?`];
+        args.push(filter.value);
+        const numeric = toFiniteNumber(filter.value);
+        if (numeric !== undefined) {
+            branches.push(`${alias}.value_number = ?`);
+            args.push(numeric);
+        }
+        if (filter.value === 'true' || filter.value === 'false') {
+            branches.push(`${alias}.value_bool = ?`);
+            args.push(filter.value === 'true' ? 1 : 0);
+        }
+        return {
+            sql: `JOIN page_fields ${alias} ON ${alias}.url = f.url AND ${alias}.field_key = ? AND (${branches.join(' OR ')})`,
+            args,
+        };
+    }
+    const numeric = toFiniteNumber(filter.value);
+    if (numeric === undefined) {
+        // The route validates a numeric op against a numeric value before
+        // ever calling in - reaching here regardless just means "nothing
+        // could possibly match", not an error this layer needs to raise.
+        return { sql: `JOIN page_fields ${alias} ON ${alias}.url = f.url AND ${alias}.field_key = ? AND 1 = 0`, args };
+    }
+    args.push(numeric);
+    return {
+        sql: `JOIN page_fields ${alias} ON ${alias}.url = f.url AND ${alias}.field_key = ? AND ${alias}.value_number ${COMPARATORS[filter.op]} ?`,
+        args,
+    };
+}
+// LEFT, not INNER - unlike a filter, sorting by a field a given page
+// doesn't have shouldn't drop that page from the results, just leave
+// it ordered with a null value (SQLite sorts NULL first in ASC order).
+// COALESCE across both typed columns since this layer has no schema in
+// hand at query time to know in advance which one a given field
+// actually uses.
+function buildSortJoin(field) {
+    return {
+        sql: 'LEFT JOIN page_fields sort_field ON sort_field.url = f.url AND sort_field.field_key = ?',
+        args: [field],
+        column: 'COALESCE(sort_field.value_number, sort_field.value_text)',
+    };
+}
+function fieldRowValue(row) {
+    if (row.value_text !== null) {
+        return row.value_text;
+    }
+    if (row.value_number !== null) {
+        return row.value_number;
+    }
+    if (row.value_bool !== null) {
+        return row.value_bool === 1;
+    }
+    return undefined;
+}
+// The one query surface a front-end talks to directly - covers a
+// blog listing (pageType + sort by publishDate + pagination), a
+// product grid (several ANDed filters + sort by a numeric field), and
+// general site search (q), rather than three narrow endpoints each
+// covering one of those. Two queries total, never N+1: one for the
+// (already paginated) matching urls, one gathering every indexed
+// field for just that page of urls to build each result's own
+// "fields" map - a product grid needs price to render, not just to
+// have matched.
+export function queryContent(searchIndexPath, params) {
+    // readOnly: true (below) throws if the file doesn't exist rather
+    // than silently auto-creating an empty one the way a normal open
+    // would - checked here instead, so "no rebuild has ever run yet" (a
+    // real, expected state for a brand new site) reads as an empty
+    // result set, not a 500.
+    if (!existsSync(searchIndexPath)) {
+        return { results: [], limit: params.limit, offset: params.offset, hasMore: false };
+    }
+    const driver = openNodeSqliteDriver(searchIndexPath, { readOnly: true, timeout: 2000 });
+    try {
+        const joins = [];
+        const joinArgs = [];
+        params.filters.forEach((filter, index) => {
+            const built = buildFilterJoin(`pf${index}`, filter);
+            joins.push(built.sql);
+            joinArgs.push(...built.args);
+        });
+        const where = [];
+        const whereArgs = [];
+        const matchExpression = params.q ? buildMatchExpression(params.q) : undefined;
+        if (matchExpression) {
+            // FTS5's own "tbl MATCH expr" special syntax only recognises the
+            // real table name here, not an alias (confirmed live - "f MATCH
+            // ?" throws "no such column: f" even though ordinary column
+            // references through the same alias work fine everywhere else in
+            // this query).
+            where.push('pages_fts MATCH ?');
+            whereArgs.push(matchExpression);
+        }
+        if (params.pageType !== undefined) {
+            where.push('f.page_type = ?');
+            whereArgs.push(params.pageType);
+        }
+        let orderJoin = '';
+        const orderJoinArgs = [];
+        let orderBy = 'f.url ASC';
+        if (params.sort) {
+            const built = buildSortJoin(params.sort.field);
+            orderJoin = built.sql;
+            orderJoinArgs.push(...built.args);
+            orderBy = `${built.column} ${params.sort.direction === 'desc' ? 'DESC' : 'ASC'}`;
+        }
+        else if (matchExpression) {
+            // FTS5's own bm25-derived rank: more negative is more relevant,
+            // so plain ascending order is "best match first".
+            orderBy = 'rank';
+        }
+        const sql = [
+            'SELECT DISTINCT f.url, f.title, f.page_type',
+            'FROM pages_fts f',
+            ...joins,
+            orderJoin,
+            where.length > 0 ? `WHERE ${where.join(' AND ')}` : '',
+            `ORDER BY ${orderBy}`,
+            'LIMIT ? OFFSET ?',
+        ]
+            .filter((part) => part !== '')
+            .join(' ');
+        // Request one extra row to know whether there's a next page,
+        // rather than a separate COUNT(*) query - a real, doubled cost on
+        // every single paginated request neither stated use case (infinite
+        // scroll, a grid's own "next" button) actually needs an exact
+        // total for.
+        const args = [...joinArgs, ...orderJoinArgs, ...whereArgs, params.limit + 1, params.offset];
+        const mainRows = driver.prepare(sql).all(...args);
+        const hasMore = mainRows.length > params.limit;
+        const pageRows = mainRows.slice(0, params.limit);
+        const fieldsByUrl = new Map();
+        if (pageRows.length > 0) {
+            const placeholders = pageRows.map(() => '?').join(', ');
+            const fieldRows = driver
+                .prepare(`SELECT url, field_key, value_text, value_number, value_bool FROM page_fields WHERE url IN (${placeholders})`)
+                .all(...pageRows.map((row) => row.url));
+            for (const row of fieldRows) {
+                const value = fieldRowValue(row);
+                if (value === undefined) {
+                    continue;
+                }
+                const entry = fieldsByUrl.get(row.url) ?? {};
+                const existing = entry[row.field_key];
+                if (existing === undefined) {
+                    entry[row.field_key] = value;
+                }
+                else if (Array.isArray(existing)) {
+                    existing.push(value);
+                }
+                else {
+                    entry[row.field_key] = [existing, value];
+                }
+                fieldsByUrl.set(row.url, entry);
+            }
+        }
+        const results = pageRows.map((row) => ({
+            url: row.url,
+            title: row.title,
+            pageType: row.page_type,
+            fields: fieldsByUrl.get(row.url) ?? {},
+        }));
+        return { results, limit: params.limit, offset: params.offset, hasMore };
+    }
+    finally {
+        driver.close();
+    }
+}