@o-a/cms-agent 0.2.1 → 0.2.2

package/dist/create-site/template/AGENTS.md

@@ -58,9 +58,9 @@ This scaffold already ships real, working examples worth reading before writing
 {% endschema %}
 ```
 
-Available variables in a section: `section.id`, `section.settings.<key>`, and `blocksHtml` (an array of already-rendered child block HTML strings - a section never sees raw block data, only finished HTML, output with `{{ html | raw }}`). A block template gets the same shape: `block.id`, `block.settings.<key>`, and (rarely) its own `blocksHtml` if it nests further blocks.
+Available variables in a section: `section.id`, `section.settings.<key>`, `blocksHtml` (an array of already-rendered child block HTML strings - a section never sees raw block data, only finished HTML, output with `{{ html | raw }}`), and `page` - the same built-in envelope a layout gets (`page.title`, `page.author`, `page.publishDate`, `page.tags`; see "Content JSON model" below). A block template gets the same shape: `block.id`, `block.settings.<key>`, `page`, and (rarely) its own `blocksHtml` if it nests further blocks. `page.author`/`publishDate`/`tags` render as empty/absent, not an error, on a page that doesn't set them - useful for printing a byline/date inside the page body without duplicating the value into a settings field.
 
-**Every property listed in a schema's `"required"` array must also declare a `"default"`** that itself satisfies the property's own constraints (e.g. not `"default": ""` against `"minLength": 1`). A schema that violates this is silently excluded from the theme entirely - it simply won't be selectable, with no error printed anywhere obvious. If a new section/block isn't showing up, check this first.
+**Every property listed in a schema's `"required"` array must also declare a `"default"`** that itself satisfies the property's own constraints (e.g. not `"default": ""` against `"minLength": 1`). A schema that violates this - or one with no `{% schema %}` block at all, or invalid JSON inside it - is excluded from the theme entirely (it simply won't be selectable), but never silently: boot prints a warning naming the type and the specific reason. If a new section/block isn't showing up, check the server's console output first.
 
 To restrict which block types are allowed under a given section/block, add `"allowedBlocks": ["button", "logo-mark"]` alongside `"properties"` in its schema - omit it entirely for no restriction (the default).
 
@@ -70,7 +70,10 @@ To restrict which block types are allowed under a given section/block, add `"all
 
 ```liquid
 {{ content_for_layout | raw }}   the page's fully-rendered sections, concatenated
-{{ page.title }}                 the page's title (the ONLY page field exposed to layouts)
+{{ page.title }}                 the page's title
+{{ page.author }}                the page's author, if set
+{{ page.publishDate }}           the page's publish date, if set
+{% for tag in page.tags %}...{% endfor %}   the page's tags, if any
 {{ menus.<name>.items }}         every menu in content/menus/, keyed by filename
 ```
 
