tadforce 0.0.0-stage → 0.3.0

package/src/build/mermaid.js

@@ -0,0 +1,107 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { TEMPLATES } from '../util/paths.js';
+import { getBrowser } from './browser.js';
+
+// Shared colour classes for flowcharts: actors, Salesforce, external systems, data, warnings.
+export const CLASSDEFS = `
+classDef actor fill:#F1E8FF,stroke:#7B3FE4,color:#2A1458,stroke-width:1.2px
+classDef sf fill:#E8F1FF,stroke:#2F6FE4,color:#0B2545,stroke-width:1.2px
+classDef ext fill:#FFF2E2,stroke:#E0861F,color:#4A2A05,stroke-width:1.2px
+classDef data fill:#E7F6EC,stroke:#2E9E5B,color:#0E3B22,stroke-width:1.2px
+classDef warn fill:#FDECEF,stroke:#D6336C,color:#5A0A23,stroke-width:1.2px
+`;
+
+export const MERMAID_CFG = {
+  startOnLoad: false,
+  theme: 'base',
+  securityLevel: 'loose',
+  htmlLabels: false,
+  fontFamily: 'Segoe UI, Arial, sans-serif',
+  themeVariables: {
+    fontFamily: 'Segoe UI, Arial, sans-serif',
+    fontSize: '14px',
+    primaryColor: '#E8F1FF',
+    primaryBorderColor: '#2F6FE4',
+    primaryTextColor: '#0B2545',
+    lineColor: '#5B6B7D',
+    secondaryColor: '#F1E8FF',
+    tertiaryColor: '#F6F8FB',
+    clusterBkg: '#F7F9FC',
+    clusterBorder: '#C9D4E3',
+    actorBkg: '#E8F1FF',
+    actorBorder: '#2F6FE4',
+    actorTextColor: '#0B2545',
+    signalColor: '#33475B',
+    signalTextColor: '#1B2632',
+    labelBoxBkgColor: '#F1E8FF',
+    labelBoxBorderColor: '#7B3FE4',
+    noteBkgColor: '#FFF8E1',
+    noteBorderColor: '#E0B000',
+    activationBkgColor: '#DCE8FF',
+    sequenceNumberColor: '#FFFFFF',
+    edgeLabelBackground: '#FFFFFF',
+  },
+  flowchart: { htmlLabels: false, curve: 'basis', padding: 12, nodeSpacing: 40, rankSpacing: 50 },
+  sequence: { showSequenceNumbers: true, actorMargin: 40, messageFontSize: 13, wrap: true, width: 160 },
+  er: { fontSize: 13, layoutDirection: 'LR' },
+  state: { fontSize: 13 },
+};
+
+const MERMAID_JS = path.join(TEMPLATES, 'vendor', 'mermaid.min.js');
+const CFG_HASH = crypto.createHash('sha1').update(JSON.stringify(MERMAID_CFG) + fs.statSync(MERMAID_JS).size).digest('hex').slice(0, 8);
+
+export const figureHash = (code) => crypto.createHash('sha1').update(CFG_HASH + code).digest('hex').slice(0, 16);
+
+/** Render Mermaid figures to SVG strings with a headless browser, using a cache keyed by content. */
+export async function renderMermaid(figures, cacheDir) {
+  if (!figures.length) return figures;
+  fs.mkdirSync(cacheDir, { recursive: true });
+  const todo = [];
+  for (const f of figures) {
+    f.hash = figureHash(f.code);
+    const p = path.join(cacheDir, f.hash + '.svg');
+    if (fs.existsSync(p)) f.svg = fs.readFileSync(p, 'utf8');
+    else todo.push(f);
+  }
+  if (!todo.length) return figures;
+  const browser = await getBrowser();
+  const page = await browser.newPage();
+  try {
+    await page.setViewport({ width: 1400, height: 900 });
+    await page.setContent('<!doctype html><html><head><meta charset="utf-8"><style>body{font-family:"Segoe UI",Arial,sans-serif;width:1400px}</style></head><body></body></html>');
+    await page.addScriptTag({ path: MERMAID_JS });
+    const results = await page.evaluate(async (codes, cfg) => {
+      // eslint-disable-next-line no-undef
+      mermaid.initialize(cfg);
+      const out = [];
+      for (let i = 0; i < codes.length; i++) {
+        try {
+          // eslint-disable-next-line no-undef
+          const r = await mermaid.render('tadfig' + i, codes[i]);
+          out.push({ svg: r.svg });
+        } catch (e) {
+          out.push({ error: String((e && e.message) || e) });
+          document.querySelectorAll('[id^="dtadfig"]').forEach((n) => n.remove());
+        }
+      }
+      return out;
+    }, todo.map((f) => f.code), MERMAID_CFG);
+    todo.forEach((f, i) => {
+      const r = results[i] || { error: 'no output' };
+      if (r.error || !/<svg/.test(r.svg || '')) {
+        f.error = (r.error || 'invalid SVG').slice(0, 400);
+        f.svg = `<pre class="mmd-error">${escapeHtml(f.error)}\n\n${escapeHtml(f.code.slice(0, 600))}</pre>`;
+        return;
+      }
+      f.svg = r.svg;
+      fs.writeFileSync(path.join(cacheDir, f.hash + '.svg'), r.svg, 'utf8');
+    });
+  } finally {
+    await page.close();
+  }
+  return figures;
+}
+
+export const escapeHtml = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');

