baldart 4.99.0 → 5.0.0

package/src/utils/symlinks.js

@@ -30,7 +30,10 @@ const CONFLICT_LOG = path.join('.baldart', 'skill-conflicts.json');
 //     kind name doesn't pluralize to the on-disk dir — e.g. `outputStyle` lives in
 //     the hyphenated `output-styles/` dir Claude Code requires, not `outputStyles/`.
 const MERGE_KINDS = {
-  agent:       { dirGetter: 'agentsDir',       ext: '.md', overlay: true,  exclude: new Set(['REGISTRY.md']) },
+  //  - slots: `.md` sources may carry `{{#flag}}` conditionals resolved at
+  //    install-time from baldart.config.yml (v5.0.0 — see agent-slots.js).
+  //    A slot-bearing source is GENERATED per-consumer even without an overlay.
+  agent:       { dirGetter: 'agentsDir',       ext: '.md', overlay: true,  slots: true, exclude: new Set(['REGISTRY.md', 'CHANGELOG.md']) },
   command:     { dirGetter: 'commandsDir',     ext: '.md', overlay: true,  exclude: new Set(['REGISTRY.md']) },
   workflow:    { dirGetter: 'workflowsDir',    ext: '.js', overlay: false, exclude: new Set() },
   outputStyle: { dirGetter: 'outputStylesDir', ext: '.md', overlay: false, exclude: new Set(), srcDir: 'output-styles' },
@@ -415,6 +418,28 @@ class SymlinkUtils {
 
     const frameworkVersion = this._readFrameworkVersion();
 
+    // v5.0.0 — install-time slot resolution (kinds with cfg.slots). Flags are
+    // resolved ONCE per merge run from baldart.config.yml; only sources that
+    // actually carry `{{#flag}}` syntax pay the fill (others stay symlinks).
+    let slotEnv = null;
+    const slotFillFor = (fwAbsolute) => {
+      if (!cfg.slots) return null;
+      const raw = fs.readFileSync(fwAbsolute, 'utf8');
+      const slots = require('./agent-slots');
+      if (!slots.hasAgentSlots(raw)) return null;
+      if (!slotEnv) {
+        const flags = slots.resolveAgentFlags(slots.loadAgentConfig(this.cwd));
+        slotEnv = { flags, configSha: slots.computeAgentConfigSha(flags) };
+      }
+      const filled = slots.fillAgentSlots(raw, slotEnv.flags);
+      return {
+        content: filled.content,
+        residual: filled.residual,
+        configSha: slotEnv.configSha,
+        rawBaseSha: require('./overlay-merger').shortSha(raw),
+      };
+    };
+
     for (const tool of tools) {
       const adapter = getAdapter(tool, this.cwd);
       const dirGetter = adapter[cfg.dirGetter];
@@ -438,14 +463,25 @@ class SymlinkUtils {
         const overlayAbs = path.join(this.cwd, overlayRel);
         const hasOverlay = cfg.overlay && fs.existsSync(overlayAbs);
 
+        // Slot fill (v5.0.0): resolved BEFORE overlay merge and BEFORE transpile,
+        // so both consume the config-effective markdown. A leftover `{{…}}` after
+        // the fill is an authoring error — surfaced, never silently stripped.
+        const slotFill = slotFillFor(fwAbsolute);
+        if (slotFill && slotFill.residual.length) {
+          const w = `unresolved slot token(s) after fill: ${slotFill.residual.join(' ')} — check the flag names in the framework source`;
+          UI.warning(`[${adapter.label}] ${kind} ${baseName}: ${w}`);
+          aggregate.warnings.push({ tool: adapter.name, kind, name: baseName, warning: w });
+        }
+
         // Transpile path: when the adapter declares a transpiler for this kind
         // (e.g. Codex agents → TOML), do NOT symlink the `.md` source — generate
-        // the tool-native file from it (overlay-merged first when present).
+        // the tool-native file from it (slot-filled + overlay-merged first).
         const transpiler = (typeof adapter.transpilerFor === 'function') ? adapter.transpilerFor(kind) : null;
         if (transpiler) {
           this._installTranspiledFile({
             kind, baseName, fwAbsolute, overlayAbs, hasOverlay,
-            targetRel, transpiler, adapter, frameworkVersion, aggregate
+            targetRel, transpiler, adapter, frameworkVersion, aggregate,
+            baseContentOverride: slotFill ? slotFill.content : null,
           });
           continue;
         }
@@ -454,11 +490,14 @@ class SymlinkUtils {
         let lstat = null;
         try { lstat = fs.lstatSync(linkPath); } catch (_) { /* absent */ }
 
-        if (hasOverlay) {
-          // Generate a real file from base + overlay.
+        if (hasOverlay || slotFill) {
+          // Generate a real file: slot-filled base + (optional) overlay.
           this._generateOverlayedFile({
             kind, name: baseName, fwAbsolute, overlayAbs, linkPath, lstat,
-            frameworkVersion, aggregate, adapter, targetRel
+            frameworkVersion, aggregate, adapter, targetRel, hasOverlay,
+            baseContentOverride: slotFill ? slotFill.content : null,
+            configSha: slotFill ? slotFill.configSha : null,
+            baseShaOverride: slotFill ? slotFill.rawBaseSha : null,
           });
         } else {
           // Plain symlink, with broken-symlink recovery (same fix-pattern as v3.5.1).
@@ -562,13 +601,14 @@ class SymlinkUtils {
    * `# baldart-generated:` marker so a later update can safely regenerate it
    * and a user fork (no marker) is never clobbered.
    */
-  _installTranspiledFile({ kind, baseName, fwAbsolute, overlayAbs, hasOverlay, targetRel, transpiler, adapter, frameworkVersion, aggregate }) {
+  _installTranspiledFile({ kind, baseName, fwAbsolute, overlayAbs, hasOverlay, targetRel, transpiler, adapter, frameworkVersion, aggregate, baseContentOverride = null }) {
     const outName = `${baseName}${transpiler.outExt}`;
     const outPath = path.join(this.cwd, targetRel, outName);
     const relOut = path.join(targetRel, outName);
 
-    // Effective markdown = overlay-merged when an overlay exists, else the base.
-    const baseContent = fs.readFileSync(fwAbsolute, 'utf8');
+    // Effective markdown = slot-filled (v5.0.0, when the source carries {{#flag}})
+    // then overlay-merged when an overlay exists, else the base.
+    const baseContent = baseContentOverride != null ? baseContentOverride : fs.readFileSync(fwAbsolute, 'utf8');
     let effectiveMd = baseContent;
     if (hasOverlay) {
       try {
@@ -621,27 +661,33 @@ class SymlinkUtils {
     aggregate.generated.push({ tool: adapter.name, kind, name: baseName });
   }
 
-  _generateOverlayedFile({ kind, name, fwAbsolute, overlayAbs, linkPath, lstat, frameworkVersion, aggregate, adapter, targetRel }) {
+  _generateOverlayedFile({ kind, name, fwAbsolute, overlayAbs, linkPath, lstat, frameworkVersion, aggregate, adapter, targetRel, hasOverlay = true, baseContentOverride = null, configSha = null, baseShaOverride = null }) {
     const { mergeOverlay, isGeneratedFile, computeBaseFileSha, ensureBaseFileShaInOverlay, refreshOverlayVersionPin } = require('./overlay-merger');
-    const baseContent = fs.readFileSync(fwAbsolute, 'utf8');
-    const baseSha = computeBaseFileSha(baseContent);
-    // Backfill base_file_sha into the overlay frontmatter so `overlay drift` is
-    // deterministic for EVERY overlay, not just freshly-scaffolded ones
-    // (additive-only, never overwrites). Done BEFORE reading overlayContent so
-    // the marker's overlay_sha already reflects it — no one-time regen churn.
-    // (v3.33.0)
-    try {
-      const bf = ensureBaseFileShaInOverlay(overlayAbs, baseSha);
-      if (bf.changed) UI.info(`[${adapter.label}] ${kind} ${name}: backfilled base_file_sha into overlay frontmatter.`);
-      // Keep the informational base_<kind>_version pin truthful — but ONLY when
-      // the base content is unchanged (sha matches). When the base HAS changed
-      // the sha differs and the pin is left stale on purpose, so it stays a
-      // legitimate drift signal to reconcile. (v4.11.0)
-      const vp = refreshOverlayVersionPin(overlayAbs, kind, frameworkVersion, baseSha);
-      if (vp.changed) UI.info(`[${adapter.label}] ${kind} ${name}: refreshed base_${kind}_version pin to v${frameworkVersion} (base unchanged).`);
-    } catch (_) { /* non-fatal — never block a merge on backfill */ }
-    const overlayContent = fs.readFileSync(overlayAbs, 'utf8');
-    const merged = mergeOverlay({ kind, name, baseContent, overlayContent, frameworkVersion });
+    // baseContentOverride = the slot-filled markdown (v5.0.0). The overlay pin
+    // and the marker's base_sha stay anchored to the RAW framework source
+    // (baseShaOverride) so upstream drift and config drift are separate signals.
+    const baseContent = baseContentOverride != null ? baseContentOverride : fs.readFileSync(fwAbsolute, 'utf8');
+    const baseSha = baseShaOverride || computeBaseFileSha(baseContent);
+    let overlayContent = '';
+    if (hasOverlay) {
+      // Backfill base_file_sha into the overlay frontmatter so `overlay drift` is
+      // deterministic for EVERY overlay, not just freshly-scaffolded ones
+      // (additive-only, never overwrites). Done BEFORE reading overlayContent so
+      // the marker's overlay_sha already reflects it — no one-time regen churn.
+      // (v3.33.0)
+      try {
+        const bf = ensureBaseFileShaInOverlay(overlayAbs, baseSha);
+        if (bf.changed) UI.info(`[${adapter.label}] ${kind} ${name}: backfilled base_file_sha into overlay frontmatter.`);
+        // Keep the informational base_<kind>_version pin truthful — but ONLY when
+        // the base content is unchanged (sha matches). When the base HAS changed
+        // the sha differs and the pin is left stale on purpose, so it stays a
+        // legitimate drift signal to reconcile. (v4.11.0)
+        const vp = refreshOverlayVersionPin(overlayAbs, kind, frameworkVersion, baseSha);
+        if (vp.changed) UI.info(`[${adapter.label}] ${kind} ${name}: refreshed base_${kind}_version pin to v${frameworkVersion} (base unchanged).`);
+      } catch (_) { /* non-fatal — never block a merge on backfill */ }
+      overlayContent = fs.readFileSync(overlayAbs, 'utf8');
+    }
+    const merged = mergeOverlay({ kind, name, baseContent, overlayContent, frameworkVersion, configSha, baseShaOverride: baseSha });
 
     if (merged.warnings && merged.warnings.length) {
       merged.warnings.forEach((w) => {
@@ -684,20 +730,34 @@ class SymlinkUtils {
       // Legacy generated file at linkPath — migrate (delete in-place, rewrite at generatedPath, symlink).
     }
 
-    // Write merged content to the indirect location.
-    fs.writeFileSync(generatedPath, merged.generated);
-
     // Compute the relative symlink target (portable across moves of the
     // project root).
     const relativeTarget = path.relative(path.dirname(linkPath), generatedPath);
 
+    // Byte-stability (v5.0.0): when the generated content is unchanged AND the
+    // consumer-visible symlink already points at it, this is a no-op — skip
+    // silently so repeated `baldart update` runs produce zero churn.
+    try {
+      if (fs.existsSync(generatedPath)
+          && fs.readFileSync(generatedPath, 'utf8') === merged.generated
+          && lstat && lstat.isSymbolicLink()
+          && path.resolve(path.dirname(linkPath), fs.readlinkSync(linkPath)) === generatedPath) {
+        aggregate.skipped.push({ tool: adapter.name, kind, name, reason: 'already-generated' });
+        return;
+      }
+    } catch (_) { /* fall through to the full write */ }
+
+    // Write merged content to the indirect location.
+    fs.writeFileSync(generatedPath, merged.generated);
+
     // Replace whatever currently lives at linkPath with the new symlink.
     if (lstat) {
       try { fs.unlinkSync(linkPath); }
       catch (_) { try { fs.rmSync(linkPath, { recursive: true, force: true }); } catch (_) { /* noop */ } }
     }
     fs.symlinkSync(relativeTarget, linkPath);
-    UI.success(`[${adapter.label}] ${kind} generated (overlay applied): ${path.join(targetRel, name)}.md → ${relativeTarget}`);
+    const mode = hasOverlay && configSha ? 'slots + overlay' : (hasOverlay ? 'overlay applied' : 'slots resolved');
+    UI.success(`[${adapter.label}] ${kind} generated (${mode}): ${path.join(targetRel, name)}.md → ${relativeTarget}`);
     aggregate.generated.push({ tool: adapter.name, kind, name, overlaySha: merged.overlaySha });
   }