@@ -170,6 +173,8 @@ unless the design needs a focal point for a cropped image, in which case use `"f
 
 A public, unauthenticated, read-only endpoint - safe to call directly from a section's own client-side JavaScript with a plain `fetch()`, no token needed. Only ever returns already-published content. Query params: `q` (full-text), `filter=field:op:value` (repeatable, ANDed; `op` is `eq`/`gt`/`gte`/`lt`/`lte`), `pageType`, `sort` (`-publishDate` for newest-first), `limit`, `offset`. Useful for a blog listing, a filterable directory, or a live search box.
 
+The index behind this endpoint keeps itself current automatically - it rebuilds in the background after every publish/unpublish/delete/move, and once at boot if no index exists yet (a fresh clone, since the index itself is never git-tracked). No manual step is needed for a blog listing built on this endpoint to work on a freshly deployed site.
+
 ## Hard constraints - do not deviate from these
 
 - **No dynamically registered Liquid tags or filters, ever.** Only standard LiquidJS built-ins (`if`, `for`, `assign`, `render`, filters like `upcase`, `times`) plus the CMS-provided context objects described above. Never invent a custom tag.

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

@@ -20,6 +20,9 @@ export interface PageContent {
     published: boolean;
     layout: string;
     sections: SectionOrBlockInstance[];
+    author?: string;
+    publishDate?: string;
+    tags?: string[];
 }
 export declare function renderSections(page: PageContent, themeTemplates: ThemeTemplates, engine: Liquid): Promise<string>;
 export type RenderMode = 'public' | 'preview';

package/dist/renderer/render-page.js

@@ -10,13 +10,16 @@ export class PageRenderError extends Error {
         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.
-async function renderInstance(instance, kind, themeTemplates, engine) {
+async function renderInstance(instance, kind, themeTemplates, engine, page) {
     const templates = kind === 'section' ? themeTemplates.sections : themeTemplates.blocks;
     const template = templates[instance.type];
     if (!template) {
@@ -24,13 +27,16 @@ async function renderInstance(instance, kind, themeTemplates, engine) {
     }
     const blocksHtml = [];
     for (const block of instance.blocks ?? []) {
-        blocksHtml.push(await renderInstance(block, 'block', themeTemplates, engine));
+        blocksHtml.push(await renderInstance(block, 'block', themeTemplates, engine, page));
     }
     // 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 }
-        : { block: { id: instance.id, type: instance.type, settings: instance.settings }, blocksHtml };
+        ? { 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));
     }
@@ -46,9 +52,10 @@ async function renderInstance(instance, kind, themeTemplates, engine) {
 // No page-level layout/wrapper concept in Phase 1 - this is the whole
 // output.
 export async function renderSections(page, themeTemplates, engine) {
+    const envelope = pageEnvelope(page);
     const html = [];
     for (const section of page.sections) {
-        html.push(await renderInstance(section, 'section', themeTemplates, engine));
+        html.push(await renderInstance(section, 'section', themeTemplates, engine, envelope));
     }
     return html.join('');
 }
@@ -134,7 +141,7 @@ export async function renderLoadedPage(page, config, themeTemplates, layouts, en
     // outputEscape: 'escape' double-escapes it into literal text.
     return (await engine.parseAndRender(layoutTemplate, {
         content_for_layout: bodyHtml,
-        page: { title: page.title },
+        page: pageEnvelope(page),
         menus,
     }));
 }

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

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

package/dist/search/rebuild-index.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { mkdirSync, readFileSync, renameSync, unlinkSync } from 'node:fs';
+import { existsSync, 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";
@@ -302,3 +302,19 @@ async function rebuildIndexJob(config) {
 export function rebuildIndex(config) {
     return enqueue(() => rebuildIndexJob(config));
 }
+// For startServer's own boot-time call: a search index is never
+// git-tracked (constraint 3 - a derived, disposable index), so a fresh
+// clone or a first-ever boot has no index file at all and GET
+// /search.json would stay permanently empty until some content write
+// happened to trigger reindex-on-write.ts, or a caller manually hit
+// POST /v1/search/rebuild. Guarded on existsSync rather than
+// unconditionally rebuilding on every restart - a currently-running
+// site's index is already kept fresh by every publish/unpublish/
+// delete/move/batch (reindex-on-write.ts), so an unconditional rebuild
+// here would just be redundant work on every ordinary restart.
+export function rebuildIndexIfMissing(config) {
+    if (existsSync(config.searchIndexPath)) {
+        return Promise.resolve();
+    }
+    return rebuildIndex(config);
+}

package/dist/server.js

@@ -12,6 +12,7 @@ import { sitemapRoutes } from "./routes/sitemap.js";
 import { CHECKPOINT_AUTHOR, runCheckpoint } from "./services/checkpoint.js";
 import { startDevTunnel } from "./services/dev-tunnel.js";
 import { startIntervalJob } from "./services/interval-job.js";
+import { reindexOnBootIfMissing } from "./services/reindex-on-write.js";
 // Never wrap v1Routes (or any route-group plugin it registers) with
 // fastify-plugin (fp()): plain app.register() gives each file its own
 // encapsulation scope by default, which Group B's auth preHandler
@@ -132,6 +133,15 @@ export async function startServer(siteRoot, options = {}) {
     const booted = bootSite(siteRoot);
     const serverConfig = loadServerConfig(siteRoot);
     const app = buildServer(booted, serverConfig, options);
+    // Previously these three failure cases (missing/invalid {% schema %}
+    // block, or a required property with no valid default) were
+    // completely silent - a broken component just stopped being
+    // selectable, with nothing distinguishing "deliberately excluded"
+    // from "you have a typo". Never a boot failure (loadThemeSchemas's
+    // own contract), just no longer silent about it either.
+    for (const warning of booted.themeSchemas.warnings ?? []) {
+        console.warn(warning);
+    }
     const doCheckpoint = () => runCheckpoint(booted.config, CHECKPOINT_AUTHOR);
     const scheduler = startIntervalJob(doCheckpoint, serverConfig.checkpointIntervalMs, (error) => {
         app.log.error(error, 'background draft checkpoint failed');
@@ -191,6 +201,13 @@ export async function startServer(siteRoot, options = {}) {
     if (address !== null && typeof address !== 'string') {
         console.log(`Site running at http://127.0.0.1:${address.port}`);
     }
