@o-a/cms-agent 0.5.1 → 0.5.3

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

@@ -135,6 +135,9 @@ export function scaffoldSite(targetDir) {
             // instead of media/. Run it from here as
             // `npm run seed-media -- .. <file>`.
             'seed-media': 'seed-media',
+            // Stops the site from any terminal, not only the one it was
+            // started in (stop-site, via vhost/data/server.pid).
+            stop: 'stop-site',
         },
         dependencies: {
             // Pinned exact, never a ^range - at v0.x even a minor bump

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

@@ -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:
@@ -429,6 +430,7 @@ 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 stop        # stops a site started by any of the above, from any terminal
 ```
 
 `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.

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/search/query-index.d.ts

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

package/dist/search/query-index.js

@@ -0,0 +1,21 @@
+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/server.js

@@ -13,6 +13,7 @@ import { CHECKPOINT_AUTHOR, runCheckpoint } from "./services/checkpoint.js";
 import { startDevTunnel } from "./services/dev-tunnel.js";
 import { startIntervalJob } from "./services/interval-job.js";
 import { reindexOnBootIfMissing } from "./services/reindex-on-write.js";
+import { isProcessAlive, readPidFile, removeOwnPidFile, writePidFile } from "./services/pid-file.js";
 // Never wrap v1Routes (or any route-group plugin it registers) with
 // fastify-plugin (fp()): plain app.register() gives each file its own
 // encapsulation scope by default, which Group B's auth preHandler
@@ -165,6 +166,7 @@ export async function startServer(siteRoot, options = {}) {
         scheduler.stop();
         process.removeListener('SIGTERM', shutdown);
         process.removeListener('SIGINT', shutdown);
+        removeOwnPidFile(booted.config);
         try {
             await doCheckpoint();
         }
@@ -185,6 +187,14 @@ export async function startServer(siteRoot, options = {}) {
         // them the two real ways to pick a different one instead of
         // rethrowing Node's own stack trace.
         if (error instanceof Error && 'code' in error && error.code === 'EADDRINUSE') {
+            // Most often it's this same site, started earlier in another
+            // terminal - say so, and how to stop it from this one.
+            const running = readPidFile(booted.config);
+            if (running && running.port === serverConfig.port && running.pid !== process.pid && isProcessAlive(running.pid)) {
+                console.error(`This site is already running on port ${serverConfig.port} (process ${running.pid}).`);
+                console.error('Stop it with "npm run stop" from vhost/, then start it again.');
+                process.exit(1);
+            }
             console.error(`Port ${serverConfig.port} is already in use.`);
             console.error(`Set a different port with the PORT environment variable (e.g. PORT=3001 node server.js), or "port" in vhost/site.config.json.`);
             process.exit(1);
@@ -200,6 +210,9 @@ export async function startServer(siteRoot, options = {}) {
     const address = app.server.address();
     if (address !== null && typeof address !== 'string') {
         console.log(`Site running at http://127.0.0.1:${address.port}`);
+        // Recorded only once the port is really bound, so a start that
+        // fails never leaves a record of a site that isn't running.
+        writePidFile(booted.config, address.port);
     }
     // A search index is never git-tracked (constraint 3), so a fresh
     // clone or first-ever boot has no index file - without this,

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/services/pid-file.d.ts

@@ -0,0 +1,13 @@
+import type { SiteConfig } from '../config.ts';
+export interface PidRecord {
+    pid: number;
+    serverPid: number;
+    port: number;
+    startedAt: string;
+}
+export declare function pidFilePath(config: SiteConfig): string;
+export declare function writePidFile(config: SiteConfig, port: number): void;
+export declare function readPidFile(config: SiteConfig): PidRecord | null;
+export declare function removeOwnPidFile(config: SiteConfig): void;
+export declare function removePidFile(config: SiteConfig): void;
+export declare function isProcessAlive(pid: number): boolean;

package/dist/services/pid-file.js

@@ -0,0 +1,54 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export function pidFilePath(config) {
+    return join(config.dataRoot, 'server.pid');
+}
+// Node sets WATCH_REPORT_DEPENDENCIES in the child it runs under
+// --watch, whose parent is then the watcher itself.
+function stopTarget() {
+    return process.env.WATCH_REPORT_DEPENDENCIES ? process.ppid : process.pid;
+}
+export function writePidFile(config, port) {
+    const record = { pid: stopTarget(), serverPid: process.pid, port, startedAt: new Date().toISOString() };
+    mkdirSync(config.dataRoot, { recursive: true });
+    writeFileSync(pidFilePath(config), `${JSON.stringify(record, null, 2)}\n`);
+}
+export function readPidFile(config) {
+    try {
+        const parsed = JSON.parse(readFileSync(pidFilePath(config), 'utf-8'));
+        const { pid, serverPid, port, startedAt } = parsed;
+        if (typeof pid !== 'number' ||
+            typeof serverPid !== 'number' ||
+            typeof port !== 'number' ||
+            typeof startedAt !== 'string') {
+            return null;
+        }
+        return { pid, serverPid, port, startedAt };
+    }
+    catch {
+        return null;
+    }
+}
+// Only removes the file if it is still this process's own record: under
+// `npm run dev` the watcher starts a new process on a theme change, and
+// the old one shutting down must not delete the record the new one has
+// just written.
+export function removeOwnPidFile(config) {
+    if (readPidFile(config)?.serverPid === process.pid) {
+        removePidFile(config);
+    }
+}
+export function removePidFile(config) {
+    rmSync(pidFilePath(config), { force: true });
+}
+// Whether a process with this id exists. EPERM means it does, but
+// belongs to another user.
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error instanceof Error && 'code' in error && error.code === 'EPERM';
+    }
+}

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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,27 @@
+// 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

@@ -0,0 +1,11 @@
+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

@@ -0,0 +1,31 @@
+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' };
+}

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

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

package/dist/stop-site/cli.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { loadSiteConfig } from "../config.js";
+import { stopSite } from "./stop-site.js";
+// Run from vhost/ (the scaffold's own "stop" script), so the site root
+// is one level up - the same relationship check-site relies on.
+const config = loadSiteConfig(resolve(process.cwd(), '..'));
+const result = await stopSite(config);
+switch (result.outcome) {
+    case 'not-running':
+        console.log("The site isn't running.");
+        break;
+    case 'removed-stale':
+        console.log(`The site isn't running. Removed a leftover record of process ${result.pid}, which has already ended.`);
+        break;
+    case 'not-a-site':
+        console.error(`Process ${result.pid} is recorded as this site, but no site is answering on port ${result.port}, so nothing was stopped.`);
+        console.error('If you are sure the site is not running, delete vhost/data/server.pid.');
+        process.exit(1);
+        break;
+    case 'stopped':
+        console.log(`Stopped the site (was on port ${result.port}).`);
+        break;
+    case 'still-stopping':
+        console.error(`Asked the site to stop (process ${result.pid}), but it is still shutting down.`);
+        process.exit(1);
+        break;
+}

package/dist/stop-site/stop-site.d.ts

@@ -0,0 +1,26 @@
+import type { SiteConfig } from '../config.ts';
+export type StopSiteResult = {
+    outcome: 'not-running';
+} | {
+    outcome: 'removed-stale';
+    pid: number;
+} | {
+    outcome: 'not-a-site';
+    pid: number;
+    port: number;
+} | {
+    outcome: 'stopped';
+    port: number;
+} | {
+    outcome: 'still-stopping';
+    pid: number;
+};
+export interface StopSiteDeps {
+    isAlive: (pid: number) => boolean;
+    signal: (pid: number) => void;
+    isSiteListening: (port: number) => Promise<boolean>;
+    sleep: (ms: number) => Promise<void>;
+    timeoutMs: number;
+}
+export declare const defaultStopSiteDeps: StopSiteDeps;
+export declare function stopSite(config: SiteConfig, deps?: StopSiteDeps): Promise<StopSiteResult>;

package/dist/stop-site/stop-site.js

@@ -0,0 +1,56 @@
+import { isProcessAlive, readPidFile, removePidFile } from "../services/pid-file.js";
+// GET /v1/capabilities is unauthenticated and always answers with the
+// agent's own version, so it's the check that something on the recorded
+// port really is a site - not just any process that happens to have
+// been given the recorded id after the site's own ended.
+async function capabilitiesAnswer(port) {
+    try {
+        const response = await fetch(new URL('/v1/capabilities', `http://127.0.0.1:${port}`), {
+            signal: AbortSignal.timeout(2_000),
+        });
+        const body = (await response.json());
+        return response.ok && typeof body.agentVersion === 'string';
+    }
+    catch {
+        return false;
+    }
+}
+export const defaultStopSiteDeps = {
+    isAlive: isProcessAlive,
+    signal: (pid) => process.kill(pid, 'SIGTERM'),
+    isSiteListening: capabilitiesAnswer,
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    // Long enough for the final draft checkpoint a graceful shutdown runs.
+    timeoutMs: 15_000,
+};
+// Stops the site recorded in vhost/data/server.pid with SIGTERM - the
+// same graceful shutdown as Ctrl+C (the server closes and runs its
+// final draft checkpoint) - then waits for it to exit. It only ever
+// signals a process that is both alive and answering as a site on the
+// recorded port, so a leftover file from a crash never gets an
+// unrelated process that has since been given the same id killed.
+export async function stopSite(config, deps = defaultStopSiteDeps) {
+    const record = readPidFile(config);
+    if (!record) {
+        return { outcome: 'not-running' };
+    }
+    if (!deps.isAlive(record.pid)) {
+        removePidFile(config);
+        return { outcome: 'removed-stale', pid: record.pid };
+    }
+    if (!(await deps.isSiteListening(record.port))) {
+        return { outcome: 'not-a-site', pid: record.pid, port: record.port };
+    }
+    deps.signal(record.pid);
+    const pollMs = 200;
+    for (let waited = 0; waited < deps.timeoutMs; waited += pollMs) {
+        if (!deps.isAlive(record.pid) && !deps.isAlive(record.serverPid)) {
+            // The server removes its own record on a graceful shutdown; this
+            // covers one that exited without getting that far.
+            removePidFile(config);
+            return { outcome: 'stopped', port: record.port };
+        }
+        await deps.sleep(pollMs);
+    }
+    return { outcome: 'still-stopping', pid: record.pid };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o-a/cms-agent",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -25,7 +25,8 @@
     "create-site": "dist/create-site/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"
+    "seed-media": "dist/media/seed-media-cli.js",
+    "stop-site": "dist/stop-site/cli.js"
   },
   "files": [
     "dist"