package/src/build/render.js

@@ -0,0 +1,299 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import MarkdownIt from 'markdown-it';
+import { exists, readText, writeText, readJson } from '../util/fsx.js';
+import { TEMPLATES, PKG_ROOT } from '../util/paths.js';
+import { loadI18n, t } from '../util/i18n.js';
+import { loadFacts } from '../facts/index.js';
+import { CLASSDEFS, renderMermaid, escapeHtml } from './mermaid.js';
+import { resolveConditionals, resolveIncludes, resolveDirectives, resolveValues } from './directives.js';
+
+export const DOCS = ['tad', 'axes'];
+const VERSION = readJson(path.join(PKG_ROOT, 'package.json')).version;
+
+export function slug(text, used) {
+  let s = String(text).replace(/<[^>]+>/g, '').replace(/&[a-z]+;/g, ' ').toLowerCase();
+  s = s.replace(/[^\p{L}\p{N}\s-]/gu, '').replace(/[\s_]+/g, '-').replace(/^-+|-+$/g, '') || 's';
+  let base = s, i = 2;
+  while (used.has(s)) s = `${base}-${i++}`;
+  used.add(s);
+  return s;
+}
+
+/** Extract Mermaid figures and number headings. `# Title {-}` is unnumbered, `{#id}` sets the anchor. */
+export function preprocess(md) {
+  const figures = [];
+  md = md.replace(/```mermaid\r?\n([\s\S]*?)```[ \t]*\r?\n(?:Figure:[ \t]*([^\n]*)\n)?/g, (m, code, caption) => {
+    code = code.replace(/\s+$/, '');
+    const first = code.trimStart().split('\n', 1)[0];
+    if (/^(flowchart|graph)\b/.test(first)) code += '\n' + CLASSDEFS;
+    figures.push({ code, caption: (caption || '').trim() });
+    return `\n\n@@FIG${figures.length - 1}@@\n\n`;
+  });
+  const out = [], counters = [0, 0, 0], headings = [], used = new Set();
+  let inCode = false, letter = 0, sub = 0;
+  for (const line of md.split('\n')) {
+    if (line.startsWith('```')) inCode = !inCode;
+    const m = inCode ? null : /^(#{1,3}) (.*)$/.exec(line);
+    if (!m) { out.push(line); continue; }
+    const lvl = m[1].length;
+    let text = m[2].trim();
+    // Appendices are lettered in order, so that optional ones never leave gaps: {{letter}} and {{sub}}
+    if (text.includes('{{letter}}')) { letter++; sub = 0; text = text.replace('{{letter}}', String.fromCharCode(64 + letter)); }
+    if (text.includes('{{sub}}')) { sub++; text = text.replace('{{sub}}', `${String.fromCharCode(64 + Math.max(letter, 1))}.${sub}`); }
+    const attr = /\s*\{([^{}]*)\}\s*$/.exec(text);
+    let nonum = false, id = null;
+    if (attr && /^(\s*(-|#[\w-]+)\s*)+$/.test(attr[1])) {
+      nonum = /(^|\s)-(\s|$)/.test(attr[1]);
+      id = (/#([\w-]+)/.exec(attr[1]) || [])[1] || null;
+      text = text.slice(0, attr.index).trim();
+    }
+    let num = null;
+    if (!nonum) {
+      counters[lvl - 1]++;
+      for (let k = lvl; k < 3; k++) counters[k] = 0;
+      num = counters.slice(0, lvl).join('.');
+    }
+    if (id) used.add(id); else id = slug((num ? num + ' ' : '') + text, used);
+    headings.push({ lvl, id, num, text });
+    out.push(`${m[1]} ${num ? `<span class="num">${num}</span> ` : ''}${text}`);
+  }
+  return { md: out.join('\n'), figures, headings };
+}
+
+export function resolveRefs(md, headings, problems) {
+  const byId = new Map(headings.map((h) => [h.id, h]));
+  return md.replace(/\{\{(ref|title):([\w-]+)\}\}/g, (m, kind, id) => {
+    const h = byId.get(id);
+    if (!h) { problems.push({ level: 'error', code: 'unknown-ref', message: `Reference to unknown section ${m}` }); return `⟨${id}⟩`; }
+    const plain = h.text.replace(/`/g, '');
+    if (kind === 'ref') return `[${h.num ? '§ ' + h.num : plain}](#${id})`;
+    return `[${h.num ? h.num + ' ' : ''}${plain}](#${id})`;
+  });
+}
+
+function mime(p) {
+  const ext = path.extname(p).toLowerCase();
+  return { '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif' }[ext] || 'application/octet-stream';
+}
+const dataUri = (p) => `data:${mime(p)};base64,${fs.readFileSync(p).toString('base64')}`;
+
+/** Text badge used when no logo file is configured. */
+export function badgeLogo(name, color) {
+  const initials = String(name || '?').split(/[\s&.-]+/).filter(Boolean).slice(0, 3).map((w) => w[0].toUpperCase()).join('') || '?';
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="160" height="160" viewBox="0 0 160 160"><rect width="160" height="160" rx="32" fill="${color}"/><text x="80" y="96" text-anchor="middle" font-family="Segoe UI,Arial,sans-serif" font-size="${initials.length > 2 ? 48 : 60}" font-weight="700" fill="#fff">${escapeHtml(initials)}</text></svg>`;
+  return 'data:image/svg+xml;base64,' + Buffer.from(svg).toString('base64');
+}
+
+/**
+ * Base name of a built document. The HTML keeps the same name from one version to the next
+ * (the review comments live in it); `{ versioned: true }` adds the version, for PDF and DOCX archives.
+ */
+export function outputName(cfg, doc, { versioned = false } = {}) {
+  const short = String(cfg.client.short || cfg.client.name || 'CLIENT').replace(/[^\w-]+/g, '_');
+  const custom = cfg.outputs && cfg.outputs.names && cfg.outputs.names[doc];
+  const base = custom || `${doc === 'tad' ? 'TAD' : 'Axes'}_${short}`;
+  return versioned && !custom ? `${base}_v${cfg.document.version}` : base;
+}
+
+const md = new MarkdownIt({ html: true, linkify: false, typographer: false });
+
+/**
+ * Build one document (tad | axes) of a workspace. Returns a report (paths, figures, problems).
+ * opts.render = false skips Mermaid rendering (tests, dry runs).
+ */
+export async function buildDocument(wsCtx, doc, opts = {}) {
+  const { cfg } = wsCtx;
+  const problems = [];
+  const facts = loadFacts(wsCtx.ws);
+  if (!facts) throw new Error('facts/facts.json not found: run `tadforce facts` first.');
+  const { lang, dict } = loadI18n(cfg.language, wsCtx.ws);
+  const glossary = wsCtx.glossary() || {};
+  const srcDir = wsCtx.p('src', doc);
+  if (!exists(srcDir)) throw new Error(`No sources in ${srcDir}: run \`tadforce scaffold --doc ${doc}\`.`);
+  const files = fs.readdirSync(srcDir).filter((f) => f.endsWith('.md')).sort();
+  if (!files.length) throw new Error(`No Markdown chapters in ${srcDir}.`);
+
+  let text = files.map((f) => readText(path.join(srcDir, f))).join('\n\n');
+  const scope = { modules: facts.modules, counts: facts.counts, org: facts.org, cfg, facts, glossary };
+  const docName = doc === 'tad' ? t(dict, 'meta.docName') : t(dict, 'meta.axesName');
+  const ctx = { facts, cfg, dict, lang, glossary, doc, docName, chapterTitle: (k) => `{{title:ch-${k}}}` };
+  text = resolveConditionals(text, scope);
+  text = resolveIncludes(text, wsCtx.ws);
+  text = resolveDirectives(text, ctx, problems);
+  text = resolveConditionals(text, scope);
+  text = resolveValues(text, ctx, problems);
+
+  const pending = [...text.matchAll(/<!--\s*tad:pending\s+([\w.-]+)\s*-->/g)].map((m) => m[1]);
+  const pre = preprocess(text);
+  let body = resolveRefs(pre.md, pre.headings, problems);
+  body = body.replace(/<!--\s*tad:pending\s+([\w.-]+)\s*-->/g, (m, id) => `<div class="pending" data-section="${id}">✍ ${escapeHtml(t(dict, 'ui.pending'))} — <code>${id}</code></div>`);
+  body = body.replace(/<!--[\s\S]*?-->/g, '');
+
+  const figures = pre.figures;
+  if (opts.render !== false) await renderMermaid(figures, wsCtx.p('.cache', 'mermaid'));
+  else for (const f of figures) f.svg = `<pre class="mmd-src">${escapeHtml(f.code)}</pre>`;
+  for (const f of figures) if (f.error) problems.push({ level: 'error', code: 'mermaid', message: `Figure "${f.caption || f.code.slice(0, 40)}" failed: ${f.error}` });
+
+  let html = md.render(body);
+
+  // Callouts: blockquotes starting with [!INTEGRATOR] / [!NOTE] / [!RECO] / [!WARN]
+  html = html.replace(/<blockquote>\s*([\s\S]*?)<\/blockquote>/g, (m, inner) => {
+    const k = /\[!(\w+)\]\s*/.exec(inner);
+    if (!k) return m;
+    const kind = k[1].toLowerCase();
+    const title = { integrator: cfg.integrator.name ? t(dict, 'doc.callout.integrator', { integrator: cfg.integrator.name }) : t(dict, 'doc.callout.team'), note: t(dict, 'doc.callout.note'), reco: t(dict, 'doc.callout.reco'), warn: t(dict, 'doc.callout.warn') }[kind] || kind;
+    return `<aside class="callout ${kind}"><div class="ct">${escapeHtml(title)}</div>${inner.replace(k[0], '')}</aside>`;
+  });
+
+  // Figures (Mermaid and hand-made SVG / HTML blocks), numbered in reading order
+  let nfig = 0;
+  const figlist = [];
+  const label = t(dict, 'doc.figure');
+  html = html.replace(/<p>@@FIG(\d+)@@<\/p>|<p class="figcap">Figure — ([\s\S]*?)<\/p>/g, (m, idx, cap) => {
+    nfig++;
+    if (idx !== undefined) {
+      const f = figures[Number(idx)];
+      figlist.push([nfig, f.caption]);
+      const c = f.caption ? `${label} ${nfig} — ${escapeHtml(f.caption)}` : `${label} ${nfig}`;
+      return `<figure class="diagram" id="fig-${nfig}"><div class="fig-body">${f.svg}</div><figcaption>${c}</figcaption></figure>`;
+    }
+    figlist.push([nfig, cap.replace(/<[^>]+>/g, '')]);
+    return `<p class="figcap" id="fig-${nfig}">${label} ${nfig} — ${cap}</p>`;
+  });
+
+  // Heading ids (same order as preprocess) and anchors
+  let hi = 0;
+  html = html.replace(/<h([1-3])>([\s\S]*?)<\/h\1>/g, (m, lvl, inner) => {
+    const h = pre.headings[hi++];
+    if (!h) return m;
+    return `<h${lvl} id="${h.id}">${inner}<a class="anchor" href="#${h.id}">#</a></h${lvl}>`;
+  });
+  html = html.replace(/<table>/g, '<div class="tw"><table>').replace(/<\/table>/g, '</table></div>');
+
+  // Table of contents (levels 1-2) and list of figures
+  const toc = [];
+  let open = false;
+  for (const h of pre.headings.filter((x) => x.lvl <= 2)) {
+    const inner = `${h.num ? `<span class="num">${h.num}</span> ` : ''}${md.renderInline(h.text)}`;
+    if (h.lvl === 1) { if (open) toc.push('</ul></li>'); toc.push(`<li class="l1"><a href="#${h.id}">${inner}</a><ul>`); open = true; }
+    else toc.push(`<li class="l2"><a href="#${h.id}">${inner}</a></li>`);
+  }
+  if (open) toc.push('</ul></li>');
+  const figs = figlist.map(([n, c]) => `<li><a href="#fig-${n}">${label} ${n} — ${escapeHtml(c)}</a></li>`).join('');
+
+  // Page assembly
+  const brand = cfg.brand;
+  const cssStr = (s) => String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  const css = readText(path.join(TEMPLATES, 'html', 'style.css'))
+    .replace('{{PRINT_FOOTER}}', cssStr(doc === 'axes' && cfg.integrator.name ? `${docName} — ${cfg.document.title} · ${cfg.integrator.name} · ${t(dict, 'doc.axesKicker')}` : `${docName} — ${cfg.document.title} · ${cfg.client.name} · ${cfg.document.classification}`))
+    .replace('{{PRINT_PAGE}}', cssStr(t(dict, 'doc.page')));
+  const brandCss = `:root{--brand:${brand.primary};--accent:${brand.accent};--accent2:${brand.accent2};--grad:linear-gradient(90deg,${brand.gradient[0]},${brand.gradient[1]});--th:${brand.tableHeader};--kpiMore:"${cssStr(t(dict, 'ui.kpiMore'))}"}@media print{:root{--brand:${brand.primary};--th:${brand.tableHeader}}}`;
+  const logo = (who) => {
+    const p = cfg[who].logo && wsCtx.p(cfg[who].logo);
+    return p && exists(p) ? dataUri(p) : badgeLogo(cfg[who].short || cfg[who].name, who === 'client' ? brand.primary : brand.accent2);
+  };
+  // Integrator and author are optional: without them the document only names the client.
+  const integrator = cfg.integrator.name || null;
+  const author = cfg.document.author || null;
+  const preparedBy = [author, integrator].filter(Boolean).join(' — ');
+  const sideLogo = integrator ? logo('integrator') : logo('client');
+  // The Improvement Axes are the integrator's internal document: its brand only (the client's when there is none).
+  const internal = doc === 'axes' && integrator;
+  const coverLogos = internal
+    ? `<img src="${logo('integrator')}" alt="${escapeHtml(integrator)}">`
+    : integrator
+      ? `<img src="${logo('integrator')}" alt="${escapeHtml(integrator)}"><img src="${logo('client')}" alt="${escapeHtml(cfg.client.name)}">`
+      : `<img src="${logo('client')}" alt="${escapeHtml(cfg.client.name)}">`;
+  const vendor = (f) => readText(path.join(TEMPLATES, 'vendor', f));
+  const coverTpl = readText(path.join(TEMPLATES, 'html', 'cover.html'));
+  const tokens = {
+    '{{VERSION}}': VERSION,
+    '{{LANG}}': t(dict, 'meta.htmlLang'),
+    '{{CSS}}': css,
+    '{{BRAND_CSS}}': brandCss,
+    '{{TITLE}}': escapeHtml(`${docName} — ${cfg.document.title} — ${cfg.client.name}`),
+    '{{DESCRIPTION}}': escapeHtml(`${docName} — ${cfg.document.title} — ${cfg.client.name}${integrator ? ` (${integrator})` : ''}`),
+    '{{COVER}}': coverTpl,
+    '{{COVER_KICKER}}': escapeHtml(doc === 'tad' ? t(dict, 'doc.kicker') : t(dict, 'doc.axesKicker')),
+    '{{COVER_NOTE}}': escapeHtml(t(dict, (doc === 'tad' ? 'doc.confidential' : 'doc.axesConfidential') + (integrator ? '' : 'Solo'), { client: cfg.client.name, integrator })),
+    '{{DOC_TITLE}}': escapeHtml(cfg.document.title),
+    '{{DOC_SUBTITLE}}': escapeHtml(cfg.document.subtitle || [cfg.client.name, ...facts.modules.clouds.filter((x) => !['events', 'shield', 'slack'].includes(x.id)).slice(0, 3).map((x) => x.name)].join(' · ')),
+    '{{DOC_REFERENCE}}': escapeHtml(doc === 'tad' ? cfg.document.reference : cfg.document.reference + '-AX'),
+    '{{DOC_VERSION}}': escapeHtml(`${cfg.document.version}${cfg.document.status ? ' — ' + cfg.document.status : ''}`),
+    '{{DOC_DATE}}': escapeHtml(cfg.document.date),
+    '{{DOC_CLASSIFICATION}}': escapeHtml(doc === 'tad' ? cfg.document.classification : t(dict, 'doc.axesKicker')),
+    '{{INTEGRATOR_NAME}}': escapeHtml(integrator || cfg.client.name),
+    '{{COVER_LOGOS}}': coverLogos,
+    '{{PREPARED_BY_ROW}}': preparedBy ? `<div><b>${escapeHtml(t(dict, 'doc.meta.author'))}</b><span>${escapeHtml(preparedBy)}</span></div>` : '',
+    '{{CLIENT_NAME}}': escapeHtml(cfg.client.name),
+    '{{TOC}}': toc.join(''),
+    '{{FIGLIST}}': figs,
+    '{{BODY}}': html,
+    '{{INTEGRATOR_LOGO}}': sideLogo,
+    '{{CLIENT_LOGO}}': logo('client'),
+    '{{SIDE_TITLE}}': escapeHtml(`${docName} — ${cfg.document.title}`),
+    '{{SIDE_SUB}}': escapeHtml(`${cfg.client.name} · v${cfg.document.version} · ${cfg.document.date}`),
+    '{{FOOTER}}': escapeHtml(`${integrator ? integrator + ' · ' : ''}${internal ? '' : cfg.client.name + ' · '}${doc === 'tad' ? cfg.document.classification : t(dict, 'doc.axesKicker')}`) + ` · <span class="gen">${escapeHtml(t(dict, 'doc.generatedBy'))}</span>`,
+    '{{I18N_JSON}}': JSON.stringify({ editor: dict.editor }).replace(/</g, '\\u003c'),
+    '{{BRAND_JSON}}': JSON.stringify(brand).replace(/</g, '\\u003c'),
+    '{{DOCX_LIB}}': vendor('html-docx.js'),
+    '{{CAPTURE_LIB}}': vendor('html2canvas.min.js'),
+    '{{EDITOR_JS}}': readText(path.join(TEMPLATES, 'html', 'editor.js')),
+  };
+  let tpl = readText(path.join(TEMPLATES, 'html', 'template.html'));
+  if (!figs) tpl = tpl.replace(/<details class="figs">[\s\S]*?<\/details>/, '');
+  // Two passes over the template only (cover tokens live inside {{COVER}}); inserted content is never re-scanned.
+  const fill = (s) => s.split(/(\{\{[A-Z0-9_]+\}\}|\{\{T:[\w.]+\}\})/).map((x) => {
+    if (tokens[x] !== undefined) return tokens[x];
+    const k = /^\{\{T:([\w.]+)\}\}$/.exec(x);
+    return k ? t(dict, k[1]) : x;
+  }).join('');
+  tokens['{{COVER}}'] = fill(coverTpl);
+  let out = fill(tpl);
+
+  // Comments saved in the browser are carried over, with their resolution.
+  const review = (cfg.review && cfg.review[doc]) || {};
+  const carried = [];
+  for (const rel of review.commentsFrom || []) {
+    const p = wsCtx.p(rel);
+    if (!exists(p)) { problems.push({ level: 'warn', code: 'comments-missing', message: `commentsFrom file not found: ${rel}` }); continue; }
+    carried.push(...readComments(readText(p)));
+  }
+  // The HTML keeps one name across versions: the comments already saved in it are carried over too.
+  const outDir = wsCtx.p(cfg.outputs.dir || 'out');
+  const htmlPath = path.join(outDir, outputName(cfg, doc) + '.html');
+  const prev = exists(htmlPath) ? readText(htmlPath) : null;
+  if (prev) {
+    const known = new Set(carried.map((c) => c.id));
+    for (const c of readComments(prev)) if (!known.has(c.id)) carried.push(c);
+  }
+  for (const c of carried) {
+    if (c.status === 'résolu') c.status = 'resolved';
+    const res = review.resolutions && review.resolutions[c.id];
+    if (res) { c.status = 'resolved'; c.response = res; }
+    if ((review.dropImages || []).includes(c.id)) c.image = null;
+  }
+  if (carried.length) {
+    const payload = JSON.stringify(carried, null, 1).replace(/</g, '\\u003c');
+    out = out.replace('<script type="application/json" id="tad-comments">[]</script>', () => `<script type="application/json" id="tad-comments">${payload}</script>`);
+  }
+
+  let backup = null;
+  // In-browser text edits cannot be merged into the Markdown sources: keep a copy so that nothing is lost.
+  if (prev && prev.includes('data-edited="1"')) {
+    backup = htmlPath.replace(/\.html$/, `_comments_${stamp()}.html`);
+    writeText(backup, prev);
+    problems.push({ level: 'warn', code: 'backup', message: `Existing file held in-browser text edits: copy kept as ${path.basename(backup)}. Report the edits into src/${doc}/*.md (comments are carried over automatically).` });
+  }
+  writeText(htmlPath, out);
+  return { doc, html: htmlPath, backup, sizeKB: Math.round(out.length / 1024), figures: nfig, mermaid: figures.length, problems, pending, headings: pre.headings };
+}
+
+export function readComments(html) {
+  const m = /<script type="application\/json" id="tad-comments">([\s\S]*?)<\/script>/.exec(html);
+  if (!m || !m[1].trim()) return [];
+  try { return JSON.parse(m[1]); } catch { return []; }
+}
+
+const stamp = () => new Date().toISOString().replace(/[-:]/g, '').replace('T', '-').slice(0, 15);

package/src/build/serve.js

@@ -0,0 +1,59 @@
+// Serve a built document on 127.0.0.1 so that « Save » in the page writes back to the very same file:
+// one file per document, the review comments never split across copies.
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+
+const MAX_BYTES = 128 * 1024 * 1024;
+
+/** Atomic write: a reader never sees a half-written document. */
+export function writeAtomic(file, content) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, content, 'utf8');
+  fs.renameSync(tmp, file);
+}
+
+/**
+ * Start the server. GET and PUT on /<token>/<file name> only; the random token keeps other pages
+ * and other local users from writing to the file. Resolves with { url, close }.
+ */
+export function serveDocument(file, { port = 0 } = {}) {
+  const abs = path.resolve(file);
+  const token = crypto.randomBytes(12).toString('hex');
+  const route = `/${token}/${encodeURIComponent(path.basename(abs))}`;
+  const server = http.createServer((req, res) => {
+    const url = (req.url || '').split('?')[0];
+    if (url !== route) { res.writeHead(404).end(); return; }
+    if (req.method === 'GET') {
+      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+      fs.createReadStream(abs).pipe(res);
+      return;
+    }
+    if (req.method === 'PUT') {
+      // Same-origin only: a page served elsewhere cannot overwrite the document.
+      const origin = req.headers.origin;
+      if (origin && origin !== `http://127.0.0.1:${server.address().port}`) { res.writeHead(403).end(); return; }
+      const chunks = []; let size = 0;
+      req.on('data', (d) => { size += d.length; if (size > MAX_BYTES) { res.writeHead(413).end(); req.destroy(); } else chunks.push(d); });
+      req.on('end', () => {
+        const body = Buffer.concat(chunks).toString('utf8');
+        if (!/^<!doctype html>/i.test(body)) { res.writeHead(400).end('not an HTML document'); return; }
+        writeAtomic(abs, body);
+        res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ ok: true, file: path.basename(abs) }));
+      });
+      return;
+    }
+    res.writeHead(405).end();
+  });
+  return new Promise((resolve, reject) => {
+    server.on('error', reject);
+    server.listen(port, '127.0.0.1', () => resolve({ url: `http://127.0.0.1:${server.address().port}${route}`, close: () => new Promise((r) => server.close(r)), server }));
+  });
+}
+
+export function openInBrowser(url) {
+  const [cmd, args] = process.platform === 'win32' ? ['cmd', ['/c', 'start', '""', url]] : process.platform === 'darwin' ? ['open', [url]] : ['xdg-open', [url]];
+  try { spawn(cmd, args, { stdio: 'ignore', detached: true }).unref(); } catch { /* the URL is printed anyway */ }
+}

