tadforce 0.0.0-stage → 0.3.0

package/src/commands/init.js

@@ -0,0 +1,132 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { exists, writeText, writeJson, copyDir, readJson } from '../util/fsx.js';
+import { defaultConfig, findWorkspace } from '../util/config.js';
+import { WORKSPACE_DIR, CONFIG_FILE, SKILLS } from '../util/paths.js';
+import { LANGUAGES, normalizeLang } from '../util/i18n.js';
+import { log } from '../util/log.js';
+import { run as doctor } from './doctor.js';
+
+const GLOSSARY = `# TADForce glossary — the client's vocabulary is law.
+# terms:   terminology imposed by the client. \`tadforce validate\` fails when an "avoid" form appears.
+# systems: names of the systems Salesforce talks to. Never guessed: confirmed by a human.
+#          "match" lists named credentials, remote sites, auth providers… or hosts (api.example.com).
+# actors:  user populations shown on the context view.
+terms: []
+#  - use: "API Gateway"
+#    avoid: ["API passerelle"]
+#    definition: "Single entry point exposing the bank's internal services."
+systems: []
+#  - id: core-banking
+#    name: "Core banking"
+#    description: "System of record for accounts and contracts"
+#    match: ["Core_Banking_NC", "api.core.example.com"]
+actors: []
+#  - name: "Branch advisors"
+#    channel: "Branch console"
+# allow: technical terms quoted in code font on purpose, unknown to the metadata (API payload fields, external IDs…)
+allow: []
+# products: Salesforce products used without trace in the metadata (reference: a file of skills/tadforce/references/modules/)
+products: []
+#  - id: marketingCloud
+#    name: "Marketing Cloud Engagement"
+#    reference: marketing
+`;
+
+const EXCLUSIONS = `# TADForce exclusions — what the document must NOT describe.
+# exclude:  components outside the production architecture (POC, test, demo, unused). "*" wildcards allowed.
+#           type (optional): apex, trigger, lwc, aura, flow, flexipage, app, object, permissionSet, omniScript, report…
+# features: decommissioned features. Their components are excluded and their keywords are forbidden in the text.
+exclude: []
+#  - name: "*Demo*"
+#    reason: "Demonstration components"
+#  - name: legacyScoring
+#    type: lwc
+#    reason: "Replaced by the scoring engine; still deployed, not used"
+features: []
+#  - name: "Search by national ID"
+#    note: "UI removed; backend kept until further notice. Do not document."
+#    components: [idSearch, IdSearchController]
+#    keywords: ["national ID search"]
+`;
+
+/** Agent folders that receive the skills. Others are added when their folder already exists. */
+const AGENT_DIRS = ['.claude', '.agents'];
+const OPTIONAL_AGENT_DIRS = ['.codex', '.cursor', '.windsurf', '.gemini', '.github', '.kiro', '.roo', '.opencode', '.continue'];
+
+export function installSkills(project, agents) {
+  const targets = agents && agents.length ? agents.map((a) => (a.startsWith('.') ? a : '.' + a)) : [...AGENT_DIRS, ...OPTIONAL_AGENT_DIRS.filter((d) => exists(path.join(project, d)))];
+  const done = [];
+  for (const dir of [...new Set(targets)]) {
+    for (const skill of fs.readdirSync(SKILLS)) {
+      copyDir(path.join(SKILLS, skill), path.join(project, dir, 'skills', skill), { overwrite: true });
+    }
+    done.push(path.join(dir, 'skills'));
+  }
+  return done;
+}
+
+/** Minimal SFDX project, knowledge files and .gitignore: everything a workspace needs, existing files kept. */
+export function ensureWorkspace(project, cfg) {
+  const ws = findWorkspace(project) || path.join(project, WORKSPACE_DIR);
+  if (!exists(path.join(project, 'sfdx-project.json'))) {
+    writeJson(path.join(project, 'sfdx-project.json'), { packageDirectories: [{ path: 'force-app', default: true }], name: path.basename(project), namespace: '', sourceApiVersion: '62.0' });
+    fs.mkdirSync(path.join(project, 'force-app', 'main', 'default'), { recursive: true });
+    log.ok('Created a minimal SFDX project (sfdx-project.json, force-app/).');
+  }
+  writeJson(path.join(ws, CONFIG_FILE), cfg);
+  if (!exists(path.join(ws, 'knowledge', 'glossary.yml'))) writeText(path.join(ws, 'knowledge', 'glossary.yml'), GLOSSARY);
+  if (!exists(path.join(ws, 'knowledge', 'exclusions.yml'))) writeText(path.join(ws, 'knowledge', 'exclusions.yml'), EXCLUSIONS);
+  if (!exists(path.join(ws, 'knowledge', 'inputs', 'README.md'))) writeText(path.join(ws, 'knowledge', 'inputs', 'README.md'), '# Inputs\n\nDrop here what the metadata cannot tell: functional specifications (`specs/`), previous architecture documents, a Code Analyzer report (`code-analyzer-results.json`), decisions. They are read by the agent, never published as such.\n');
+  if (!exists(path.join(ws, '.gitignore'))) writeText(path.join(ws, '.gitignore'), '.snapshot/\n.cache/\nout/*_comments_*.html\n');
+  return ws;
+}
+
+async function ask(rl, q, def) {
+  if (!rl) return def;
+  const a = (await rl.question(`  ${q}${def ? ` [${def}]` : ''}: `)).trim();
+  return a || def;
+}
+
+export async function run(args) {
+  const project = path.resolve(args.cwd || process.cwd());
+  log.banner('init');
+  const existing = findWorkspace(project);
+  const ws = existing || path.join(project, WORKSPACE_DIR);
+  const interactive = process.stdin.isTTY && !args.yes;
+  const rl = interactive ? readline.createInterface({ input: process.stdin, output: process.stdout }) : null;
+  try {
+    const prev = existing ? readJson(path.join(ws, CONFIG_FILE)) : {};
+    const base = defaultConfig(prev);
+    if (interactive) log.step('A few facts only you can confirm (Enter keeps the default):');
+    const language = args.lang || (await ask(rl, `Document language (${LANGUAGES.join('/')} built in, or any code: es, de, it, pt, ar…)`, base.language));
+    const clientName = args.client || (await ask(rl, 'Client name', prev.client?.name || base.client.name));
+    const short = args.short || (await ask(rl, 'Client short name (used in file names)', prev.client?.short || clientName.replace(/[^A-Za-z0-9]/g, '').slice(0, 8).toUpperCase()));
+    const integrator = args.integrator || (await ask(rl, 'Integrator (blank if none)', base.integrator.name || ''));
+    const author = args.author || (await ask(rl, 'Author of the document (blank: not shown)', base.document.author || ''));
+    const title = args.title || (await ask(rl, 'Document title', base.document.title));
+    const alias = args.org || (await ask(rl, 'Salesforce org alias (blank: decide later)', base.org.alias || ''));
+    const cfg = defaultConfig({
+      ...prev,
+      language: normalizeLang(language),
+      client: { ...base.client, name: clientName, short },
+      integrator: { ...base.integrator, name: integrator || null },
+      document: { ...base.document, author: author || null, title, reference: prev.document?.reference || `TAD-${short}-CRM`, environment: args.environment || base.document.environment, status: language === 'fr' && !prev.document?.status ? 'Pour revue' : base.document.status, classification: language === 'fr' && !prev.document?.classification ? 'Confidentiel' : base.document.classification },
+      org: { alias: alias || null },
+    });
+    ensureWorkspace(project, cfg);
+    log.ok(`Workspace ready: ${path.relative(project, ws) || '.'}/`);
+    if (args.skills !== false) {
+      const dirs = installSkills(project, args.agents ? String(args.agents).split(',') : null);
+      log.ok(`Skills installed in ${dirs.join(', ')} → run /tadforce in your agent.`);
+    }
+  } finally {
+    if (rl) rl.close();
+  }
+  console.log('');
+  await doctor({ cwd: project });
+  console.log('');
+  log.human('open your AI agent in this folder and type /tadforce — or run `npx tadforce doctor` to finish the setup here.');
+  return 0;
+}

