baldart 5.0.1 → 5.2.0

package/src/utils/research-library.js

@@ -0,0 +1,92 @@
+/**
+ * Research library scaffolding (v5.1.0).
+ *
+ * Creates/seeds the consumer-owned research library at `paths.research_dir`:
+ * category subdirectories + two seed files copied from framework-internal
+ * templates (INDEX.md — the library map; SOURCES.md — the live source matrix).
+ *
+ * Lifecycle ownership (deliberate, see research-protocol.md):
+ *   - `configure` CREATES (right after writing the key) — createDir: true
+ *   - `doctor` REPAIRS (confirmable actions)             — createDir: true
+ *   - `update` only BACKFILLS seeds into an EXISTING dir — createDir: false
+ *     (never resurrects a deliberately deleted library)
+ *
+ * Idempotent and silent on already-existing artifacts (no per-run warnings).
+ * Returns the repo-relative paths it created THIS run, so `update` can scope
+ * its auto-commit to exactly these artifacts (v4.89.2 lesson) while the rest
+ * of the library stays consumer-owned and untouched.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const FRAMEWORK_TEMPLATES = path.join('.framework', 'framework', 'templates');
+
+const CATEGORY_DIRS = [
+  'architecture',
+  'integrations',
+  'regulatory',
+  'ux-patterns',
+  'algorithms',
+  'tooling',
+  '_archive',
+];
+
+const SEEDS = [
+  { template: 'research-index.template.md', dest: 'INDEX.md' },
+  { template: 'research-sources.template.md', dest: 'SOURCES.md' },
+];
+
+/**
+ * @param {string} cwd - consumer repo root
+ * @param {object|null} config - parsed baldart.config.yml
+ * @param {{createDir?: boolean}} [opts]
+ * @returns {string[]} repo-relative paths created this run
+ */
+function ensureResearchLibrary(cwd, config, opts = {}) {
+  const createDir = opts.createDir !== false;
+  const created = [];
+
+  const key = config && config.paths && config.paths.research_dir;
+  if (!key || typeof key !== 'string') return created; // opt-out / unconfigured — no-op
+
+  const dirAbs = path.join(cwd, key);
+  if (!fs.existsSync(dirAbs)) {
+    if (!createDir) return created; // update path: never resurrect a deleted library
+    fs.mkdirSync(dirAbs, { recursive: true });
+    created.push(key);
+  }
+
+  for (const sub of CATEGORY_DIRS) {
+    const subAbs = path.join(dirAbs, sub);
+    if (!fs.existsSync(subAbs)) fs.mkdirSync(subAbs, { recursive: true });
+  }
+
+  for (const seed of SEEDS) {
+    const destAbs = path.join(dirAbs, seed.dest);
+    if (fs.existsSync(destAbs)) continue; // consumer-owned — never overwrite, never warn
+    const srcAbs = path.join(cwd, FRAMEWORK_TEMPLATES, seed.template);
+    if (!fs.existsSync(srcAbs)) continue; // older framework payload — doctor backfills later
+    fs.copyFileSync(srcAbs, destAbs);
+    created.push(path.join(key, seed.dest));
+  }
+
+  return created;
+}
+
+/**
+ * Parse the `matrix_version:` frontmatter value from a source-matrix file.
+ * Returns null when the file is missing/unreadable or carries no version —
+ * callers treat null as "cannot compare" (never a failure).
+ */
+function readMatrixVersion(fileAbs) {
+  try {
+    const head = fs.readFileSync(fileAbs, 'utf8').slice(0, 500);
+    const m = head.match(/^matrix_version:\s*["']?(\d+\.\d+\.\d+)["']?\s*$/m);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { ensureResearchLibrary, readMatrixVersion, CATEGORY_DIRS };

package/src/utils/symlinks.js

@@ -948,6 +948,9 @@ class SymlinkUtils {
       'skill-project-context.snippet.md',
       'component-spec.template.md', // canonical prose-body template — consumed by serialize-spec.mjs, not hand-edited
       'overlays', // example overlays directory — consumers reference, don't copy wholesale
+      'research-index.template.md', // research library seed — copied to ${paths.research_dir}/INDEX.md by ensureResearchLibrary
+      'research-sources.template.md', // source matrix seed + default-matrix SSOT — copied to ${paths.research_dir}/SOURCES.md
+      'research-sources.CHANGELOG.md', // matrix version history — framework metadata, never installed
     ]);
 
     this.ensureDirectory('templates');