@o-a/cms-agent 0.2.1 → 0.3.0

package/dist/routes/media.js

@@ -1,18 +1,10 @@
 import { extname } from 'node:path';
 import multipart from '@fastify/multipart';
+import { ALLOWED_UPLOAD_EXTENSIONS } from "../media/filename.js";
 import { ManageMediaError, deleteMedia, listMedia, putMedia } from "../media/manage-media.js";
 import { PathSafetyError } from "../services/path-safety.js";
 import { WRITE_ROUTE_RATE_LIMIT } from "../services/rate-limit-config.js";
 import { requireScope } from "../services/token-auth.js";
-// Images only - confirmed with the user, not a general document
-// library. Checked against the *original* uploaded filename, not the
-// client-supplied mimetype header (trivially spoofable) and not the
-// stored content-addressed filename (built only after this check
-// passes, from the same already-validated extension). .svg is
-// rejected regardless of this list even though it's technically an
-// image format - docs/cms-build-plan.md's own "SVG rejected outright,
-// not sanitised" decision.
-const ALLOWED_UPLOAD_EXTENSIONS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp']);
 function sendManageMediaError(reply, error) {
     if (error.reason === 'not-found') {
         reply.code(404).send({ statusCode: 404, error: 'Not Found', message: error.message });
@@ -29,6 +21,10 @@ async function handleUploadMedia(request, reply, config) {
         reply.code(400).send({ statusCode: 400, error: 'Bad Request', message: 'Expected a multipart file upload' });
         return;
     }
+    // Checked against the *original* uploaded filename, not the
+    // client-supplied mimetype header (trivially spoofable) and not the
+    // stored content-addressed filename (built only after this check
+    // passes, from the same already-validated extension).
     const extension = extname(data.filename).toLowerCase();
     if (!ALLOWED_UPLOAD_EXTENSIONS.has(extension)) {
         reply.code(415).send({

package/dist/routes/publish.js

@@ -1,7 +1,7 @@
 import { isValidCommitAuthor } from "../services/git.js";
 import { PathSafetyError } from "../services/path-safety.js";
 import { WRITE_ROUTE_RATE_LIMIT } from "../services/rate-limit-config.js";
-import { PublishError, publishDrafts, unpublishPage } from "../services/publish.js";
+import { PublishError, publishDrafts, publishPage, unpublishPage } from "../services/publish.js";
 import { requireScope } from "../services/token-auth.js";
 function isNonEmptyString(value) {
     return typeof value === 'string' && value.length > 0;
@@ -19,7 +19,7 @@ function parsePublishBody(body) {
     }
     return { paths, message, author };
 }
-function parseUnpublishBody(body) {
+function parsePublishedFlagBody(body) {
     if (typeof body !== 'object' || body === null) {
         return null;
     }
@@ -73,7 +73,7 @@ export const publishRoutes = async (fastify, opts) => {
         }
     });
     fastify.post('/unpublish/*', { preHandler: requireScope(opts.tokens, 'content'), config: WRITE_ROUTE_RATE_LIMIT }, async (request, reply) => {
-        const parsed = parseUnpublishBody(request.body);
+        const parsed = parsePublishedFlagBody(request.body);
         if (!parsed) {
             reply.code(400).send({
                 statusCode: 400,
@@ -102,4 +102,38 @@ export const publishRoutes = async (fastify, opts) => {
             throw error;
         }
     });
+    // The twin of /unpublish/* above: sets published:true on a live page
+    // in place and commits. Deliberately separate from /publish, which
+    // promotes drafts - a page that is live but unpublished has no draft
+    // to promote, so /publish cannot reach it at all (draft-not-found),
+    // and promoting a draft would publish every pending edit along with
+    // the flag. This only ever changes the one boolean.
+    fastify.post('/publish-page/*', { preHandler: requireScope(opts.tokens, 'content'), config: WRITE_ROUTE_RATE_LIMIT }, async (request, reply) => {
+        const parsed = parsePublishedFlagBody(request.body);
+        if (!parsed) {
+            reply.code(400).send({
+                statusCode: 400,
+                error: 'Bad Request',
+                message: 'Expected { message: string, author: { name, email } }',
+            });
+            return;
+        }
+        const relativePath = request.params['*'];
+        try {
+            await publishPage(opts.config, relativePath, parsed.message, parsed.author);
+            reply.send({ ok: true });
+        }
+        catch (error) {
+            // Same PathSafetyError guard as every other :path route here.
+            if (error instanceof PathSafetyError) {
+                reply.code(404).send({ statusCode: 404, error: 'Not Found', message: 'No content at that path' });
+                return;
+            }
+            if (error instanceof PublishError) {
+                replyForPublishError(reply, error);
+                return;
+            }
+            throw error;
+        }
+    });
 };

package/dist/routes/sitemap.d.ts

@@ -3,4 +3,5 @@ import type { SiteConfig } from '../config.ts';
 export interface SitemapRouteOptions {
     config: SiteConfig;
 }
+export declare function buildSitemapUrls(config: SiteConfig): string[];
 export declare const sitemapRoutes: FastifyPluginAsync<SitemapRouteOptions>;

package/dist/routes/sitemap.js

@@ -24,7 +24,13 @@ function isPublished(contentRoot, relativePath) {
 // never authoritative", see cms-build-plan.md). A saved sitemap would
 // go stale the moment anything is published or unpublished; this
 // can't.
-function buildSitemapUrls(config) {
+// Exported for site-check/run-check.ts's own reuse - it needs the
+// identical "every published page's own URL" walk this route already
+// does, and duplicating it would be the exact kind of drift this
+// codebase avoids elsewhere (see slugify.ts's own "second use
+// justifies the abstraction" precedent, cited directly in this
+// project's own admin sibling repo).
+export function buildSitemapUrls(config) {
     const urls = [];
     for (const relativePath of listFilesRecursively(config.pagesRoot, config.pagesRoot, '.json')) {
         // The 404 page must never be listed as a real crawlable URL,

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.d.ts

@@ -12,3 +12,4 @@ export declare class PublishError extends Error {
 export declare function preparePublishDrafts(config: SiteConfig, themeSchemas: ThemeSchemas, relativePaths: string[]): PreparedOperation;
 export declare function publishDrafts(config: SiteConfig, themeSchemas: ThemeSchemas, relativePaths: string[], message: string, author: CommitAuthor): Promise<void>;
 export declare function unpublishPage(config: SiteConfig, relativePath: string, message: string, author: CommitAuthor): Promise<void>;
+export declare function publishPage(config: SiteConfig, relativePath: string, message: string, author: CommitAuthor): Promise<void>;

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
@@ -240,9 +241,73 @@ async function unpublishPageJob(config, relativePath, message, author) {
         throw new PublishError(reason, `Unpublish failed: ${errorMessage}`, { cause: error });
     }
 }
+// The exact twin of unpublishPageJob above, flipping the same flag the
+// other way: reads the live file, sets published true, commits. Kept as
+// its own job rather than a parameterised shared one - the two read
+// identically but say opposite things, and a boolean argument at every
+// call site ("publishPage(config, path, true)") reads far worse than
+// two named functions.
+//
+// Deliberately does NOT validate against the theme schemas, matching
+// unpublish rather than publishDrafts: this only ever touches content
+// that is already live, and was therefore already validated when it was
+// published in the first place. publishDrafts validates because it
+// promotes a draft, which may never have been checked before.
+//
+// Like unpublish, never touches a draft. A page with unpublished edits
+// pending keeps them, and this only changes whether what is already
+// live is publicly visible.
+async function publishPageJob(config, relativePath, message, author) {
+    const livePath = sanitisePath(config.contentRoot, relativePath);
+    let original;
+    try {
+        original = readFileSync(livePath);
+    }
+    catch {
+        throw new PublishError('page-not-found', `No live page found at "${relativePath}"`);
+    }
+    const parsed = JSON.parse(original.toString('utf-8'));
+    parsed.published = true;
+    const updated = Buffer.from(JSON.stringify(parsed, null, 2));
+    // Same minimal inline restore unpublishPageJob uses, and for the same
+    // reason - one file, no draft, so the two-file publish rollback()
+    // above would need an unused draft slot for no benefit.
+    try {
+        writeFileSync(livePath, updated);
+        commitPaths(config.siteRoot, [livePath], message, author);
+    }
+    catch (error) {
+        try {
+            writeFileSync(livePath, original);
+        }
+        catch {
+            throw new PublishError('rollback-failed', 'Publishing this page failed and rolling back afterwards also failed; the working tree may be inconsistent and needs manual inspection', { cause: error });
+        }
+        const reason = error instanceof GitOperationError ? 'commit-failed' : 'write-failed';
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new PublishError(reason, `Publishing this page failed: ${errorMessage}`, { cause: error });
+    }
+}
 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;
+}
+// Twin of unpublishPage - same queue, same background reindex (a page
+// becoming visible changes the index exactly as much as one leaving it).
+export function publishPage(config, relativePath, message, author) {
+    const result = enqueue(() => publishPageJob(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/dist/services/validation.js

@@ -5,6 +5,20 @@ import { Ajv } from 'ajv';
 // authors, not agent code, and are validated the same lenient way
 // everywhere (see theme-schemas.ts).
 const ajv = new Ajv({ allErrors: true, strict: false });
+// The six format values guide-theme-authoring.md/AGENTS.md actually
+// document (richtext/image/textarea/uri/date/color/range/toggle - uri
+// and date are real standard JSON Schema formats already understood
+// without this) are still, correctly, UI hints only: registering them
+// as a literal no-op format (the `true` here, not a real validator
+// function) doesn't make Ajv enforce anything about them, it only
+// stops it printing "unknown format \"x\" ignored" for values that are
+// completely expected. A theme author's genuine typo (e.g. "iamge")
+// still isn't in this list, so it still warns - this only silences the
+// six we ourselves tell theme authors to use, not unknown-format
+// warnings in general.
+for (const format of ['richtext', 'image', 'textarea', 'color', 'range', 'toggle']) {
+    ajv.addFormat(format, true);
+}
 const schemasDir = join(import.meta.dirname, '..', 'schemas');
 function readSchema(filename) {
     return JSON.parse(readFileSync(join(schemasDir, filename), 'utf-8'));
@@ -70,7 +84,25 @@ export function requiredFieldsHaveValidDefaults(schema) {
         if (typeof propertySchema !== 'object' || propertySchema === null || !('default' in propertySchema)) {
             return false;
         }
-        return ajv.validate(propertySchema, propertySchema.default) === true;
+        // ajv.validate compiles+runs propertySchema in isolation, detached
+        // from whatever schema it was pulled out of - a "$ref" pointing at
+        // a "$defs" entry declared on the parent (not inside this property
+        // sub-schema itself) can't resolve here, and Ajv throws
+        // (MissingRefError) rather than returning false. That's a real
+        // theme-authoring mistake (this function's whole contract assumes
+        // a schema self-contained enough to validate standalone), not a
+        // reason to crash the caller - loadTypeSchemas already treats a
+        // false return here as "type excluded, boot warning printed", so
+        // folding a thrown validation error into that exact same false
+        // keeps every possible way a required field's default can be
+        // unusable on the one graceful path, instead of one of them being
+        // the sole exception that takes the whole server down.
+        try {
+            return ajv.validate(propertySchema, propertySchema.default) === true;
+        }
+        catch {
+            return false;
+        }
     });
 }
 export function validateInstance(instance, kind, themeSchemas) {

package/dist/site-check/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/site-check/cli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { runSiteCheck } from "./run-check.js";
+// Run from vhost/ (see the scaffold's own "check" script), so the
+// site root is one level up - the exact same relative relationship
+// SERVER_JS in create-site/generate-site.ts already relies on.
+const siteRoot = resolve(process.cwd(), '..');
+const KIND_LABELS = {
+    schema: 'Theme schema',
+    'render-error': 'Render error',
+    'missing-asset': 'Missing asset',
+    'broken-link': 'Broken link',
+};
+function printGrouped(findings) {
+    const byKind = new Map();
+    for (const finding of findings) {
+        const list = byKind.get(finding.kind) ?? [];
+        list.push(finding);
+        byKind.set(finding.kind, list);
+    }
+    for (const [kind, list] of byKind) {
+        console.log(`\n${KIND_LABELS[kind]} (${list.length}):`);
+        for (const finding of list) {
+            const location = finding.pageUrl ? `  ${finding.pageUrl}: ` : '  ';
+            console.log(`${location}${finding.message}`);
+        }
+    }
+}
+const result = await runSiteCheck(siteRoot);
+if (result.ok) {
+    console.log('No problems found.');
+    process.exit(0);
+}
+console.log(`${result.findings.length} problem${result.findings.length === 1 ? '' : 's'} found:`);
+printGrouped(result.findings);
+process.exit(1);

package/dist/site-check/run-check.d.ts

@@ -0,0 +1,11 @@
+export type CheckFindingKind = 'schema' | 'render-error' | 'missing-asset' | 'broken-link';
+export interface CheckFinding {
+    kind: CheckFindingKind;
+    message: string;
+    pageUrl?: string;
+}
+export interface CheckResult {
+    ok: boolean;
+    findings: CheckFinding[];
+}
+export declare function runSiteCheck(siteRoot: string): Promise<CheckResult>;