package/src/commands/org.js

@@ -0,0 +1,151 @@
+// auth (browser login), detect (startup facts for the questions), manifest and retrieve.
+import fs from 'node:fs';
+import path from 'node:path';
+import { exists, readText, writeText, writeJson } from '../util/fsx.js';
+import { loadWorkspace } from '../util/config.js';
+import { TEMPLATES } from '../util/paths.js';
+import { sfJson, sfInteractive, soql } from '../sf/sf.js';
+import { log } from '../util/log.js';
+
+function requireAlias(ctx, args) {
+  const alias = args.org || ctx.cfg.org.alias;
+  if (!alias) throw new Error('No target org. Pass --org <alias> or run `tadforce init --org <alias>`.');
+  return alias;
+}
+
+export async function auth(args) {
+  const ctx = loadWorkspace(args.cwd || process.cwd());
+  const alias = args.alias || args.org || ctx.cfg.org.alias || 'tadforce-org';
+  const instance = args.instanceUrl || (args.sandbox ? 'https://test.salesforce.com' : null);
+  log.banner('auth');
+  log.human(`a browser window opens: log in to the org, then click « Allow ». Alias: ${alias}`);
+  const ok = sfInteractive(['org', 'login', 'web', '--alias', alias, ...(instance ? ['--instance-url', instance] : [])]);
+  if (!ok) { log.fail('Login did not complete.'); return 1; }
+  ctx.save({ ...ctx.cfg, org: { ...ctx.cfg.org, alias } });
+  log.ok(`Org authorized and saved in the workspace as "${alias}".`);
+  return 0;
+}
+
+/** Facts to propose answers for the startup questions (language, client, integrator, environment). */
+export async function detect(args) {
+  const ctx = loadWorkspace(args.cwd || process.cwd());
+  const alias = requireAlias(ctx, args);
+  const display = await sfJson(['org', 'display', '--target-org', alias]);
+  const org = ((await soql('SELECT Name, IsSandbox, OrganizationType, LanguageLocaleKey, DefaultLocaleSidKey, InstanceName FROM Organization', alias)).records || [])[0] || {};
+  const username = display.username || '';
+  const domain = (/@([^@]+)$/.exec(username) || [])[1] || null;
+  const result = {
+    alias,
+    username,
+    instanceUrl: display.instanceUrl,
+    apiVersion: display.apiVersion,
+    organization: { name: org.Name, sandbox: org.IsSandbox, edition: org.OrganizationType, language: org.LanguageLocaleKey, locale: org.DefaultLocaleSidKey, instance: org.InstanceName },
+    proposals: {
+      language: /^fr/i.test(org.LanguageLocaleKey || '') ? 'fr' : 'en',
+      client: org.Name,
+      environment: org.IsSandbox ? 'Sandbox' : 'Production',
+      integratorFromUserDomain: domain && !/salesforce\.com$|force\.com$/.test(domain) ? domain.split('.').slice(-2, -1)[0] : null,
+    },
+  };
+  console.log(JSON.stringify(result, null, 2));
+  return 0;
+}
+
+const FOLDERED = { Report: 'ReportFolder', Dashboard: 'DashboardFolder', EmailTemplate: 'EmailFolder', Document: 'DocumentFolder' };
+
+/** Build tadforce/.snapshot/package.xml: curated wildcard manifest filtered on what the org supports. */
+export async function manifest(args) {
+  const ctx = loadWorkspace(args.cwd || process.cwd());
+  const alias = requireAlias(ctx, args);
+  const mode = args.mode || ctx.cfg.manifest.mode || 'curated';
+  const out = ctx.p('.snapshot', 'package.xml');
+  log.banner('manifest');
+  if (mode === 'full') {
+    log.step('Listing every metadata component of the org (packages excluded)…');
+    await sfJson(['project', 'generate', 'manifest', '--from-org', alias, '--output-dir', ctx.p('.snapshot'), '--name', 'package.xml', ...(ctx.cfg.manifest.includePackages ? ['--include-packages', 'managed,unlocked'] : [])], { timeoutMs: 1800000 });
+    log.ok(`Manifest written: ${path.relative(ctx.project, out)}`);
+    return 0;
+  }
+  const tpl = readText(path.join(TEMPLATES, 'manifest', 'package-tad.xml'));
+  const types = [...tpl.matchAll(/<types>([\s\S]*?)<\/types>/g)].map((m) => ({ name: /<name>([^<]+)<\/name>/.exec(m[1])[1], members: [...m[1].matchAll(/<members>([^<]+)<\/members>/g)].map((x) => x[1]) }));
+  const version = /<version>([^<]+)<\/version>/.exec(tpl)[1];
+  log.step('Asking the org which metadata types it supports…');
+  const described = await sfJson(['org', 'list', 'metadata-types', '--target-org', alias], { timeoutMs: 300000 });
+  const supported = new Set();
+  for (const o of described.metadataObjects || []) { supported.add(o.xmlName); for (const ch of o.childXmlNames || []) supported.add(ch); }
+  const kept = [], dropped = [];
+  for (const t of types) (supported.has(t.name) || t.name === 'CustomObject' ? kept : dropped).push(t);
+
+  // Foldered types: `*` does not reach inside folders, list each folder's content explicitly.
+  for (const t of kept.filter((x) => FOLDERED[x.name])) {
+    try {
+      const folders = await sfJson(['org', 'list', 'metadata', '--metadata-type', FOLDERED[t.name], '--target-org', alias]);
+      const names = [];
+      for (const fo of (Array.isArray(folders) ? folders : []).filter((x) => !x.namespacePrefix)) {
+        names.push(fo.fullName);
+        const items = await sfJson(['org', 'list', 'metadata', '--metadata-type', t.name, '--folder', fo.fullName, '--target-org', alias]).catch(() => []);
+        for (const it of Array.isArray(items) ? items : []) if (!it.namespacePrefix) names.push(it.fullName);
+      }
+      if (t.name === 'Report' || t.name === 'Dashboard') {
+        const unfiled = await sfJson(['org', 'list', 'metadata', '--metadata-type', t.name, '--folder', 'unfiled$public', '--target-org', alias]).catch(() => []);
+        for (const it of Array.isArray(unfiled) ? unfiled : []) names.push(it.fullName);
+      }
+      t.members = [...new Set(names)].sort();
+      log.info(`${t.name}: ${t.members.length} member(s) in folders`);
+    } catch (e) { log.warn(`${t.name}: folder listing failed (${e.message.slice(0, 120)})`); }
+  }
+  // Standard objects: `*` covers custom objects only; add the standard objects the org exposes.
+  try {
+    const objs = await sfJson(['org', 'list', 'metadata', '--metadata-type', 'CustomObject', '--target-org', alias], { timeoutMs: 300000 });
+    const co = kept.find((x) => x.name === 'CustomObject');
+    const std = (Array.isArray(objs) ? objs : []).filter((o) => !o.namespacePrefix && !/__/.test(o.fullName)).map((o) => o.fullName);
+    co.members = [...new Set(['*', ...co.members, ...std])].sort((a, b) => (a === '*' ? -1 : b === '*' ? 1 : a.localeCompare(b)));
+    log.info(`CustomObject: * plus ${std.length} standard object(s)`);
+  } catch (e) { log.warn(`Standard objects listing failed, keeping the template list (${e.message.slice(0, 120)})`); }
+
+  const xml = ['<?xml version="1.0" encoding="UTF-8"?>', '<Package xmlns="http://soap.sforce.com/2006/04/metadata">',
+    ...kept.filter((t) => t.members.length).map((t) => `    <types>\n${t.members.map((m) => `        <members>${m}</members>`).join('\n')}\n        <name>${t.name}</name>\n    </types>`),
+    `    <version>${version}</version>`, '</Package>', ''].join('\n');
+  writeText(out, xml);
+  writeJson(ctx.p('.snapshot', 'manifest-report.json'), { mode, kept: kept.map((t) => t.name), dropped: dropped.map((t) => t.name) });
+  log.ok(`Manifest written: ${path.relative(ctx.project, out)} (${kept.length} types${dropped.length ? `, ${dropped.length} not available in this org` : ''})`);
+  return 0;
+}
+
+/** Retrieve the manifest into tadforce/.snapshot/source, type batch by type batch. force-app is never touched. */
+export async function retrieve(args) {
+  const ctx = loadWorkspace(args.cwd || process.cwd());
+  const alias = requireAlias(ctx, args);
+  const mf = ctx.p('.snapshot', 'package.xml');
+  if (!exists(mf)) throw new Error('No manifest: run `tadforce manifest` first.');
+  const xml = readText(mf);
+  const types = [...xml.matchAll(/<types>[\s\S]*?<\/types>/g)].map((m) => m[0]);
+  const version = /<version>([^<]+)<\/version>/.exec(xml)[1];
+  const size = Number(args.batchSize || 12);
+  const outDir = ctx.p(ctx.cfg.source.dir);
+  fs.mkdirSync(outDir, { recursive: true });
+  log.banner('retrieve');
+  const failed = [];
+  const runBatch = async (batch, label) => {
+    const p = ctx.p('.snapshot', 'batch.xml');
+    writeText(p, `<?xml version="1.0" encoding="UTF-8"?>\n<Package xmlns="http://soap.sforce.com/2006/04/metadata">\n${batch.join('\n')}\n    <version>${version}</version>\n</Package>\n`);
+    await sfJson(['project', 'retrieve', 'start', '--manifest', p, '--target-org', alias, '--output-dir', outDir, '--wait', String(args.wait || 60), '--ignore-conflicts'], { timeoutMs: 3600000, cwd: ctx.project });
+    log.ok(label);
+  };
+  for (let i = 0; i < types.length; i += size) {
+    const batch = types.slice(i, i + size);
+    const names = batch.map((b) => /<name>([^<]+)<\/name>/.exec(b)[1]);
+    try {
+      await runBatch(batch, `${names.join(', ')}`);
+    } catch (e) {
+      log.warn(`Batch failed (${e.message.slice(0, 160)}) — retrying type by type`);
+      for (const b of batch) {
+        const n = /<name>([^<]+)<\/name>/.exec(b)[1];
+        try { await runBatch([b], n); } catch (e2) { failed.push({ type: n, error: e2.message.slice(0, 300) }); log.warn(`${n}: skipped (${e2.message.slice(0, 120)})`); }
+      }
+    }
+  }
+  writeJson(ctx.p('.snapshot', 'retrieve-report.json'), { failed });
+  log.ok(`Snapshot ready in ${path.relative(ctx.project, outDir)}${failed.length ? ` — ${failed.length} type(s) could not be retrieved (see .snapshot/retrieve-report.json)` : ''}.`);
+  return 0;
+}

