domma-cms 0.30.0 → 0.32.1

package/{scripts/migrate-docs.js → server/services/docs.js}

@@ -1,26 +1,39 @@
 /**
- * One-shot porter: admin documentation screens → public page artefacts under
- * the Domma Docs project. Reads each admin HTML template, strips the admin-only
- * view header, wraps the body in page frontmatter tagged `project: domma-docs`,
- * and writes content/pages/domma-docs/<path>.md. Re-runnable (overwrites).
+ * Domma Docs — request-time renderer
  *
- * Run: node scripts/migrate-docs.js
+ * Serves the Domma CMS handbook at /domma-docs/* directly from the admin doc
+ * HTML templates (admin/js/templates/docs/*.html) at request time. There is no
+ * baked content: a domma-cms version bump ships new templates and the docs
+ * update everywhere automatically — no porter, no per-site provisioning, no
+ * staleness. (Replaces the one-shot scripts/migrate-docs.js bake.)
+ *
+ * The publish switch is the `domma-docs` project's enabled flag, enforced by
+ * the route (server/routes/docs-public.js); this service only renders.
+ *
+ * Pipeline per leaf page: read template → strip admin chrome → rewrite links →
+ * extract inline <style> → dedent → escape code brackets → structure body into
+ * native Domma shortcodes ([card]/[tabs]/[accordion]) → wrap with hero, nav,
+ * breadcrumb and prev/next → parseMarkdown → renderPage. Section landing pages
+ * (/domma-docs and the Usage/Tutorials/API indexes) are synthesized from the
+ * MAP so the nav never links to a 404.
  */
-import {mkdirSync, readFileSync, writeFileSync} from 'node:fs';
-import {dirname, join} from 'node:path';
+import {readFile} from 'node:fs/promises';
+import {fileURLToPath} from 'node:url';
+import {dirname, join, resolve} from 'node:path';
 
-const TPL = 'admin/js/templates/docs';
-const OUT = 'content/pages/domma-docs';
-const CUSTOM_CSS = 'content/custom.css';
+import {parseMarkdown} from './markdown.js';
+import {renderPage} from './renderer.js';
+import * as cache from './cache/index.js';
 
