@o-a/cms-agent 0.5.1 → 0.5.2

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:

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/package.json

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