package/src/commands/review.js

@@ -0,0 +1,35 @@
+// `tadforce review`: open the document to comment it (Save writes back to the same file),
+// and list the open comments for the agent (/tadforce-review folds them into the sources).
+import path from 'node:path';
+import { exists } from '../util/fsx.js';
+import { loadWorkspace } from '../util/config.js';
+import { outputName } from '../build/render.js';
+import { serveDocument, openInBrowser } from '../build/serve.js';
+import { log } from '../util/log.js';
+import * as docs from './docs.js';
+
+export function documentPath(ctx, args) {
+  const doc = args.doc && args.doc !== 'all' ? args.doc : 'tad';
+  return args._[1] ? path.resolve(args._[1]) : path.join(ctx.p(ctx.cfg.outputs.dir || 'out'), outputName(ctx.cfg, doc) + '.html');
+}
+
+/** Serve the file until Ctrl+C. Every Save in the page replaces this file, comments included. */
+export async function open(file) {
+  const s = await serveDocument(file);
+  log.ok(`Open: ${s.url}`);
+  log.info(`« Save » in the page writes into ${file} — one file, the comments stay in it. Ctrl+C to stop.`);
+  openInBrowser(s.url);
+  await new Promise((resolve) => { process.once('SIGINT', resolve); process.once('SIGTERM', resolve); });
+  await s.close();
+  return 0;
+}
+
+export async function run(args) {
+  const ctx = loadWorkspace(args.cwd || process.cwd());
+  const file = documentPath(ctx, args);
+  if (!exists(file)) throw new Error(`No document at ${file}: run \`tadforce build\` first.`);
+  await docs.comments({ ...args, _: ['comments', file] });
+  if (args.json || args.open === false || !process.stdout.isTTY) return 0;
+  console.log('');
+  return open(file);
+}