package/src/cli.js

@@ -0,0 +1,68 @@
+import path from 'node:path';
+import { parseArgs } from './util/args.js';
+import { log, c, setQuiet } from './util/log.js';
+import { readJson } from './util/fsx.js';
+import { PKG_ROOT } from './util/paths.js';
+import * as initCmd from './commands/init.js';
+import * as doctorCmd from './commands/doctor.js';
+import * as org from './commands/org.js';
+import * as docs from './commands/docs.js';
+import * as specCmd from './commands/spec.js';
+import * as reviewCmd from './commands/review.js';
+import * as updateCmd from './commands/update.js';
+
+// The four commands of the run. Everything else stays available for experts and CI.
+const MAIN = {
+  doctor: [doctorCmd.run, 'Everything before the writing, in one loop: tools, project, org login, metadata, questions'],
+  build: [docs.build, 'Build the document: HTML always, --pdf --docx on demand, then validate (--open to review it)'],
+  review: [reviewCmd.run, 'Open the document to comment it (Save writes to the same file) and list the open comments'],
+  update: [updateCmd.run, 'Months later: read the org again, archive the old facts, list the sections to rewrite, bump the version'],
+};
+const ADVANCED = {
+  init: [initCmd.run, 'Create the workspace and install the agent skills (doctor does it too)'],
+  auth: [org.auth, 'Authorize an org in the browser and save its alias (doctor does it too)'],
+  detect: [org.detect, 'Print org facts that answer the startup questions (JSON)'],
+  manifest: [org.manifest, 'Build the wildcard manifest filtered on what the org supports'],
+  retrieve: [org.retrieve, 'Retrieve the manifest into tadforce/.snapshot (force-app untouched)'],
+  facts: [docs.facts, 'Extract facts.json from the metadata (--org adds aggregated org facts)'],
+  prepare: [docs.prepare, 'manifest → retrieve → facts --org → scaffold, in one go (CI)'],
+  scaffold: [docs.scaffold, 'Copy the chapter skeletons into tadforce/src (existing files kept)'],
+  next: [specCmd.next, 'Next section to write, with its specification and the facts to use (--json)'],
+  spec: [specCmd.spec, 'Specification of one section (tadforce spec data.domains) — no id lists them all'],
+  validate: [docs.validate, 'Check the document: pending sections, placeholders, identifiers, glossary, secrets, anchors'],
+  comments: [docs.comments, 'List the review comments saved in a built HTML file'],
+  status: [docs.status, 'Where the workspace stands'],
+  'install-skills': [async (a) => { const d = initCmd.installSkills(path.resolve(a.cwd || process.cwd()), a.agents ? String(a.agents).split(',') : null); log.ok(`Skills installed in ${d.join(', ')}`); return 0; }, 'Install or update the agent skills (--agents claude,agents,cursor…)'],
+};
+const COMMANDS = { ...MAIN, ...ADVANCED };
+
+function help(all) {
+  const v = readJson(path.join(PKG_ROOT, 'package.json')).version;
+  console.log(`${c.violet('▲')} ${c.bold('TADForce')} ${v} — AI-Powered Salesforce Technical Documentation. ${c.dim('No evidence, no sentence.')}\n`);
+  console.log(`Usage: ${c.bold('npx tadforce <command> [options]')}\n`);
+  for (const [k, [, d]] of Object.entries(MAIN)) console.log(`  ${c.cyan(k.padEnd(15))} ${d}`);
+  if (all) {
+    console.log('\nAdvanced (CI, experts):');
+    for (const [k, [, d]] of Object.entries(ADVANCED)) console.log(`  ${c.cyan(k.padEnd(15))} ${d}`);
+  } else console.log(c.dim(`\n  ${Object.keys(ADVANCED).length} advanced commands: tadforce help --all`));
+  console.log('\nCommon options: --cwd <dir>  --org <alias>  --doc tad|axes|all  --json  --quiet');
+  console.log(`Start here:     ${c.bold('npx tadforce doctor')}   then type ${c.bold('/tadforce')} in your AI agent.\n`);
+}
+
+export async function main(argv) {
+  const args = parseArgs(argv);
+  const cmd = args._[0];
+  if (args.quiet) setQuiet(true);
+  if (args.version || args.v) { console.log(readJson(path.join(PKG_ROOT, 'package.json')).version); return 0; }
+  if (!cmd || cmd === 'help' || args.help || args.h) { help(args.all); return 0; }
+  const entry = COMMANDS[cmd];
+  if (!entry) { log.fail(`Unknown command "${cmd}".`); help(); return 1; }
+  if (args.cwd) args.cwd = path.resolve(args.cwd);
+  try {
+    return (await entry[0](args)) || 0;
+  } catch (e) {
+    log.fail(e.message);
+    if (process.env.TADFORCE_DEBUG) console.error(e.stack);
+    return 1;
+  }
+}