@cogenta/cli 0.2.2 → 0.3.0

package/dist/commands/serve.js

@@ -1,14 +1,32 @@
-import { readFile } from 'node:fs/promises';
+import { readFile, stat } from 'node:fs/promises';
 import { createServer } from 'node:http';
 import { dirname, join } from 'node:path';
 import process from 'node:process';
 import { pathToFileURL } from 'node:url';
-import { buildContentSchema, createAgentsRouter, createAuditRouter, createAuthRouter, createContentGateway, createContentService, createMediaRouter, createPermissionLayer, createRestRouter, executeGraphQL, resolveActor, } from '@cogenta/api';
+import { buildContentSchema, createAgentsRouter, createAssistantRouter, createAuditRouter, createAuthRouter, createContentGateway, createContentService, createMediaRouter, createMfaRecommendationSource, createNoticeDismissalStore, createNoticeRouter, createPermissionLayer, createRestRouter, createSearchRouter, createSitePlanRouter, createSuspiciousActivitySource, createTaxonomyRouter, createUsersRouter, errorResponse, executeGraphQL, resolveActor, variantKeyFor, } from '@cogenta/api';
 import { createAuthStore } from '@cogenta/auth';
 import { CogentaError, createDatabaseMediaStore, createDatabaseRegistry, createLogger, createStorageRegistry, isCogentaError, loadConfig, } from '@cogenta/core';
-import { buildSchemaDocument, createContentStore, createRedirectStore, createSchemaTables, withReadOnlyStore, } from '@cogenta/schema';
+import { buildSchemaDocument, createContentStore, createRedirectStore, createSchemaTables, createSearchIndex, createTaxonomyStore, withLifecycleEvents, withReadOnlyStore, withSearchIndexing, } from '@cogenta/schema';
 import { serveAdminAsset } from './admin-assets.js';