package/src/commands/spec.js

@@ -0,0 +1,91 @@
+// `tadforce spec <id>` and `tadforce next`: what to write, with the facts to write it from.
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+import { exists, readText, readYaml } from '../util/fsx.js';
+import { loadWorkspace } from '../util/config.js';
+import { TEMPLATES } from '../util/paths.js';
+import { loadFacts } from '../facts/index.js';
+import { resolveConditionals, get } from '../build/directives.js';
+import { DOCS } from '../build/render.js';
+import { log } from '../util/log.js';
+
+const specs = () => readYaml(path.join(TEMPLATES, 'specs', 'sections.yml'), {}).sections || {};
+
+/** Compact view of a facts path: arrays are summarised (count + first items), long strings cut. */
+function excerpt(value, depth = 0) {
+  if (Array.isArray(value)) {
+    const items = value.slice(0, depth ? 8 : 25).map((v) => excerpt(v, depth + 1));
+    return value.length > items.length ? { count: value.length, first: items } : items;
+  }
+  if (value && typeof value === 'object') {
+    if (depth > 2) return '{…}';
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, excerpt(v, depth + 1)]));
+  }
+  if (typeof value === 'string' && value.length > 200) return value.slice(0, 199) + '…';
+  return value;
+}
+
+export function specWithFacts(ctx, id) {
+  const s = specs()[id];
+  if (!s) return null;
+  const facts = loadFacts(ctx.ws) || {};
+  const out = { id, ...s, factsExcerpt: {} };
+  for (const p of s.facts || []) {
+    if (p.startsWith('knowledge/')) {
+      const dir = ctx.p(p);
+      out.factsExcerpt[p] = exists(dir) ? fs.readdirSync(dir) : [];
+      continue;
+    }
+    const v = get(facts, p) ?? get(facts.counts || {}, p);
+    if (v !== undefined) out.factsExcerpt[p] = excerpt(v);
+  }
+  if (s.modules) {
+    const refs = s.modules.includes('all detected') ? (facts.modules && facts.modules.references) || [] : s.modules.filter((m) => (facts.modules && facts.modules.references || []).includes(m) || s.modules.length === 1);
+    out.readModules = refs.map((r) => `skills/tadforce/references/modules/${r}.md`);
+  }
+  return out;
+}
+
+export async function spec(args) {
+  const ctx = loadWorkspace(args.cwd || process.cwd());
+  const id = args._[1];
+  if (!id) { console.log(Object.keys(specs()).join('\n')); return 0; }
+  const s = specWithFacts(ctx, id);
+  if (!s) { log.fail(`Unknown section "${id}".`); return 1; }
+  console.log(args.json ? JSON.stringify(s, null, 2) : YAML.stringify(s, { lineWidth: 120 }));
+  return 0;
+}
+
+/** First section still to write (in reading order), among the sections active for this org. */
+export async function next(args) {
+  const ctx = loadWorkspace(args.cwd || process.cwd());
+  const facts = loadFacts(ctx.ws);
+  if (!facts) { log.fail('Run `tadforce facts` first.'); return 1; }
+  const scope = { modules: facts.modules, counts: facts.counts, org: facts.org, cfg: ctx.cfg, facts, glossary: ctx.glossary() };
+  const docs = !args.doc || args.doc === 'all' ? DOCS : [args.doc];
+  let remaining = 0, first = null;
+  for (const doc of docs) {
+    const dir = ctx.p('src', doc);
+    if (!exists(dir)) continue;
+    for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.md')).sort()) {
+      const raw = readText(path.join(dir, f));
+      const active = resolveConditionals(raw, scope);
+      for (const m of active.matchAll(/<!--\s*tad:pending\s+([\w.-]+)\s*-->/g)) {
+        remaining++;
+        if (!first) {
+          const line = raw.split('\n').findIndex((l) => l.includes(m[0])) + 1;
+          first = { doc, file: path.relative(ctx.project, path.join(dir, f)).split(path.sep).join('/'), line, marker: m[0] };
+          first.spec = specWithFacts(ctx, m[1]) || { id: m[1] };
+        }
+      }
+    }
+  }
+  const result = { remaining, next: first };
+  if (args.json) { console.log(JSON.stringify(result, null, 2)); return 0; }
+  if (!first) { log.ok('Every section is written. Run `tadforce build --pdf --docx`.'); return 0; }
+  log.banner(`next · ${remaining} section(s) to write`);
+  console.log(`${first.file}:${first.line}  ${first.marker}\n`);
+  console.log(YAML.stringify(first.spec, { lineWidth: 120 }));
+  return 0;
+}