-// Page chrome (hero, cards, grid, buttons) uses native Domma shortcode
-// components — see wrapPage() and the landing pages — so they get the framework's
-// own designs and effects. The only custom CSS we keep is whatever inline
-// <style> the templates carried (e.g. API method badges), collected below. Set
-// to '' so no hand-rolled layout CSS competes with Domma's components.
-// Only functional nav chrome (breadcrumb + prev/next bar) — Domma has no
-// Markdown breadcrumb component. Everything else (hero, cards, tabs, accordion,
-// buttons) is a native Domma component. Token-based so it follows the theme.
+// import.meta.url-relative (NOT cwd-relative): the templates live beside the
+// engine's admin dir in both the npm-package layout and each child site's
+// physical copy. server/services/docs.js → ../../admin/js/templates/docs.
+const TPL_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '../..', 'admin/js/templates/docs');
+
+// Functional nav chrome only (breadcrumb + prev/next + section nav). Everything
+// else (hero, cards, tabs, accordion, buttons) is a native Domma component, so
+// it follows the theme. Injected as an inline <style> per docs page at render
+// time — no dependency on content/custom.css.
 const DOCS_BODY_CSS = `.doc-breadcrumb { display: flex; flex-wrap: wrap; gap: .5rem; align-items: center; max-width: 80ch; margin: 0 auto 1.25rem; font-size: .85rem; color: var(--dm-text-muted); }
 .doc-breadcrumb a { color: var(--dm-primary); text-decoration: none; }
 .doc-breadcrumb a:hover { text-decoration: underline; }
@@ -29,11 +42,7 @@ const DOCS_BODY_CSS = `.doc-breadcrumb { display: flex; flex-wrap: wrap; gap: .5
 .doc-pagenav .btn-secondary { margin-inline: auto; }
 .doc-nav { display: flex; flex-wrap: wrap; gap: .4rem; justify-content: center; max-width: 80ch; margin: 0 auto 1.75rem; padding: .5rem; border: 1px solid var(--dm-card-border, var(--dm-border)); border-radius: var(--dm-radius-lg, 14px); background: var(--dm-card-bg, var(--dm-surface)); }`;
 
-// Inline <style> blocks pulled out of the templates are accumulated here
-// (deduped) and written to custom.css with the base styles.
-const collectedStyles = new Set();
-
-// template basename → {path (URL tail = file path), title}
+// template basename → [url tail (= file path), title]
 const MAP = [
     ['usage-pages',          'usage/pages',          'Pages'],
     ['usage-media',          'usage/media',          'Media'],
@@ -66,18 +75,9 @@ const MAP = [
     ['api-actions',          'api/actions',          'Actions API']
 ];
 
-// Drop the admin-only header block (<div class="view-header"> ... </div>).
-// The header contains no nested <div>, so a non-greedy match to the first
-// </div> is correct.
-function stripHeader(html) {
-    return html.replace(/<div class="view-header">[\s\S]*?<\/div>\s*/, '');
-}
-
-// The admin templates link with admin-SPA hash routes (#/…) and stale
-// /resources/… paths, none of which resolve on the public site. Rewrite them:
-// doc-to-doc links → public /domma-docs/… paths; admin-feature links → the
-// admin SPA (/admin#/…); resources links with a doc equivalent → that doc; the
-// rest of /resources/… (no equivalent) are unwrapped to plain text.
+// Admin-SPA hash routes and stale /resources/… paths don't resolve on the
+// public site — rewrite doc-to-doc links to /domma-docs/…, admin-feature links
+// to the admin SPA, and unwrap the rest.
 const LINK_MAP = {
     '#/docs/components-walkthrough': '/domma-docs/components/walkthrough',
     '#/docs/components-rules':       '/domma-docs/components/rules',
@@ -96,6 +96,39 @@ const LINK_MAP = {
     '/resources/shortcodes':         '/domma-docs/usage/shortcodes',
     '/resources/components':         '/domma-docs/components'
 };
+
+// The four top-level doc sections — rendered as a persistent nav on every page.
+const SECTIONS = [
+    {label: 'Usage',         href: '/domma-docs/usage'},
+    {label: 'Tutorials',     href: '/domma-docs/tutorials'},
+    {label: 'Components',    href: '/domma-docs/components'},
+    {label: 'API Reference', href: '/domma-docs/api'}
+];
+
+// Section landing pages keyed by url tail → section label. The Components
+// landing is the Components Reference leaf (MAP tail 'components'), so it is
+// NOT synthesized here.
+const LANDINGS = {
+    '':          'Home',
+    'usage':     'Usage',
+    'tutorials': 'Tutorials',
+    'api':       'API Reference'
+};
+
+// ── pure transform helpers (relocated from scripts/migrate-docs.js) ──────────
+
+function escText(s) {
+    return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function heroAttr(s) {
+    return String(s).replace(/"/g, '&quot;');
+}
+
+// Drop the admin-only header block (<div class="view-header"> … </div>).
+function stripHeader(html) {
+    return html.replace(/<div class="view-header">[\s\S]*?<\/div>\s*/, '');
+}
+
 function rewriteLinks(html) {
     let out = html;
     for (const [from, to] of Object.entries(LINK_MAP)) {
@@ -106,22 +139,22 @@ function rewriteLinks(html) {
     return out;
 }
 
-// Pull every inline <style> block out of the body (collecting its CSS for
-// custom.css) so no styling is lumped into the page content.
+// Pull every inline <style> block out of the body, returning the cleaned HTML
+// plus the extracted (deduped) CSS — collected PER CALL (no shared module state,
+// which would leak across requests in a long-lived server).
 function stripStyleBlocks(html) {
-    return html.replace(/<style\b[^>]*>([\s\S]*?)<\/style>\s*/gi, (_m, css) => {
+    const styles = new Set();
+    const out = html.replace(/<style\b[^>]*>([\s\S]*?)<\/style>\s*/gi, (_m, css) => {
         const trimmed = css.trim();
-        if (trimmed) collectedStyles.add(trimmed);
+        if (trimmed) styles.add(trimmed);
         return '';
     });
+    return {html: out, styles: [...styles]};
 }
 
-// The admin templates are deeply indented. Markdown treats any line indented
-// 4+ spaces as a code block, which would render the structural HTML (tables,
-// divs, headings) as escaped source text. Strip leading indentation from every
-// line OUTSIDE <pre> blocks so each structural tag starts at column 0 and marked
-// passes it through as raw HTML. Inside <pre>, whitespace is significant (code
-// samples) and is preserved verbatim.
+// Markdown treats any line indented 4+ spaces as a code block. Strip leading
+// indentation OUTSIDE <pre> so structural HTML passes through as raw HTML;
+// inside <pre> whitespace is significant and preserved.
 function dedentOutsidePre(html) {
     const parts = html.split(/(<pre\b[^>]*>[\s\S]*?<\/pre>)/gi);
     return parts.map((part, i) =>
@@ -129,59 +162,16 @@ function dedentOutsidePre(html) {
     ).join('');
 }
 
-// Shortcode examples in the docs live inside <code>/<pre>. The render pipeline's
-// code-scrubber protects <pre> and backtick spans but NOT bare inline <code>,
-// so examples like [grid cols="N"]...[/grid] in table cells would be expanded
-// as real shortcodes. Escape square brackets inside every <pre> and <code>
-// region so all examples render literally on the public page.
+// Escape square brackets inside <pre> and <code> so shortcode examples render
+// literally instead of being expanded by the render pipeline.
 function escapeCodeBrackets(html) {
     const esc = (region) => region.replace(/\[/g, '&#91;').replace(/\]/g, '&#93;');
-    html = html.replace(/<pre\b[^>]*>[\s\S]*?<\/pre>/gi, esc);   // <pre> first (incl. nested <code>)
-    html = html.replace(/<code\b[^>]*>[\s\S]*?<\/code>/gi, esc); // then standalone inline <code>
+    html = html.replace(/<pre\b[^>]*>[\s\S]*?<\/pre>/gi, esc);
+    html = html.replace(/<code\b[^>]*>[\s\S]*?<\/code>/gi, esc);
     return html;
 }
 
-function frontmatter(title) {
-    return `---\ntitle: ${title}\nlayout: default\nstatus: published\nvisibility: public\nproject: domma-docs\n---\n\n`;
-}
-
-// The four top-level doc sections — rendered as a persistent nav on every page.
-const SECTIONS = [
-    {label: 'Usage',         href: '/domma-docs/usage'},
-    {label: 'Tutorials',     href: '/domma-docs/tutorials'},
-    {label: 'Components',    href: '/domma-docs/components'},
-    {label: 'API Reference', href: '/domma-docs/api'}
-];
-
-// Persistent section nav (Home + the four sections, current one highlighted).
-// Rendered just under the hero on every doc page so navigation is always present.
-function docNav(activeLabel) {
-    const links = [{label: 'Home', href: '/domma-docs'}, ...SECTIONS].map(s => {
-        const active = s.label === activeLabel;
-        return `<a class="btn btn-sm ${active ? 'btn-primary' : 'btn-ghost'}" href="${s.href}">${escText(s.label)}</a>`;
-    }).join('');
-    return `<nav class="doc-nav">${links}</nav>`;
-}
-
-// Section label + landing URL for the hero eyebrow, derived from the page path.
-function sectionFor(path) {
-    if (path.startsWith('usage/'))     return {label: 'Usage',         href: '/domma-docs/usage'};
-    if (path.startsWith('tutorials/')) return {label: 'Tutorials',     href: '/domma-docs/tutorials'};
-    if (path.startsWith('api/'))       return {label: 'API Reference', href: '/domma-docs/api'};
-    if (path === 'components' || path.startsWith('components/')) return {label: 'Components', href: '/domma-docs/components'};
-    return {label: 'Documentation', href: '/domma-docs'};
-}
-
-function heroAttr(s) {
-    return String(s).replace(/"/g, '&quot;');
-}
-function escText(s) {
-    return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-}
-
-// Every template wraps its content in a consistent .row > .col-12 > .docs-body
-// shell (opening at the top, three closing </div> at the very end). Strip it to
-// get the bare inner content so we can split it into sections.
+// Strip the consistent .row > .col-12 > .docs-body shell to get the bare inner.
 function unwrapDocsBody(html) {
     return html.trim()
         .replace(/^<div class="row">\s*<div class="col-12">\s*<div class="docs-body">/, '')
@@ -189,7 +179,7 @@ function unwrapDocsBody(html) {
         .trim();
 }
 
-// Plain-text heading title, safe to use as a shortcode attribute value.
+// Plain-text heading title, safe as a shortcode attribute value.
 function headingText(inner) {
     return inner.replace(/<[^>]+>/g, '')
         .replace(/&amp;/g, '&').replace(/&mdash;/g, '—').replace(/&ndash;/g, '–')
@@ -210,9 +200,7 @@ function splitSections(inner, level) {
     return {preamble, sections};
 }
 
-// Turn the body into native Domma components. ≥7 sections → accordion (a long
-// scannable reference); 2–6 → tabs (first pane shown, rest a click away); <2 →
-// a single card. Any preamble before the first heading leads in its own card.
+// ≥7 sections → accordion; 2–6 → tabs; <2 → a single card.
 function structureBody(body) {
     const inner = unwrapDocsBody(body);
     const level = /<h2\b/i.test(inner) ? 2 : 3;
@@ -227,8 +215,26 @@ function structureBody(body) {
         sections.map(s => `[item title="${s.title}"]\n${s.body}\n[/item]`).join('\n') + '\n[/accordion]';
 }
 
-// Assemble a content page: full-width hero, breadcrumb, structured body, and a
-// prev / back-to-section / next nav bar (Domma .btn styles).
+// Persistent section nav (Home + the four sections, current one highlighted).
+function docNav(activeLabel) {
+    const links = [{label: 'Home', href: '/domma-docs'}, ...SECTIONS].map(s => {
+        const active = s.label === activeLabel;
+        return `<a class="btn btn-sm ${active ? 'btn-primary' : 'btn-ghost'}" href="${s.href}">${escText(s.label)}</a>`;
+    }).join('');
+    return `<nav class="doc-nav">${links}</nav>`;
+}
+
+// Section label + landing URL for the hero eyebrow, derived from the page path.
+function sectionFor(path) {
+    if (path.startsWith('usage/'))     return {label: 'Usage',         href: '/domma-docs/usage'};
+    if (path.startsWith('tutorials/')) return {label: 'Tutorials',     href: '/domma-docs/tutorials'};
+    if (path.startsWith('api/'))       return {label: 'API Reference', href: '/domma-docs/api'};
+    if (path === 'components' || path.startsWith('components/')) return {label: 'Components', href: '/domma-docs/components'};
+    return {label: 'Documentation', href: '/domma-docs'};
+}
+
+// Assemble a leaf page: hero, persistent nav, breadcrumb, structured body, and
+// a prev / back-to-section / next nav bar.
 function buildPage(section, title, body, prev, next) {
     const hero = `[hero title="${heroAttr(title)}" tagline="${heroAttr(section.label)}" variant="gradient" align="center" fullwidth="true"][/hero]`;
     const nav = docNav(section.label);
@@ -242,39 +248,111 @@ function buildPage(section, title, body, prev, next) {
     return `${hero}\n\n${nav}\n\n${crumb}\n\n${structureBody(body)}\n\n${pagenav}`;
 }
 
-let n = 0;
-for (let i = 0; i < MAP.length; i++) {
-    const [tpl, path, title] = MAP[i];
+// ── landing pages ────────────────────────────────────────────────────────────
+
+// Build a section landing body: hero + nav + a grid of cards linking each leaf.
+function buildSectionLanding(label) {
+    const section = SECTIONS.find(s => s.label === label);
+    const pages = MAP.filter(m => sectionFor(m[1]).label === label);
+    const hero = `[hero title="${heroAttr(label)}" tagline="Domma Docs" variant="gradient" align="center" fullwidth="true"][/hero]`;
+    const cards = pages.map(([, tail, title]) =>
+        `[card]\n### ${escText(title)}\n\n[button label="Read ${heroAttr(title)} →" href="/domma-docs/${tail}" variant="ghost" /]\n[/card]`
+    ).join('\n');
+    return {title: label, body: `${hero}\n\n${docNav(label)}\n\n[grid cols="3"]\n${cards}\n[/grid]`};
+}
+
+// Build the home landing: hero + nav + a card per top-level section.
+function buildHomeLanding() {
+    const hero = `[hero title="Domma Docs" tagline="The Domma CMS handbook" variant="gradient" align="center" fullwidth="true"][/hero]`;
+    const cards = [
+        {label: 'Usage',         href: '/domma-docs/usage',      icon: 'book-open',     blurb: 'Day-to-day guides for running the CMS — pages, media, navigation, shortcodes and more.'},
+        {label: 'Tutorials',     href: '/domma-docs/tutorials',  icon: 'academic-cap',  blurb: 'Step-by-step walkthroughs that build something real from start to finish.'},
+        {label: 'Components',    href: '/domma-docs/components', icon: 'puzzle',        blurb: 'The full component reference — shortcodes, how-tos, walkthroughs and rules.'},
+        {label: 'API Reference', href: '/domma-docs/api',        icon: 'code',          blurb: 'Every REST endpoint for headless and external integrations.'}
+    ].map(s =>
+        `[card icon="${s.icon}" title="${heroAttr(s.label)}"]\n${escText(s.blurb)}\n\n[button label="Browse ${heroAttr(s.label)} →" href="${s.href}" variant="primary" /]\n[/card]`
+    ).join('\n');
+    return {title: 'Documentation', body: `${hero}\n\n${docNav('Home')}\n\n[grid cols="2"]\n${cards}\n[/grid]`};
+}
+
+// ── render ───────────────────────────────────────────────────────────────────
+
+// Build the shortcode body for a doc path, or null if the path is unknown.
+// Returns {title, body, styles[]} — `styles` is the inline CSS extracted from a
+// leaf template (empty for synthesized landings).
+async function buildDocBody(docPath) {
+    if (docPath in LANDINGS) {
+        const built = docPath === '' ? buildHomeLanding() : buildSectionLanding(LANDINGS[docPath]);
+        return {...built, styles: []};
+    }
+    const entry = MAP.find(m => m[1] === docPath);
+    if (!entry) return null;
+    const [tpl, path, title] = entry;
+    let src;
+    try {
+        src = await readFile(join(TPL_DIR, `${tpl}.html`), 'utf8');
+    } catch {
+        return null; // template missing — treat as a 404
+    }
+    const {html: stripped, styles} = stripStyleBlocks(stripHeader(src));
+    const body = escapeCodeBrackets(dedentOutsidePre(rewriteLinks(stripped))).trim();
     const section = sectionFor(path);
-    const src  = readFileSync(join(TPL, `${tpl}.html`), 'utf8');
-    const body = escapeCodeBrackets(dedentOutsidePre(rewriteLinks(stripStyleBlocks(stripHeader(src))))).trim();
     // prev / next are the section-mates either side of this page in MAP order.
     const mates = MAP.filter(m => sectionFor(m[1]).label === section.label);
     const mi = mates.findIndex(m => m[1] === path);
     const prev = mi > 0 ? mates[mi - 1] : null;
     const next = mi >= 0 && mi < mates.length - 1 ? mates[mi + 1] : null;
-    const dest = join(OUT, `${path}.md`);
-    mkdirSync(dirname(dest), {recursive: true});
-    writeFileSync(dest, frontmatter(title) + buildPage(section, title, body, prev, next) + '\n');
-    n++;
+    return {title, body: buildPage(section, title, body, prev, next), styles};
 }
