baldart 5.5.0 → 5.7.0

package/src/utils/skill-gate.js

@@ -0,0 +1,139 @@
+/**
+ * skill-gate.js — install-time feature-gating for framework skills.
+ *
+ * BALDART ships ~40 skills; Codex reserves only ~2% of its context window for
+ * skill descriptions, so linking every skill (including ones whose gating
+ * `features.*` flag is OFF, which then refuse at runtime anyway) wastes that
+ * budget. This module decides, per install/update, WHICH framework skills to
+ * link into a consumer, based on an OPTIONAL `requires_feature` frontmatter
+ * field in each skill's `SKILL.md`.
+ *
+ * The gate is PURELY install-time (resolved here by the Node installer) — both
+ * Claude (`.claude/skills/`) and Codex (`.agents/skills/`) simply see fewer
+ * directories. Neither runtime interprets `requires_feature`; it is a BALDART
+ * authoring construct, ignored by the skill loaders exactly like `version:` /
+ * `effort:`. So the filter is natively portable across both tools and applied
+ * from a single code path (the gate is shared SEMANTICS, not runtime mechanics).
+ *
+ * Frontmatter contract (all OPTIONAL — a skill with no `requires_feature` is
+ * ALWAYS linked, backwards-compatible default):
+ *   requires_feature: has_design_system                 # string  → link iff true
+ *   requires_feature: [has_design_system, has_e2e_review] # list = AND (all true)
+ *
+ * Fail-open everywhere (never hide a skill by accident — the safety net must
+ * not become a tribunal):
+ *   - config absent / unreadable / malformed → link EVERYTHING.
+ *   - a single skill's frontmatter malformed  → link THAT skill (per-skill),
+ *     never crash the whole merge.
+ *
+ * NOTE: we read `features.*` DIRECTLY from baldart.config.yml rather than reuse
+ * `agent-slots.resolveAgentFlags()` — that flag set intentionally covers only
+ * the keys the agent SLOT sources reference and omits `has_prd_workflow` /
+ * `has_e2e_review`, which ARE skill gates. Reading the raw block keeps the gate
+ * correct for every existing (and future) `features.*` key with no coupling.
+ *
+ * This introduces NO new `baldart.config.yml` key (it consumes existing
+ * `features.*`) — the schema-change propagation rule does NOT apply. It is
+ * skill-frontmatter metadata, like `version`/`effort`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Load the `features` block from baldart.config.yml.
+ * @returns {{ features: Object|null }} `features: null` signals "config
+ *   unavailable" → callers must fail-open (link everything).
+ */
+function loadFeatures(cwd) {
+  try {
+    const yaml = require('js-yaml');
+    const cfgPath = path.join(cwd, 'baldart.config.yml');
+    if (!fs.existsSync(cfgPath)) return { features: null };
+    const cfg = yaml.load(fs.readFileSync(cfgPath, 'utf8'));
+    if (!cfg || typeof cfg !== 'object') return { features: null };
+    const features = (cfg.features && typeof cfg.features === 'object') ? cfg.features : {};
+    return { features };
+  } catch (_) {
+    return { features: null };
+  }
+}
+
+/**
+ * Extract the OPTIONAL `requires_feature` from a skill's SKILL.md frontmatter.
+ * @returns {string[]|null} normalized list of required feature keys, or null
+ *   when the skill is ungated / has no SKILL.md / frontmatter is unparseable
+ *   (fail-open: null ⇒ always link).
+ */
+function readRequiredFeatures(skillDir) {
+  try {
+    const skillMd = path.join(skillDir, 'SKILL.md');
+    if (!fs.existsSync(skillMd)) return null;
+    const raw = fs.readFileSync(skillMd, 'utf8');
+    if (!raw.startsWith('---')) return null;
+    // Frontmatter is between the first two `---` fences.
+    const end = raw.indexOf('\n---', 3);
+    if (end === -1) return null;
+    const fmText = raw.slice(3, end);
+    const yaml = require('js-yaml');
+    const fm = yaml.load(fmText);
+    if (!fm || typeof fm !== 'object') return null;
+    const req = fm.requires_feature;
+    if (req == null) return null;
+    const list = (Array.isArray(req) ? req : [req])
+      .map(x => String(x).trim())
+      .filter(Boolean);
+    return list.length ? list : null;
+  } catch (_) {
+    // Malformed frontmatter for THIS skill → fail-open (link it).
+    return null;
+  }
+}
+
+/**
+ * Decide which framework skills to link vs skip for this consumer.
+ *
+ * @param {string} frameworkSkillsDir absolute path to
+ *   `.framework/framework/.claude/skills/`
+ * @param {string} cwd consumer repo root (where baldart.config.yml lives)
+ * @returns {{ toLink: string[], gatedOff: string[], failOpen: boolean }}
+ *   `toLink` = skill dir names to link; `gatedOff` = skill dir names to skip
+ *   (and prune if already linked); `failOpen` = true when config was
+ *   unavailable so nothing was gated.
+ */
+function resolveSkillGate(frameworkSkillsDir, cwd) {
+  const result = { toLink: [], gatedOff: [], failOpen: false };
+
+  let names = [];
+  try {
+    names = fs.readdirSync(frameworkSkillsDir).filter(name => {
+      if (name.startsWith('.')) return false;
+      try { return fs.lstatSync(path.join(frameworkSkillsDir, name)).isDirectory(); }
+      catch (_) { return false; }
+    });
+  } catch (_) {
+    return result; // no framework skills dir → empty sets, caller handles
+  }
+
+  const { features } = loadFeatures(cwd);
+
+  // Config unavailable → fail-open: link everything, gate nothing.
+  if (features === null) {
+    result.failOpen = true;
+    result.toLink = names.slice();
+    return result;
+  }
+
+  for (const name of names) {
+    const required = readRequiredFeatures(path.join(frameworkSkillsDir, name));
+    if (!required) { result.toLink.push(name); continue; }
+    // AND semantics: link iff EVERY required feature is explicitly true.
+    const allOn = required.every(f => features[f] === true);
+    if (allOn) result.toLink.push(name);
+    else result.gatedOff.push(name);
+  }
+
+  return result;
+}
+
+module.exports = { resolveSkillGate, readRequiredFeatures, loadFeatures };