-import { loadSkinCss, renderRequestedPage } from './theme-render.js';
+import { buildAssistant, withVectorIndexing } from './assistant.js';
+import { createContentWebhookEmitter } from './content-webhooks.js';
+import { applySecurity } from './http-security.js';
+import { selectMediaImageProcessor } from './media-images.js';
+import { renderSearchPage } from './search-page.js';
+import { createSecurityAlertWatch } from './security-alerts.js';
+import { buildSitemapFiles, collectRoutedResources, renderRobots, seoSiteFor } from './seo.js';
+import { createSitePlanning } from './site-plan.js';
+import { cssEtag, loadThemeCss } from './theme-css.js';
+import { DEFAULT_IMAGE_ENDPOINT, joinStyles, loadSkinCss, renderDraftPage, renderRequestedPage, STYLESHEET_PATH, } from './theme-render.js';
+/** `/sitemap.xml` and the `/sitemap-N.xml` chunks a large site splits into. */
+const SITEMAP_PATH = /^\/sitemap(?:-\d+)?\.xml$/u;
+/** The only `Content-Type` values `/_image` will ever put on the wire. */
+const SERVABLE_IMAGE_TYPES = new Set([
+    'image/avif',
+    'image/webp',
+    'image/jpeg',
+    'image/png',
+]);
 const SCHEMA_FILE_CANDIDATES = [
     'cogenta.schema.ts',
     'cogenta.schema.mts',
@@ -25,6 +43,16 @@ const SCHEMA_FILE_CANDIDATES = [
  * collections has nothing to serve.
  */
 export async function loadCollections(projectRoot) {
+    return (await loadSchemaModule(projectRoot)).collections;
+}
+/**
+ * The same file, read for both halves of the content model.
+ *
+ * Taxonomies arrive as a **named** export beside the default one
+ * (`export const taxonomies = [...]`), so every schema file written before
+ * `schema@2.0` keeps loading unchanged and simply declares none.
+ */
+export async function loadSchemaModule(projectRoot) {
     for (const candidate of SCHEMA_FILE_CANDIDATES) {
         const path = join(projectRoot, candidate);
         let module;
@@ -49,7 +77,18 @@ export async function loadCollections(projectRoot) {
                 hint: 'Export the array defineCollection() built, the same one passed to createSchemaTables in tests.',
             });
         }
-        return collections;
+        const taxonomies = module.taxonomies;
+        if (taxonomies !== undefined && !Array.isArray(taxonomies)) {
+            throw new CogentaError({
+                code: 'SCHEMA_INVALID',
+                message: `${path} exports "taxonomies", but not as an array.`,
+                hint: 'Export the array defineTaxonomy() built: export const taxonomies = [category].',
+            });
+        }
+        return {
+            collections: collections,
+            taxonomies: (taxonomies ?? []),
+        };
     }
     throw new CogentaError({
         code: 'SCHEMA_INVALID',
@@ -57,6 +96,29 @@ export async function loadCollections(projectRoot) {
         hint: 'Create cogenta.schema.ts, default-exporting the array of collections defineCollection() built.',
     });
 }
+/**
+ * The schema file this project actually loads, or `undefined` when it has
+ * none.
+ *
+ * Anything that *writes* the schema back has to target this, not a guessed
+ * name: `loadCollections` prefers `cogenta.schema.ts` (the form ADR-0010
+ * calls for — TypeScript in git), so a writer that assumed `.mjs` would
+ * create tables and then write a file nothing reads, leaving an operator
+ * with orphan tables and no collections after the restart it was told to do.
+ */
+export async function findSchemaFile(projectRoot) {
+    for (const candidate of SCHEMA_FILE_CANDIDATES) {
+        const path = join(projectRoot, candidate);
+        try {
+            await stat(path);
+            return path;
+        }
+        catch {
+            // Try the next candidate — same order `loadCollections` uses.
+        }
+    }
+    return undefined;
+}
 /**
  * True only when the candidate file itself does not exist — never for a
  * missing import *inside* it, which must surface as a real error rather than
@@ -75,33 +137,92 @@ function isModuleNotFound(error, path) {
     // `.ts`) surfaced as a hard SCHEMA_INVALID instead of trying the next one.
     return error.message.includes(pathToFileURL(path).href) || error.message.includes(path);
 }
+/**
+ * What `/api/assistant` answers with when this process built no assistant at
+ * all — a caller that did not ask for one, in a test or an embedding. Exactly
+ * what `createAssistToolset` returns with no provider, restated here so
+ * `assembleSite` need not construct one to say "off".
+ */
+const EMPTY_TOOLSET = Object.freeze({
+    available: false,
+    reason: 'No AI provider is configured for this site, so the writing assistant is switched off. Everything else in the CMS works exactly the same.',
+    tools: Object.freeze([]),
+    capabilities: Object.freeze([]),
+});
 /** `relyingPartyId` is the bare host: WebAuthn ties a passkey to a domain, not a URL. */
 function webauthnConfigFor(site) {
     const host = new URL(site.url).hostname;
     return { relyingPartyName: site.name, relyingPartyId: host, origin: site.url };
 }
-async function assembleSite(db, collections, signingKey, site, storage, health, 
-/** Optional: no caller constructs an agent registry today, and `/api/agents` simply is not mounted when this is absent — see `agentsRouter` on `Site`. */
-agents, 
-/**
- * "Commencer par une démo en lecture seule" (L9 tâche 12, playground). Every
- * write REST or GraphQL could attempt refuses with `CONTENT_READ_ONLY`
- * instead of landing — wrapped once here, at the one place both transports'
- * stores are actually constructed, so neither can bypass it.
- */
-readOnly = false, 
-/** `null` when `theme.tokens.json` is absent or invalid — see `loadSkinCss`. */
-skinCss = null) {
-    await createSchemaTables(db, collections);
+async function assembleSite(options) {
+    const { db, collections, site, storage, logger } = options;
+    const readOnly = options.readOnly ?? false;
+    const styles = options.styles ?? null;
+    const taxonomies = options.taxonomies ?? [];
+    // Taxonomies first: a `f.taxonomy()` field carries a real foreign key into
+    // the terms table, which therefore has to exist before the collection does.
+    await createSchemaTables(db, collections, taxonomies);
+    // Full-text search, connected for the first time (L10 task 3). The index is
+    // derived data and creates its own physical table, so a fresh install can
+    // index its first entry without a migration having run.
+    //
+    // Accepted from the caller when there is one: `runServe` builds it before the
+    // assistant so the semantic half can be fused with *this* index rather than
+    // with a second one over the same table.
+    const searchIndex = options.searchIndex ?? (await createSearchIndex({ db }));
     const stores = new Map();
     const storeFor = (collection) => {
         const existing = stores.get(collection.name);
         if (existing !== undefined)
             return existing;
-        const created = createContentStore({ db, collection });
-        const stored = readOnly ? withReadOnlyStore(created) : created;
-        stores.set(collection.name, stored);
-        return stored;
+        // `siblings` is what lets `delete()` enforce `restrict` in application
+        // code (ADR-0022): trashing is an UPDATE, so the foreign key has nothing
+        // left to refuse at that moment.
+        const created = createContentStore({ db, collection, siblings: collections });
+        const guarded = readOnly ? withReadOnlyStore(created) : created;
+        // Outermost, so a read-only refusal happens *before* anything is indexed:
+        // a write that never landed must not change the index either.
+        const indexed = withSearchIndexing(guarded, {
+            collection,
+            index: searchIndex,
+            onError: (error) => logger.error('search index write failed', {
+                collection: collection.name,
+                error: String(error),
+            }),
+        });
+        // The semantic half, wrapped the same way and for the same reason (L18
+        // task 5): REST and GraphQL are handed the same store instances, so one
+        // wrap covers both and neither can write content the index never hears
+        // about. Absent entirely when no embedder is available.
+        const stored = options.assistant?.vectors === undefined
+            ? indexed
+            : withVectorIndexing(indexed, {
+                collection,
+                siteId: site.url,
+                store: options.assistant.vectors.store,
+                embeddings: options.assistant.vectors.embeddings,
+                onError: (error) => logger.error('vector index write failed', {
+                    collection: collection.name,
+                    error: String(error),
+                }),
+            });
+        // Outermost of all: an event must describe a write that really landed, so
+        // it fires after the read-only guard has had its chance to refuse and
+        // after the index has been brought back in step. A receiver that rebuilt a
+        // page from an event the store then rejected would serve a page that never
+        // existed.
+        const observed = options.onContentEvent == null
+            ? stored
+            : withLifecycleEvents(stored, {
+                collection,
+                emit: options.onContentEvent,
+                onError: (error) => logger.error('content webhook emit failed', {
+                    collection: collection.name,
+                    error: String(error),
+                }),
+            });
+        stores.set(collection.name, observed);
+        return observed;
     };
     // The gateway (below) reads `stores` directly rather than through
     // `storeFor` — REST's own lazy population left it empty for any
@@ -122,41 +243,137 @@ skinCss = null) {
     });
     const auth = await createAuthStore({
         db,
-        signingKey,
+        signingKey: options.signingKey,
         collections,
         issuer: site.name,
         webauthn: webauthnConfigFor(site),
     });
+    // One store per taxonomy, made once: a term store holds no state beyond its
+    // table, but re-deriving it per request would re-resolve every identifier.
+    const taxonomyStores = new Map();
+    const taxonomyStoreFor = (taxonomy) => {
+        const existing = taxonomyStores.get(taxonomy.name);
+        if (existing !== undefined)
+            return existing;
+        const created = createTaxonomyStore({ db, taxonomy });
+        taxonomyStores.set(taxonomy.name, created);
+        return created;
+    };
     const mediaStore = createDatabaseMediaStore({ db });
+    const noticeDismissals = createNoticeDismissalStore(db);
+    await noticeDismissals.ensureTable();
     return {
         db,
         auth,
         restRouter: createRestRouter({ service, siteUrl: site.url }),
         authRouter: createAuthRouter({ auth }),
-        mediaRouter: createMediaRouter({ store: mediaStore, storage }),
+        mediaRouter: createMediaRouter({
+            store: mediaStore,
+            storage,
+            ...(options.images === undefined || options.images === null
+                ? {}
+                : { images: options.images }),
+        }),
         auditRouter: createAuditRouter({ audit: auth.audit }),
-        ...(agents === undefined ? {} : { agentsRouter: createAgentsRouter(agents) }),
+        taxonomyRouter: createTaxonomyRouter({
+            taxonomies,
+            permissions,
+            storeFor: (taxonomy) => taxonomyStoreFor(taxonomy),
+        }),
+        searchRouter: createSearchRouter({
+            index: searchIndex,
+            collections,
+            permissions,
+            defaultLocale: site.defaultLocale,
+        }),
+        securityAlerts: options.onSecurityEvent == null
+            ? null
+            : createSecurityAlertWatch({
+                rateLimit: auth.rateLimit,
+                send: options.onSecurityEvent,
+                siteUrl: site.url,
+                logger,
+            }),
+        noticeRouter: createNoticeRouter({
+            // One source today, and the seam is the array: a future recommendation
+            // (a plugin update waiting, a certificate about to expire) is one more
+            // entry here and nothing else anywhere.
+            sources: [
+                createMfaRecommendationSource({ collections, credentials: auth.credentials }),
+                // The failed-sign-in table has been written to since L2 and read by
+                // nothing but the limiter's own counter (L14 task 4). One extra source
+                // in this array is the whole wiring — the seam the notice mechanism was
+                // designed around.
+                createSuspiciousActivitySource({ rateLimit: auth.rateLimit }),
+            ],
+            dismissals: noticeDismissals,
+        }),
+        usersRouter: createUsersRouter({ auth }),
+        assistantRouter: createAssistantRouter({
+            toolset: (options.assistant?.toolset ?? EMPTY_TOOLSET),
+            collections,
+            permissions,
+            site,
+            logger,
+        }),
+        ...(options.agents === undefined ? {} : { agentsRouter: createAgentsRouter(options.agents) }),
+        ...(options.sitePlans === undefined
+            ? {}
+            : { sitePlanRouter: createSitePlanRouter(options.sitePlans) }),
         mediaStore,
         storage,
+        images: options.images ?? null,
         graphqlSchema: buildContentSchema({ collections }),
         gateway: createContentGateway({ collections, stores, permissions }),
-        schemaDocument: buildSchemaDocument(collections, {
-            locales: site.locales,
-            defaultLocale: site.defaultLocale,
-        }),
+        permissions,
+        schemaDocument: buildSchemaDocument(collections, { locales: site.locales, defaultLocale: site.defaultLocale }, taxonomies),
+        redirects,
         collections,
+        taxonomies,
         site,
-        skinCss,
-        health,
+        styles,
+        security: options.security,
+        health: options.health,
         dispose: async () => {
             await db.close();
         },
     };
 }
