@o-a/cms-agent 0.5.0 → 0.5.2

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

@@ -124,6 +124,17 @@ export function scaffoldSite(targetDir) {
             tunnel: 'node server.js --tunnel',
             dev: 'node --watch-path=../theme server.js',
             check: 'check-site',
+            // seed-media is the package's own installed CLI bin, exposed
+            // as a script for exactly the same reason check is: there is
+            // no package.json or node_modules at the SITE root, only here
+            // in vhost/, so the obvious-looking `npx seed-media` run from
+            // the site directory resolves nothing locally, goes to the
+            // public registry for a package by that name and dies with
+            // E404 - while still exiting 0. That is not hypothetical: it
+            // is what sent a generated site's images into theme/root/
+            // instead of media/. Run it from here as
+            // `npm run seed-media -- .. <file>`.
+            'seed-media': 'seed-media',
         },
         dependencies: {
             // Pinned exact, never a ^range - at v0.x even a minor bump

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

@@ -38,7 +38,7 @@ This scaffold already ships real, working examples worth reading before writing
 **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. **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"`. **Set its `"type"` to that kind too** (`"project"`, `"article"`) - not `"page"`. Every page an editor creates from a template inherits the template's own `type`, and that value is what listings filter on, so an Article template left at `"type": "page"` silently produces articles no blog index can find. This is easy to get wrong because the template still validates and previews perfectly either way; nothing fails, the listing is simply always empty. 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. **Put every image through `seed-media` before referencing it - never copy image files into the repo by hand.** Photographs and other content images do not belong in the site root, in `theme/root/`, or in `theme/assets/`; they belong in `media/`, under a content-addressed filename the CMS generates. Run `npx seed-media . <file>...` from the site directory and use the `/media/...` URL it prints, as the `url` of a `format: "image"` setting rendered through the `responsive-media` snippet - never a hand-written `<img>`. See "Images" below for the detail and for how this changes once a server is running. Getting this wrong is quiet rather than loud: the page still renders, the image is simply missing.
+5. **Put every image through `seed-media` before referencing it - never copy image files into the repo by hand.** Photographs and other content images do not belong in the site root, in `theme/root/`, or in `theme/assets/`; they belong in `media/`, under a content-addressed filename the CMS generates. Run `npm run seed-media -- .. <file>...` from `vhost/` (the same place `npm run check` runs from) and use the `/media/...` URL it prints, as the `url` of a `format: "image"` setting rendered through the `responsive-media` snippet - never a hand-written `<img>`. See "Images" below for the detail and for how this changes once a server is running. Getting this wrong is quiet rather than loud: the page still renders, the image is simply missing.
 6. Preview the result, then run `npm run check` before considering the task done - it renders every page for real and fails on any image or link pointing at a file that does not exist, which is the fastest way to catch a misplaced image. See "Previewing your work".
 
 ### Worked example - a section
@@ -104,7 +104,8 @@ Write the description as one short sentence about what the section **is**, not w
 {{ page.author }}                the page's author, if set
 {{ page.publishDate }}           the page's publish date, if set
 {% for tag in page.tags %}...{% endfor %}   the page's tags, if any
-{{ menus.<name>.items }}         every menu in content/menus/, keyed by filename
+{{ menus.<handle>.items }}       every menu in content/menus/, keyed by handle (its filename)
+{{ menus.<handle>.name }}        that menu's optional display name (blank when unset)
 ```
 
 ### Snippets
@@ -275,7 +276,7 @@ Required fields, `additionalProperties: false`:
 
 | Field | Type | Notes |
 |---|---|---|
-| `schemaVersion` | integer | Always `6` for new content |
+| `schemaVersion` | integer | Always `7` for new content |
 | `name` | string | Internal label (shown in the admin's page tree) |
 | `title` | string | Rendered as `{{ page.title }}` |
 | `type` | string | **The field that decides which listings a page appears in.** Free-form (e.g. `"page"`, `"project"`, `"article"`), lowercase by convention. It is indexed as `pageType` and is what `GET /search.json?pageType=...` filters on, so a project listing, a blog index and a team directory each depend on their pages carrying the right value here. Give every kind of page its own type; `"page"` is for ordinary one-off pages only |
@@ -289,7 +290,7 @@ Each entry in `sections` requires `id` (any non-empty string, unique within the
 
 ```json
 {
-  "schemaVersion": 6,
+  "schemaVersion": 7,
   "name": "Home",
   "title": "Welcome",
   "type": "page",
@@ -308,10 +309,10 @@ Each entry in `sections` requires `id` (any non-empty string, unique within the
 }
 ```
 
-`content/menus/<name>.json` - referenced in layouts as `{{ menus.<name>.items }}`:
+`content/menus/<handle>.json` - the filename is the menu's handle, referenced in layouts as `{{ menus.<handle>.items }}`. An optional `"name"` is its display name (editable in the admin, available as `{{ menus.<handle>.name }}`). Renaming the file changes the handle and empties every layout still using the old one, so change `"name"` to rename a menu:
 
 ```json
-{ "schemaVersion": 6, "items": [{ "label": "Home", "url": "/" }, { "label": "About", "url": "/about" }] }
+{ "schemaVersion": 7, "items": [{ "label": "Home", "url": "/" }, { "label": "About", "url": "/about" }] }
 ```
 
 `content/redirects.json` - a single file, not a folder:
@@ -385,11 +386,14 @@ Guard the call on the url, as above. An unset image renders nothing at all rathe
 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
+cd vhost
+npm run seed-media -- .. photo.jpg another.png
 # photo.jpg -> /media/photo-3f9a2b7c1e04.jpg
 # another.png -> /media/another-91cd4a08f2b1.png
 ```
 
+Run it from `vhost/`, not the site root. There is no `package.json` or `node_modules` at the site root - the CMS is installed under `vhost/` - so a bare `npx seed-media` there resolves nothing locally, goes to the public npm registry looking for a package called "seed-media", and fails with a 404 while still exiting 0.
+
 Then use the printed URL as the `url` of a `format: "image"` setting, exactly like a real upload's - not as a plain string:
 
 ```json
@@ -440,6 +444,8 @@ From `vhost/`, with the site's dependencies already installed (no need for the s
 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.
+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 `src`/`srcset`/`poster`/`href` in the rendered HTML pointing at a `/media/`, `/assets/`, or root-static file that doesn't actually exist on disk; any internal link that doesn't point at a real, published page; and **any content image or video being served from `theme/root/` or `theme/assets/` instead of `media/`**. Exits non-zero if it finds anything - safe to run after generating content, not just as a manual spot-check.
+
+That last one has no other way of being noticed: the file exists, so the page renders perfectly. It is simply invisible to the media library and an editor can never replace it.
 
 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": 6,
+  "schemaVersion": 7,
   "items": [
     { "label": "About", "url": "/about" },
     { "label": "Careers", "url": "/careers" },

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

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

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

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 6,
+  "schemaVersion": 7,
   "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": 6,
+  "schemaVersion": 7,
   "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": 6,
+  "schemaVersion": 7,
   "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": 6,
+  "schemaVersion": 7,
   "title": "Careers — Granite CMS",
   "type": "page",
   "layout": "theme",

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

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

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

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

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

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 6,
+  "schemaVersion": 7,
   "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": 6,
+  "schemaVersion": 7,
   "title": "Quickstart — Granite CMS",
   "type": "page",
   "layout": "theme",

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

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

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

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

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

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

package/dist/create-site/template/vhost/docker-entrypoint.sh

@@ -1,6 +1,12 @@
 #!/bin/sh
 set -e
 
+# /seed is the image-baked copy of the site; /site is where the
+# persistent volume is mounted. Overridable only so the test suite can
+# run this exact script against temporary directories.
+SEED="${CMS_SEED_DIR:-/seed}"
+SITE="${CMS_SITE_DIR:-/site}"
+
 # First boot against an empty mounted volume: seed it from the
 # image-baked copy at /seed (content, theme, the already-`npm
 # install`ed vhost/node_modules). A later boot finds /site/vhost
@@ -8,8 +14,28 @@ set -e
 # identically with a real persistent volume mounted at /site
 # (production) or with nothing mounted at all (a quick local trial,
 # where content just lives in the ephemeral container layer).
-if [ ! -d /site/vhost ]; then
-  cp -r /seed/. /site/
+if [ ! -d "$SITE/vhost" ]; then
+  cp -r "$SEED/." "$SITE/"
+else
+  # Every later boot: refresh the agent itself from the image, and
+  # nothing else. Content, drafts, media and theme on the volume are
+  # the live site's own and are never touched - but the installed
+  # @o-a/cms-agent is code, not content, so without this a redeploy
+  # built from a newer agent would keep running the old one from the
+  # volume forever. Only the dependency manifest and its installed
+  # packages are copied; site.config.json (tokens) and server.js stay
+  # as they are on the volume.
+  #
+  # This leaves vhost/package.json (and package-lock.json) showing as
+  # modified in the volume's git working tree after an upgrade. That is
+  # deliberate: nothing here commits, since publishing is the only
+  # routine operation that creates a commit.
+  cp "$SEED/vhost/package.json" "$SITE/vhost/package.json"
+  if [ -f "$SEED/vhost/package-lock.json" ]; then
+    cp "$SEED/vhost/package-lock.json" "$SITE/vhost/package-lock.json"
+  fi
+  rm -rf "$SITE/vhost/node_modules"
+  cp -r "$SEED/vhost/node_modules" "$SITE/vhost/node_modules"
 fi
 
 # The site root must be a real git repository (services/startup-checks.ts) -
@@ -18,13 +44,13 @@ fi
 # git-archive-style upload of tracked file contents only, which never
 # includes .git at all. Recovered here rather than assumed away: if
 # it's missing, start a fresh repo over the already-seeded content.
-if [ ! -d /site/.git ]; then
-  git -C /site init --quiet
-  git -C /site add -A
+if [ ! -d "$SITE/.git" ]; then
+  git -C "$SITE" init --quiet
+  git -C "$SITE" add -A
   GIT_AUTHOR_NAME="cms-agent" GIT_AUTHOR_EMAIL="cms-agent@localhost" \
     GIT_COMMITTER_NAME="cms-agent" GIT_COMMITTER_EMAIL="cms-agent@localhost" \
-    git -C /site commit --quiet -m "chore: initial scaffold (recovered - .git was not part of the deploy upload)"
+    git -C "$SITE" commit --quiet -m "chore: initial scaffold (recovered - .git was not part of the deploy upload)"
 fi
 
-cd /site/vhost
+cd "$SITE/vhost"
 exec node server.js

package/dist/migrations/index.d.ts

@@ -1,3 +1,3 @@
 import type { MigrationMap } from '../services/migration-runner.ts';
-export declare const CURRENT_SCHEMA_VERSION = 6;
+export declare const CURRENT_SCHEMA_VERSION = 7;
 export declare const migrations: MigrationMap;

package/dist/migrations/index.js

@@ -1,7 +1,7 @@
 // The current content schema version. Bumping this and adding a new
 // migrations[N] entry is the only way a content shape may change
 // (constraint 4) - never a manual edit convention.
-export const CURRENT_SCHEMA_VERSION = 6;
+export const CURRENT_SCHEMA_VERSION = 7;
 // A trivial identity migration, proving the mechanism (per the build
 // plan's Phase 1 scope): no shape change, only the version bump. Safe
 // against page.schema.json's schemaVersion: { minimum: 1 } (not an
@@ -63,10 +63,21 @@ function migrateV5ToV6(content) {
     const title = typeof content.title === 'string' ? content.title : '';
     return { ...content, schemaVersion: 6, name: title };
 }
+// menu.schema.json gains an optional "name": the admin's own display
+// label for a menu, editable without touching its filename (which is
+// what themes reference it by, as menus.<filename>, so renaming the
+// file would silently empty every nav that uses it). Optional, so no
+// existing menu needs a value invented for it - the admin falls back
+// to deriving one from the filename, exactly as it always has. No
+// shape change for pages at all; only the version bump.
+function migrateV6ToV7(content) {
+    return { ...content, schemaVersion: 7 };
+}
 export const migrations = {
     1: migrateV1ToV2,
     2: migrateV2ToV3,
     3: migrateV3ToV4,
     4: migrateV4ToV5,
     5: migrateV5ToV6,
+    6: migrateV6ToV7,
 };

package/dist/renderer/render-page.js

@@ -168,11 +168,21 @@ export function getPageMtimeMs(config, relativePath) {
 // A menu edit affects every page's rendered nav, not just one page, so
 // the cache's freshness check needs one value covering all menus
 // together rather than per-page tracking. The max mtime across every
-// menu file serves that - any single menu changing bumps it. 0 (never
-// stale relative to anything) when there are no menus at all, matching
-// listFilesRecursively's own "missing directory returns []" behaviour.
+// menu file covers an edit. It does not cover a menu being renamed (a
+// handle change keeps the file's mtime) or deleted (removes one), so
+// the menus directory's own mtime is included too: that changes
+// whenever an entry is added, renamed or removed. Menus are flat, so
+// the one directory is enough. 0 (never stale relative to anything)
+// when there are no menus at all, matching listFilesRecursively's own
+// "missing directory returns []" behaviour.
 export function getMenusMtimeMs(config) {
     let max = 0;
+    try {
+        max = statSync(config.menusRoot).mtimeMs;
+    }
+    catch {
+        // No content/menus/ at all - nothing to track.
+    }
     for (const relativePath of listFilesRecursively(config.menusRoot, config.menusRoot, '.json')) {
         try {
             const { mtimeMs } = statSync(sanitisePath(config.menusRoot, relativePath));

package/dist/routes/menus.js

@@ -1,5 +1,6 @@
 import { isValidCommitAuthor } from "../services/git.js";
-import { ManageMenuError, saveMenu } from "../services/manage-menus.js";
+import { ManageMenuError, renameMenu, saveMenu } from "../services/manage-menus.js";
+import { findMenuReferences, isValidMenuHandle } from "../services/menu-references.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";
@@ -67,6 +68,72 @@ async function handleSaveMenu(request, reply, config) {
         throw error;
     }
 }
+function parseRenameMenuBody(body) {
+    if (typeof body !== 'object' || body === null) {
+        return null;
+    }
+    const { from, to, message, author } = body;
+    if (!isNonEmptyString(from) || !isNonEmptyString(to) || !isNonEmptyString(message) || !isValidCommitAuthor(author)) {
+        return null;
+    }
+    return { from, to, message, author };
+}
+// Takes handles (what a layout writes: menus.<handle>.items), not file
+// paths - a rename can only ever move a menu within content/menus/.
+// If-Match is the menu's current etag, as for a save.
+async function handleRenameMenu(request, reply, config) {
+    const ifMatch = request.headers['if-match'];
+    if (typeof ifMatch !== 'string' || ifMatch.length === 0) {
+        reply.code(428).send({
+            statusCode: 428,
+            error: 'Precondition Required',
+            message: 'An If-Match header is required to rename a menu',
+        });
+        return;
+    }
+    const parsed = parseRenameMenuBody(request.body);
+    if (!parsed) {
+        reply.code(400).send({
+            statusCode: 400,
+            error: 'Bad Request',
+            message: 'Expected { from: string, to: string, message: string, author: { name, email } }',
+        });
+        return;
+    }
+    try {
+        const result = await renameMenu(config, parsed.from, parsed.to, ifMatch, parsed.message, parsed.author);
+        reply.header('etag', result.etag).send({ ok: true, staleThemeReferences: result.staleThemeReferences });
+    }
+    catch (error) {
+        if (error instanceof PathSafetyError) {
+            reply.code(400).send({ statusCode: 400, error: 'Bad Request', message: 'Not a valid menu handle' });
+            return;
+        }
+        if (error instanceof ManageMenuError && error.reason === 'not-found') {
+            reply.code(404).send({ statusCode: 404, error: 'Not Found', message: error.message });
+            return;
+        }
+        if (error instanceof ManageMenuError && error.reason === 'conflict') {
+            reply.code(409).send({ statusCode: 409, error: 'Conflict', message: error.message });
+            return;
+        }
+        if (error instanceof ManageMenuError && error.reason === 'validation-failed') {
+            reply.code(400).send({ statusCode: 400, error: 'Bad Request', message: error.message });
+            return;
+        }
+        throw error;
+    }
+}
+// Read-only and advisory: which theme files mention a handle, so the
+// admin can warn before a rename or delete empties a nav.
+function handleMenuReferences(request, reply, config) {
+    const handle = request.query.handle;
+    if (typeof handle !== 'string' || !isValidMenuHandle(handle)) {
+        reply.code(400).send({ statusCode: 400, error: 'Bad Request', message: 'Expected ?handle=<menu handle>' });
+        return;
+    }
+    reply.send({ handle, themeFiles: findMenuReferences(config, handle) });
+}
 // GET/DELETE/move for menus/ paths deliberately stay on the existing
 // generic /v1/content routes (Group N) - only this write path is new.
 // Its own namespace (/v1/menus, not wedged into /v1/content), matching
@@ -74,4 +141,8 @@ async function handleSaveMenu(request, reply, config) {
 // with type-conditional write behaviour.
 export const menusRoutes = async (fastify, opts) => {
     fastify.put('/menus/*', { preHandler: requireScope(opts.tokens, 'content'), config: WRITE_ROUTE_RATE_LIMIT }, async (request, reply) => handleSaveMenu(request, reply, opts.config));
+    // Static paths, distinct from PUT /menus/* by method (POST/GET), the
+    // same way POST /content/move sits beside DELETE /content/*.
+    fastify.post('/menus/rename', { preHandler: requireScope(opts.tokens, 'content'), config: WRITE_ROUTE_RATE_LIMIT }, async (request, reply) => handleRenameMenu(request, reply, opts.config));
+    fastify.get('/menus/references', { preHandler: requireScope(opts.tokens, 'content') }, async (request, reply) => handleMenuReferences(request, reply, opts.config));
 };

package/dist/schemas/menu.schema.json

@@ -7,6 +7,7 @@
   "required": ["schemaVersion", "items"],
   "properties": {
     "schemaVersion": { "type": "integer", "minimum": 1 },
+    "name": { "type": "string", "minLength": 1 },
     "items": {
       "type": "array",
       "items": {

package/dist/services/manage-menus.d.ts

@@ -1,6 +1,6 @@
 import type { SiteConfig } from '../config.ts';
 import type { CommitAuthor } from './git.ts';
-export type ManageMenuReason = 'validation-failed' | 'conflict' | 'write-failed' | 'commit-failed' | 'rollback-failed';
+export type ManageMenuReason = 'validation-failed' | 'not-found' | 'conflict' | 'write-failed' | 'commit-failed' | 'rollback-failed';
 export declare class ManageMenuError extends Error {
     readonly reason: ManageMenuReason;
     constructor(reason: ManageMenuReason, message: string, options?: {
@@ -8,3 +8,8 @@ export declare class ManageMenuError extends Error {
     });
 }
 export declare function saveMenu(config: SiteConfig, relativePath: string, content: unknown, expectedEtag: string, message: string, author: CommitAuthor): Promise<string>;
+export interface RenameMenuResult {
+    etag: string;
+    staleThemeReferences: string[];
+}
+export declare function renameMenu(config: SiteConfig, from: string, to: string, expectedEtag: string, message: string, author: CommitAuthor): Promise<RenameMenuResult>;

package/dist/services/manage-menus.js

@@ -1,8 +1,9 @@
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { ContentReadError, readContentFile } from "./content-read.js";
 import { computeEtag, etagsMatch } from "./etag.js";
 import { commitPaths } from "./git.js";
+import { findMenuReferences, isValidMenuHandle } from "./menu-references.js";
 import { sanitisePath } from "./path-safety.js";
 import { validateMenu } from "./validation.js";
 import { enqueue } from "./write-queue.js";
@@ -82,3 +83,56 @@ async function saveMenuJob(config, relativePath, content, expectedEtag, message,
 export function saveMenu(config, relativePath, content, expectedEtag, message, author) {
     return enqueue(() => saveMenuJob(config, relativePath, content, expectedEtag, message, author));
 }
+// Changes a menu's handle: moves content/menus/<from>.json to
+// <to>.json in one commit. Contents are untouched, so the returned
+// etag is the same one the menu already had. Refuses rather than
+// overwriting when <to> is taken, and checks If-Match against <from>
+// like every other menu write, so a rename made from a stale view is
+// refused rather than applied.
+async function renameMenuJob(config, from, to, expectedEtag, message, author) {
+    if (!isValidMenuHandle(from) || !isValidMenuHandle(to)) {
+        throw new ManageMenuError('validation-failed', 'A menu handle may only contain letters, numbers, hyphens and underscores');
+    }
+    if (from === to) {
+        throw new ManageMenuError('validation-failed', `The menu is already called "${to}"`);
+    }
+    mkdirSync(config.menusRoot, { recursive: true });
+    const fromPath = sanitisePath(config.menusRoot, `${from}.json`);
+    const toPath = sanitisePath(config.menusRoot, `${to}.json`);
+    const currentEtag = readCurrentEtag(config, `${from}.json`);
+    if (currentEtag === null) {
+        throw new ManageMenuError('not-found', `No menu with the handle "${from}"`);
+    }
+    if (!etagsMatch(currentEtag, expectedEtag)) {
+        throw new ManageMenuError('conflict', `If-Match "${expectedEtag}" does not match the current ETag for "${from}.json"`);
+    }
+    // existsSync is case-insensitive on a case-insensitive filesystem
+    // (macOS by default), so "main" -> "Main" is refused there rather
+    // than risking a rename onto itself. Harmless: pick another handle.
+    if (existsSync(toPath)) {
+        throw new ManageMenuError('conflict', `A menu with the handle "${to}" already exists`);
+    }
+    try {
+        renameSync(fromPath, toPath);
+    }
+    catch (error) {
+        throw new ManageMenuError('write-failed', `Could not rename "${from}" to "${to}"`, { cause: error });
+    }
+    try {
+        commitPaths(config.siteRoot, [fromPath, toPath], message, author);
+    }
+    catch (error) {
+        try {
+            renameSync(toPath, fromPath);
+        }
+        catch (rollbackError) {
+            throw new ManageMenuError('rollback-failed', 'Menu rename failed and rolling back afterwards also failed; the working tree may be inconsistent and needs manual inspection', { cause: rollbackError });
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new ManageMenuError('commit-failed', `Menu rename failed: ${detail}`, { cause: error });
+    }
+    return { etag: currentEtag, staleThemeReferences: findMenuReferences(config, from) };
+}
+export function renameMenu(config, from, to, expectedEtag, message, author) {
+    return enqueue(() => renameMenuJob(config, from, to, expectedEtag, message, author));
+}

package/dist/services/menu-references.d.ts

@@ -0,0 +1,3 @@
+import type { SiteConfig } from '../config.ts';
+export declare function isValidMenuHandle(handle: string): boolean;
+export declare function findMenuReferences(config: SiteConfig, handle: string): string[];

package/dist/services/menu-references.js

@@ -0,0 +1,38 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { listFilesRecursively } from "./fs-walk.js";
+// A menu's handle is its filename without .json - what a layout writes
+// as menus.<handle>.items. Menus are flat (no subfolders), and these
+// are the only characters a Liquid dot-lookup reads as one name.
+const MENU_HANDLE = /^[A-Za-z0-9_-]+$/;
+export function isValidMenuHandle(handle) {
+    return MENU_HANDLE.test(handle);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+// Which theme files mention a menu by handle, as site-relative paths
+// (e.g. "theme/layouts/theme.liquid"). Read-only and advisory: it lets
+// the admin warn before a rename or delete leaves a nav empty. Matches
+// both menus.<handle> and menus['<handle>'] / menus["<handle>"], and
+// the dot form only as a whole name, so "main" never matches
+// menus.mainFooter. A handle built at runtime ({% assign m = ... %})
+// can't be seen here, which is why this only ever informs a warning,
+// never blocks anything.
+export function findMenuReferences(config, handle) {
+    if (!isValidMenuHandle(handle)) {
+        return [];
+    }
+    const escaped = escapeRegExp(handle);
+    const pattern = new RegExp(`menus(?:\\.${escaped}(?![A-Za-z0-9_-])|\\[\\s*(['"])${escaped}\\1\\s*\\])`);
+    return listFilesRecursively(config.themeRoot, config.siteRoot, '.liquid')
+        .filter((relativePath) => {
+        try {
+            return pattern.test(readFileSync(join(config.siteRoot, relativePath), 'utf-8'));
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort();
+}

package/dist/services/menus.d.ts

@@ -1,5 +1,6 @@
 import type { SiteConfig } from '../config.ts';
 export interface MenuContent {
+    name?: string;
     items: Array<{
         label: string;
         url: string;

package/dist/services/menus.js

@@ -7,7 +7,8 @@ function tryReadMenu(fullPath) {
         if (!Array.isArray(parsed.items)) {
             return null;
         }
-        return { items: parsed.items };
+        const items = parsed.items;
+        return typeof parsed.name === 'string' ? { name: parsed.name, items } : { items };
     }
     catch {
         // One malformed menu file is skipped individually, not fatal to

package/dist/site-check/cli.js

@@ -10,6 +10,7 @@ const KIND_LABELS = {
     'render-error': 'Render error',
     'missing-asset': 'Missing asset',
     'broken-link': 'Broken link',
+    'misplaced-media': 'Misplaced media',
 };
 function printGrouped(findings) {
     const byKind = new Map();

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

@@ -1,4 +1,4 @@
-export type CheckFindingKind = 'schema' | 'render-error' | 'missing-asset' | 'broken-link';
+export type CheckFindingKind = 'schema' | 'render-error' | 'missing-asset' | 'broken-link' | 'misplaced-media';
 export interface CheckFinding {
     kind: CheckFindingKind;
     message: string;

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

@@ -4,6 +4,7 @@ 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";
+import { ALLOWED_UPLOAD_EXTENSIONS } from "../media/filename.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),
@@ -11,25 +12,46 @@ import { urlToPagePath } from "../services/urls.js";
 // "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;
+// poster is included deliberately: a video's poster is a real content
+// image and was not being checked at all before.
+const ATTR_PATTERN = /\b(src|href|poster|srcset)="([^"]*)"/g;
 function extractReferences(html) {
     const refs = [];
     for (const match of html.matchAll(ATTR_PATTERN)) {
-        const [, single, srcset] = match;
-        if (single !== undefined) {
-            refs.push(single);
+        const attribute = match[1] ?? '';
+        const value = match[2] ?? '';
+        if (attribute !== 'srcset') {
+            refs.push({ url: value, attribute });
         }
-        else if (srcset !== undefined) {
-            for (const entry of srcset.split(',')) {
+        else {
+            for (const entry of value.split(',')) {
                 const url = entry.trim().split(/\s+/)[0];
                 if (url) {
-                    refs.push(url);
+                    refs.push({ url, attribute });
                 }
             }
         }
     }
     return refs;
 }
+// Any scheme at all that is not http(s). The previous version listed
+// data: explicitly and nothing else, so mailto: (and tel:, and anything
+// future) fell through to the static-file branch below and was reported
+// as a missing file under theme/root/, purely because the text after
+// the "@" contains a dot. One real site produced 39 such findings and
+// not one true one, which is worse than no check: it teaches whoever
+// reads the output to ignore it.
+function hasExternalScheme(ref) {
+    return ref.startsWith('//') || /^[a-z][a-z0-9+.-]*:/i.test(ref);
+}
+// A content photograph or clip, as opposed to a design asset. Keyed off
+// the same extension list the media upload route accepts, so the two
+// cannot drift; .svg is absent from it, which is what keeps an inline
+// logo or icon from being mistaken for misplaced content.
+function isUploadableMedia(path) {
+    const lower = path.toLowerCase();
+    return [...ALLOWED_UPLOAD_EXTENSIONS].some((extension) => lower.endsWith(extension));
+}
 // 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
@@ -48,6 +70,17 @@ function looksLikeStaticFile(path) {
 // 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) {
+    // sanitisePath realpaths its root unconditionally, so a site that has
+    // no media/, theme/assets/ or theme/root/ directory at all threw a
+    // raw ENOENT out of the whole check rather than reporting anything -
+    // the check crashing with a stack trace on exactly the sites most
+    // likely to hold a broken reference. A root that does not exist means
+    // the file underneath it does not exist either, which is an ordinary
+    // finding, not an error.
+    if (!existsSync(root)) {
+        findings.push({ kind: 'missing-asset', message: `${originalPath} does not exist under ${rootLabel}`, pageUrl });
+        return;
+    }
     try {
         const filePath = sanitisePath(root, relativePath);
         if (!existsSync(filePath)) {
@@ -62,6 +95,13 @@ function checkStaticReference(findings, root, relativePath, originalPath, rootLa
         throw error;
     }
 }
+// The file exists, so nothing else would ever flag it - which is
+// precisely why this needs saying. A content image outside media/ is
+// invisible to the media library, cannot be replaced by an editor, and
+// is not what the CMS manages.
+function misplacedMessage(path, where) {
+    return `${path} is a content image served from ${where} - it belongs in media/ (run \`npm run seed-media -- .. <file>\` from vhost/ and use the /media/... URL it prints)`;
+}
 export async function runSiteCheck(siteRoot) {
     const booted = bootSite(siteRoot);
     const findings = [];
@@ -86,18 +126,27 @@ export async function runSiteCheck(siteRoot) {
             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('//')) {
+        for (const { url: ref, attribute } of extractReferences(html)) {
+            if (hasExternalScheme(ref)) {
                 continue;
             }
             const path = ref.split(/[?#]/)[0] ?? ref;
+            // Only src/srcset/poster can carry a content image. An href is a
+            // link or a favicon, and flagging those would make this useless.
+            const rendersMedia = attribute !== 'href' && isUploadableMedia(path);
             if (path.startsWith('/media/')) {
                 checkStaticReference(findings, booted.config.mediaRoot, path.slice('/media/'.length), path, 'media/', pageUrl);
             }
             else if (path.startsWith('/assets/')) {
+                if (rendersMedia) {
+                    findings.push({ kind: 'misplaced-media', message: misplacedMessage(path, 'theme/assets/'), pageUrl });
+                }
                 checkStaticReference(findings, booted.config.assetsRoot, path.slice('/assets/'.length), path, 'theme/assets/', pageUrl);
             }
             else if (looksLikeStaticFile(path)) {
+                if (rendersMedia) {
+                    findings.push({ kind: 'misplaced-media', message: misplacedMessage(path, 'theme/root/'), pageUrl });
+                }
                 checkStaticReference(findings, booted.config.rootMirrorRoot, path.slice(1), path, 'theme/root/', pageUrl);
             }
             else if (path !== '' && !publishedUrlSet.has(path)) {

package/package.json

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