+    // A search index is never git-tracked (constraint 3), so a fresh
+    // clone or first-ever boot has no index file - without this,
+    // GET /search.json would stay empty until the first content write.
+    // Fire-and-forget, after the port is already bound: never blocks
+    // startup, and a slow/failed rebuild is never a reason the server
+    // itself fails to come up.
+    reindexOnBootIfMissing(booted.config);
     if (options.tunnel) {
         try {
             tunnel = await (options.startTunnel ?? startDevTunnel)(serverConfig.port);

package/dist/services/batch.js

@@ -4,6 +4,7 @@ import { commitPaths } from "./git.js";
 import { MoveError, prepareMovePage } from "./move.js";
 import { PublishError, preparePublishDrafts } from "./publish.js";
 import { enqueue } from "./write-queue.js";
+import { reindexInBackground } from "./reindex-on-write.js";
 export class BatchError extends Error {
     reason;
     // Which part of the batch failed. operationIndex indexes into the
@@ -132,5 +133,13 @@ async function rollbackAndThrow(undoStack, cause, context) {
     throw new BatchError('commit-failed', `Batch failed: ${detail}`, { cause, ...context });
 }
 export function runBatch(config, themeSchemas, operations, publish, message, author) {
-    return enqueue(() => batchJob(config, themeSchemas, operations, publish, message, author));
+    const result = enqueue(() => batchJob(config, themeSchemas, operations, publish, message, author));
+    // One trigger for the whole batch, regardless of which operation
+    // types it contained (content-delete/move/publish affect the index,
+    // draft-write/draft-discard don't) - simpler and no real cost than
+    // inspecting `operations` to decide, since this never blocks the
+    // caller either way. See reindex-on-write.ts for why this is
+    // fire-and-forget, chained onto `result` rather than awaited here.
+    result.then(() => reindexInBackground(config), () => undefined);
+    return result;
 }

package/dist/services/delete-content.js

@@ -5,6 +5,7 @@ import { sanitisePath } from "./path-safety.js";
 import { RedirectError, addRedirect, isValidRedirectTarget, loadRedirects, serialiseRedirects, } from "./redirects.js";
 import { pagePathToUrl } from "./urls.js";
 import { enqueue } from "./write-queue.js";
+import { reindexInBackground } from "./reindex-on-write.js";
 const PAGES_PREFIX = 'pages/';
 // Returns null for anything else (menus have no public URL at all, so
 // redirects are meaningless there).
@@ -159,5 +160,7 @@ async function deleteContentJob(config, relativePath, redirectTo, message, autho
     }
 }
 export function deleteContent(config, relativePath, redirectTo, message, author) {
-    return enqueue(() => deleteContentJob(config, relativePath, redirectTo, message, author));
+    const result = enqueue(() => deleteContentJob(config, relativePath, redirectTo, message, author));
+    result.then(() => reindexInBackground(config), () => undefined);
+    return result;
 }

package/dist/services/move.js

@@ -6,6 +6,7 @@ import { sanitisePath } from "./path-safety.js";
 import { addRedirect, loadRedirects, removeRedirectForPath, serialiseRedirects } from "./redirects.js";
 import { pagePathToUrl, urlToPagePath } from "./urls.js";
 import { enqueue } from "./write-queue.js";
+import { reindexInBackground } from "./reindex-on-write.js";
 export class MoveError extends Error {
     reason;
     constructor(reason, message, options) {
@@ -171,5 +172,7 @@ async function movePageJob(config, fromUrl, toUrl, message, author, options = {}
     }
 }
 export function movePage(config, fromUrl, toUrl, message, author, options = {}) {
-    return enqueue(() => movePageJob(config, fromUrl, toUrl, message, author, options));
+    const result = enqueue(() => movePageJob(config, fromUrl, toUrl, message, author, options));
+    result.then(() => reindexInBackground(config), () => undefined);
+    return result;
 }

package/dist/services/publish.js

@@ -6,6 +6,7 @@ import { loadRedirects, removeRedirectForPath, serialiseRedirects } from "./redi
 import { pagePathToUrl } from "./urls.js";
 import { validateContent } from "./validation.js";
 import { enqueue } from "./write-queue.js";
+import { reindexInBackground } from "./reindex-on-write.js";
 const PAGES_PREFIX = 'pages/';
 // Mirrors delete-content.ts's urlForDeletedEntry - a tiny duplicated
 // helper, not a shared abstraction. Returns null for anything else
@@ -241,8 +242,18 @@ async function unpublishPageJob(config, relativePath, message, author) {
     }
 }
 export function publishDrafts(config, themeSchemas, relativePaths, message, author) {
-    return enqueue(() => publishDraftsJob(config, themeSchemas, relativePaths, message, author));
+    const result = enqueue(() => publishDraftsJob(config, themeSchemas, relativePaths, message, author));
+    // Only on success - a failed publish changed nothing, so there's
+    // nothing to reindex. Chained onto `result` rather than awaited here:
+    // by the time this callback runs, the write-queue's own tail has
+    // already advanced past this job, so reindexInBackground's own
+    // enqueue()d rebuild queues cleanly behind it (see that function's
+    // own comment on why calling it any earlier would deadlock).
+    result.then(() => reindexInBackground(config), () => undefined);
+    return result;
 }
 export function unpublishPage(config, relativePath, message, author) {
-    return enqueue(() => unpublishPageJob(config, relativePath, message, author));
+    const result = enqueue(() => unpublishPageJob(config, relativePath, message, author));
+    result.then(() => reindexInBackground(config), () => undefined);
+    return result;
 }

package/dist/services/reindex-on-write.d.ts

@@ -0,0 +1,3 @@
+import type { SiteConfig } from '../config.ts';
+export declare function reindexInBackground(config: SiteConfig): void;
+export declare function reindexOnBootIfMissing(config: SiteConfig): void;

package/dist/services/reindex-on-write.js

@@ -0,0 +1,30 @@
+import { rebuildIndex, rebuildIndexIfMissing } from "../search/rebuild-index.js";
+// Search is a derived, disposable index (constraint 3) - previously
+// nothing ever rebuilt it except a caller manually hitting
+// POST /v1/search/rebuild, so GET /search.json stayed empty forever on
+// a fresh site and stale forever after a real edit. This is the one
+// place that closes that gap: called after a content-affecting write's
+// own enqueue()d promise has already resolved.
+//
+// Deliberately fire-and-forget, never awaited by the caller: rebuildIndex
+// is itself enqueue()d internally (search/rebuild-index.ts) - awaiting it
+// from inside the very job whose own completion is what let this run
+// would deadlock (routes/search.ts's own comment describes the same
+// hazard for a second, nested enqueue() call). A failed reindex must
+// also never surface as a failure of the write that triggered it - the
+// write already succeeded, and the index is rebuildable from content at
+// any time, so a logged-and-swallowed failure here is the correct
+// severity, not a thrown error.
+export function reindexInBackground(config) {
+    void rebuildIndex(config).catch((error) => {
+        console.error('Background search reindex failed:', error);
+    });
+}
+// startServer's own boot-time call - see rebuildIndexIfMissing's own
+// comment for why this is conditional (existsSync), unlike the
+// unconditional reindexInBackground above.
+export function reindexOnBootIfMissing(config) {
+    void rebuildIndexIfMissing(config).catch((error) => {
+        console.error('Background search reindex failed:', error);
+    });
+}

package/dist/services/theme-schemas.js

@@ -12,9 +12,13 @@ import { requiredFieldsHaveValidDefaults } from "./validation.js";
 // loadFlatTemplates walk exactly (already established for snippets/
 // layouts), extended to extract the embedded {% schema %} block instead
 // of returning the raw file contents.
-function loadTypeSchemas(typesDir) {
+//
+// kind is only used to word each warning ("Section" vs "Block") -
+// callers already know which directory they asked for.
+function loadTypeSchemas(typesDir, kind) {
     const schemas = {};
     const acceptsBlocks = {};
+    const warnings = [];
     let entries;
     try {
         entries = readdirSync(typesDir, { withFileTypes: true })
@@ -22,10 +26,11 @@ function loadTypeSchemas(typesDir) {
             .map((entry) => entry.name);
     }
     catch {
-        return { schemas, acceptsBlocks };
+        return { schemas, acceptsBlocks, warnings };
     }
     for (const fileName of entries) {
         const type = fileName.slice(0, -'.liquid'.length);
+        const label = `${kind} type "${type}" (${fileName}) was excluded from the theme`;
         let source;
         try {
             source = readFileSync(join(typesDir, fileName), 'utf-8');
@@ -35,6 +40,7 @@ function loadTypeSchemas(typesDir) {
         }
         const parsed = parseThemeComponentFile(source);
         if (!parsed) {
+            warnings.push(`${label}: no valid {% schema %} block found (missing, or not parseable JSON).`);
             continue;
         }
         // A type whose required settings fields lack usable defaults is
@@ -42,6 +48,7 @@ function loadTypeSchemas(typesDir) {
         // never a boot failure, just excluded from what gets registered
         // (guide-theme-authoring.md, Group L).
         if (!requiredFieldsHaveValidDefaults(parsed.schema)) {
+            warnings.push(`${label}: a property listed in "required" has no valid "default" (see guide-theme-authoring.md).`);
             continue;
         }
         schemas[type] = parsed.schema;
@@ -50,14 +57,15 @@ function loadTypeSchemas(typesDir) {
         // blocksHtml), not a schema field (guide-theme-authoring.md).
         acceptsBlocks[type] = parsed.markup.includes('blocksHtml');
     }
-    return { schemas, acceptsBlocks };
+    return { schemas, acceptsBlocks, warnings };
 }
 export function loadThemeSchemas(themeRoot) {
-    const sections = loadTypeSchemas(join(themeRoot, 'sections'));
-    const blocks = loadTypeSchemas(join(themeRoot, 'blocks'));
+    const sections = loadTypeSchemas(join(themeRoot, 'sections'), 'Section');
+    const blocks = loadTypeSchemas(join(themeRoot, 'blocks'), 'Block');
     return {
         sections: sections.schemas,
         blocks: blocks.schemas,
         acceptsBlocks: { sections: sections.acceptsBlocks, blocks: blocks.acceptsBlocks },
+        warnings: [...sections.warnings, ...blocks.warnings],
     };
 }

package/dist/services/validation.d.ts

@@ -14,6 +14,7 @@ export interface ThemeSchemas {
         sections: Record<string, boolean>;
         blocks: Record<string, boolean>;
     };
+    warnings?: string[];
 }
 export declare function requiredFieldsHaveValidDefaults(schema: object): boolean;
 export declare function validateInstance(instance: unknown, kind: 'section' | 'block', themeSchemas: ThemeSchemas): ValidationResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o-a/cms-agent",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "type": "module",
   "publishConfig": {
     "access": "public"