+/**
+ * No route on this server takes a JSON body anywhere near this size — the
+ * one exception, `/api/site-plans`, already caps its base64 document
+ * payloads at 60 MiB total inside `site-plan-router.ts`. This is a ceiling
+ * above that, not a route-specific limit: `readBody` runs for every mutating
+ * request, most of them long before any permission check, so an unbounded
+ * read here was a way for an anonymous caller to make the server buffer an
+ * arbitrarily large body before ever being told no.
+ */
+const MAX_REQUEST_BODY_BYTES = 64 * 1024 * 1024;
 async function readBody(req) {
     const chunks = [];
-    for await (const chunk of req)
-        chunks.push(chunk);
+    let total = 0;
+    let tooLarge = false;
+    for await (const chunk of req) {
+        const buf = chunk;
+        total += buf.length;
+        if (total > MAX_REQUEST_BODY_BYTES) {
+            // Bound memory by not buffering any more chunks, but keep draining the
+            // socket rather than destroying it: a client mid-write over the same
+            // TCP connection this response has to go out on can be reset by an
+            // early `req.destroy()`, which loses the 413 response along with it.
+            // Letting the read finish costs bandwidth, never unbounded memory.
+            tooLarge = true;
+            continue;
+        }
+        chunks.push(buf);
+    }
+    if (tooLarge) {
+        throw new CogentaError({
+            code: 'REQUEST_BODY_TOO_LARGE',
+            message: `The request body exceeds the ${MAX_REQUEST_BODY_BYTES}-byte limit.`,
+            hint: 'Send a smaller payload.',
+        });
+    }
     if (chunks.length === 0)
         return undefined;
     const text = Buffer.concat(chunks).toString('utf8');
@@ -297,6 +514,49 @@ async function recordAuthAudit(site, actor, method, pathname, response, logger)
         .record({ actorId: userId, actorRoles: roles, action: 'auth.login' })
         .catch((error) => logger.error('audit record failed', { error: String(error) }));
 }
