@o-a/cms-agent 0.1.6 → 0.2.0

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();
+    }
+}

package/dist/search/rebuild-index.js

@@ -1,10 +1,20 @@
-import { mkdirSync, readFileSync, unlinkSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
+import { setImmediate as yieldToEventLoop } from 'node:timers/promises';
 import { listFilesRecursively } from "../services/fs-walk.js";
-import { postPathToUrl } from "../services/post-urls.js";
+import { loadThemeSchemas } from "../services/theme-schemas.js";
 import { pagePathToUrl } from "../services/urls.js";
 import { enqueue } from "../services/write-queue.js";
 import { openNodeSqliteDriver } from "./drivers/node-sqlite-driver.js";
+// How many content files the rebuild loop processes between yields to
+// the event loop (see the yield's own comment below for why this
+// exists at all). Large enough that setImmediate's own overhead is
+// negligible next to the real per-file work (a parse plus several
+// SQLite inserts); small enough that no single slice runs long enough
+// to meaningfully stall another request. Not a config knob - no
+// evidence yet this needs to be tunable per site.
+const YIELD_EVERY_N_FILES = 25;
 function collectStrings(value, out) {
     if (typeof value === 'string') {
         out.push(value);
@@ -39,73 +49,256 @@ function extractBody(instances) {
     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.
+// Epoch milliseconds for a date-like string - undefined if it doesn't
+// parse, so a malformed date is silently skipped rather than indexed
+// as a nonsensical NaN row (the same "malformed input skipped, not a
+// rebuild failure" tolerance every other part of this pipeline
+// already has for a bad file or a missing theme type).
+function parseDateValue(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+// Turns one raw value into ApiFieldRow entries for a given field key -
+// shared by both theme-flagged fields (extractInstanceApiFields below)
+// and the built-in post envelope fields (extractEnvelopeApiFields),
+// since both need the identical "what does this value actually mean
+// for indexing" logic. Three shapes:
+// - an array: one row per scalar element, all under the same
+//   fieldKey (e.g. a post's own "tags") - a plain "eq" filter then
+//   matches via the exact same mechanism a single-valued field already
+//   uses, no separate array-aware query logic needed anywhere else.
+// - a date-like string (isDateField true - a theme field schema'd
+//   "type": "string", "format": "date", reusing the existing format
+//   convention, or the post envelope's own publishDate): stored as an
+//   epoch-ms number in valueNumber, not text, so range operators work
+//   on it through the same numeric path a flagged price field uses.
+// - a plain scalar (string/number/boolean): stored in its own typed
+//   column. Anything else (object, null, undefined) has nothing
+//   sensible to store or compare and is silently skipped, the same way
+//   a malformed schema block already is elsewhere in this pipeline.
+function pushFieldValue(blockType, instanceId, fieldKey, value, isDateField, out) {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            pushFieldValue(blockType, instanceId, fieldKey, item, isDateField, out);
+        }
+        return;
+    }
+    if (typeof value === 'string' && isDateField) {
+        const epoch = parseDateValue(value);
+        if (epoch !== undefined) {
+            out.push({ blockType, instanceId, fieldKey, valueText: null, valueNumber: epoch, valueBool: null });
+        }
+        return;
+    }
+    if (typeof value === 'string') {
+        out.push({ blockType, instanceId, fieldKey, valueText: value, valueNumber: null, valueBool: null });
+    }
+    else if (typeof value === 'number') {
+        out.push({ blockType, instanceId, fieldKey, valueText: null, valueNumber: value, valueBool: null });
+    }
+    else if (typeof value === 'boolean') {
+        out.push({ blockType, instanceId, fieldKey, valueText: null, valueNumber: null, valueBool: value ? 1 : 0 });
+    }
+}
+// Reads schema.properties for the given instance's own type, keeping
+// only properties explicitly flagged "api": true (an unvalidated,
+// theme-authored JSON Schema keyword - same status as "format"/
+// "allowedBlocks", see docs/theme-authoring-guide.md and
+// services/validation.ts's own allowedBlockTypesOf) - and pairs each
+// with its actual value out of instance.settings via pushFieldValue.
+function extractInstanceApiFields(instance, schemaMap, out) {
+    const type = typeof instance.type === 'string' ? instance.type : undefined;
+    const id = typeof instance.id === 'string' ? instance.id : undefined;
+    if (!type || !id) {
+        return;
+    }
+    const properties = schemaMap[type]?.properties;
+    if (!properties || typeof properties !== 'object') {
+        return;
+    }
+    const settings = (instance.settings && typeof instance.settings === 'object' ? instance.settings : {});
+    for (const [key, propSchema] of Object.entries(properties)) {
+        const schema = propSchema;
+        if (schema?.api !== true) {
+            continue;
+        }
+        const isDateField = schema.type === 'string' && schema.format === 'date';
+        pushFieldValue(type, id, key, settings[key], isDateField, out);
+    }
+}
+// Built-in envelope fields, auto-indexed with no "api": true needed -
+// author/publishDate/tags are optional on every page (page.schema.json),
+// so indexing is presence-based rather than gated on a specific "type"
+// value: any page carrying one of these fields gets it indexed,
+// regardless of what its own type string is. block_type '__page__' is a
+// sentinel (never a real theme type, which always matches a *.liquid
+// filename) marking these rows as envelope-level rather than a real
+// section/block instance; instanceId is the page's own url - stable
+// and unique enough, since there's exactly one envelope per page.
+function extractEnvelopeApiFields(page, url) {
+    const rows = [];
+    pushFieldValue('__page__', url, 'author', page.author, false, rows);
+    pushFieldValue('__page__', url, 'publishDate', page.publishDate, true, rows);
+    pushFieldValue('__page__', url, 'tags', page.tags, false, rows);
+    return rows;
+}
+// Top-level page.sections entries are sections; every level of nested
+// .blocks (arbitrarily deep - instance.schema.json's blocks is self-
+// referential, same reasoning extractBody's own walk above already
+// documents) is a block, so which theme-schema map applies flips
+// exactly once, at the top, and stays fixed for everything nested
+// underneath.
+function extractApiFields(sections, sectionSchemas, blockSchemas) {
+    const rows = [];
+    const walk = (list, schemaMap) => {
+        if (!list) {
+            return;
+        }
+        for (const instance of list) {
+            extractInstanceApiFields(instance, schemaMap, rows);
+            walk(instance.blocks, blockSchemas);
+        }
+    };
+    walk(sections, sectionSchemas);
+    return rows;
+}
+function unlinkIfExists(path) {
     try {
-        unlinkSync(config.searchIndexPath);
+        unlinkSync(path);
     }
     catch (error) {
         if (error.code !== 'ENOENT') {
             throw error;
         }
     }
-    const driver = openNodeSqliteDriver(config.searchIndexPath);
+}
+// A fresh sqlite file is never actually left in WAL mode by this
+// module (nothing here turns that on), but cleaning up any stray
+// -wal/-shm sidecar files defensively costs nothing and avoids ever
+// leaving one behind next to an abandoned temp build.
+function cleanupSqliteArtifacts(path) {
+    unlinkIfExists(path);
+    unlinkIfExists(`${path}-wal`);
+    unlinkIfExists(`${path}-shm`);
+}
+async function rebuildIndexJob(config) {
+    mkdirSync(config.dataRoot, { recursive: true });
+    // Built into a fresh temp file, then renamed atomically over the
+    // real path (below) - not the old delete-then-recreate-in-place
+    // approach, which left a real window where a concurrent read saw
+    // either a missing file or one that exists but has no tables in it
+    // yet. POSIX rename() is atomic: a reader always sees either the
+    // complete old index or the complete new one, never an in-between
+    // state, and never has to retry an open that landed in the gap.
+    const tmpPath = `${config.searchIndexPath}.tmp-${randomUUID()}`;
+    cleanupSqliteArtifacts(tmpPath);
+    const themeSchemas = loadThemeSchemas(config.themeRoot);
     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'));
+        const driver = openNodeSqliteDriver(tmpPath);
+        try {
+            driver.exec('CREATE VIRTUAL TABLE pages_fts USING fts5(url UNINDEXED, title, body, page_type UNINDEXED)');
+            // A plain table, not FTS5 - page_fields holds typed, exact/range-
+            // comparable values (a price, a rating), the opposite of pages_fts's
+            // own free-text matching. One row per exposed field per instance
+            // (not one column per field name): a page can carry several
+            // instances of the same block type (several "product" blocks on one
+            // listing page), each with its own value, and different pages may
+            // expose entirely different field sets - a fixed column-per-field
+            // schema can't accommodate either. No foreign key back to
+            // pages_fts.url - this whole index is disposable and rebuilt wholly
+            // from scratch every time, same as pages_fts itself.
+            driver.exec('CREATE TABLE page_fields (url TEXT NOT NULL, block_type TEXT NOT NULL, instance_id TEXT NOT NULL, field_key TEXT NOT NULL, value_text TEXT, value_number REAL, value_bool INTEGER)');
+            // Composite, not a bare field_key index - field_key alone only
+            // narrows to one field's rows; leading with it here still serves
+            // that same narrowing (the leftmost-column rule), but the second
+            // column also covers the typed value comparison itself (an
+            // equality or range check) without a further per-row scan. url
+            // supports the self-join a multi-field query ANDs together
+            // (queryContent, query-content.ts) - with no index there, ANDing a
+            // second filter means scanning page_fields in full for every row
+            // the first filter matched.
+            driver.exec('CREATE INDEX page_fields_key_number ON page_fields (field_key, value_number)');
+            driver.exec('CREATE INDEX page_fields_key_text ON page_fields (field_key, value_text)');
+            driver.exec('CREATE INDEX page_fields_url ON page_fields (url)');
+            const insert = driver.prepare('INSERT INTO pages_fts (url, title, body, page_type) VALUES (?, ?, ?, ?)');
+            const insertField = driver.prepare('INSERT INTO page_fields (url, block_type, instance_id, field_key, value_text, value_number, value_bool) VALUES (?, ?, ?, ?, ?, ?, ?)');
+            // 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 }];
+            driver.exec('BEGIN');
+            let filesExamined = 0;
+            for (const { root, toUrl } of collections) {
+                for (const relativePath of listFilesRecursively(root, root, '.json')) {
+                    // A genuine macrotask yield (setImmediate, not a microtask like
+                    // Promise.resolve()/queueMicrotask - Node drains every queued
+                    // microtask before the event loop ever reaches its I/O phases,
+                    // so a chain of only-microtask yields still fully blocks an
+                    // incoming HTTP request from being processed). Without this,
+                    // this loop's entire body - potentially thousands of files -
+                    // runs as one uninterruptible synchronous block: since Node is
+                    // single-threaded, that means every other request the server
+                    // is handling (auth, content reads, publishes) stalls for the
+                    // rebuild's whole duration, not just other search queries.
+                    // Counted once per file examined regardless of whether it
+                    // ends up skipped below, so the cadence tracks total work
+                    // done, not just files actually indexed.
+                    filesExamined += 1;
+                    if (filesExamined % YIELD_EVERY_N_FILES === 0) {
+                        await yieldToEventLoop();
+                    }
+                    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 pageType = typeof page.type === 'string' ? page.type : '';
+                    const body = extractBody(page.sections);
+                    insert.run(url, title, body, pageType);
+                    const apiFields = [
+                        ...extractApiFields(page.sections, themeSchemas.sections, themeSchemas.blocks),
+                        ...extractEnvelopeApiFields(page, url),
+                    ];
+                    for (const row of apiFields) {
+                        insertField.run(url, row.blockType, row.instanceId, row.fieldKey, row.valueText, row.valueNumber, row.valueBool);
+                    }
                 }
-                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');
         }
-        driver.exec('COMMIT');
+        finally {
+            driver.close();
+        }
+        renameSync(tmpPath, config.searchIndexPath);
     }
-    finally {
-        driver.close();
+    catch (error) {
+        cleanupSqliteArtifacts(tmpPath);
+        throw error;
     }
 }
-// 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.
+// Queued via enqueue() - two concurrent rebuilds could otherwise both
+// build their own temp file and both attempt the final rename; the
+// second rename would still win cleanly (rename() just replaces
+// whatever is there), but the first rebuild's now-orphaned temp file
+// would never get cleaned up. 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

@@ -18,5 +18,6 @@ export interface ServerConfig {
     ipAllowlist: string[];
     checkpointIntervalMs: number;
     media: MediaConfig;
+    adminBaseUrl: string | undefined;
 }
 export declare function loadServerConfig(siteRoot: string): ServerConfig;

package/dist/server-config.js

@@ -128,6 +128,31 @@ function parseIpAllowlist(value) {
     });
     return value;
 }
+// Undefined -> undefined: absence means the /admin redirect feature
+// is off entirely, not a default target to redirect to (there's no
+// sensible default admin URL to assume). Validated as a real absolute
+// http(s) URL, not just any non-empty string, since it becomes a
+// redirect target - rejects `javascript:`/`ftp:`/anything else before
+// it can ever reach a Location header.
+function parseAdminBaseUrl(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new StartupCheckError('invalid-site-config', `site.config.json's "adminBaseUrl" must be a non-empty string, got ${JSON.stringify(value)}`);
+    }
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new StartupCheckError('invalid-site-config', `site.config.json's "adminBaseUrl" must be a valid URL, got ${JSON.stringify(value)}`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new StartupCheckError('invalid-site-config', `site.config.json's "adminBaseUrl" must be an http or https URL, got ${JSON.stringify(value)}`);
+    }
+    return value;
+}
 function parseCheckpointIntervalMs(value) {
     if (value === undefined) {
         return DEFAULT_CHECKPOINT_INTERVAL_MS;
@@ -182,6 +207,7 @@ export function loadServerConfig(siteRoot) {
             ipAllowlist: [],
             checkpointIntervalMs: DEFAULT_CHECKPOINT_INTERVAL_MS,
             media: { maxUploadBytes: DEFAULT_MEDIA_MAX_UPLOAD_BYTES },
+            adminBaseUrl: undefined,
         };
     }
     let parsed;
@@ -206,5 +232,6 @@ export function loadServerConfig(siteRoot) {
     const ipAllowlist = parseIpAllowlist(record.ipAllowlist);
     const checkpointIntervalMs = parseCheckpointIntervalMs(record.checkpointIntervalMs);
     const media = parseMedia(record.media);
-    return { port: resolvePort(port), tokens, rateLimit, trustProxy, ipAllowlist, checkpointIntervalMs, media };
+    const adminBaseUrl = parseAdminBaseUrl(record.adminBaseUrl);
+    return { port: resolvePort(port), tokens, rateLimit, trustProxy, ipAllowlist, checkpointIntervalMs, media, adminBaseUrl };
 }