domma-cms 0.25.15 → 0.30.0

package/server/services/email.js

@@ -1,167 +1,167 @@
-/**
- * Core Email Utility
- * Nodemailer transport factory and generic form email sending utility.
- */
-import nodemailer from 'nodemailer';
-
-let lastSendResult = null;
-
-/**
- * Return the most recent email send result, or null if no send has occurred.
- *
- * @returns {{ ok: boolean, at: string, info: string|null } | null}
- */
-export function getLastSendResult() {
-    return lastSendResult;
-}
-
-/**
- * Record the outcome of an email send for health reporting.
- *
- * @param {boolean} ok
- * @param {string|null} info
- * @returns {void}
- */
-function recordSendResult(ok, info) {
-    lastSendResult = {
-        ok,
-        at: new Date().toISOString(),
-        info: info || null
-    };
-}
-
-/**
- * Escape HTML special characters for safe use in email bodies.
- *
- * @param {string} str
- * @returns {string}
- */
-export function escapeHtml(str) {
-    return String(str)
-        .replace(/&/g, '&')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&#39;');
-}
-
-/**
- * Create a nodemailer transport.
- * Falls back to an Ethereal test account when no SMTP host is configured.
- *
- * @param {{ host: string, port: number, secure: boolean, user: string, pass: string }} smtp
- * @returns {Promise<import('nodemailer').Transporter>}
- * @throws {Error} If Ethereal test account creation fails.
- */
-export async function createTransport(smtp) {
-    if (smtp?.host) {
-        return nodemailer.createTransport({
-            host: smtp.host,
-            port: smtp.port || 587,
-            secure: smtp.secure || false,
-            auth: smtp.user ? { user: smtp.user, pass: smtp.pass } : undefined,
-            tls: { rejectUnauthorized: false }
-        });
-    }
-
-    // No SMTP configured — use Ethereal for dev/demo
-    const testAccount = await nodemailer.createTestAccount();
-    console.log('[email] No SMTP configured. Using Ethereal test account:', testAccount.user);
-    return nodemailer.createTransport({
-        host: 'smtp.ethereal.email',
-        port: 587,
-        secure: false,
-        auth: { user: testAccount.user, pass: testAccount.pass }
-    });
-}
-
-/**
- * Send a generic transactional email.
- *
- * @param {import('nodemailer').Transporter} transport
- * @param {{ from: string, fromName: string, to: string, subject: string, html: string, text: string }} opts
- * @returns {Promise<void>}
- * @throws {Error} If sending the email fails.
- */
-export async function sendEmail(transport, {from, fromName, to, subject, html, text}) {
-    try {
-        const info = await transport.sendMail({
-            from: `"${fromName}" <${from}>`,
-            to,
-            subject,
-            text,
-            html
-        });
-        recordSendResult(true, info.messageId);
-
-        const previewUrl = nodemailer.getTestMessageUrl(info);
-        if (previewUrl) {
-            console.log('[email] Preview URL:', previewUrl);
-        }
-        return info;
-    } catch (err) {
-        recordSendResult(false, err.message);
-        throw err;
-    }
-}
-
-/**
- * Send an HTML + plain-text form submission notification email.
- * Builds a generic table of field→value pairs from the submitted data.
- *
- * @param {import('nodemailer').Transporter} transport
- * @param {{ from: string, fromName: string, to: string, subject: string, formTitle: string, fields: Array<{name: string, label: string}>, data: Record<string, unknown> }} opts
- * @returns {Promise<void>}
- * @throws {Error} If sending the email fails.
- */
-export async function sendFormEmail(transport, { from, fromName, to, subject, formTitle, fields, data }) {
-    const rows = fields.map(field => {
-        const val  = data[field.name] ?? '';
-        const safe = escapeHtml(String(val)).replace(/\n/g, '<br>');
-        const safeLabel = escapeHtml(field.label || field.name);
-        return `
-        <tr>
-            <td style="padding:8px 12px;font-weight:600;background:#f9f9f9;border:1px solid #eee;white-space:nowrap;vertical-align:top;">${safeLabel}</td>
-            <td style="padding:8px 12px;border:1px solid #eee;vertical-align:top;">${safe}</td>
-        </tr>`.trim();
-    }).join('\n');
-
-    const plainRows = fields.map(field => {
-        const val = data[field.name] ?? '';
-        return `${field.label || field.name}: ${val}`;
-    }).join('\n');
-
-    const html = `
-<!DOCTYPE html>
-<html>
-<body style="font-family:sans-serif;max-width:640px;margin:0 auto;padding:20px;">
-    <h2 style="color:#333;margin-bottom:4px;">New Form Submission</h2>
-    <p style="color:#888;margin-top:0;font-size:.9rem;">${escapeHtml(formTitle)}</p>
-    <table style="width:100%;border-collapse:collapse;margin-top:16px;">
-        ${rows}
-    </table>
-</body>
-</html>`.trim();
-
-    const text = `New form submission: ${formTitle}\n\n${plainRows}`;
-
-    try {
-        const info = await transport.sendMail({
-            from: `"${fromName}" <${from}>`,
-            to,
-            subject,
-            text,
-            html
-        });
-        recordSendResult(true, info.messageId);
-
-        const previewUrl = nodemailer.getTestMessageUrl(info);
-        if (previewUrl) {
-            console.log('[email] Preview URL:', previewUrl);
-        }
-        return info;
-    } catch (err) {
-        recordSendResult(false, err.message);
-        throw err;
-    }
-}
+/**
+ * Core Email Utility
+ * Nodemailer transport factory and generic form email sending utility.
+ */
+import nodemailer from 'nodemailer';
+
+let lastSendResult = null;
+
+/**
+ * Return the most recent email send result, or null if no send has occurred.
+ *
+ * @returns {{ ok: boolean, at: string, info: string|null } | null}
+ */
+export function getLastSendResult() {
+    return lastSendResult;
+}
+
+/**
+ * Record the outcome of an email send for health reporting.
+ *
+ * @param {boolean} ok
+ * @param {string|null} info
+ * @returns {void}
+ */
+function recordSendResult(ok, info) {
+    lastSendResult = {
+        ok,
+        at: new Date().toISOString(),
+        info: info || null
+    };
+}
+
+/**
+ * Escape HTML special characters for safe use in email bodies.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+export function escapeHtml(str) {
+    return String(str)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+
+/**
+ * Create a nodemailer transport.
+ * Falls back to an Ethereal test account when no SMTP host is configured.
+ *
+ * @param {{ host: string, port: number, secure: boolean, user: string, pass: string }} smtp
+ * @returns {Promise<import('nodemailer').Transporter>}
+ * @throws {Error} If Ethereal test account creation fails.
+ */
+export async function createTransport(smtp) {
+    if (smtp?.host) {
+        return nodemailer.createTransport({
+            host: smtp.host,
+            port: smtp.port || 587,
+            secure: smtp.secure || false,
+            auth: smtp.user ? { user: smtp.user, pass: smtp.pass } : undefined,
+            tls: { rejectUnauthorized: false }
+        });
+    }
+
+    // No SMTP configured — use Ethereal for dev/demo
+    const testAccount = await nodemailer.createTestAccount();
+    console.log('[email] No SMTP configured. Using Ethereal test account:', testAccount.user);
+    return nodemailer.createTransport({
+        host: 'smtp.ethereal.email',
+        port: 587,
+        secure: false,
+        auth: { user: testAccount.user, pass: testAccount.pass }
+    });
+}
+
+/**
+ * Send a generic transactional email.
+ *
+ * @param {import('nodemailer').Transporter} transport
+ * @param {{ from: string, fromName: string, to: string, subject: string, html: string, text: string }} opts
+ * @returns {Promise<void>}
+ * @throws {Error} If sending the email fails.
+ */
+export async function sendEmail(transport, {from, fromName, to, subject, html, text}) {
+    try {
+        const info = await transport.sendMail({
+            from: `"${fromName}" <${from}>`,
+            to,
+            subject,
+            text,
+            html
+        });
+        recordSendResult(true, info.messageId);
+
+        const previewUrl = nodemailer.getTestMessageUrl(info);
+        if (previewUrl) {
+            console.log('[email] Preview URL:', previewUrl);
+        }
+        return info;
+    } catch (err) {
+        recordSendResult(false, err.message);
+        throw err;
+    }
+}
+
+/**
+ * Send an HTML + plain-text form submission notification email.
+ * Builds a generic table of field→value pairs from the submitted data.
+ *
+ * @param {import('nodemailer').Transporter} transport
+ * @param {{ from: string, fromName: string, to: string, subject: string, formTitle: string, fields: Array<{name: string, label: string}>, data: Record<string, unknown> }} opts
+ * @returns {Promise<void>}
+ * @throws {Error} If sending the email fails.
+ */
+export async function sendFormEmail(transport, { from, fromName, to, subject, formTitle, fields, data }) {
+    const rows = fields.map(field => {
+        const val  = data[field.name] ?? '';
+        const safe = escapeHtml(String(val)).replace(/\n/g, '<br>');
+        const safeLabel = escapeHtml(field.label || field.name);
+        return `
+        <tr>
+            <td style="padding:8px 12px;font-weight:600;background:#f9f9f9;border:1px solid #eee;white-space:nowrap;vertical-align:top;">${safeLabel}</td>
+            <td style="padding:8px 12px;border:1px solid #eee;vertical-align:top;">${safe}</td>
+        </tr>`.trim();
+    }).join('\n');
+
+    const plainRows = fields.map(field => {
+        const val = data[field.name] ?? '';
+        return `${field.label || field.name}: ${val}`;
+    }).join('\n');
+
+    const html = `
+<!DOCTYPE html>
+<html>
+<body style="font-family:sans-serif;max-width:640px;margin:0 auto;padding:20px;">
+    <h2 style="color:#333;margin-bottom:4px;">New Form Submission</h2>
+    <p style="color:#888;margin-top:0;font-size:.9rem;">${escapeHtml(formTitle)}</p>
+    <table style="width:100%;border-collapse:collapse;margin-top:16px;">
+        ${rows}
+    </table>
+</body>
+</html>`.trim();
+
+    const text = `New form submission: ${formTitle}\n\n${plainRows}`;
+
+    try {
+        const info = await transport.sendMail({
+            from: `"${fromName}" <${from}>`,
+            to,
+            subject,
+            text,
+            html
+        });
+        recordSendResult(true, info.messageId);
+
+        const previewUrl = nodemailer.getTestMessageUrl(info);
+        if (previewUrl) {
+            console.log('[email] Preview URL:', previewUrl);
+        }
+        return info;
+    } catch (err) {
+        recordSendResult(false, err.message);
+        throw err;
+    }
+}

