@o-a/cms-agent 0.2.2 → 0.3.0

package/dist/create-site/generate-site.js

@@ -86,6 +86,13 @@ export function scaffoldSite(targetDir) {
     // could lose or that leaks into version control.
     const token = generateToken();
     writeFileSync(join(vhostDir, 'site.config.json'), JSON.stringify({
+        // Written explicitly, matching server-config.ts's own
+        // DEFAULT_PORT, rather than left absent - a real value here
+        // is a visible, editable config knob; an absent key is
+        // invisible until something else is already using the
+        // default port, at which point the failure is a raw
+        // EADDRINUSE crash instead of an obvious setting to change.
+        port: 3000,
         tokens: [{ hash: token.hash, scopes: ['content', 'theme', 'media'] }],
     }, null, 2));
     const packageName = sanitisePackageName(basename(targetDir));
@@ -100,9 +107,23 @@ export function scaffoldSite(targetDir) {
         // straight to one of those (no Dockerfile in the loop) simply
         // wouldn't boot. "tunnel" mirrors the --tunnel flag create-site
         // already tells the operator about in its own next-steps output.
+        // "dev" is Node's own --watch-path, not custom fs-watching code
+        // - confirmed empirically that it both picks up changes to a
+        // plain file under a watched directory that's never imported
+        // (theme/*.liquid is only ever read via readFileSync) and sends
+        // a real SIGTERM on restart, which server.js's own shutdown
+        // handling already listens for. "../theme" because npm run dev
+        // runs with cwd vhost/, a sibling of theme/. Deliberately not
+        // content/ - that's already read fresh on every request, so
+        // watching it would only cause pointless restarts on every
+        // content edit. "check" is check-site, the package's own
+        // installed CLI bin - runs from vhost/ (site-check/cli.ts's own
+        // assumed cwd relationship), same pattern as start/tunnel/dev.
         scripts: {
             start: 'node server.js',
             tunnel: 'node server.js --tunnel',
+            dev: 'node --watch-path=../theme server.js',
+            check: 'check-site',
         },
         dependencies: {
             // Pinned exact, never a ^range - at v0.x even a minor bump

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

@@ -33,9 +33,12 @@ This scaffold already ships real, working examples worth reading before writing
 ## Turning a design into code - the actual workflow
 
 1. Break the design into distinct repeating/reusable visual components. Each one becomes a `theme/sections/<name>.liquid` (a self-contained region of a page) or `theme/blocks/<name>.liquid` (a smaller item nested inside a section, e.g. one card in a grid, one FAQ row).
-2. Each file has two parts: ordinary Liquid/HTML markup, and a `{% schema %} ... {% endschema %}` block containing a single JSON object - a plain [JSON Schema draft-07](https://json-schema.org/draft-07) description of that component's `settings`. The schema block is stripped out before rendering, so a real Liquid tag never sees it - place it anywhere in the file (convention: at the end).
+2. Each file has two parts: ordinary Liquid/HTML markup, and a `{% schema %} ... {% endschema %}` block containing a single JSON object - a settings description using *only* the JSON Schema draft-07 keywords listed below, never the full spec. The schema block is stripped out before rendering, so a real Liquid tag never sees it - place it anywhere in the file (convention: at the end).
+
+**Only these keywords are supported**: `type`, `properties`, `required`, `additionalProperties`, `default`, `minLength`, `maxLength`, `minimum`, `maximum`, `pattern`, `enum`, `items`, `minItems`, `maxItems`, plus the custom `format`/`title`/`description`/`allowedBlocks`/`api`/`swatches`/`step`/`unit` keywords documented below. **Never `$ref`, `$defs`, `definitions`, `allOf`, `anyOf`, `oneOf`, `not`, or `if`/`then`/`else`** - every property's schema must be fully self-contained, written out in full where it's used. If the same shape (e.g. an image object) repeats across several properties or several component files, write it out each time rather than trying to share/reference a definition - there is no cross-referencing mechanism here, in a single schema block or across files, regardless of what standard JSON Schema itself supports elsewhere.
 3. Once the theme components exist, compose an actual page by writing a file under `content/pages/` whose `sections` array references those types by filename, with a `settings` object matching each one's schema (see "Content JSON model" below).
-4. Preview the result before considering the task done - see "Previewing your work".
+4. **For any page type the site will have more than one of** - a project, an article, a case study, a team member - also write a starting point for it under `theme/templates/<name>.json`. This is easy to skip and worth not skipping: without a template, every new page an editor creates starts completely blank, and they have to rebuild the same section stack by hand every time. A template is just a real page file kept in a different folder - the same shape as anything under `content/pages/` (`schemaVersion`, `name`, `title`, `type`, `layout`, `published`, `sections`), validated identically, using the section types this theme already defines. Its `"title"` is the label an editor picks from, so name it for the page type (`"Project"`, `"Article"`), never `"Untitled"`. Fill each section's settings with short placeholder copy rather than leaving them empty - a template is a starting point to edit, not a blank form. A template that fails validation is skipped silently at boot, so preview a page built from it.
+5. Preview the result before considering the task done - see "Previewing your work".
 
 ### Worked example - a section
 
@@ -64,6 +67,23 @@ Available variables in a section: `section.id`, `section.settings.<key>`, `block
 
 To restrict which block types are allowed under a given section/block, add `"allowedBlocks": ["button", "logo-mark"]` alongside `"properties"` in its schema - omit it entirely for no restriction (the default).
 
+### Naming a section or block for the admin
+
+Give every section and block a `"title"` and a `"description"`, as plain annotations on the schema object alongside `"properties"`:
+
+```json
+{
+  "title": "Image band",
+  "description": "A full width photograph with an optional caption.",
+  "type": "object",
+  "properties": { }
+}
+```
+
+Neither affects validation. The admin's "Add a Section" dialog lists one row per type showing the title with the description beside it, so a type with no description shows a bare name and an editor has to guess what it is for. Omit the `"title"` and the type's filename is shown instead (`image-band`), which reads as code, not as a choice.
+
+Write the description as one short sentence about what the section **is**, not which fields it has - the fields are already visible the moment the section is added. "A full width photograph with an optional caption" is useful; "Heading, image and caption fields" is not.
+
 ### Layouts
 
 `theme/layouts/theme.liquid` is required - every theme must define a layout named exactly `theme` as the default (a page can opt into a different one via its own `"layout"` field). A layout only ever sees:
@@ -97,9 +117,136 @@ Every setting is plain JSON Schema (`string`, `integer`, `number`, `boolean`, `a
 | `toggle` | `boolean` | Switch instead of a checkbox (same underlying data) |
 | (none) | `boolean` | Plain checkbox |
 | (none) | `string` + `"enum"` | Segmented tabs (few short options) or a `<select>` (more/longer) - decided automatically, not choosable |
+| (none) | `array` + `items.type: "string"` | Repeatable list of text lines, with add/remove/drag-to-reorder - `minItems`/`maxItems` bound how many lines the admin UI allows; `items.minLength`/`items.maxLength` apply per line |
+| (none) | `array` + `items.type: "object", items.format: "image"` | A gallery: a grid of image thumbnails, add via the media picker, remove/drag-to-reorder - `minItems`/`maxItems` bound how many images the admin UI allows. Each item is exactly `{ "url": "...", "focalX": 0.5, "focalY": 0.5 }`, the same shape a lone `format: "image"` field stores - **no other properties are supported on a gallery item** (see "This is a closed set" below) |
 
 A `format` on the wrong `type` (e.g. `image` on a `string`) is a mistake, not something the admin guesses around - it silently falls back to a plain widget for that type.
 
+### Minimal form - prefer this
+
+Every type/format combination above needs nothing beyond what triggers it - no `additionalProperties`, no `required`, no `default`, no nested `properties` describing an object's own shape. None of that is what makes the admin recognise a field; it only matters if you actually need the stricter validation or a guaranteed starting value (see below). Default to the minimal form:
+
+```json
+"heading": {
+  "type": "string"
+}
+
+"columns": {
+  "type": "integer"
+}
+
+"enabled": {
+  "type": "boolean"
+}
+
+"enabled": {
+  "type": "boolean",
+  "format": "toggle"
+}
+
+"bio": {
+  "type": "string",
+  "format": "textarea"
+}
+
+"body": {
+  "type": "string",
+  "format": "richtext"
+}
+
+"link": {
+  "type": "string",
+  "format": "uri"
+}
+
+"publishDate": {
+  "type": "string",
+  "format": "date"
+}
+
+"accent": {
+  "type": "string",
+  "format": "color"
+}
+
+"align": {
+  "type": "string",
+  "enum": ["left", "center", "right"]
+}
+
+"fontSize": {
+  "type": "integer",
+  "format": "range",
+  "minimum": 12,
+  "maximum": 24
+}
+
+"poster": {
+  "type": "object",
+  "format": "image"
+}
+
+"tags": {
+  "type": "array",
+  "items": { "type": "string" }
+}
+
+"gallery": {
+  "type": "array",
+  "items": { "type": "object", "format": "image" }
+}
+```
+
+`fontSize`'s `minimum`/`maximum` are the one exception - they're not optional boilerplate, the `range` widget genuinely doesn't trigger without both.
+
+A custom display label uses the standard JSON Schema `"title"` keyword (`"title": "Section Heading"`) - skip it and the property key auto-humanizes instead (`backgroundImage` -> "Background Image"), which is why none of the examples above bother with one.
+
+Only reach for `"required"` + `"default"` (and, for stricter content validation, `"additionalProperties": false` on an object/`minLength`/`pattern`/etc.) when a field genuinely must always have a value from the moment a component is added - skip both and it just starts empty/unset, which is a valid state for every type above. See "Worked example - a section" above for what that fuller form looks like once it's actually needed, and remember the L1 rule if you do use it: a required field's `default` is validated against that field's *own* full schema, including `minItems`/`minLength`/etc. - `"default": []` against `"minItems": 1` fails just as surely as an empty string against `"minLength": 1` does.
+
+### This is a closed set - do not invent a new field shape
+
+**The table above is exhaustive.** These are the only setting shapes the admin has a real editor for. A setting whose shape doesn't match one of these rows exactly still technically works - Ajv validates it, the content saves - but the admin can only offer a raw JSON textarea for it, which is a bad editing experience for a human, not a fallback to design around. Never invent a new combination of `type`/`format`/`items` hoping the admin will render something sensible for it; if a design need doesn't map onto one of these rows, use the pattern below instead of a wider array shape.
+
+**A repeating item with more than one independent field is a block, never an array-shaped setting.** For example, a "before/after" or "lightbox" style section needing several frames, each with its own image *and* a caption *and* a timestamp, is not `"type": "array", "items": { "type": "object", "properties": { "image": ..., "caption": ..., "time": ... } } }` - that shape has no admin widget and never will (it's an open-ended amount of nested field types, not a closed set like the table above). Model it as a block type instead:
+
+```liquid
+{# theme/blocks/frame.liquid #}
+<figure class="lightstudy__frame">
+  <img src="{{ block.settings.image.url }}" alt="{{ block.settings.caption }}">
+  <figcaption><span class="numeral">{{ block.settings.time }}</span> {{ block.settings.caption }}</figcaption>
+</figure>
+{% schema %}
+{
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["image", "caption", "time"],
+  "properties": {
+    "image": { "type": "object", "format": "image", "default": { "url": "", "focalX": 0.5, "focalY": 0.5 } },
+    "caption": { "type": "string", "minLength": 1, "default": "The room in a particular light" },
+    "time": { "type": "string", "minLength": 1, "default": "12:00" }
+  }
+}
+{% endschema %}
+```
+
+Then the parent section just loops `blocksHtml`, exactly as it already does for any other block type - see "Section markup" above. This gets real add/remove/drag-to-reorder and a proper per-field settings form (image picker, text inputs) for every one of `image`/`caption`/`time` independently, for free - a single array setting never gets that, no matter how its `items` schema is shaped.
+
+A multi-line field (e.g. an animated headline, one line per array entry) uses the array shape above rather than a single `format: "textarea"` string - each line is edited and reordered independently:
+
+```json
+{
+  "type": "array",
+  "minItems": 1,
+  "maxItems": 4,
+  "items": { "type": "string", "minLength": 1 },
+  "default": ["New section"]
+}
+```
+
+```liquid
+{% for line in section.settings.heading %}<span>{{ line }}</span>{% endfor %}
+```
+
 A separate keyword, `"api": true`, can be added to any scalar property to expose its value through `GET /search.json` for structured filtering, independent of full-text search - see that section below.
 
 ## Content JSON model
@@ -169,6 +316,22 @@ Uploads go through `POST /v1/media` (multipart, requires a token with `media` sc
 
 unless the design needs a focal point for a cropped image, in which case use `"format": "image"` (see the table above) instead of a plain string.
 
+If you're writing starter content before a server is even running - so `POST /v1/media` isn't reachable yet - use the `seed-media` CLI instead of placing images under `theme/root/`. It computes the exact same content-addressed filename a real upload would, so the result is indistinguishable from one:
+
+```
+npx seed-media <site-directory> photo.jpg another.png
+# photo.jpg -> /media/photo-3f9a2b7c1e04.jpg
+# another.png -> /media/another-91cd4a08f2b1.png
+```
+
+Then use the printed URL exactly like a real upload's:
+
+```json
+{ "type": "string", "default": "/media/photo-3f9a2b7c1e04.jpg" }
+```
+
+This is only for seeding starter content offline - once a server is running, a later image change from an editor still goes through `POST /v1/media` or the admin's media library as normal.
+
 ## `GET /search.json`
 
 A public, unauthenticated, read-only endpoint - safe to call directly from a section's own client-side JavaScript with a plain `fetch()`, no token needed. Only ever returns already-published content. Query params: `q` (full-text), `filter=field:op:value` (repeatable, ANDed; `op` is `eq`/`gt`/`gte`/`lt`/`lte`), `pageType`, `sort` (`-publishDate` for newest-first), `limit`, `offset`. Useful for a blog listing, a filterable directory, or a live search box.
@@ -183,6 +346,7 @@ The index behind this endpoint keeps itself current automatically - it rebuilds
 - **One file, one type, no subfolders** inside `layouts/`, `sections/`, `blocks/`, `snippets/` - and the filename must match `^[a-z0-9][a-z0-9-]*$` exactly.
 - **The `{% schema %}` block must be valid, parseable JSON.** A malformed or missing schema fails the whole component, not just the settings half.
 - **`additionalProperties: false` applies everywhere in content JSON** - don't add a field "just in case"; anything not in the tables above fails validation.
+- **Never invent a new setting field shape.** The "Field format hints" table is the complete, closed list of what the admin can actually edit - a plain type, a type plus one of the listed `format` values, `array` of plain strings, or `array` of plain images. A repeating item with more than one field of its own (an image plus a caption, a date, anything else) is a block type, not a wider array setting - see "This is a closed set" above.
 
 ## Previewing your work
 
@@ -191,6 +355,21 @@ From `vhost/`:
 ```
 npm start          # boots the site on the port set in vhost/site.config.json
 npm run tunnel      # same, plus a public tunnel URL for sharing a preview
+npm run dev         # same, plus auto-restart whenever a theme/ file changes - use this one while iterating
 ```
 
+`npm run dev` only watches `theme/` - content changes (via the API) already show up on the next request with no restart needed, so there's nothing to gain watching `content/` too.
+
 Then request the page you changed (`curl http://localhost:<port>/<path>`, or open it in a browser) and confirm it actually renders as expected before considering a change finished - a page that fails schema validation or references a non-existent section type won't crash the server, but the specific page/component involved will misbehave silently.
+
+## Checking your work: `npm run check`
+
+From `vhost/`, with the site's dependencies already installed (no need for the server to be running):
+
+```
+npm run check
+```
+
+Renders every published page for real and reports, in one pass: any theme component excluded at boot (same warnings the server itself prints, see "Minimal form" above); any `<img src>`/`srcset`/`<a href>` in the rendered HTML pointing at a `/media/`, `/assets/`, or root-static file that doesn't actually exist on disk; and any internal link that doesn't point at a real, published page. Exits non-zero if it finds anything - safe to run after generating content, not just as a manual spot-check.
+
+This catches the specific failure mode a snippet like `responsive-image` can introduce silently: a `widths` list that includes a size nothing was actually uploaded/generated for renders a perfectly normal-looking page with one broken image at that breakpoint - nothing about the page itself is wrong, so nothing else would ever flag it.

package/dist/create-site/template/content/menus/footerCompany.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 6,
   "items": [
     { "label": "About", "url": "/about" },
     { "label": "Careers", "url": "/careers" },

package/dist/create-site/template/content/menus/footerProduct.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 6,
   "items": [
     { "label": "Features", "url": "#features" },
     { "label": "Pricing", "url": "#pricing" },

package/dist/create-site/template/content/menus/footerResources.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 6,
   "items": [
     { "label": "Documentation", "url": "/docs" },
     { "label": "Theme authoring guide", "url": "/docs/themes" },

package/dist/create-site/template/content/menus/main.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 1,
+  "schemaVersion": 6,
   "items": [
     { "label": "Features", "url": "#features" },
     { "label": "How it works", "url": "#how-it-works" },

package/dist/create-site/template/content/pages/404.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 4,
+  "schemaVersion": 6,
   "title": "Page not found — Granite CMS",
   "type": "page",
   "layout": "theme",

package/dist/create-site/template/content/pages/about/careers.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 4,
+  "schemaVersion": 6,
   "title": "Careers — Granite CMS",
   "type": "page",
   "layout": "theme",

package/dist/create-site/template/content/pages/about/team.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 4,
+  "schemaVersion": 6,
   "title": "Team — Granite CMS",
   "type": "page",
   "layout": "theme",

package/dist/create-site/template/content/pages/about.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 4,
+  "schemaVersion": 6,
   "title": "About — Granite CMS",
   "type": "page",
   "layout": "theme",

package/dist/create-site/template/content/pages/docs/deployment.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 4,
+  "schemaVersion": 6,
   "title": "Deployment — Granite CMS",
   "type": "page",
   "layout": "theme",

package/dist/create-site/template/content/pages/docs/getting-started/quickstart.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 4,
+  "schemaVersion": 6,
   "title": "Quickstart — Granite CMS",
   "type": "page",
   "layout": "theme",

package/dist/create-site/template/content/pages/docs/getting-started.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 4,
+  "schemaVersion": 6,
   "title": "Getting Started — Granite CMS",
   "type": "page",
   "layout": "theme",

package/dist/create-site/template/content/pages/docs.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 4,
+  "schemaVersion": 6,
   "title": "Docs — Granite CMS",
   "type": "page",
   "layout": "theme",

package/dist/create-site/template/content/pages/index.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 4,
+  "schemaVersion": 6,
   "title": "Granite CMS — Solid foundations for client sites",
   "type": "page",
   "layout": "theme",

package/dist/media/filename.d.ts

@@ -1 +1,2 @@
+export declare const ALLOWED_UPLOAD_EXTENSIONS: Set<string>;
 export declare function buildMediaFilename(originalFilename: string, bytes: Buffer): string;

package/dist/media/filename.js

@@ -21,6 +21,19 @@ import { basename, extname } from 'node:path';
 // lowercase, non [a-z0-9-] runs collapsed to a single "-", trimmed -
 // not a second, independently-invented convention.
 const HASH_LENGTH = 12;
+// Images only - confirmed with the user, not a general document
+// library. .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 (a real stored-XSS path
+// otherwise: mime-types.ts maps .svg to a real image/svg+xml content
+// type, and an SVG loaded as a top-level navigation, not just <img>-
+// embedded, can execute a script it carries).
+//
+// Exported from here, not left as routes/media.ts's own private
+// constant, specifically so seed-media.ts (an offline tool with no
+// HTTP request to validate) enforces the exact same rule rather than
+// a second, independently-maintained copy of it.
+export const ALLOWED_UPLOAD_EXTENSIONS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp']);
 export function buildMediaFilename(originalFilename, bytes) {
     const hash = createHash('sha256').update(bytes).digest('hex').slice(0, HASH_LENGTH);
     const base = basename(originalFilename, extname(originalFilename));

package/dist/media/seed-media-cli.d.ts

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

package/dist/media/seed-media-cli.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { seedMedia } from "./seed-media.js";
+const [targetArg, ...sourceArgs] = process.argv.slice(2);
+if (!targetArg || sourceArgs.length === 0) {
+    console.error('Usage: seed-media <site-directory> <path> [<path> ...]');
+    process.exit(1);
+}
+const siteDir = resolve(process.cwd(), targetArg);
+const sourcePaths = sourceArgs.map((sourceArg) => resolve(process.cwd(), sourceArg));
+const result = seedMedia(siteDir, sourcePaths);
+for (const entry of result.entries) {
+    if (entry.status === 'seeded') {
+        console.log(`${entry.sourcePath} -> ${entry.url}`);
+    }
+    else {
+        console.log(`${entry.sourcePath}: skipped (${entry.reason})`);
+    }
+}
+if (!result.ok) {
+    process.exit(1);
+}

package/dist/media/seed-media.d.ts

@@ -0,0 +1,11 @@
+export interface SeedMediaEntry {
+    sourcePath: string;
+    status: 'seeded' | 'skipped-invalid-type';
+    url?: string;
+    reason?: string;
+}
+export interface SeedMediaResult {
+    ok: boolean;
+    entries: SeedMediaEntry[];
+}
+export declare function seedMedia(siteRoot: string, sourcePaths: string[]): SeedMediaResult;

package/dist/media/seed-media.js

@@ -0,0 +1,76 @@
+import { mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+import { ALLOWED_UPLOAD_EXTENSIONS, buildMediaFilename } from "./filename.js";
+// A directory argument expands to its own direct child files only -
+// one level, not recursive, matching theme-schemas.ts's own flat-
+// directory convention for exactly the same reason (a predictable,
+// easy-to-reason-about walk, not a surprise deep scan).
+function expandSourcePaths(sourcePaths) {
+    const files = [];
+    for (const sourcePath of sourcePaths) {
+        if (statSync(sourcePath).isDirectory()) {
+            for (const entry of readdirSync(sourcePath, { withFileTypes: true })) {
+                if (entry.isFile()) {
+                    files.push(join(sourcePath, entry.name));
+                }
+            }
+        }
+        else {
+            files.push(sourcePath);
+        }
+    }
+    return files;
+}
+// Seeds one or more local image files directly into a site's media/,
+// computing the exact same content-addressed filename a real
+// POST /v1/media upload would - see this module's own filename.ts for
+// why that's safe to do offline (a pure function of a filename and the
+// file's own bytes, no server/database involved). For an AI agent (or
+// any offline tool) generating a site's starter content before a
+// server is even running - GET /media/* just serves whatever file
+// exists at the requested path, so the result is indistinguishable
+// from a real upload.
+//
+// siteRoot is an operator/agent-supplied directory, the same category
+// as scaffoldSite/mintToken - not a web request's own :path, so
+// sanitisePath's traversal concern doesn't apply here (see
+// mint-token.ts's own comment on this exact point).
+//
+// Never a git commit - media is never git-tracked (constraint 2,
+// matching manage-media.ts's own "no commit, no author... Media is
+// never git-tracked" comment).
+//
+// A disallowed file type is skipped, not a reason to abort the whole
+// batch - an agent seeding a dozen images should still get the eleven
+// good ones, with the one bad one clearly reported. The allowlist
+// itself is the one thing that must not be relaxed here: it's the
+// same rule the real upload route enforces (ALLOWED_UPLOAD_EXTENSIONS,
+// shared, not a second copy), because skipping it would reopen the
+// real stored-XSS path SVG rejection exists to close, for whoever
+// later visits the live site - not a concern about this tool's own
+// caller, who already has full local trust.
+export function seedMedia(siteRoot, sourcePaths) {
+    const mediaRoot = join(siteRoot, 'media');
+    mkdirSync(mediaRoot, { recursive: true });
+    const entries = [];
+    for (const sourcePath of expandSourcePaths(sourcePaths)) {
+        const extension = extname(sourcePath).toLowerCase();
+        if (!ALLOWED_UPLOAD_EXTENSIONS.has(extension)) {
+            entries.push({
+                sourcePath,
+                status: 'skipped-invalid-type',
+                reason: `"${extension}" is not an accepted image type`,
+            });
+            continue;
+        }
+        const bytes = readFileSync(sourcePath);
+        const name = buildMediaFilename(basename(sourcePath), bytes);
+        // No existence check first: content-addressed naming means
+        // re-seeding the same bytes writes identical bytes over identical
+        // bytes - a harmless idempotent overwrite, matching
+        // local-fs-driver.ts's own put() precedent exactly.
+        writeFileSync(join(mediaRoot, name), bytes);
+        entries.push({ sourcePath, status: 'seeded', url: `/media/${name}` });
+    }
+    return { ok: entries.every((entry) => entry.status === 'seeded'), entries };
+}

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/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

@@ -241,6 +241,53 @@ 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) {
     const result = enqueue(() => publishDraftsJob(config, themeSchemas, relativePaths, message, author));
     // Only on success - a failed publish changed nothing, so there's
@@ -257,3 +304,10 @@ export function unpublishPage(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/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>;

package/dist/site-check/run-check.js

@@ -0,0 +1,109 @@
+import { existsSync } from 'node:fs';
+import { bootSite } from "../boot.js";
+import { renderPage } from "../renderer/render-page.js";
+import { PathSafetyError, sanitisePath } from "../services/path-safety.js";
+import { buildSitemapUrls } from "../routes/sitemap.js";
+import { urlToPagePath } from "../services/urls.js";
+// A reference this project's own theme conventions actually produce:
+// src="...", srcset="w1 480w, w2 960w" (comma-separated, each entry a
+// url then a space then a width descriptor - strip the descriptor),
+// href="...". Not a full HTML parser - matching SchemaField.tsx's own
+// "the schema surface here is narrow and flat... a library would be
+// heavier than the problem warrants" precedent for the equivalent
+// choice on the admin side.
+const ATTR_PATTERN = /\b(?:src|href)="([^"]*)"|\bsrcset="([^"]*)"/g;
+function extractReferences(html) {
+    const refs = [];
+    for (const match of html.matchAll(ATTR_PATTERN)) {
+        const [, single, srcset] = match;
+        if (single !== undefined) {
+            refs.push(single);
+        }
+        else if (srcset !== undefined) {
+            for (const entry of srcset.split(',')) {
+                const url = entry.trim().split(/\s+/)[0];
+                if (url) {
+                    refs.push(url);
+                }
+            }
+        }
+    }
+    return refs;
+}
+// True for a root-relative static path that looks like a real file
+// (has a "." in its last path segment - /favicon.ico, /robots.txt),
+// as opposed to a page URL like /about or /blog/hello-world, which
+// never do. Doesn't need to be perfect - a page URL with a literal dot
+// in its own slug is vanishingly unlikely and, worst case, just gets
+// checked against the wrong bucket and reported as the wrong kind of
+// finding, never silently skipped.
+function looksLikeStaticFile(path) {
+    const lastSegment = path.split('/').pop() ?? '';
+    return lastSegment.includes('.');
+}
+// A rendered reference is theme/content-derived, not a live HTTP
+// request's own :path - but the same traversal concern still applies
+// (constraint 7), so it still goes through sanitisePath rather than a
+// bare join+existsSync. A reference that fails to sanitise (a "../"
+// escaping root) is exactly as real a finding as one that's simply
+// missing - reported the same way, not silently skipped.
+function checkStaticReference(findings, root, relativePath, originalPath, rootLabel, pageUrl) {
+    try {
+        const filePath = sanitisePath(root, relativePath);
+        if (!existsSync(filePath)) {
+            findings.push({ kind: 'missing-asset', message: `${originalPath} does not exist under ${rootLabel}`, pageUrl });
+        }
+    }
+    catch (error) {
+        if (error instanceof PathSafetyError) {
+            findings.push({ kind: 'missing-asset', message: `${originalPath} is not a safe reference under ${rootLabel} (${error.message})`, pageUrl });
+            return;
+        }
+        throw error;
+    }
+}
+export async function runSiteCheck(siteRoot) {
+    const booted = bootSite(siteRoot);
+    const findings = [];
+    for (const warning of booted.themeSchemas.warnings ?? []) {
+        findings.push({ kind: 'schema', message: warning });
+    }
+    const publishedUrls = buildSitemapUrls(booted.config);
+    const publishedUrlSet = new Set(publishedUrls);
+    for (const pageUrl of publishedUrls) {
+        // urlToPagePath's own result is relative to pagesRoot (e.g.
+        // "about.json"), but renderPage's own relativePath is relative to
+        // contentRoot - the same "pages/" prefix routes/public.ts's own
+        // toRenderPath helper adds before every one of its renderPage
+        // calls.
+        const relativePath = `pages/${urlToPagePath(pageUrl)}`;
+        let html;
+        try {
+            html = await renderPage(booted.config, booted.themeTemplates, booted.layouts, booted.engine, relativePath, 'public');
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            findings.push({ kind: 'render-error', message: detail, pageUrl });
+            continue;
+        }
+        for (const ref of extractReferences(html)) {
+            if (ref.startsWith('http://') || ref.startsWith('https://') || ref.startsWith('data:') || ref.startsWith('//')) {
+                continue;
+            }
+            const path = ref.split(/[?#]/)[0] ?? ref;
+            if (path.startsWith('/media/')) {
+                checkStaticReference(findings, booted.config.mediaRoot, path.slice('/media/'.length), path, 'media/', pageUrl);
+            }
+            else if (path.startsWith('/assets/')) {
+                checkStaticReference(findings, booted.config.assetsRoot, path.slice('/assets/'.length), path, 'theme/assets/', pageUrl);
+            }
+            else if (looksLikeStaticFile(path)) {
+                checkStaticReference(findings, booted.config.rootMirrorRoot, path.slice(1), path, 'theme/root/', pageUrl);
+            }
+            else if (path !== '' && !publishedUrlSet.has(path)) {
+                findings.push({ kind: 'broken-link', message: `${path} does not point at a published page`, pageUrl });
+            }
+        }
+    }
+    return { ok: findings.length === 0, findings };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o-a/cms-agent",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -23,7 +23,9 @@
   },
   "bin": {
     "create-site": "dist/create-site/cli.js",
-    "mint-token": "dist/create-site/mint-token-cli.js"
+    "mint-token": "dist/create-site/mint-token-cli.js",
+    "check-site": "dist/site-check/cli.js",
+    "seed-media": "dist/media/seed-media-cli.js"
   },
   "files": [
     "dist"
@@ -35,7 +37,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "lint": "eslint .",
     "test": "node --experimental-strip-types --test",
-    "test:packaging": "node --experimental-strip-types --test e2e/create-site-packaging.check.ts",
+    "test:packaging": "node --experimental-strip-types --test --test-concurrency=1 e2e/create-site-packaging.check.ts e2e/dev-watch.check.ts",
     "build": "tsc -p tsconfig.build.json && rm -rf dist/schemas dist/create-site/template && cp -r src/schemas/. dist/schemas/ && cp -r src/create-site/template/. dist/create-site/template/",
     "prepack": "npm run build"
   },

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

@@ -1,5 +0,0 @@
-export interface SearchResult {
-    url: string;
-    title: string;
-}
-export declare function queryIndex(searchIndexPath: string, term: string): SearchResult[];

package/dist/search/query-index.js

@@ -1,21 +0,0 @@
-import { openNodeSqliteDriver } from "./drivers/node-sqlite-driver.js";
-// Never queued: an in-flight query holding an open handle during a
-// concurrent rebuild's unlink just keeps reading the pre-rebuild inode
-// (stale but consistent, never torn) - queuing a read against the same
-// queue as writes would only add latency for no correctness benefit.
-export function queryIndex(searchIndexPath, term) {
-    const driver = openNodeSqliteDriver(searchIndexPath);
-    try {
-        const rows = driver.prepare('SELECT url, title FROM pages_fts WHERE pages_fts MATCH ?').all(term);
-        // node:sqlite returns rows as [Object: null prototype] instances;
-        // rebuilt here as plain objects so callers (and assert.deepEqual)
-        // never have to know that's a driver implementation detail.
-        return rows.map((row) => {
-            const { url, title } = row;
-            return { url, title };
-        });
-    }
-    finally {
-        driver.close();
-    }
-}

package/dist/services/post-urls.d.ts

@@ -1,3 +0,0 @@
-export declare function isBlogUrl(url: string): boolean;
-export declare function urlToPostPath(url: string): string | null;
-export declare function postPathToUrl(relativePostPath: string): string;

package/dist/services/post-urls.js

@@ -1,27 +0,0 @@
-// Pure, filesystem-free mapping between a /blog/<slug> URL and a
-// post's path relative to postsRoot. Unlike pages' arbitrary nested
-// paths (about.json beside a sibling about/ directory), posts are
-// flat only - a URL with more than one segment after /blog/ is never
-// a valid post URL, enforced here rather than left to sanitisePath.
-const BLOG_PREFIX = '/blog/';
-// /blog is a permanently reserved namespace: both "/blog" itself (no
-// slug) and every "/blog/..." URL are recognised here, so a caller can
-// route the whole namespace to post resolution before ever checking
-// for a page, matching the confirmed reserved-namespace decision.
-export function isBlogUrl(url) {
-    return url === '/blog' || url.startsWith(BLOG_PREFIX);
-}
-export function urlToPostPath(url) {
-    if (!url.startsWith(BLOG_PREFIX)) {
-        return null;
-    }
-    const slug = url.slice(BLOG_PREFIX.length);
-    if (slug === '' || slug.includes('/')) {
-        return null;
-    }
-    return `${slug}.json`;
-}
-export function postPathToUrl(relativePostPath) {
-    const withoutExtension = relativePostPath.replace(/\.json$/, '');
-    return `${BLOG_PREFIX}${withoutExtension}`;
-}

package/dist/services/resolve-blog-url.d.ts

@@ -1,11 +0,0 @@
-import type { SiteConfig } from '../config.ts';
-export type ResolvedBlogUrl = {
-    kind: 'post';
-    relativePath: string;
-} | {
-    kind: 'redirect';
-    to: string;
-} | {
-    kind: 'not-found';
-};
-export declare function resolveBlogUrl(config: SiteConfig, url: string): ResolvedBlogUrl;

package/dist/services/resolve-blog-url.js

@@ -1,31 +0,0 @@
-import { existsSync } from 'node:fs';
-import { sanitisePath } from "./path-safety.js";
-import { buildRedirectLookup, loadRedirects } from "./redirects.js";
-import { urlToPostPath } from "./post-urls.js";
-// Mirrors resolve-url.ts's shape exactly (a live post always wins over
-// a redirect at the same URL), kept as its own distinct result type
-// rather than reusing ResolvedUrl - clearer branching at the call site
-// and avoids touching Group C's already-tested resolve-url.ts.
-//
-// Unlike pagesRoot (always expected to exist on a real site),
-// postsRoot is optional - a site that has never used blog posts has
-// no content/posts/ directory at all. sanitisePath calls realpathSync
-// directly on its root argument, which throws a raw, uncaught ENOENT
-// if that root itself is missing - so postsRoot's existence is checked
-// first, before ever calling sanitisePath, rather than letting a
-// perfectly ordinary "no posts yet" site crash on its first /blog/ hit.
-export function resolveBlogUrl(config, url) {
-    const relativePath = urlToPostPath(url);
-    if (relativePath !== null && existsSync(config.postsRoot)) {
-        const postFile = sanitisePath(config.postsRoot, relativePath);
-        if (existsSync(postFile)) {
-            return { kind: 'post', relativePath };
-        }
-    }
-    const lookup = buildRedirectLookup(loadRedirects(config).entries);
-    const to = lookup.get(url);
-    if (to !== undefined) {
-        return { kind: 'redirect', to };
-    }
-    return { kind: 'not-found' };
-}