-console.log(`[migrate-docs] wrote ${n} pages to ${OUT}`);
 
-// Write the docs CSS (base + extracted inline styles) into content/custom.css
-// as an idempotent managed block, so styling lives in the custom CSS file
-// rather than being lumped into the pages.
-const BEGIN = '/* >>> Domma Docs styles (managed by scripts/migrate-docs.js) — do not edit between markers >>> */';
-const END   = '/* <<< Domma Docs styles <<< */';
-const cssBody = [DOCS_BODY_CSS, ...collectedStyles].filter(Boolean).join('\n\n');
-const block = `${BEGIN}\n${cssBody}\n${END}`;
+/**
+ * Render a Domma Docs page to full HTML, or return null for an unknown path
+ * (the route turns that into a 404). Cached per path+origin under the static
+ * 'docs' tag — invalidated on boot so a version bump never serves stale HTML.
+ *
+ * @param {string} docPath  url tail after /domma-docs (e.g. 'usage/pages', '' for home)
+ * @param {{user?: object|null, baseUrl?: string}} [opts]
+ * @returns {Promise<string|null>}
+ */
+export async function renderDocPage(docPath, opts = {}) {
+    const path = String(docPath || '').replace(/^\/+|\/+$/g, '');
+    const built = await buildDocBody(path);
+    if (!built) return null;
+
+    const {user = null, baseUrl} = opts;
+    return cache.wrap(
+        `docs:${path}:o${baseUrl || ''}`,
+        async () => {
+            const parsed = await parseMarkdown(built.body, {user});
+            const css = [DOCS_BODY_CSS, ...built.styles].filter(Boolean).join('\n\n');
+            const html = `<style>${css}</style>\n${parsed.html}`;
+            const page = {
+                title:          built.title,
+                layout:         'default',
+                status:         'published',
+                visibility:     'public',
+                project:        'domma-docs',
+                urlPath:        `/domma-docs${path ? '/' + path : ''}`,
+                html,
+                usedComponents: parsed.usedComponents || [],
+                dconfig:        parsed.data?.dconfig || null,
+                seo:            {title: built.title},
+                sidebar:        false,
+                tags:           ['docs']
+            };
+            return renderPage(page, {baseUrl, user});
+        },
+        {tags: ['docs']}
+    );
+}
 
-let existing = '';
-try { existing = readFileSync(CUSTOM_CSS, 'utf8'); } catch { /* file may not exist */ }
-const blockRe = new RegExp(
-    BEGIN.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '[\\s\\S]*?' + END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-);
-const next = blockRe.test(existing)
-    ? existing.replace(blockRe, block)
-    : (existing.trim() ? existing.trimEnd() + '\n\n' : '') + block + '\n';
-writeFileSync(CUSTOM_CSS, next);
-console.log(`[migrate-docs] wrote docs CSS (${collectedStyles.size} extracted block(s) + base) to ${CUSTOM_CSS}`);
+/**
+ * Every valid doc path (home + 29 leaves + 3 section landings). The Components
+ * landing is the 'components' leaf, already in MAP. `renderDocPage` returning
+ * null is the authoritative miss; this is an enumeration aid (e.g. sitemap).
+ *
+ * @returns {string[]}
+ */
+export function listDocPaths() {
+    return ['', ...MAP.map(m => m[1]), 'usage', 'tutorials', 'api'];
+}