package/server/services/presetCollections.js

@@ -51,6 +51,7 @@ const PRESETS = [
             {name: 'icon',        label: 'Icon',        type: 'text',     default: 'folder'},
             {name: 'rootUrl',     label: 'Root URL',    type: 'text'},
             {name: 'sortOrder',   label: 'Sort Order',  type: 'number',   default: 0},
+            {name: 'enabled',     label: 'Enabled',     type: 'boolean',  default: true},
             {name: 'protected',   label: 'Protected',   type: 'boolean',  default: false}
         ],
         api: {

package/server/services/projects.js

@@ -36,6 +36,23 @@ const CORE_PROJECT_SEED = {
     icon:        'home',
     rootUrl:     '/',
     sortOrder:   -1,
+    enabled:     true,
+    protected:   true
+};
+
+/** Slug of the built-in, disabled-by-default documentation project. */
+export const DOCS_PROJECT_SLUG = 'domma-docs';
+
+/** Seed record for the Domma Docs project (created at boot if absent). */
+const DOCS_PROJECT_SEED = {
+    slug:        DOCS_PROJECT_SLUG,
+    name:        'Domma Docs',
+    description: 'The Domma CMS handbook — guides, tutorials, component & API ' +
+                 'reference. Switch on to publish it on your own site.',
+    icon:        'document',
+    rootUrl:     '/domma-docs',
+    sortOrder:   0,
+    enabled:     false,
     protected:   true
 };
 
@@ -105,6 +122,7 @@ export async function createProject(input) {
         icon:        input.icon        || 'folder',
         ...(input.rootUrl != null && {rootUrl: input.rootUrl}),
         sortOrder:   Number.isFinite(input.sortOrder) ? input.sortOrder : 0,
+        enabled:     input.enabled !== false,
         ...(typeof input.createdBy === 'string' && input.createdBy.trim() && {createdBy: input.createdBy.trim()}),
         createdAt:   now,
         updatedAt:   now
@@ -127,8 +145,9 @@ export async function seedCoreProject() {
     const {entries} = await listEntries(PROJECTS_COLLECTION_SLUG, {limit: 0});
     const existing = entries.find(e => e.data?.slug === CORE_PROJECT_SLUG);
     if (existing) {
-        if (existing.data.protected === true) return normalise(existing);
-        const adopted = {...existing.data, protected: true, updatedAt: new Date().toISOString()};
+        // Core is always protected and always enabled — adopt both invariants.
+        if (existing.data.protected === true && existing.data.enabled !== false) return normalise(existing);
+        const adopted = {...existing.data, protected: true, enabled: true, updatedAt: new Date().toISOString()};
         await updateEntry(PROJECTS_COLLECTION_SLUG, existing.id, adopted);
         return adopted;
     }
@@ -138,6 +157,24 @@ export async function seedCoreProject() {
     return data;
 }
 
+/**
+ * Seed the built-in Domma Docs project at boot. Create-if-absent by slug — an
+ * existing record (including the admin's enabled/disabled choice and any edits)
+ * is returned untouched. Disabled by default: a fresh site ships with the docs
+ * off until an admin enables the project.
+ *
+ * @returns {Promise<object>} The docs project record.
+ */
+export async function seedDocsProject() {
+    const {entries} = await listEntries(PROJECTS_COLLECTION_SLUG, {limit: 0});
+    const existing = entries.find(e => e.data?.slug === DOCS_PROJECT_SLUG);
+    if (existing) return normalise(existing);
+    const now = new Date().toISOString();
+    const data = {...DOCS_PROJECT_SEED, createdAt: now, updatedAt: now};
+    await createEntry(PROJECTS_COLLECTION_SLUG, data);
+    return data;
+}
+
 /**
  * Update a project. Slug is immutable. Preserves createdAt; bumps updatedAt.
  * The core project's `rootUrl` and `protected` flag are locked; its name,
@@ -159,6 +196,9 @@ export async function updateProject(slug, input) {
         if (input.protected != null && input.protected !== existing.protected) {
             throw new Error("Cannot change the core project's protected flag");
         }
+        if (input.enabled === false) {
+            throw new Error('Cannot disable the core project');
+        }
     }
     const merged = {
         ...existing,
@@ -167,6 +207,7 @@ export async function updateProject(slug, input) {
         ...(input.icon        != null && {icon:        input.icon}),
         ...(input.rootUrl     != null && {rootUrl:     input.rootUrl}),
         ...(Number.isFinite(input.sortOrder) && {sortOrder: input.sortOrder}),
+        ...(typeof input.enabled === 'boolean' && {enabled: input.enabled}),
         slug,
         createdAt: existing.createdAt,
         updatedAt: new Date().toISOString()
@@ -196,6 +237,9 @@ export async function deleteProject(slug) {
     const {entries} = await listEntries(PROJECTS_COLLECTION_SLUG, {limit: 0});
     const entry = entries.find(e => e.data?.slug === slug);
     if (!entry) return false;
+    if (entry.data?.protected === true) {
+        throw new Error(`Cannot delete the protected "${slug}" project`);
+    }
     await deleteEntry(PROJECTS_COLLECTION_SLUG, entry.id);
     return true;
 }
@@ -229,7 +273,28 @@ export function validateProject(project) {
 }
 
 function normalise(entry) {
-    return {...(entry.data || {})};
+    const data = entry.data || {};
+    // `enabled` is default-on: legacy records (and any record missing the
+    // field) are treated as enabled. Only an explicit `false` disables.
+    return {...data, enabled: data.enabled !== false};
+}
+
+/**
+ * Whether the given project is enabled (i.e. not switched off). A disabled
+ * project is a hard kill-switch on its PUBLIC surfaces — public pages 404 and
+ * its external API (collections + custom endpoints + tokens) is refused.
+ *
+ * The core project is always enabled. An unknown slug resolves to core by
+ * fallback elsewhere, so it is reported enabled here (never a block).
+ *
+ * @param {string} slug
+ * @returns {Promise<boolean>}
+ */
+export async function isProjectEnabled(slug) {
+    if (!slug || slug === CORE_PROJECT_SLUG) return true;
+    const project = await getProject(slug);
+    if (!project) return true;
+    return project.enabled !== false;
 }
 
 /**
@@ -455,6 +520,10 @@ export async function untagAllForProject(projectSlug) {
     if (projectSlug === CORE_PROJECT_SLUG) {
         throw new Error('Cannot untag the core project — artefacts would immediately resolve back to it');
     }
+    const proj = await getProject(projectSlug);
+    if (proj?.protected === true) {
+        throw new Error(`Cannot untag the protected "${projectSlug}" project — its pages would resolve back to core`);
+    }
     const counts = {
         pages: 0, collections: 0, forms: 0, actions: 0,
         menus: 0, blocks: 0, components: 0, views: 0, roles: 0, users: 0, apis: 0

package/server/services/sidebar-migration.js

@@ -63,13 +63,80 @@ const SEED_ITEMS = [
     {
         text: 'Documentation', icon: 'book',
         items: [
-            {text: 'Usage',         url: '#/documentation',  icon: 'book'},
-            {text: 'Tutorials',     url: '#/tutorials',      icon: 'document'},
-            {text: 'API Reference', url: '#/api-reference',  icon: 'code'}
+            DOC_USAGE_SUBMENU(),
+            DOC_TUTORIALS_SUBMENU(),
+            DOC_COMPONENTS_SUBMENU(),
+            DOC_API_SUBMENU()
         ]
     }
 ];
 
+// ─── Documentation sub-trees ──────────────────────────────────────────────
+// Defined as factory functions so the seed and the migration each get their
+// own fresh object (never a shared reference). Used by both SEED_ITEMS (fresh
+// installs) and ensureDocumentationSubmenus() (existing installs).
+
+function DOC_USAGE_SUBMENU() {
+    return {
+        text: 'Usage', icon: 'book',
+        items: [
+            {text: 'Pages',         url: '#/docs/usage/pages',         icon: 'file-text'},
+            {text: 'Media',         url: '#/docs/usage/media',         icon: 'image'},
+            {text: 'Navigation',    url: '#/docs/usage/navigation',    icon: 'menu'},
+            {text: 'DConfig',       url: '#/docs/usage/dconfig',       icon: 'settings'},
+            {text: 'Shortcodes',    url: '#/docs/usage/shortcodes',    icon: 'code'},
+            {text: 'Site Settings', url: '#/docs/usage/site-settings', icon: 'settings'},
+            {text: 'Plugins',       url: '#/docs/usage/plugins',       icon: 'package'},
+            {text: 'Users & Roles', url: '#/docs/usage/users-roles',   icon: 'users'},
+            {text: 'Views',         url: '#/docs/usage/views',         icon: 'eye'},
+            {text: 'Actions',       url: '#/docs/usage/actions',       icon: 'zap'},
+            {text: 'CTA Shortcode', url: '#/docs/usage/cta-shortcode', icon: 'zap'}
+        ]
+    };
+}
+
+function DOC_TUTORIALS_SUBMENU() {
+    return {
+        text: 'Tutorials', icon: 'document',
+        items: [
+            {text: 'Building a CRUD App', url: '#/tutorials/crud',   icon: 'database'},
+            {text: 'Writing a Plugin',    url: '#/tutorials/plugin', icon: 'package'},
+            {text: 'Form Follow-Up',      url: '#/tutorials/forms',  icon: 'layout'}
+        ]
+    };
+}
+
+function DOC_COMPONENTS_SUBMENU() {
+    return {
+        text: 'Components', icon: 'component',
+        items: [
+            {text: 'Reference',   url: '#/docs/components',             icon: 'book'},
+            {text: 'How-To',      url: '#/docs/components-howto',       icon: 'zap'},
+            {text: 'Walkthrough', url: '#/docs/components-walkthrough', icon: 'document'},
+            {text: 'Rules',       url: '#/docs/components-rules',       icon: 'shield'}
+        ]
+    };
+}
+
+function DOC_API_SUBMENU() {
+    return {
+        text: 'API Reference', icon: 'code',
+        items: [
+            {text: 'Authentication', url: '#/docs/api/authentication', icon: 'shield'},
+            {text: 'Pages',          url: '#/docs/api/pages',          icon: 'file-text'},
+            {text: 'Settings',       url: '#/docs/api/settings',       icon: 'settings'},
+            {text: 'Layouts',        url: '#/docs/api/layouts',        icon: 'layout'},
+            {text: 'Navigation',     url: '#/docs/api/navigation',     icon: 'menu'},
+            {text: 'Media',          url: '#/docs/api/media',          icon: 'image'},
+            {text: 'Users',          url: '#/docs/api/users',          icon: 'users'},
+            {text: 'Plugins',        url: '#/docs/api/plugins',        icon: 'package'},
+            {text: 'Collections',    url: '#/docs/api/collections',    icon: 'database'},
+            {text: 'Views API',      url: '#/docs/api/views',          icon: 'eye'},
+            {text: 'Actions API',    url: '#/docs/api/actions',        icon: 'zap'}
+        ]
+    };
+}
+
 async function exists(p) {
     try { await fs.access(p); return true; } catch { return false; }
 }
@@ -160,3 +227,78 @@ export async function ensureSidebarItem({groupText, item}, opts = {}) {
     console.log(`[admin-sidebar] Added "${item.text}" to the ${groupText} group`);
     return {ensured: true};
 }
+
+/**
+ * Upgrade EXISTING installs so the Documentation group's one-page docs become
+ * per-topic submenus. Idempotent and non-clobbering:
+ *
+ *  - If the persisted menu has no "Documentation" group, do nothing (the admin
+ *    may have removed it deliberately — don't resurrect it).
+ *  - Convert each flat leaf — "Usage" (`#/documentation`), "Tutorials"
+ *    (`#/tutorials`) and "API Reference" (`#/api-reference`) — into its
+ *    submenu, replacing the node in place so its position is preserved. A leaf
+ *    that the admin already turned into a parent, or whose new pages already
+ *    appear anywhere in the group, is left untouched.
+ *  - Add the Components submenu only if `#/docs/components` isn't present yet —
+ *    inserted before "API Reference" when that node exists.
+ *
+ * Returns `{updated: boolean, reason?: string}`.
+ *
+ * @param {{configDir?: string}} [opts]
+ */
+export async function ensureDocumentationSubmenus(opts = {}) {
+    const configDir = opts.configDir || DEFAULT_CONFIG_DIR;
+    const menuPath  = path.join(configDir, 'menus', 'admin-sidebar.json');
+
+    if (!await exists(menuPath)) {
+        return {updated: false, reason: 'admin-sidebar.json not present'};
+    }
+
+    const menu  = await readJson(menuPath);
+    const items = Array.isArray(menu.items) ? menu.items : [];
+    const docGroup = items.find(n => typeof n?.text === 'string' && n.text.toLowerCase() === 'documentation');
+    if (!docGroup || !Array.isArray(docGroup.items)) {
+        return {updated: false, reason: 'no Documentation group'};
+    }
+
+    const hasUrl = (nodes, url) => Array.isArray(nodes) &&
+        nodes.some(n => n?.url === url || hasUrl(n?.items, url));
+    const findByText = (text) => docGroup.items.findIndex(n =>
+        typeof n?.text === 'string' && n.text.toLowerCase() === text.toLowerCase());
+
+    let changed = false;
+
+    // Leaf → submenu conversions. `guardUrl` is a page from the submenu: if it's
+    // already present anywhere we've migrated before and skip.
+    const CONVERSIONS = [
+        {text: 'Usage',         guardUrl: '#/docs/usage/pages',         build: DOC_USAGE_SUBMENU},
+        {text: 'Tutorials',     guardUrl: '#/tutorials/crud',           build: DOC_TUTORIALS_SUBMENU},
+        {text: 'API Reference', guardUrl: '#/docs/api/authentication',  build: DOC_API_SUBMENU}
+    ];
+    for (const {text, guardUrl, build} of CONVERSIONS) {
+        if (hasUrl(docGroup.items, guardUrl)) continue;
+        const idx = findByText(text);
+        if (idx === -1) continue;
+        const node = docGroup.items[idx];
+        const alreadyParent = Array.isArray(node.items) && node.items.length > 0;
+        if (alreadyParent) continue;
+        docGroup.items[idx] = build();
+        changed = true;
+    }
+
+    // Components submenu — add if absent, before API Reference.
+    if (!hasUrl(docGroup.items, '#/docs/components')) {
+        const apiIdx = findByText('API Reference');
+        const node = DOC_COMPONENTS_SUBMENU();
+        if (apiIdx !== -1) docGroup.items.splice(apiIdx, 0, node);
+        else docGroup.items.push(node);
+        changed = true;
+    }
+
+    if (!changed) return {updated: false, reason: 'already up to date'};
+
+    menu.meta = {...(menu.meta || {}), updatedAt: new Date().toISOString()};
+    await writeJson(menuPath, menu);
+    console.log('[admin-sidebar] Upgraded Documentation group with per-topic submenus');
+    return {updated: true};
+}