package/src/commands/update.js

@@ -0,0 +1,154 @@
+// `tadforce update`: a few months later, bring an existing document up to date. The previous facts are
+// archived, the org is read again, and only the sections touched by what changed are handed back to the agent.
+import fs from 'node:fs';
+import path from 'node:path';
+import { exists, readJson, readText, readYaml, writeJson } from '../util/fsx.js';
+import { AREAS, fingerprints } from '../facts/fingerprints.js';
+import { loadWorkspace, sourceDirs } from '../util/config.js';
+import { TEMPLATES } from '../util/paths.js';
+import { log, c } from '../util/log.js';
+import { templateLang } from '../util/i18n.js';
+import * as org from './org.js';
+import * as docs from './docs.js';
+
+/** Component name from a metadata path: classes/Foo.cls → Foo, lwc/bar/bar.js → bar, objects/X/fields/Y… → X.Y. */
+function component(rel) {
+  const [folder, ...rest] = rel.split('/');
+  const strip = (s) => s.replace(/(-meta)?\.xml$/, '').replace(/\.[^.]+$/, '');
+  if (folder === 'objects' && rest.length > 2) return `${rest[0]}.${strip(rest[2])}`;
+  if (rest.length > 1) return rest[0];
+  return strip(rest[0] || folder);
+}
+
+export function diffFingerprints(before, after) {
+  const changes = { added: new Map(), removed: new Map(), changed: new Map() };
+  const put = (kind, rel) => { const key = `${rel.split('/')[0]}:${component(rel)}`; if (!changes[kind].has(key)) changes[kind].set(key, { folder: rel.split('/')[0], name: component(rel) }); };
+  for (const [rel, h] of Object.entries(after)) { if (!(rel in before)) put('added', rel); else if (before[rel] !== h) put('changed', rel); }
+  for (const rel of Object.keys(before)) if (!(rel in after)) put('removed', rel);
+  // a component with some files added and others changed counts once, as changed
+  for (const k of changes.changed.keys()) { changes.added.delete(k); changes.removed.delete(k); }
+  for (const k of changes.added.keys()) if (changes.removed.has(k)) { changes.changed.set(k, changes.added.get(k)); changes.added.delete(k); changes.removed.delete(k); }
+  return Object.fromEntries(Object.entries(changes).map(([k, m]) => [k, [...m.values()].sort((a, b) => (a.folder + a.name).localeCompare(b.folder + b.name))]));
+}
+
+/** Counts that moved: { 'apex.classes': [132, 140] }. */
+export function diffCounts(a = {}, b = {}, prefix = '') {
+  const out = {};
+  for (const k of new Set([...Object.keys(a), ...Object.keys(b)])) {
+    const x = a[k], y = b[k], key = prefix ? `${prefix}.${k}` : k;
+    if (x && typeof x === 'object' || y && typeof y === 'object') Object.assign(out, diffCounts(x || {}, y || {}, key));
+    else if (x !== y) out[key] = [x ?? 0, y ?? 0];
+  }
+  return out;
+}
+
+/** Where each section lives: spec id → chapter file and the heading anchor above its marker. */
+function sectionLocations(lang) {
+  const out = {};
+  for (const doc of ['tad', 'axes']) {
+    const dir = path.join(TEMPLATES, doc, lang);
+    if (!exists(dir)) continue;
+    for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.md')).sort()) {
+      let anchor = null;
+      for (const line of readText(path.join(dir, f)).split('\n')) {
+        const h = /^#{1,4} .*\{[^}]*#([\w-]+)[^}]*\}\s*$/.exec(line);
+        if (h) anchor = h[1];
+        const m = /<!--\s*tad:pending\s+([\w.-]+)\s*-->/.exec(line);
+        if (m) out[m[1]] = { doc, file: `src/${doc}/${f}`, anchor };
+      }
+    }
+  }
+  return out;
+}
+
+/** Sections whose spec reads a facts area that changed. */
+export function affectedSections(areas, specs, locations) {
+  const hits = [];
+  for (const [id, s] of Object.entries(specs)) {
+    const reasons = [];
+    for (const p of s.facts || []) {
+      const fp = p.replace(/^counts\./, '');
+      for (const [area, why] of Object.entries(areas)) {
+        if (p === 'counts' || fp === area || fp.startsWith(area + '.') || area.startsWith(fp + '.') || (p === 'modules' && area === 'modules')) reasons.push(...why);
+      }
+    }
+    if (reasons.length) hits.push({ id, ...(locations[id] || {}), reasons: [...new Set(reasons)].slice(0, 12) });
+  }
+  return hits;
+}
+
+const nextVersion = (v) => { const m = /^(\d+)\.(\d+)$/.exec(String(v)); return m ? `${m[1]}.${Number(m[2]) + 1}` : `${v}.1`; };
+
+export async function run(args) {
+  const ctx = loadWorkspace(args.cwd || process.cwd());
+  const say = (fn) => { if (!args.json) fn(); };
+  const before = ctx.p('facts', 'facts.json');
+  if (!exists(before)) throw new Error('No previous facts: run `tadforce doctor` and `tadforce build` first.');
+  say(() => log.banner('update'));
+
+  // 1. Archive what the current document was written from.
+  const stamp = new Date().toISOString().slice(0, 10);
+  const archive = ctx.p('facts', 'history', stamp);
+  fs.mkdirSync(archive, { recursive: true });
+  const oldFacts = readJson(before);
+  const oldPrints = exists(ctx.p('facts', 'fingerprints.json')) ? readJson(ctx.p('facts', 'fingerprints.json')) : fingerprints(sourceDirs(ctx));
+  writeJson(path.join(archive, 'facts.json'), oldFacts);
+  writeJson(path.join(archive, 'fingerprints.json'), oldPrints);
+  say(() => log.ok(`Previous facts archived in ${path.relative(ctx.project, archive)}`));
+
+  // 2. Read the org again (a fresh snapshot: deleted components must disappear too).
+  const mode = ctx.cfg.source.mode || 'org';
+  const quiet = async (fn) => { if (!args.json) return fn(); const o = console.log; console.log = () => {}; try { return await fn(); } finally { console.log = o; } };
+  if (mode !== 'local' && !args.skipRetrieve) {
+    const snap = ctx.p(ctx.cfg.source.dir);
+    if (exists(snap)) fs.rmSync(snap, { recursive: true, force: true });
+    for (const fn of [org.manifest, org.retrieve]) { const code = await quiet(() => fn({ ...args, cwd: ctx.project })); if (code) return code; }
+  }
+  await quiet(() => docs.facts({ ...args, cwd: ctx.project, org: mode === 'local' || args.skipRetrieve ? false : ctx.cfg.org.alias }));
+  const ctx2 = loadWorkspace(ctx.project);
+  const newPrints = fingerprints(sourceDirs(ctx2));
+  writeJson(ctx2.p('facts', 'fingerprints.json'), newPrints);
+  const newFacts = readJson(ctx2.p('facts', 'facts.json'));
+
+  // 3. What changed, and which sections it touches.
+  const diff = diffFingerprints(oldPrints, newPrints);
+  const counts = diffCounts(oldFacts.counts, newFacts.counts);
+  const areas = {};
+  const note = (area, why) => { (areas[area] ||= []).push(why); };
+  for (const [kind, list] of Object.entries(diff)) for (const x of list) note(AREAS[x.folder], `${kind} ${x.folder}:${x.name}`);
+  const COUNT_AREAS = { objects: 'data', fields: 'data', recordTypes: 'data', validationRules: 'data', cmdt: 'data.cmdtTypes', flows: 'automation.flows', omni: 'automation.omnistudio' };
+  for (const [k, [a, b]] of Object.entries(counts)) { const top = k.split('.')[0]; if (top !== 'exclusions') note(COUNT_AREAS[top] || top, `count ${k}: ${a} → ${b}`); }
+  const modulesBefore = (oldFacts.modules?.clouds || []).map((x) => x.name), modulesAfter = (newFacts.modules?.clouds || []).map((x) => x.name);
+  for (const m of modulesAfter.filter((x) => !modulesBefore.includes(x))) note('modules', `new product detected: ${m}`);
+  for (const m of modulesBefore.filter((x) => !modulesAfter.includes(x))) note('modules', `product no longer detected: ${m}`);
+  const specs = readYaml(path.join(TEMPLATES, 'specs', 'sections.yml'), {}).sections || {};
+  const sections = affectedSections(areas, specs, sectionLocations(templateLang(ctx2.cfg.language)));
+
+  // 4. New version in the document control.
+  const cfg = ctx2.cfg;
+  const total = diff.added.length + diff.changed.length + diff.removed.length;
+  const from = cfg.document.version;
+  if (total && args.bump !== false) {
+    const by = [cfg.document.author, cfg.integrator.name].filter(Boolean).join(' — ') || cfg.client.name;
+    const history = cfg.document.history && cfg.document.history.length ? cfg.document.history : [{ version: from, date: cfg.document.date, author: by, purpose: cfg.language === 'fr' ? 'Version initiale' : 'Initial version' }];
+    cfg.document.version = nextVersion(from);
+    cfg.document.date = stamp;
+    const purpose = cfg.language === 'fr'
+      ? `Mise à jour : ${diff.added.length} composant(s) ajouté(s), ${diff.changed.length} modifié(s), ${diff.removed.length} supprimé(s)`
+      : `Update: ${diff.added.length} component(s) added, ${diff.changed.length} changed, ${diff.removed.length} removed`;
+    cfg.document.history = [...history, { version: cfg.document.version, date: stamp, author: by, purpose }];
+    ctx2.save(cfg);
+  }
+  const report = { from, to: cfg.document.version, changes: diff, counts, sections, next: sections.length ? 'rewrite each listed section from the new facts (keep its heading and anchor), then `tadforce build`' : 'tadforce build' };
+  writeJson(ctx2.p('facts', 'update.json'), report);
+  if (args.json) { console.log(JSON.stringify(report, null, 2)); return 0; }
+
+  if (!total && !Object.keys(counts).length) { log.ok('Nothing changed since the last version. The document is up to date.'); return 0; }
+  log.ok(`${diff.added.length} added · ${diff.changed.length} changed · ${diff.removed.length} removed · ${Object.keys(counts).length} count(s) moved`);
+  for (const [kind, list] of Object.entries(diff)) if (list.length) console.log(`  ${c.bold(kind)}: ${list.slice(0, 15).map((x) => `${x.folder}/${x.name}`).join(', ')}${list.length > 15 ? c.dim(` … +${list.length - 15}`) : ''}`);
+  if (total) log.ok(`Version ${from} → ${cfg.document.version} (history updated)`);
+  log.step(`${sections.length} section(s) to review:`);
+  for (const s of sections) console.log(`  ${c.cyan(s.id.padEnd(28))} ${c.dim((s.file || '') + (s.anchor ? '#' + s.anchor : ''))}  ${s.reasons.slice(0, 2).join('; ')}`);
+  log.human('let your agent rewrite these sections (/tadforce-update), then `tadforce build`. Numbers and generated tables update by themselves.');
+  return 0;
+}