@cogenta/cli 0.2.0 → 0.3.0

package/dist/commands/http-security.js

@@ -0,0 +1,153 @@
+/**
+ * Headers every response carries, whatever it is.
+ *
+ * Deliberately short. `X-Content-Type-Options` stops a browser guessing that
+ * an uploaded file is a script; `X-Frame-Options` and `Referrer-Policy` are
+ * the two others with no plausible downside and a real failure mode without
+ * them. Anything beyond that (`Permissions-Policy`, COEP/COOP) breaks real
+ * pages depending on what a site embeds, so it belongs in the site's own
+ * `csp` string rather than in a default nobody chose.
+ */
+const ALWAYS = Object.freeze({
+    'x-content-type-options': 'nosniff',
+    'x-frame-options': 'SAMEORIGIN',
+    'referrer-policy': 'strict-origin-when-cross-origin',
+});
+/** Which cache-control a path class gets. */
+export function cacheControlFor(pathname, security) {
+    // Never store an API response: they are per-actor by construction — the same
+    // URL answers differently for an editor and for a stranger — and a shared
+    // cache that keeps one is a permission leak, not a performance win.
+    if (pathname.startsWith('/api/'))
+        return 'no-store';
+    // The admin shell is a signed-in application. Its hashed assets could be
+    // cached forever, but `index.html` must not be, and telling them apart here
+    // would duplicate Vite's naming convention in a second place.
+    if (pathname === '/admin' || pathname.startsWith('/admin/'))
+        return 'no-store';
+    // Images and sitemaps set their own, longer, values at their route.
+    if (pathname === '/_image' || pathname === '/robots.txt')
+        return null;
+    if (pathname === '/search')
+        return null;
+    // A public page: cacheable, briefly. `must-revalidate` rather than a long
+    // max-age because publishing is supposed to be visible immediately, and a
+    // CMS whose edits appear ten minutes later is a CMS people stop trusting.
+    return security.pageMaxAge === 0
+        ? 'no-store'
+        : `public, max-age=0, s-maxage=${security.pageMaxAge}, must-revalidate`;
+}
+/**
+ * The CORS headers this request earns, or an empty object.
+ *
+ * The origin is echoed rather than reflected blindly: only an exact match in
+ * the configured list, or `*` when the list holds it. `Vary: Origin` goes out
+ * with any match, because a shared cache that stores one origin's response
+ * and serves it to another is the whole class of CORS cache-poisoning bugs.
+ */
+export function corsHeadersFor(origin, security) {
+    const { cors } = security;
+    if (cors.origins.length === 0 || origin === undefined)
+        return {};
+    const wildcard = cors.origins.includes('*');
+    if (!wildcard && !cors.origins.includes(origin))
+        return {};
+    return {
+        'access-control-allow-origin': wildcard && !cors.credentials ? '*' : origin,
+        vary: 'Origin',
+        ...(cors.credentials ? { 'access-control-allow-credentials': 'true' } : {}),
+    };
+}
+/** The extra headers a preflight needs on top of the ones above. */
+export function preflightHeadersFor(security) {
+    return {
+        'access-control-allow-methods': security.cors.methods.join(', '),
+        'access-control-allow-headers': security.cors.headers.join(', '),
+        'access-control-max-age': String(security.cors.maxAge),
+    };
+}
+function baseHeadersFor(req, pathname, security) {
+    const headers = { ...ALWAYS };
+    if (security.csp !== undefined && security.csp !== false) {
+        headers['content-security-policy'] = security.csp;
+    }
+    // Only over TLS. Sent on a plain HTTP response the header is ignored by
+    // browsers anyway, and sending it locally is how somebody pins
+    // `localhost` to HTTPS and cannot develop for the next year.
+    if (security.hstsMaxAge > 0 && isSecure(req)) {
+        headers['strict-transport-security'] = `max-age=${security.hstsMaxAge}${security.hstsIncludeSubDomains ? '; includeSubDomains' : ''}`;
+    }
+    const origin = headerOf(req, 'origin');
+    Object.assign(headers, corsHeadersFor(origin, security));
+    // A page render is per-actor: `renderRequestedPage` passes the requesting
+    // actor's context down, so an editor's `GET /blog/embargoed` returns the
+    // draft. `public, s-maxage=…` is precisely the pair RFC 9111 §3.5 says
+    // re-authorises a *shared* cache to store a response to a request carrying
+    // `Authorization` — a CDN in front of the site would then serve that draft
+    // to everyone for a minute. Anything sent with credentials is private and
+    // unstorable, whatever class its path belongs to. Found by the security
+    // review of L10 task 6.
+    const cacheControl = hasCredentials(req)
+        ? 'private, no-store'
+        : cacheControlFor(pathname, security);
+    if (cacheControl !== null)
+        headers['cache-control'] = cacheControl;
+    return headers;
+}
+/** True when the request carries something that makes its answer actor-specific. */
+function hasCredentials(req) {
+    return headerOf(req, 'authorization') !== undefined || headerOf(req, 'cookie') !== undefined;
+}
+function headerOf(req, name) {
+    const value = req.headers[name];
+    return Array.isArray(value) ? value[0] : value;
+}
+/** True behind a TLS socket, or behind a proxy that says it terminated one. */
+function isSecure(req) {
+    if ('encrypted' in req.socket && req.socket.encrypted === true)
+        return true;
+    return headerOf(req, 'x-forwarded-proto')?.split(',')[0]?.trim() === 'https';
+}
+/**
+ * Applies the headers to every response of this request, and answers a CORS
+ * preflight outright.
+ *
+ * Returns `true` when the request is finished — the caller must then do
+ * nothing else. Patching `writeHead` rather than calling `setHeader` up front
+ * is what makes this survive the routes that pass a header object of their
+ * own: `res.writeHead(200, { 'content-type': … })` replaces every header
+ * previously set, so setting them early would silently lose them on most of
+ * the routes in this file.
+ */
+export function applySecurity(req, res, pathname, security) {
+    const base = baseHeadersFor(req, pathname, security);
+    const original = res.writeHead.bind(res);
+    // Both of Node's overloads are accepted, so no existing call site changes.
+    // An array-of-raw-headers form exists too and is not used anywhere here; it
+    // is passed through untouched rather than half-merged.
+    res.writeHead = ((status, reasonOrHeaders, maybeHeaders) => {
+        const supplied = typeof reasonOrHeaders === 'string' ? maybeHeaders : (reasonOrHeaders ?? maybeHeaders);
+        if (Array.isArray(supplied)) {
+            return typeof reasonOrHeaders === 'string'
+                ? original(status, reasonOrHeaders, supplied)
+                : original(status, supplied);
+        }
+        const merged = { ...base, ...(supplied ?? {}) };
+        return typeof reasonOrHeaders === 'string'
+            ? original(status, reasonOrHeaders, merged)
+            : original(status, merged);
+    });
+    if (req.method === 'OPTIONS') {
+        const origin = headerOf(req, 'origin');
+        const allowed = corsHeadersFor(origin, security);
+        // A preflight for an origin that is not allowed gets a plain 204 with no
+        // CORS headers: the browser then refuses the real request on its own. A
+        // 403 would be no more secure and would look like a server fault in the
+        // console instead of the policy decision it is.
+        res.writeHead(204, Object.keys(allowed).length === 0 ? {} : preflightHeadersFor(security));
+        res.end();
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=http-security.js.map

package/dist/commands/http-security.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-security.js","sourceRoot":"","sources":["../../src/commands/http-security.ts"],"names":[],"mappings":"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"}

package/dist/commands/links.d.ts

@@ -0,0 +1,24 @@
+import { type Logger } from '@cogenta/core';
+import type { Output, Writer } from '../output.js';
+export type LinksSubcommand = 'check';
+export interface LinksOptions {
+    readonly subcommand: string | undefined;
+    readonly cwd?: string;
+    readonly env?: Record<string, string | undefined>;
+    readonly logger?: Logger;
+    readonly out: Output;
+    readonly stderr: Writer;
+    /** Also follow `http(s)` links that leave the site. Off unless asked. */
+    readonly external?: boolean;
+}
+/**
+ * `cogenta links check` (L14 task 3).
+ *
+ * Exit codes are the ones a cron entry can act on: 0 nothing broken, 1 broken
+ * links were found or the site could not be read, 2 the command line was
+ * wrong. A non-zero exit for "found broken links" is deliberate — that is what
+ * makes this usable as a CI or scheduled check rather than something whose
+ * output somebody has to read.
+ */
+export declare function runLinks(options: LinksOptions): Promise<number>;
+//# sourceMappingURL=links.d.ts.map

package/dist/commands/links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../../src/commands/links.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,MAAM,EAEZ,MAAM,eAAe,CAAA;AAStB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAGlD,MAAM,MAAM,eAAe,GAAG,OAAO,CAAA;AAErC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAC5B;AA+BD;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CA+ErE"}

package/dist/commands/links.js

@@ -0,0 +1,109 @@
+import { dirname, resolve as resolvePath } from 'node:path';
+import process from 'node:process';
+import { createDatabaseRegistry, createLogger, isCogentaError, loadConfig, } from '@cogenta/core';
+import { checkLinks, createContentStore, createSchemaTables, } from '@cogenta/schema';
+import { loadCollections } from './serve.js';
+const USAGE = `Usage
+  cogenta links check [--external]
+
+Walks every published entry, follows every link it holds, and reports the ones
+that lead nowhere: a reference to a deleted or still-unpublished entry, a
+site-relative path that matches no route, and — with --external — an outside
+URL that answers with an error or cannot be reached at all.
+
+Nothing about this runs on its own. This project guarantees no durable
+background worker (rule R1), so "periodically" means a cron entry calling this
+command, not a scheduler pretending to exist inside the site.
+`;
+const REASON_TEXT = {
+    unknown_collection: 'points at a collection this site does not have',
+    target_missing: 'points at content that does not exist',
+    target_unpublished: 'points at content that is not published',
+    unroutable_path: 'is a path no route can serve',
+    http_error: 'answered with an error status',
+    unreachable: 'could not be reached',
+};
+function describe(broken) {
+    const target = broken.link.kind === 'url' ? broken.link.href : `${broken.link.collection}/${broken.link.id}`;
+    const status = broken.status === undefined ? '' : ` (${broken.status})`;
+    return `${broken.collection}/${broken.entryId} [${broken.locale}] ${broken.at}\n    → ${target}${status} — ${REASON_TEXT[broken.reason]}`;
+}
+/**
+ * `cogenta links check` (L14 task 3).
+ *
+ * Exit codes are the ones a cron entry can act on: 0 nothing broken, 1 broken
+ * links were found or the site could not be read, 2 the command line was
+ * wrong. A non-zero exit for "found broken links" is deliberate — that is what
+ * makes this usable as a CI or scheduled check rather than something whose
+ * output somebody has to read.
+ */
+export async function runLinks(options) {
+    const { out, stderr } = options;
+    const env = options.env ?? process.env;
+    const logger = options.logger ?? createLogger({ level: 'silent' });
+    if (options.subcommand === undefined) {
+        stderr(`cogenta links needs a subcommand.\n\n${USAGE}`);
+        return 2;
+    }
+    if (options.subcommand !== 'check') {
+        stderr(`Unknown subcommand "${options.subcommand}". Only "check" exists today.\n\n${USAGE}`);
+        return 2;
+    }
+    const loaded = await loadConfig({
+        ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+        env,
+    });
+    const projectRoot = loaded.path === null ? resolvePath(options.cwd ?? process.cwd()) : dirname(loaded.path);
+    let selection = null;
+    try {
+        const collections = await loadCollections(projectRoot);
+        selection = await createDatabaseRegistry({ logger }).select(loaded.config.database);
+        const db = selection.instance;
+        await createSchemaTables(db, collections);
+        const stores = new Map();
+        const storeFor = (collection) => {
+            const existing = stores.get(collection.name);
+            if (existing !== undefined)
+                return existing;
+            const created = createContentStore({ db, collection });
+            stores.set(collection.name, created);
+            return created;
+        };
+        const report = await checkLinks({
+            collections,
+            storeFor,
+            locales: loaded.config.site.locales,
+            defaultLocale: loaded.config.site.defaultLocale,
+            ...(options.external === true ? { checkExternal: true } : {}),
+        });
+        if (report.broken.length === 0) {
+            out.ok(`Checked ${report.checkedLinks} link(s) across ${report.checkedEntries} published entries. Nothing broken.`);
+            if (report.skippedExternal > 0) {
+                out.detail(`${report.skippedExternal} external link(s) were not followed. Pass --external to check them.`);
+            }
+            return 0;
+        }
+        out.warn(`${report.broken.length} broken link(s) in ${report.checkedEntries} published entries:`);
+        for (const broken of report.broken)
+            out.detail(describe(broken));
+        if (report.skippedExternal > 0) {
+            out.detail(`${report.skippedExternal} external link(s) were not followed. Pass --external to check them.`);
+        }
+        return 1;
+    }
+    catch (error) {
+        if (isCogentaError(error)) {
+            stderr(`${error.code}: ${error.message}\n`);
+            if (error.hint !== undefined)
+                stderr(`${error.hint}\n`);
+        }
+        else {
+            stderr(`${error instanceof Error ? error.stack : String(error)}\n`);
+        }
+        return 1;
+    }
+    finally {
+        await selection?.instance.close();
+    }
+}
+//# sourceMappingURL=links.js.map

package/dist/commands/links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.js","sourceRoot":"","sources":["../../src/commands/links.ts"],"names":[],"mappings":"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"}

package/dist/commands/media-images.d.ts

@@ -0,0 +1,67 @@
+import type { ImageSize, MediaImageProcessor } from '@cogenta/api';
+import type { Logger } from '@cogenta/core';
+import { contentTypeOf, type ImageFormat, type ImageTransformer } from '@cogenta/render';
+/**
+ * `@cogenta/render`'s image pipeline, wired to the media upload (L10 task 5).
+ *
+ * The pipeline, `srcset.ts` and the two driver tiers (sharp, WASM libvips)
+ * have existed since L3 and were called by nothing. This module is where they
+ * meet a real upload.
+ *
+ * ## Why variants are produced at upload rather than on demand
+ *
+ * `createImagePipeline` is deliberately lazy — it renders a variant the first
+ * time a browser asks for one — and that is the right design for a build step
+ * that would otherwise materialise N formats × M widths × K images. It is the
+ * wrong design here, and the lot says so explicitly ("au moment de l'upload,
+ * pas à la volée"), for a reason worth writing down: `cogenta serve` has no
+ * durable variant cache. `createMemoryVariantStore` dies with the process, so
+ * a lazy pipeline behind it re-decodes every image after every restart, and
+ * on the shared hosting Cogenta targets (R10's own list) that is the slowest
+ * possible answer on the coldest possible machine.
+ *
+ * Producing a bounded, deterministic set once — the `SRCSET_WIDTHS` ladder,
+ * capped at the intrinsic width, in WebP — makes the set nameable, which is
+ * what lets `variantNames` clean them up on delete without a `list` call the
+ * `StorageDriver` interface does not have.
+ *
+ * ## Why WebP and not AVIF
+ *
+ * WebP is universally supported in 2026 and encodes in a fraction of AVIF's
+ * time. AVIF's extra compression is real, but paying it per upload on a
+ * WASM tier — the tier that always exists (R10) — would make an upload of a
+ * handful of images take minutes. A second format can be added the day the
+ * pipeline is asked for one, and the ladder is the only thing that has to
+ * change.
+ */
+declare const VARIANT_FORMAT: ImageFormat;
+/** The name of one rendition under an asset's variant prefix. */
+export declare function variantName(width: number, format?: ImageFormat): string;
+/**
+ * The widths actually produced for an image.
+ *
+ * `candidateWidths` caps the ladder at the intrinsic width, so a 500px logo
+ * yields 320 and 500 rather than five upscaled copies of itself — upscaling
+ * costs bytes and gains nothing.
+ */
+export declare function variantWidthsFor(intrinsic: ImageSize): readonly number[];
+export interface MediaImageProcessorOptions {
+    readonly transformer: ImageTransformer;
+    readonly quality?: number;
+}
+export declare function createMediaImageProcessor(options: MediaImageProcessorOptions): MediaImageProcessor;
+/**
+ * The processor for the driver this host can actually run, or `null`.
+ *
+ * `null` rather than a throw: an install where neither tier loads must still
+ * upload and serve images at their original size. That is the same "absent,
+ * not broken" degradation R2 applies to the LLM and R1 to every other driver
+ * — a CMS that refuses an upload because a WebAssembly module would not boot
+ * is worse than one that serves a full-size JPEG.
+ */
+export declare function selectMediaImageProcessor(logger: Logger): Promise<{
+    processor: MediaImageProcessor;
+    driver: string;
+} | null>;
+export { contentTypeOf, VARIANT_FORMAT };
+//# sourceMappingURL=media-images.d.ts.map

package/dist/commands/media-images.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-images.d.ts","sourceRoot":"","sources":["../../src/commands/media-images.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,mBAAmB,EAAwB,MAAM,cAAc,CAAA;AACxF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,EAEL,aAAa,EAGb,KAAK,WAAW,EAChB,KAAK,gBAAgB,EAItB,MAAM,iBAAiB,CAAA;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,QAAA,MAAM,cAAc,EAAE,WAAoB,CAAA;AAE1C,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,WAA4B,GAAG,MAAM,CAEvF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,MAAM,EAAE,CAExE;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAA;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,0BAA0B,GAClC,mBAAmB,CAsCrB;AAED;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,SAAS,EAAE,mBAAmB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAapE;AAED,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,CAAA"}

package/dist/commands/media-images.js

@@ -0,0 +1,107 @@
+import { candidateWidths, contentTypeOf, createImageRegistry, DEFAULT_QUALITY, planTransform, SRCSET_WIDTHS, suffixOf, } from '@cogenta/render';
+/**
+ * `@cogenta/render`'s image pipeline, wired to the media upload (L10 task 5).
+ *
+ * The pipeline, `srcset.ts` and the two driver tiers (sharp, WASM libvips)
+ * have existed since L3 and were called by nothing. This module is where they
+ * meet a real upload.
+ *
+ * ## Why variants are produced at upload rather than on demand
+ *
+ * `createImagePipeline` is deliberately lazy — it renders a variant the first
+ * time a browser asks for one — and that is the right design for a build step
+ * that would otherwise materialise N formats × M widths × K images. It is the
+ * wrong design here, and the lot says so explicitly ("au moment de l'upload,
+ * pas à la volée"), for a reason worth writing down: `cogenta serve` has no
+ * durable variant cache. `createMemoryVariantStore` dies with the process, so
+ * a lazy pipeline behind it re-decodes every image after every restart, and
+ * on the shared hosting Cogenta targets (R10's own list) that is the slowest
+ * possible answer on the coldest possible machine.
+ *
+ * Producing a bounded, deterministic set once — the `SRCSET_WIDTHS` ladder,
+ * capped at the intrinsic width, in WebP — makes the set nameable, which is
+ * what lets `variantNames` clean them up on delete without a `list` call the
+ * `StorageDriver` interface does not have.
+ *
+ * ## Why WebP and not AVIF
+ *
+ * WebP is universally supported in 2026 and encodes in a fraction of AVIF's
+ * time. AVIF's extra compression is real, but paying it per upload on a
+ * WASM tier — the tier that always exists (R10) — would make an upload of a
+ * handful of images take minutes. A second format can be added the day the
+ * pipeline is asked for one, and the ladder is the only thing that has to
+ * change.
+ */
+const VARIANT_FORMAT = 'webp';
+/** The name of one rendition under an asset's variant prefix. */
+export function variantName(width, format = VARIANT_FORMAT) {
+    return `${width}.${suffixOf(format)}`;
+}
+/**
+ * The widths actually produced for an image.
+ *
+ * `candidateWidths` caps the ladder at the intrinsic width, so a 500px logo
+ * yields 320 and 500 rather than five upscaled copies of itself — upscaling
+ * costs bytes and gains nothing.
+ */
+export function variantWidthsFor(intrinsic) {
+    return candidateWidths(intrinsic.width, intrinsic.width, SRCSET_WIDTHS);
+}
+export function createMediaImageProcessor(options) {
+    const { transformer } = options;
+    const quality = options.quality ?? DEFAULT_QUALITY;
+    return {
+        probe: async (bytes) => {
+            try {
+                const metadata = await transformer.metadata(bytes);
+                return { width: metadata.width, height: metadata.height };
+            }
+            catch {
+                // Not an image this tier can decode. The upload is still legitimate —
+                // `verifyRealType` already sniffed the container — so the honest
+                // answer is "no dimensions", not a refusal.
+                return null;
+            }
+        },
+        variants: async (bytes, intrinsic) => {
+            const metadata = await transformer.metadata(bytes);
+            const produced = [];
+            for (const width of variantWidthsFor(intrinsic)) {
+                const rendered = await transformer.transform(bytes, planTransform(metadata, { width, format: VARIANT_FORMAT, quality }));
+                produced.push({
+                    name: variantName(width, VARIANT_FORMAT),
+                    bytes: rendered.bytes,
+                    contentType: rendered.contentType,
+                });
+            }
+            return produced;
+        },
+        variantNames: (intrinsic) => variantWidthsFor(intrinsic).map((width) => variantName(width)),
+    };
+}
+/**
+ * The processor for the driver this host can actually run, or `null`.
+ *
+ * `null` rather than a throw: an install where neither tier loads must still
+ * upload and serve images at their original size. That is the same "absent,
+ * not broken" degradation R2 applies to the LLM and R1 to every other driver
+ * — a CMS that refuses an upload because a WebAssembly module would not boot
+ * is worse than one that serves a full-size JPEG.
+ */
+export async function selectMediaImageProcessor(logger) {
+    try {
+        const selection = await createImageRegistry({ logger }).select({});
+        return {
+            processor: createMediaImageProcessor({ transformer: selection.instance }),
+            driver: selection.driver,
+        };
+    }
+    catch (error) {
+        logger.warn('no image driver available; uploads will carry no variants', {
+            error: String(error),
+        });
+        return null;
+    }
+}
+export { contentTypeOf, VARIANT_FORMAT };
+//# sourceMappingURL=media-images.js.map

package/dist/commands/media-images.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-images.js","sourceRoot":"","sources":["../../src/commands/media-images.ts"],"names":[],"mappings":"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"}

package/dist/commands/search-page.d.ts

@@ -0,0 +1,40 @@
+import type { AccessContext, ContentGateway, SearchRouter } from '@cogenta/api';
+import { type CollectionDefinition } from '@cogenta/schema';
+/**
+ * `GET /search?q=…` — the public half of L10 task 3.
+ *
+ * The lot asks for "un bloc `search` optionnel côté thème public (formulaire
+ * + page de résultats)". The form and the results page are here; the **block**
+ * deliberately is not.
+ *
+ * Contract B is frozen (2026-08-13) and AGENTS.md forbids adding a block to
+ * the vocabulary without an RFC. A `search` block would be a contract B
+ * addition, so it would need a major version bump and a migration note — a
+ * decision that does not belong inside a lot whose whole premise is "no new
+ * capability, only wiring". A real route serving a real results page gives a
+ * visitor the same thing without touching the contract at all; when an RFC
+ * for a `search` block does happen, it can render through this same query.
+ *
+ * The page is `noindex`: a search results page is exactly the kind of thin,
+ * infinitely-many-URLs page a crawler must not index, and `buildMetaTags`
+ * takes `noindex` as an option precisely for it.
+ */
+export interface SearchPageOptions {
+    readonly router: SearchRouter;
+    readonly gateway: ContentGateway;
+    readonly collections: readonly CollectionDefinition[];
+    readonly site: {
+        readonly name: string;
+        readonly url: string;
+        readonly locales: readonly string[];
+        readonly defaultLocale: string;
+    };
+    /** The joined skin+theme stylesheet `cogenta serve` serves at `STYLESHEET_PATH` (`theme-render.ts`'s `joinStyles`). `null` when neither could be loaded — served unstyled rather than refused. */
+    readonly styles: string | null;
+}
+/**
+ * The whole page. Returns HTML; the caller decides the status code (always
+ * 200 — an empty result set is an answer, not a failure).
+ */
+export declare function renderSearchPage(query: string, options: SearchPageOptions, context: AccessContext): Promise<string>;
+//# sourceMappingURL=search-page.d.ts.map

package/dist/commands/search-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-page.d.ts","sourceRoot":"","sources":["../../src/commands/search-page.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC/E,OAAO,EAAa,KAAK,oBAAoB,EAAkB,MAAM,iBAAiB,CAAA;AAItF;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAChC,QAAQ,CAAC,WAAW,EAAE,SAAS,oBAAoB,EAAE,CAAA;IACrD,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;QACpB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;QACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;KAC/B,CAAA;IACD,kMAAkM;IAClM,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AA+ED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,CAAC,CAmDjB"}

package/dist/commands/search-page.js

@@ -0,0 +1,104 @@
+import { buildPath } from '@cogenta/schema';
+import { escapeHtmlAttribute, escapeHtmlText } from '@cogenta/seo';
+import { STYLESHEET_PATH } from './theme-render.js';
+/**
+ * Turns hits into links.
+ *
+ * The hit itself carries no URL — the index stores text, not routes — so each
+ * one is read back through the same permission-checked gateway that answered
+ * the search. An entry in a collection with no `routing`, or whose route
+ * parameters are incomplete, is listed without a link rather than with a URL
+ * that 404s.
+ */
+async function resolveHits(hits, options, context) {
+    const byName = new Map(options.collections.map((collection) => [collection.name, collection]));
+    const resolved = [];
+    for (const hit of hits) {
+        const collection = byName.get(hit.collection);
+        if (collection === undefined)
+            continue;
+        let href = null;
+        if (collection.routing !== undefined) {
+            const entry = await options.gateway.read(hit.collection, hit.id, context);
+            if (entry !== null) {
+                const params = Object.fromEntries(Object.entries(entry.values).filter((pair) => typeof pair[1] === 'string'));
+                const complete = collection.routing.pattern
+                    .split('/')
+                    .filter((segment) => segment.startsWith(':'))
+                    .every((segment) => params[segment.slice(1)] !== undefined || segment === ':id');
+                if (complete) {
+                    href = buildPath(collection, { ...params, id: entry.id }, collection.routing.locale === true ? entry.locale : undefined);
+                }
+            }
+        }
+        resolved.push({ title: hit.title.length > 0 ? hit.title : hit.id, href });
+    }
+    return resolved;
+}
+/** The form on its own, so an empty query still gets a usable page. */
+function searchForm(query) {
+    return `<form class="cg-search__form" action="/search" method="get" role="search">
+<label for="cg-search-q">Search</label>
+<input id="cg-search-q" type="search" name="q" value="${escapeHtmlAttribute(query)}" required>
+<button type="submit">Search</button>
+</form>`;
+}
+function resultList(results) {
+    if (results.length === 0)
+        return `<p class="cg-search__empty">Nothing matched that search.</p>`;
+    return `<ol class="cg-search__results">
+${results
+        .map((result) => result.href === null
+        ? `<li>${escapeHtmlText(result.title)}</li>`
+        : `<li><a href="${escapeHtmlAttribute(result.href)}">${escapeHtmlText(result.title)}</a></li>`)
+        .join('\n')}
+</ol>`;
+}
+/**
+ * The whole page. Returns HTML; the caller decides the status code (always
+ * 200 — an empty result set is an answer, not a failure).
+ */
+export async function renderSearchPage(query, options, context) {
+    const trimmed = query.trim();
+    let results = [];
+    let failure = null;
+    if (trimmed.length > 0) {
+        const response = await options.router.handle({ method: 'GET', path: '/api/search', query: { q: trimmed } }, context);
+        if (response.status === 200) {
+            const body = response.body;
+            results = await resolveHits(body.data, options, context);
+        }
+        else {
+            // The router's own message, never a rewritten one: it already says what
+            // failed and what to do about it, and inventing a second wording here
+            // is how the two drift apart.
+            const body = response.body;
+            failure = body.error?.message ?? 'The search could not be completed.';
+        }
+    }
+    const heading = trimmed.length === 0 ? 'Search' : `Search results for “${escapeHtmlText(trimmed)}”`;
+    const main = failure !== null
+        ? `<p class="cg-search__error" role="alert">${escapeHtmlText(failure)}</p>`
+        : trimmed.length === 0
+            ? ''
+            : resultList(results);
+    return `<!doctype html>
+<html lang="${escapeHtmlAttribute(options.site.defaultLocale)}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${heading} — ${escapeHtmlText(options.site.name)}</title>
+<meta name="robots" content="noindex, follow" />
+${options.styles === null ? '' : `<link rel="stylesheet" href="${STYLESHEET_PATH}">`}
+</head>
+<body>
+<main class="cg-main" id="cg-main">
+<h1 class="cg-page__title">${heading}</h1>
+${searchForm(trimmed)}
+${main}
+</main>
+</body>
+</html>
+`;
+}
+//# sourceMappingURL=search-page.js.map