baldart 4.82.0 → 4.83.0

package/src/utils/root-primitives.js

@@ -0,0 +1,418 @@
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const {
+  mergeOverlay,
+  shortSha,
+  MARKER_PREFIX,
+  isGeneratedFile,
+} = require('./overlay-merger');
+
+/**
+ * Root-file primitives writer (AGENTS.md + CLAUDE.md).
+ *
+ * BALDART ships versioned skeletons under
+ * `.framework/framework/templates/primitives/<NAME>.md`. This module resolves
+ * their `{{ slot }}` / `{{> partial }}` / `{{#flag}}` placeholders from
+ * `baldart.config.yml` (+ package.json / README probes) at install/update time,
+ * merges `.baldart/overlays/<NAME>.md` (OVERRIDE/APPEND/PREPEND via
+ * overlay-merger), stamps a `baldart-generated` marker, and writes the concrete
+ * file to the consumer repo root.
+ *
+ * The marker reuses overlay-merger's MARKER_PREFIX and keeps `kind`, `name`,
+ * `base_sha`, `overlay_sha` in the positions overlay-merger's `readMarker`
+ * expects — so `isGeneratedFile()` and the framework-edit-gate recognise these
+ * root files as generated. Two extra trailing fields (`config_sha`,
+ * `primitive_version`) are appended AFTER `overlay_sha`, which readMarker
+ * tolerates (it matches a prefix). `base_sha` carries the raw-template sha.
+ *
+ * States handled per file (checked in this order): generated (regenerate) →
+ * symlink (legacy AGENTS.md → replace) → handwritten (adopt) → absent (create).
+ */
+
+const FRAMEWORK_PAYLOAD = path.join('.framework', 'framework');
+const PRIMITIVES = ['AGENTS', 'CLAUDE'];
+
+// ---------------------------------------------------------------------------
+// small fs helpers (mirror configure.js detect() ergonomics)
+// ---------------------------------------------------------------------------
+function readSafe(p) { try { return fs.readFileSync(p, 'utf8'); } catch (_) { return ''; } }
+function readJsonSafe(p) { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) { return null; } }
+function existsAt(p) { try { fs.accessSync(p); return true; } catch (_) { return false; } }
+
+function loadConfig(cwd) {
+  const p = path.join(cwd, 'baldart.config.yml');
+  try { return yaml.load(fs.readFileSync(p, 'utf8')) || {}; }
+  catch (_) { return {}; }
+}
+
+function readPrimitiveVersion(templateContent) {
+  const m = templateContent.match(/baldart-primitive:[^\n]*primitive_version=([0-9]+\.[0-9]+\.[0-9]+)/);
+  return m ? m[1] : '0.0.0';
+}
+
+// ---------------------------------------------------------------------------
+// slot resolution — deterministic, no LLM, no invention
+// ---------------------------------------------------------------------------
+const PRETTY = {
+  nextjs: 'Next.js', remix: 'Remix', sveltekit: 'SvelteKit', astro: 'Astro',
+  nuxt: 'Nuxt', rails: 'Rails', django: 'Django', fastapi: 'FastAPI', express: 'Express',
+  supabase: 'Supabase', firestore: 'Firestore', postgres: 'Postgres', mysql: 'MySQL',
+  mongodb: 'MongoDB', dynamodb: 'DynamoDB', sqlite: 'SQLite',
+  'firebase-auth': 'Firebase Auth', 'supabase-auth': 'Supabase Auth', clerk: 'Clerk',
+  auth0: 'Auth0', cognito: 'Cognito', nextauth: 'NextAuth', lucia: 'Lucia',
+  playwright: 'Playwright', cypress: 'Cypress', biome: 'Biome', vitest: 'Vitest',
+  eslint: 'ESLint', prettier: 'Prettier', tsc: 'TypeScript', jest: 'Jest',
+};
+function pretty(v) { return PRETTY[v] || v; }
+
+function detectPackageManager(cwd) {
+  if (existsAt(path.join(cwd, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (existsAt(path.join(cwd, 'yarn.lock'))) return 'yarn';
+  if (existsAt(path.join(cwd, 'bun.lockb'))) return 'bun';
+  return 'npm';
+}
+
+function deriveSourceRoot(cwd) {
+  for (const d of ['src', 'app', 'lib']) {
+    if (existsAt(path.join(cwd, d))) return `${d}/`;
+  }
+  return '';
+}
+
+function firstParagraph(readme) {
+  if (!readme) return '';
+  const lines = readme.split('\n');
+  let i = 0;
+  // skip leading blanks + a single H1
+  while (i < lines.length && lines[i].trim() === '') i++;
+  if (i < lines.length && /^#\s+/.test(lines[i])) i++;
+  while (i < lines.length && lines[i].trim() === '') i++;
+  const para = [];
+  while (i < lines.length && lines[i].trim() !== '' && !/^#{1,6}\s/.test(lines[i]) && !/^[-*]\s/.test(lines[i])) {
+    para.push(lines[i].trim());
+    i++;
+  }
+  const text = para.join(' ').trim();
+  return text.length > 200 ? text.slice(0, 197).trimEnd() + '…' : text;
+}
+
+/**
+ * Resolve every slot + partial + flag from config and repo probes.
+ * Returns { scalars, partials, flags, meta }.
+ */
+function resolveSlots(cwd, cfg) {
+  const pkg = readJsonSafe(path.join(cwd, 'package.json')) || {};
+  const readme = readSafe(path.join(cwd, 'README.md'));
+  const identity = cfg.identity || {};
+  const stack = cfg.stack || {};
+  const paths = cfg.paths || {};
+  const features = cfg.features || {};
+  const git = cfg.git || {};
+  const toolchain = cfg.toolchain || {};
+  const pm = detectPackageManager(cwd);
+
+  // identity.name
+  let name = identity.brand_name || pkg.name || path.basename(cwd);
+  if (typeof name === 'string' && name.startsWith('@') && name.includes('/')) name = name.split('/')[1];
+
+  // identity.description
+  const description = firstParagraph(readme)
+    || (pkg.description ? String(pkg.description).trim() : '')
+    || '<!-- TODO: one-line description of what this project is -->';
+
+  // stack.summary (compose present, pretty)
+  const stackParts = [];
+  if (stack.framework && stack.framework !== 'none') stackParts.push(pretty(stack.framework));
+  if (stack.database && stack.database !== 'none') stackParts.push(pretty(stack.database));
+  if (stack.auth_provider && stack.auth_provider !== 'none') stackParts.push(pretty(stack.auth_provider));
+  const e2e = stack.testing && stack.testing.e2e;
+  if (e2e) stackParts.push(pretty(e2e));
+  if (Array.isArray(toolchain.installed_tools)) {
+    for (const t of toolchain.installed_tools) { const p = pretty(t); if (!stackParts.includes(p)) stackParts.push(p); }
+  }
+  const stackSummary = stackParts.length ? stackParts.join(' · ') : 'the project stack';
+
+  // stack.node
+  let node = (pkg.engines && pkg.engines.node) ? String(pkg.engines.node).trim() : '';
+  if (!node) { const nvmrc = readSafe(path.join(cwd, '.nvmrc')).trim(); if (nvmrc) node = nvmrc.replace(/^v/, ''); }
+  const nodeSuffix = node ? ` Node ${node}.` : '';
+
+  // output style (Claude-only, personal settings)
+  const settingsLocal = readJsonSafe(path.join(cwd, '.claude', 'settings.local.json')) || {};
+  const outputStyle = typeof settingsLocal.outputStyle === 'string' ? settingsLocal.outputStyle : '';
+
+  // flags
+  const flags = {
+    has_backlog: features.has_backlog === true,
+    has_adrs: features.has_adrs === true,
+    has_i18n: features.has_i18n === true,
+    has_design_system: features.has_design_system === true,
+    has_toolchain: features.has_toolchain === true,
+    has_project_status: !!(paths.references_dir && existsAt(path.join(cwd, paths.references_dir, 'project-status.md'))),
+    output_style: !!outputStyle,
+  };
+
+  const scalars = {
+    'identity.name': name,
+    'identity.description': description,
+    'stack.summary': stackSummary,
+    'stack.node_suffix': nodeSuffix,
+    'git.trunk_branch': git.trunk_branch || 'main',
+    'git.feature_prefix': 'feat', // STATIC BALDART convention
+    'git.commit_format': '[FEAT-XXXX] description', // STATIC default (override via overlay)
+    'i18n.registry': paths.i18n_registry || 'the i18n registry',
+    'output_style': outputStyle,
+  };
+
+  const partials = {
+    commands_section: buildCommandsSection(pkg, toolchain, pm),
+    repo_map: buildRepoMap(cwd, paths, flags),
+  };
+
+  return { scalars, partials, flags };
+}
+
+function buildCommandsSection(pkg, toolchain, pm) {
+  const scripts = (pkg && pkg.scripts) || {};
+  const tc = (toolchain && toolchain.commands) || {};
+  const run = (s) => `${pm} run ${s}`;
+  const rows = [];
+  const push = (label, cmd) => { if (cmd) rows.push(`| \`${cmd}\` | ${label} |`); };
+  push('Run the app (dev)', scripts.dev ? run('dev') : (scripts.start ? run('start') : ''));
+  push('Production build', tc.build || (scripts.build ? run('build') : ''));
+  push('Lint', tc.lint || (scripts.lint ? run('lint') : ''));
+  push('Type check', tc.typecheck || (scripts.typecheck ? run('typecheck') : ''));
+  push('Unit tests', tc.test || (scripts.test ? run('test') : ''));
+  push('E2E tests', scripts['test:e2e'] ? run('test:e2e') : '');
+  push('Full QA gate', scripts.qa ? run('qa') : '');
+  if (!rows.length) return '';
+  return '## Commands\n\n| Command | Purpose |\n|---|---|\n' + rows.join('\n') + '\n';
+}
+
+function buildRepoMap(cwd, paths, flags) {
+  const lines = ['- `AGENTS.md` (this file) + `CLAUDE.md` (Claude Code entry).'];
+  const sourceRoot = deriveSourceRoot(cwd);
+  if (sourceRoot) lines.push(`- \`${sourceRoot}\` — application code.`);
+  if (flags.has_backlog && paths.backlog_dir) lines.push(`- \`${paths.backlog_dir}\` — work cards.`);
+  if (paths.references_dir) lines.push(`- \`${paths.references_dir}\` — data model, API, status, history.`);
+  if (flags.has_adrs && paths.adrs_dir) lines.push(`- \`${paths.adrs_dir}\` — architectural decision records.`);
+  if (flags.has_design_system && paths.design_system) lines.push(`- \`${paths.design_system}\` — design-system SSOT.`);
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// minimal template engine: {{#flag}}…{{/flag}}, {{> partial}}, {{ scalar }}
+// ---------------------------------------------------------------------------
+function fillTemplate(template, { scalars, partials, flags }) {
+  // 1. strip leading authoring banner (<!-- baldart-primitive: … -->)
+  let out = template.replace(/^?\s*<!--\s*baldart-primitive:[\s\S]*?-->\s*\n/, '');
+
+  // 2. conditionals (non-nested; each flag block resolved independently)
+  out = out.replace(/\{\{#([\w.]+)\}\}\n?([\s\S]*?)\{\{\/\1\}\}\n?/g, (_, key, body) =>
+    (flags[key] ? body : ''));
+
+  // 3. partials (whole-line replacement)
+  out = out.replace(/^[ \t]*\{\{>\s*([\w.]+)\s*\}\}[ \t]*$/gm, (_, key) =>
+    (partials[key] != null ? partials[key] : ''));
+
+  // 4. scalars
+  out = out.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_, key) =>
+    (scalars[key] != null ? String(scalars[key]) : ''));
+
+  // 5. cleanup — drop empty bullets/rows, collapse blank runs, single trailing NL
+  out = out
+    .split('\n')
+    .filter((l) => !/^\s*[-|]\s*$/.test(l))
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .replace(/\s+$/, '') + '\n';
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// marker
+// ---------------------------------------------------------------------------
+function buildRootMarker({ name, templateSha, overlaySha, configSha, primitiveVersion }) {
+  return `${MARKER_PREFIX} kind=root name=${name} base_sha=${templateSha} overlay_sha=${overlaySha || 'none'} config_sha=${configSha} primitive_version=${primitiveVersion}
+     DO NOT EDIT MANUALLY. Edit .baldart/overlays/${name}.md instead;
+     this file is regenerated by \`npx baldart update\`. -->`;
+}
+
+function readRootMarker(content) {
+  const idx = content.indexOf(MARKER_PREFIX);
+  if (idx === -1) return null;
+  const block = content.slice(idx, idx + 4000);
+  const end = block.indexOf('-->');
+  if (end === -1) return null;
+  const seg = block.slice(0, end);
+  const kind = (seg.match(/kind=(\S+)/) || [])[1];
+  if (kind !== 'root') return null;
+  return {
+    name: (seg.match(/name=(\S+)/) || [])[1] || null,
+    templateSha: (seg.match(/base_sha=(\S+)/) || [])[1] || null,
+    overlaySha: (seg.match(/overlay_sha=(\S+)/) || [])[1] || null,
+    configSha: (seg.match(/config_sha=(\S+)/) || [])[1] || null,
+    primitiveVersion: (seg.match(/primitive_version=(\S+)/) || [])[1] || null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// build the generated content for one primitive (no fs side effects)
+// ---------------------------------------------------------------------------
+function renderPrimitive({ cwd, name, cfg, frameworkVersion, overlayContent }) {
+  const templatePath = path.join(cwd, FRAMEWORK_PAYLOAD, 'templates', 'primitives', `${name}.md`);
+  const template = readSafe(templatePath);
+  if (!template) return null;
+  const primitiveVersion = readPrimitiveVersion(template);
+  const resolved = resolveSlots(cwd, cfg);
+  const filled = fillTemplate(template, resolved);
+
+  // section-merge overlay via the proven engine, then swap in our own marker.
+  const { generated } = mergeOverlay({
+    kind: 'root', name, baseContent: filled,
+    overlayContent: overlayContent || '', frameworkVersion,
+  });
+  // mergeOverlay puts its marker first (no frontmatter on root files); strip it.
+  let body = generated;
+  const mstart = body.indexOf(MARKER_PREFIX);
+  if (mstart !== -1) {
+    const mend = body.indexOf('-->', mstart);
+    if (mend !== -1) body = body.slice(mend + 3).replace(/^\n/, '');
+  }
+
+  const templateSha = shortSha(template);
+  const overlaySha = overlayContent ? shortSha(overlayContent) : 'none';
+  const configSha = shortSha(JSON.stringify(resolved) + '|' + templateSha);
+  const marker = buildRootMarker({ name, templateSha, overlaySha, configSha, primitiveVersion });
+  return { content: `${marker}\n${body}`.replace(/\s+$/, '') + '\n', templateSha, overlaySha, configSha, primitiveVersion };
+}
+
+// ---------------------------------------------------------------------------
+// state detection
+// ---------------------------------------------------------------------------
+function detectState(cwd, name) {
+  const rootPath = path.join(cwd, `${name}.md`);
+  let lstat = null;
+  try { lstat = fs.lstatSync(rootPath); } catch (_) { return { state: 'absent', content: '' }; }
+  if (lstat.isSymbolicLink()) return { state: 'symlink', content: '' };
+  const content = readSafe(rootPath);
+  if (isGeneratedFile(content) && readRootMarker(content)) return { state: 'generated', content };
+  return { state: 'handwritten', content };
+}
+
+// ---------------------------------------------------------------------------
+// public: status (for doctor) — does NOT write
+// ---------------------------------------------------------------------------
+function rootPrimitiveStatus({ cwd, name, cfg }) {
+  cfg = cfg || loadConfig(cwd);
+  const { state, content } = detectState(cwd, name);
+  if (state === 'absent') return { state, stale: true, reason: 'missing' };
+  if (state === 'symlink') return { state, stale: true, reason: 'legacy-symlink' };
+  if (state === 'handwritten') return { state, stale: false, reason: 'handwritten (needs adoption — run interactively)' };
+  // generated → compare marker vs freshly rendered
+  const rendered = renderPrimitive({ cwd, name, cfg, frameworkVersion: readFrameworkVersion(cwd), overlayContent: readOverlay(cwd, name) });
+  if (!rendered) return { state, stale: false, reason: 'no-template' };
+  const stale = content.replace(/\s+$/, '') !== rendered.content.replace(/\s+$/, '');
+  return { state, stale, reason: stale ? 'template / overlay / config drift' : 'up-to-date' };
+}
+
+function readOverlay(cwd, name) {
+  return readSafe(path.join(cwd, '.baldart', 'overlays', `${name}.md`));
+}
+function readFrameworkVersion(cwd) {
+  // The subtree pulls the whole repo into `.framework/`, so the VERSION file
+  // (repo root) lands at `.framework/VERSION` — NOT under the `framework/`
+  // payload subdir. (Informational only: feeds mergeOverlay's baseVersionTargeted.)
+  return readSafe(path.join(cwd, '.framework', 'VERSION')).trim() || 'unknown';
+}
+
+function isAutonomous(opts) {
+  if (opts && typeof opts.autonomous === 'boolean') return opts.autonomous;
+  return !!(process.env.CI || process.env.BALDART_AUTONOMOUS) || !process.stdout.isTTY;
+}
+
+// ---------------------------------------------------------------------------
+// public: write all root primitives (add / update / doctor / migrate)
+// ---------------------------------------------------------------------------
+/**
+ * @param {Object} opts
+ * @param {string} opts.cwd
+ * @param {string[]} [opts.tools]        enabled tools; CLAUDE.md needs 'claude'
+ * @param {boolean} [opts.autonomous]    CI/unattended → never mutate a handwritten file
+ * @returns {{ written:[], adopted:[], skipped:[], blockers:[] }}
+ */
+function writeRootPrimitives(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const tools = (opts.tools && opts.tools.length) ? opts.tools : ['claude'];
+  const UI = safeUI();
+  const cfg = loadConfig(cwd);
+  const frameworkVersion = readFrameworkVersion(cwd);
+  const autonomous = isAutonomous(opts);
+  const result = { written: [], adopted: [], skipped: [], blockers: [] };
+
+  for (const name of PRIMITIVES) {
+    // CLAUDE.md is Claude-only.
+    if (name === 'CLAUDE' && !tools.includes('claude')) { result.skipped.push({ name, reason: 'claude-disabled' }); continue; }
+
+    const templatePath = path.join(cwd, FRAMEWORK_PAYLOAD, 'templates', 'primitives', `${name}.md`);
+    if (!existsAt(templatePath)) { result.skipped.push({ name, reason: 'no-template' }); continue; }
+
+    const rootPath = path.join(cwd, `${name}.md`);
+    const overlayPath = path.join(cwd, '.baldart', 'overlays', `${name}.md`);
+    const { state, content } = detectState(cwd, name);
+
+    // Adoption: a handwritten file with no overlay yet.
+    if (state === 'handwritten' && !existsAt(overlayPath)) {
+      if (autonomous) {
+        result.blockers.push({ name, reason: `${name}.md è scritto a mano — esegui \`npx baldart\` in modalità interattiva per adottarlo in un overlay (nessuna modifica applicata ora)` });
+        result.skipped.push({ name, reason: 'handwritten-autonomous' });
+        continue;
+      }
+      // Preserve the handwritten file verbatim into the overlay (zero-loss on disk).
+      try {
+        fs.mkdirSync(path.dirname(overlayPath), { recursive: true });
+        fs.writeFileSync(overlayPath, content, 'utf8');
+      } catch (e) {
+        result.blockers.push({ name, reason: `impossibile scrivere l'overlay di adozione: ${e.message}` });
+        continue;
+      }
+      result.adopted.push({ name, overlay: path.relative(cwd, overlayPath) });
+      UI && UI.info(`Adottato ${name}.md → ${path.relative(cwd, overlayPath)} (verbatim, zero perdita). Rivedi e ri-smista: molte sezioni potrebbero appartenere all'overlay di AGENTS.md.`);
+    }
+
+    // Render + write (generated / symlink / absent / just-adopted).
+    const overlayContent = readOverlay(cwd, name);
+    const rendered = renderPrimitive({ cwd, name, cfg, frameworkVersion, overlayContent });
+    if (!rendered) { result.skipped.push({ name, reason: 'render-failed' }); continue; }
+
+    // Byte-stable: skip write if unchanged (avoids spurious diffs on update).
+    if (state === 'generated' && content.replace(/\s+$/, '') === rendered.content.replace(/\s+$/, '')) {
+      result.skipped.push({ name, reason: 'up-to-date' });
+      continue;
+    }
+    try {
+      if (state === 'symlink') { try { fs.unlinkSync(rootPath); } catch (_) {} }
+      fs.writeFileSync(rootPath, rendered.content, 'utf8');
+      result.written.push({ name, from: state });
+      UI && UI.success(`Root primitive scritto: ${name}.md (${state})`);
+    } catch (e) {
+      result.blockers.push({ name, reason: `impossibile scrivere ${name}.md: ${e.message}` });
+    }
+  }
+  return result;
+}
+
+function safeUI() { try { return require('./ui'); } catch (_) { return null; } }
+
+module.exports = {
+  writeRootPrimitives,
+  rootPrimitiveStatus,
+  renderPrimitive,
+  resolveSlots,
+  fillTemplate,
+  readRootMarker,
+  buildRootMarker,
+  detectState,
+  PRIMITIVES,
+};

package/src/utils/symlinks.js

@@ -150,15 +150,12 @@ class SymlinkUtils {
   async createBulkSymlinks(opts = {}) {
     const mode = opts.mode || 'prompt';
 
-    // AGENTS.md and the cross-tool `agents/` reference dir remain BULK
-    // symlinks — they're single canonical artifacts of the framework that
-    // do not need per-item user-overlay behaviour.
-    await this.createSymlink(
-      path.join(FRAMEWORK_PAYLOAD, 'AGENTS.md'),
-      'AGENTS.md',
-      { mode }
-    );
-
+    // NB: `AGENTS.md` is NO LONGER a bulk symlink since v4.83.0 — it is a
+    // generated real file (skeleton + slots + overlay) written by
+    // writeRootPrimitives(), which createAllSymlinks() invokes after the
+    // per-item merges. A pre-v4.83.0 install has AGENTS.md as a symlink; the
+    // writer detects that (state 'symlink') and replaces it with the generated
+    // file. The cross-tool `agents/` reference dir stays a bulk symlink.
     await this.createSymlink(
       path.join(FRAMEWORK_PAYLOAD, 'agents'),
       'agents',
@@ -358,6 +355,22 @@ class SymlinkUtils {
     this.mergeOutputStyles({ tools: opts.tools });
 
     UI.newline();
+    UI.section('Writing Root Primitives');
+    this.writeRootPrimitives({ tools: opts.tools, autonomous: opts.autonomous });
+
+    UI.newline();
+  }
+
+  /**
+   * Generate the root-file primitives (AGENTS.md + CLAUDE.md) from the
+   * versioned skeletons under `.framework/framework/templates/primitives/`,
+   * filling slots from baldart.config.yml and merging `.baldart/overlays/`.
+   * Delegates to the standalone writer module (see src/utils/root-primitives.js).
+   */
+  writeRootPrimitives(opts = {}) {
+    return require('./root-primitives').writeRootPrimitives({
+      cwd: this.cwd, tools: opts.tools, autonomous: opts.autonomous,
+    });
   }
 
   // -----------------------------------------------------------------------
@@ -695,8 +708,9 @@ class SymlinkUtils {
   }
 
   verifySymlinks() {
+    // NB: `AGENTS.md` is NOT here since v4.83.0 — it is a generated real file
+    // (writeRootPrimitives), no longer a bulk symlink. Only `agents/` remains.
     const bulkSymlinks = [
-      'AGENTS.md',
       'agents'
     ];