package/src/utils/symlinks.js

@@ -210,7 +210,7 @@ class SymlinkUtils {
    */
   mergeSkills(opts = {}) {
     const tools = (opts.tools && opts.tools.length) ? opts.tools : ['claude'];
-    const aggregate = { linked: [], skipped: [], conflicts: [] };
+    const aggregate = { linked: [], skipped: [], conflicts: [], pruned: [], gatedOff: [] };
 
     const frameworkSkillsDir = path.join(this.cwd, FRAMEWORK_PAYLOAD, '.claude', 'skills');
     if (!fs.existsSync(frameworkSkillsDir)) {
@@ -218,17 +218,31 @@ class SymlinkUtils {
       return aggregate;
     }
 
-    const frameworkSkills = fs.readdirSync(frameworkSkillsDir).filter(name => {
-      if (name.startsWith('.')) return false;
-      const full = path.join(frameworkSkillsDir, name);
-      return fs.lstatSync(full).isDirectory();
-    });
+    // Feature-gate: link only the skills whose `requires_feature` frontmatter is
+    // satisfied by this consumer's `features.*` (fail-open when config is
+    // unavailable → link everything). Resolved ONCE and applied to EVERY tool
+    // from this single code path — the gate is shared semantics, so Claude and
+    // Codex stay identical by construction. See src/utils/skill-gate.js.
+    const gate = require('./skill-gate').resolveSkillGate(frameworkSkillsDir, this.cwd);
+    const frameworkSkills = gate.toLink;
+    aggregate.gatedOff = gate.gatedOff.slice();
+    if (gate.gatedOff.length) {
+      UI.info(`Feature-gate: ${gate.gatedOff.length} skill(s) skipped (gating feature off): ${gate.gatedOff.join(', ')}`);
+    }
 
     for (const tool of tools) {
       const result = this._mergeSkillsForTool(tool, frameworkSkills, frameworkSkillsDir);
       aggregate.linked.push(...result.linked);
       aggregate.skipped.push(...result.skipped);
       aggregate.conflicts.push(...result.conflicts);
+
+      // Prune direction: remove any pre-existing framework symlink for a skill
+      // that is now gated-off (e.g. a feature flipped false after a prior
+      // install, or a fail-open install that linked everything before config
+      // existed). Only OUR framework symlinks are removed — never a real user
+      // skill dir, never a user-override symlink pointing elsewhere.
+      const pruneResult = this._pruneGatedSkillsForTool(tool, gate.gatedOff, frameworkSkillsDir);
+      aggregate.pruned.push(...pruneResult.pruned);
     }
 
     if (aggregate.conflicts.length > 0) {
@@ -329,6 +343,54 @@ class SymlinkUtils {
     return result;
   }
 
+  /**
+   * Prune framework skill symlinks that are now gated-off — internal.
+   *
+   * This is the reconcile (removal) direction of the feature-gate: turning a
+   * `features.*` flag off (or a fail-open first install that linked everything
+   * before config existed) must actually REMOVE the stale symlinks, or the
+   * skill-description budget never shrinks. Each `name` in `gatedOff` is a
+   * framework skill name by construction (it came from the framework catalog),
+   * so basename∈catalog is guaranteed; we still verify the link RESOLVES to our
+   * framework source for that exact skill before unlinking. Safety invariants:
+   *   - never touch a real directory (a user-authored skill of the same name);
+   *   - never touch a symlink pointing ANYWHERE ELSE (a user override, cf. the
+   *     `user-symlink-override` branch in _mergeSkillsForTool).
+   */
+  _pruneGatedSkillsForTool(toolName, gatedOff, frameworkSkillsDir) {
+    const { getAdapter } = require('./tool-adapters');
+    const adapter = getAdapter(toolName, this.cwd);
+    const result = { pruned: [] };
+    if (!gatedOff || !gatedOff.length) return result;
+
+    const skillsRel = adapter.skillsDir();
+    const userSkillsDir = path.join(this.cwd, skillsRel);
+    if (!fs.existsSync(userSkillsDir)) return result;
+
+    for (const name of gatedOff) {
+      const linkPath = path.join(userSkillsDir, name);
+      let lstat = null;
+      try { lstat = fs.lstatSync(linkPath); } catch (_) { continue; /* absent */ }
+
+      // Only ever remove a symlink — a real dir here is a user-authored skill.
+      if (!lstat.isSymbolicLink()) continue;
+
+      const current = fs.readlinkSync(linkPath);
+      const resolved = path.resolve(path.dirname(linkPath), current);
+      const frameworkTarget = path.join(frameworkSkillsDir, name);
+
+      // Unlink ONLY when it resolves to OUR framework source for this skill.
+      // A symlink pointing elsewhere is a deliberate user override → leave it.
+      if (resolved === frameworkTarget) {
+        fs.unlinkSync(linkPath);
+        UI.info(`[${adapter.label}] Skill unlinked (feature gated off): ${path.join(skillsRel, name)}`);
+        result.pruned.push({ tool: toolName, name });
+      }
+    }
+
+    return result;
+  }
+
   // -----------------------------------------------------------------------
   // Public composite operations
   // -----------------------------------------------------------------------
@@ -827,7 +889,10 @@ class SymlinkUtils {
           UI.warning(`[${adapter.label}] Legacy bulk skills symlink at ${skillsRel}. Run \`npx baldart update\` to convert to per-item.`);
           allValid = false;
         } else {
-          const sample = ['skill-creator', 'frontend-design', 'bug', 'prd', 'capture'];
+          // Sample ONLY always-linked skills — never feature-gated ones (e.g.
+          // prd/capture), which are legitimately absent when their feature is
+          // off and would make this probe brittle / falsely alarming.
+          const sample = ['skill-creator', 'bug', 'simplify', 'overlay', 'find-skills'];
           let frameworkLinks = 0;
           sample.forEach(name => {
             const p = path.join(skillsDir, name);