+/**
+ * Account management, in the audit log.
+ *
+ * Who created an account, who changed a role, who disabled someone and who cut
+ * a session short are exactly the events an append-only, hash-chained log
+ * exists for — and they were previously invisible, since the only way to do any
+ * of it was a terminal.
+ *
+ * Recorded here, at the transport boundary, for the same reason the content and
+ * media audits are: the router stays a pure request-in/response-out value, and
+ * only a response that actually succeeded is written down.
+ */
+async function recordUserAudit(site, actor, method, pathname, response, logger) {
+    if (response.status < 200 || response.status >= 300)
+        return;
+    const segments = pathname.split('/').filter((segment) => segment.length > 0);
+    // ['api', 'users', <id?>, <'sessions' | 'password'>?, <sessionId?>]
+    const target = segments[2];
+    const sub = segments[3];
+    const action = method === 'POST' && target === undefined
+        ? 'user.create'
+        : method === 'PATCH' && target !== undefined && sub === undefined
+            ? 'user.update'
+            : method === 'POST' && sub === 'password'
+                ? 'user.password_change'
+                : method === 'DELETE' && sub === 'sessions'
+                    ? 'user.session_revoke'
+                    : null;
+    if (action === null)
+        return;
+    // The subject is named, never anything that could sign anyone in: no
+    // password, no token, not even the new roles' provenance beyond the id.
+    const created = response.body?.data?.user;
+    const subjectId = typeof created?.id === 'string' ? created.id : target === 'me' ? actor.id : (target ?? null);
+    await site.auth.audit
+        .record({
+        actorId: actor.id,
+        actorRoles: actor.roles,
+        action,
+        ...(subjectId === null ? {} : { entryId: subjectId }),
+    })
+        .catch((error) => logger.error('audit record failed', { error: String(error) }));
+}
 function writeRestResponse(res, response) {
     res.writeHead(response.status, response.headers);
     res.end(response.body === null || response.body === undefined
@@ -330,6 +590,104 @@ async function serveMediaFile(site, actor, id, req, res) {
     stream.on('error', () => res.destroy());
     stream.pipe(res);
 }
+/**
+ * `GET /_image?id=…&w=…` — the public delivery endpoint for images.
+ *
+ * **Public on purpose, and only for images.** A `<img src>` in a published
+ * page is fetched by a visitor's browser with no session, so an endpoint the
+ * theme can point at cannot be behind the same authentication as
+ * `/api/media/{id}/file`. Restricting it to `kind === 'image'` is what keeps
+ * that from widening to every uploaded PDF and video: those stay behind the
+ * authenticated route, unchanged.
+ *
+ * It serves the rendition the upload already produced, and falls back to the
+ * original when there is none — an asset uploaded before the pipeline
+ * existed, a width outside the ladder, or a host with no image driver. It
+ * never renders on demand: nothing here decodes an image, so a public URL
+ * cannot be turned into CPU by asking for a size nobody stored.
+ */
+async function serveImageVariant(site, url, req, res) {
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+        res.writeHead(405, { allow: 'GET' }).end();
+        return;
+    }
+    const id = url.searchParams.get('id');
+    if (id === null || id === '') {
+        jsonError(res, 400, 'QUERY_INVALID', 'An image request must name the media it wants.');
+        return;
+    }
+    const asset = await site.mediaStore.get(id);
+    if (asset === null || asset.kind !== 'image') {
+        jsonError(res, 404, 'MEDIA_NOT_FOUND', `No image asset with id "${id}".`);
+        return;
+    }
+    let key = asset.storageKey;
+    // Never the asset's recorded `mimeType` unquestioned. Uploads now record
+    // the sniffed type, but an asset stored before that fix — or by a future
+    // writer that skips the route — could carry `text/html`, and this endpoint
+    // is public, unauthenticated and on the site's own origin. A type that is
+    // not an image serves as an opaque download instead of executing.
+    let contentType = SERVABLE_IMAGE_TYPES.has(asset.mimeType)
+        ? asset.mimeType
+        : 'application/octet-stream';
+    const requested = Number(url.searchParams.get('w'));
+    if (site.images !== null &&
+        Number.isInteger(requested) &&
+        requested > 0 &&
+        asset.width !== null &&
+        asset.height !== null) {
+        const names = site.images.variantNames({ width: asset.width, height: asset.height });
+        const wanted = `${requested}.`;
+        const match = names.find((name) => name.startsWith(wanted));
+        if (match !== undefined) {
+            const variantKey = variantKeyFor(id, match);
+            if (await site.storage.exists(variantKey)) {
+                key = variantKey;
+                if (match.endsWith('.webp'))
+                    contentType = 'image/webp';
+            }
+        }
+    }
+    const stream = await site.storage.get(key);
+    res.writeHead(200, {
+        'content-type': contentType,
+        // Long, because the URL names an immutable rendition of an immutable
+        // upload: replacing an image means a new media id, never new bytes under
+        // the same one.
+        'cache-control': 'public, max-age=31536000, immutable',
+    });
+    stream.on('error', () => res.destroy());
+    stream.pipe(res);
+}
+/**
+ * Loads the media a theme render references, as `@cogenta/render`'s
+ * `MediaAsset`.
+ *
+ * The two shapes are deliberately different types (ADR-0016: the delivery
+ * plane declares its own wire types rather than importing the engine's), so
+ * this is the one place they are mapped. Only images and videos exist in that
+ * shape at all — a PDF has no `srcset` — so anything else is left out and
+ * `ctx.image()` refuses it clearly.
+ */
+async function loadRenderMedia(site, ids) {
+    const found = new Map();
+    for (const id of new Set(ids)) {
+        const asset = await site.mediaStore.get(id);
+        if (asset === null)
+            continue;
+        if (asset.kind !== 'image' && asset.kind !== 'video')
+            continue;
+        found.set(id, {
+            id: asset.id,
+            kind: asset.kind,
+            alt: asset.alt,
+            ...(asset.width === null ? {} : { width: asset.width }),
+            ...(asset.height === null ? {} : { height: asset.height }),
+            focal: asset.focal,
+        });
+    }
+    return found;
+}
 /**
  * Builds the Node request handler from an already-assembled site.
  *
@@ -342,6 +700,11 @@ async function serveMediaFile(site, actor, id, req, res) {
 export function createRequestListener(site, logger) {
     return async (req, res) => {
         const url = new URL(req.url ?? '/', 'http://localhost');
+        // Before anything else, and once: CORS, the security headers and the
+        // cache-control class of this path (L10 task 6). A preflight is answered
+        // here and never reaches a route.
+        if (applySecurity(req, res, url.pathname, site.security))
+            return;
         try {
             const actor = await resolveActor(site.auth, Object.fromEntries(Object.entries(req.headers).map(([key, value]) => [
                 key,
@@ -367,12 +730,46 @@ export function createRequestListener(site, logger) {
                 jsonError(res, 404, 'CONTENT_NOT_FOUND', 'No admin asset matches this path.');
                 return;
             }
+            // The theme's stylesheet: public, cacheable, and the same URL every
+            // page links, so a visitor pays for ~26 kB once instead of on every
+            // page. Inlining it in each document would cost that on every
+            // navigation; a `<link>` with a real ETag costs a conditional request
+            // that answers 304. There is nothing to permission-check — the sheet is
+            // derived from the skin's tokens and contains no content.
+            if (url.pathname === STYLESHEET_PATH) {
+                if (req.method !== 'GET') {
+                    res.writeHead(405, { allow: 'GET' }).end();
+                    return;
+                }
+                if (site.styles === null) {
+                    jsonError(res, 404, 'CONTENT_NOT_FOUND', 'This site has no stylesheet.');
+                    return;
+                }
+                const etag = cssEtag(site.styles);
+                if (req.headers['if-none-match'] === etag) {
+                    res.writeHead(304, { etag }).end();
+                    return;
+                }
+                res.writeHead(200, {
+                    'content-type': 'text/css; charset=utf-8',
+                    etag,
+                    // Revalidate every time: a skin swap must show up on the next
+                    // request, which is the whole promise of contract D's hot swap. The
+                    // ETag makes that revalidation a 304 rather than a re-download.
+                    'cache-control': 'public, max-age=0, must-revalidate',
+                });
+                res.end(site.styles);
+                return;
+            }
             if (url.pathname.startsWith('/api/auth/')) {
                 const body = req.method === 'GET' || req.method === 'DELETE' ? undefined : await readBody(req);
                 const request = toRestRequest(req, url, body);
                 const response = await site.authRouter.handle(request);
                 writeRestResponse(res, response);
                 await recordAuthAudit(site, actor, req.method ?? 'GET', url.pathname, response, logger);
+                // A refused sign-in is the only clock a brute-force alert can honestly
+                // have here (L14 task 4) — see `security-alerts.ts` for why not a timer.
+                await site.securityAlerts?.observe(response.status);
                 return;
             }
             // Public and read-only: `schema.json` describes collection shapes and
@@ -390,6 +787,13 @@ export function createRequestListener(site, logger) {
             // Serving the file itself sits outside `mediaRouter`: its `RestResponse`
             // is JSON-only, and a binary body has no shape to fit into that without
             // widening the transport contract every other route relies on.
+            // The public image endpoint (L10 task 5). Before the `/api/*` block on
+            // purpose: it is not an API route, and it is the one media path a
+            // visitor's browser reaches with no session.
+            if (url.pathname === DEFAULT_IMAGE_ENDPOINT) {
+                await serveImageVariant(site, url, req, res);
+                return;
+            }
             const fileMatch = /^\/api\/media\/([^/]+)\/file$/u.exec(url.pathname);
             if (fileMatch !== null) {
                 await serveMediaFile(site, actor, decodeURIComponent(fileMatch[1] ?? ''), req, res);
@@ -421,6 +825,15 @@ export function createRequestListener(site, logger) {
                 await recordContentAudit(site, actor, req.method ?? 'GET', url.pathname, body, response, logger);
                 return;
             }
+            // Terms live apart from content on purpose: a taxonomy is not a
+            // collection, and a site may legitimately name both the same thing
+            // (ADR-0022). Its router owns its own permission door.
+            if (url.pathname.startsWith('/api/taxonomies')) {
+                const body = req.method === 'GET' || req.method === 'DELETE' ? undefined : await readBody(req);
+                const request = toRestRequest(req, url, body);
+                writeRestResponse(res, await site.taxonomyRouter.handle(request, context));
+                return;
+            }
             if (url.pathname.startsWith('/api/media')) {
                 const body = req.method === 'GET' || req.method === 'DELETE' ? undefined : await readBody(req);
                 const request = toRestRequest(req, url, body);
@@ -429,11 +842,57 @@ export function createRequestListener(site, logger) {
                 await recordMediaAudit(site, actor, req.method ?? 'GET', url.pathname, response, logger);
                 return;
             }
+            // The full-text index, reachable at last (L10 task 3). Its own router
+            // decides which collections this actor may search — never this layer.
+            if (url.pathname === '/api/search') {
+                const request = toRestRequest(req, url, undefined);
+                writeRestResponse(res, await site.searchRouter.handle(request, context));
+                return;
+            }
             if (url.pathname.startsWith('/api/audit')) {
                 const request = toRestRequest(req, url, undefined);
                 writeRestResponse(res, await site.auditRouter.handle(request, context.actor));
                 return;
             }
+            if (url.pathname.startsWith('/api/notices')) {
+                const request = toRestRequest(req, url, undefined);
+                writeRestResponse(res, await site.noticeRouter.handle(request, context.actor));
+                return;
+            }
+            if (url.pathname.startsWith('/api/users')) {
+                const body = req.method === 'GET' || req.method === 'DELETE' ? undefined : await readBody(req);
+                const request = toRestRequest(req, url, body);
+                const response = await site.usersRouter.handle(request, context.actor);
+                writeRestResponse(res, response);
+                await recordUserAudit(site, actor, req.method ?? 'GET', url.pathname, response, logger);
+                return;
+            }
+            if (url.pathname.startsWith('/api/site-plans') && site.sitePlanRouter !== undefined) {
+                // `SitePlanRouter` itself refuses every route to a non-admin actor,
+                // but only after `readBody` has already buffered the whole request —
+                // and this route, alone among this server's routes, invites
+                // multi-megabyte bodies by design (uploaded documents). Checking the
+                // role here, before the body is read at all, means an unauthenticated
+                // or non-admin caller is turned away without the server ever reading
+                // what they sent.
+                if (!context.actor.roles.includes('admin')) {
+                    jsonError(res, 403, 'FORBIDDEN', 'Only the admin role may propose or apply a site plan.');
+                    return;
+                }
+                const body = req.method === 'GET' || req.method === 'DELETE' ? undefined : await readBody(req);
+                const request = toRestRequest(req, url, body);
+                writeRestResponse(res, await site.sitePlanRouter.handle(request, context.actor));
+                return;
+            }
+            // Always mounted, on every site (L18). On one with no AI provider it is
+            // the route that answers `{available: false}`, which is precisely what
+            // lets the admin panel disappear instead of failing.
+            if (url.pathname.startsWith('/api/assistant')) {
+                const body = req.method === 'GET' ? undefined : await readBody(req);
+                const request = toRestRequest(req, url, body);
+                writeRestResponse(res, await site.assistantRouter.handle(request, context));
+                return;
+            }
             if (url.pathname.startsWith('/api/agents') && site.agentsRouter !== undefined) {
                 const request = toRestRequest(req, url, undefined);
                 writeRestResponse(res, await site.agentsRouter.handle(request, context.actor));
@@ -459,22 +918,189 @@ export function createRequestListener(site, logger) {
                 res.end(JSON.stringify({ data: health }));
                 return;
             }
+            // The visual page builder's preview (L16). It renders an *unsaved* block
+            // list through the very function that renders the published page, so the
+            // builder can show the real thing in an iframe instead of a React
+            // approximation of the twelve blocks.
+            //
+            // Three gates, in this order, before any of that happens:
+            //  1. an authenticated actor — an anonymous caller has no editing
+            //     session, so it has no business asking for a render of a page state
+            //     that does not exist yet;
+            //  2. `update` on the collection, asked of the same `PermissionLayer`
+            //     every other write path asks (R4: the route verifies, the renderer
+            //     does not);
+            //  3. `renderDraftPage` reads the stored entry through the same
+            //     permission-checked gateway, and every `collectionList` block on
+            //     the page queries through it too — so a draft cannot be used to
+            //     read content this actor could not already read.
+            if (url.pathname === '/api/builder/render') {
+                if (req.method !== 'POST') {
+                    res.writeHead(405, { allow: 'POST' }).end();
+                    return;
+                }
+                if (actor.id === null) {
+                    jsonError(res, 401, 'UNAUTHENTICATED', 'This preview needs a signed-in editor.');
+                    return;
+                }
+                const body = (await readBody(req));
+                const collectionName = typeof body?.collection === 'string' ? body.collection : '';
+                const entryId = typeof body?.entryId === 'string' ? body.entryId : '';
+                const collection = site.collections.find((entry) => entry.name === collectionName);
+                if (collection === undefined || entryId === '') {
+                    jsonError(res, 404, 'CONTENT_NOT_FOUND', 'No such collection or entry.');
+                    return;
+                }
+                // `errorResponse` rather than the outer catch: it is what turns a
+                // `CogentaError` into the status its code deserves (403 for
+                // `FORBIDDEN`), and it is already the mapping every `/api/*` router
+                // uses. The outer catch would answer 500 to a refusal.
+                let html;
+                try {
+                    site.permissions.assert('update', collection, context);
+                    html = await renderDraftPage({
+                        collection: collectionName,
+                        entryId,
+                        blocks: (body?.blocks ?? {}),
+                        ...(typeof body?.values === 'object' && body.values !== null
+                            ? { values: body.values }
+                            : {}),
+                    }, {
+                        collections: site.collections,
+                        gateway: site.gateway,
+                        site: site.site,
+                        styles: site.styles,
+                        loadMedia: (ids) => loadRenderMedia(site, ids),
+                    }, context);
+                }
+                catch (error) {
+                    logger.warn('builder preview refused', {
+                        error: isCogentaError(error) ? error.toJSON() : String(error),
+                    });
+                    writeRestResponse(res, errorResponse(error));
+                    return;
+                }
+                if (html === null) {
+                    jsonError(res, 404, 'CONTENT_NOT_FOUND', 'No such collection or entry.');
+                    return;
+                }
+                res.writeHead(200, {
+                    'content-type': 'application/json; charset=utf-8',
+                    // A draft is never cacheable, by anyone, for any length of time.
+                    'cache-control': 'no-store',
+                });
+                res.end(JSON.stringify({ data: { html } }));
+                return;
+            }
+            // Everything below is the public site rather than the API, so the
+            // redirect table gets its turn first: a page renamed last month must
+            // answer its old URL with the 301 the rename recorded, not a 404 (L10
+            // task 2). Before route matching, so a redirect wins even when some
+            // other entry has since taken the old path — that is what `release()`
+            // is for on the write side.
+            if (req.method === 'GET' || req.method === 'HEAD') {
+                const redirect = await site.redirects.resolve(url.pathname);
+                if (redirect !== null) {
+                    res.writeHead(redirect.status, {
+                        location: `${redirect.to}${url.search}`,
+                        'cache-control': redirect.status === 301 ? 'public, max-age=3600' : 'no-store',
+                    });
+                    res.end();
+                    return;
+                }
+            }
+            // `robots.txt` and `sitemap.xml`, from the real content (L10 task 2).
+            // Both are built as `ANONYMOUS` inside `collectRoutedResources`,
+            // whoever asked: a crawler and a signed-in editor must get the same
+            // document, or the sitemap advertises URLs the crawler cannot fetch.
+            if (url.pathname === '/robots.txt') {
+                if (req.method !== 'GET') {
+                    res.writeHead(405, { allow: 'GET' }).end();
+                    return;
+                }
+                res.writeHead(200, {
+                    'content-type': 'text/plain; charset=utf-8',
+                    'cache-control': 'public, max-age=3600',
+                });
+                res.end(renderRobots(seoSiteFor(site.site)));
+                return;
+            }
+            if (SITEMAP_PATH.test(url.pathname)) {
+                if (req.method !== 'GET') {
+                    res.writeHead(405, { allow: 'GET' }).end();
+                    return;
+                }
+                const seoSite = seoSiteFor(site.site);
+                const files = buildSitemapFiles(seoSite, await collectRoutedResources(site.collections, site.gateway));
+                const file = files.find((candidate) => candidate.path === url.pathname);
+                if (file !== undefined) {
+                    res.writeHead(200, {
+                        'content-type': 'application/xml; charset=utf-8',
+                        'cache-control': 'public, max-age=600',
+                    });
+                    res.end(file.contents);
+                    return;
+                }
+                // `/sitemap-9.xml` on a site that only needs one file is a real 404,
+                // not an empty urlset: an empty chunk would tell a crawler the site
+                // has nothing there rather than that the URL is wrong.
+                jsonError(res, 404, 'CONTENT_NOT_FOUND', 'No sitemap file at this path.');
+                return;
+            }
+            // The public search page (L10 task 3): a real form and a real results
+            // list, served through the same permission-checked search router the
+            // API uses. Deliberately a route rather than a contract B block — see
+            // `search-page.ts` for why.
+            if (url.pathname === '/search' && req.method === 'GET') {
+                const html = await renderSearchPage(url.searchParams.get('q') ?? '', {
+                    router: site.searchRouter,
+                    gateway: site.gateway,
+                    collections: site.collections,
+                    site: site.site,
+                    styles: site.styles,
+                }, context);
+                res.writeHead(200, {
+                    'content-type': 'text/html; charset=utf-8',
+                    'cache-control': 'no-store',
+                });
+                res.end(html);
+                return;
+            }
             // Real theme HTML for anything else — see `theme-render.ts`'s own
             // doc comment for what this is and, as importantly, what it isn't
             // (no Astro build, one theme, no image pipeline). GET only: rendering
             // a page has no meaningful response to any other method.
             if (req.method === 'GET') {
-                const html = await renderRequestedPage(url.pathname, {
+                const renderOptions = {
                     collections: site.collections,
                     gateway: site.gateway,
                     site: site.site,
-                    skinCss: site.skinCss,
-                }, context);
+                    styles: site.styles,
+                    loadMedia: (ids) => loadRenderMedia(site, ids),
+                };
+                const html = await renderRequestedPage(url.pathname, renderOptions, context);
                 if (html !== null) {
                     res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
                     res.end(html);
                     return;
                 }
+                // The site's own 404 page (L14 task 2). It is an ordinary entry at
+                // `site.notFoundPath`, rendered by exactly the same function and
+                // through exactly the same permission-checked gateway as any other
+                // page — a custom 404 that could show content the visitor may not read
+                // would be a hole, not a feature.
+                //
+                // The guard matters: without it, a site whose 404 page is missing (or
+                // whose `notFoundPath` is itself unroutable) would ask for it again
+                // for every unmatched URL forever. One extra lookup, never two.
+                if (url.pathname !== site.site.notFoundPath) {
+                    const notFound = await renderRequestedPage(site.site.notFoundPath, renderOptions, context);
+                    if (notFound !== null) {
+                        res.writeHead(404, { 'content-type': 'text/html; charset=utf-8' });
+                        res.end(notFound);
+                        return;
+                    }
+                }
             }
             res.writeHead(404, { 'content-type': 'application/json; charset=utf-8' });
             res.end(JSON.stringify({
@@ -485,6 +1111,10 @@ export function createRequestListener(site, logger) {
             logger.error('request failed', {
                 error: isCogentaError(error) ? error.toJSON() : String(error),
             });
+            if (isCogentaError(error) && error.code === 'REQUEST_BODY_TOO_LARGE') {
+                jsonError(res, 413, error.code, error.message);
+                return;
+            }
             res.writeHead(500, { 'content-type': 'application/json; charset=utf-8' });
             res.end(JSON.stringify({
                 error: { code: 'INTERNAL', message: 'The request could not be completed.' },
@@ -494,6 +1124,8 @@ export function createRequestListener(site, logger) {
 }
 const DEFAULT_PORT = 4000;
 const DEFAULT_HOST = '127.0.0.1';
+/** How long a shutdown waits for open connections before cutting them. */
+const SHUTDOWN_GRACE_MS = 2_000;
 /**
  * Runs until `options.signal` aborts. Returns 0 on a clean shutdown, 1 if
  * startup failed — nothing here calls `process.exit` (same convention as
@@ -515,8 +1147,11 @@ export async function runServe(options) {
         return 1;
     }
     let collections;
+    let taxonomies;
     try {
-        collections = await loadCollections(projectRoot);
+        const schema = await loadSchemaModule(projectRoot);
+        collections = schema.collections;
+        taxonomies = schema.taxonomies;
     }
     catch (error) {
         if (isCogentaError(error)) {
@@ -531,8 +1166,63 @@ export async function runServe(options) {
     }
     const selection = await createDatabaseRegistry({ logger }).select(loaded.config.database);
     const storageSelection = await createStorageRegistry({ logger }).select(loaded.config.storage);
-    const skinCss = await loadSkinCss((path) => readFile(path, 'utf8'), join(projectRoot, 'theme.tokens.json'));
-    const site = await assembleSite(selection.instance, collections, loaded.config.auth.signingKey, loaded.config.site, storageSelection.instance, async () => ({ database: await selection.health(), storage: await storageSelection.health() }), undefined, options.readOnly ?? false, skinCss);
+    const styles = joinStyles(await loadSkinCss((path) => readFile(path, 'utf8'), join(projectRoot, 'theme.tokens.json')), await loadThemeCss({ read: (url) => readFile(url, 'utf8') }));
+    const images = await selectMediaImageProcessor(logger);
+    // One signed channel for both outbound events — the content lifecycle (task
+    // 1) and the suspicious-activity alert (task 4). One set of endpoints, one
+    // secret, one signing path.
+    const webhooks = createContentWebhookEmitter({
+        webhooks: loaded.config.webhooks,
+        siteUrl: loaded.config.site.url,
+        logger,
+    });
+    // L18. Never fatal: everything inside degrades to "off" with a log line
+    // rather than stopping the site from serving (R2).
+    const searchIndex = await createSearchIndex({ db: selection.instance });
+    const assistant = await buildAssistant({
+        config: loaded.config,
+        db: selection.instance,
+        logger,
+        // Beside the full-text index, never instead of it: the semantic half is
+        // fused with this one by RRF (L18 task 5).
+        fullText: searchIndex,
+    });
+    const site = await assembleSite({
+        db: selection.instance,
+        assistant,
+        searchIndex,
+        collections,
+        taxonomies,
+        signingKey: loaded.config.auth.signingKey,
+        site: loaded.config.site,
+        storage: storageSelection.instance,
+        logger,
+        health: async () => ({
+            database: await selection.health(),
+            storage: await storageSelection.health(),
+        }),
+        readOnly: options.readOnly ?? false,
+        styles,
+        images: images?.processor ?? null,
+        security: loaded.config.security,
+        sitePlans: await createSitePlanning({
+            projectRoot,
+            db: selection.instance,
+            collections,
+            config: loaded.config,
+            logger,
+            readOnly: options.readOnly ?? false,
+            // ADR-0010: the schema is writable in development only. `cogenta dev`
+            // says development; `cogenta serve` does not, and a plan can then be
+            // proposed and reviewed but never applied.
+            development: options.development ?? false,
+        }),
+        // The signed outbound webhook channel, connected to the content lifecycle
+        // for the first time (L14 task 1). `null` when the site configured no
+        // endpoint, or configured one without a signing secret.
+        onContentEvent: webhooks.emit,
+        onSecurityEvent: webhooks.send,
+    });
     const server = createServer(createRequestListener(site, logger));
     const port = options.port ?? DEFAULT_PORT;
     const host = options.host ?? DEFAULT_HOST;
@@ -546,7 +1236,8 @@ export async function runServe(options) {
     const address = server.address();
     const boundPort = typeof address === 'object' && address !== null ? address.port : port;
     out.ok(`Listening on http://${host}:${boundPort}`);
-    out.detail(`${collections.length} collection(s), db driver: ${selection.driver}, storage driver: ${storageSelection.driver}`);
+    out.detail(`${collections.length} collection(s), db driver: ${selection.driver}, storage driver: ${storageSelection.driver}, image driver: ${images?.driver ?? 'none'}`);
+    out.detail(assistant.summary);
     options.onListening?.({ port: boundPort, host });
     await new Promise((resolve) => {
         if (options.signal === undefined)
@@ -559,7 +1250,16 @@ export async function runServe(options) {
     });
     await new Promise((resolve, reject) => {
         server.close((error) => (error ? reject(error) : resolve()));
+        // `close()` alone waits for every open connection to end, and a client
+        // that fetched a large response and never read the body holds one open
+        // indefinitely — a media download is exactly that shape. Without the
+        // grace period, one such client turns Ctrl-C into a hang. Found while
+        // writing the image tests, where a deliberately unread image body kept
+        // the whole process alive.
+        const grace = setTimeout(() => server.closeAllConnections(), SHUTDOWN_GRACE_MS);
+        grace.unref();
     });
+    await assistant.dispose();
     await selection.dispose();
     await storageSelection.dispose();
     await site.dispose().catch(() => undefined); // selection.dispose() already closed the same handle