baldart 3.6.2

package/src/commands/configure.js

@@ -0,0 +1,385 @@
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const UI = require('../utils/ui');
+
+const CONFIG_FILE = 'baldart.config.yml';
+// The subtree pull copies the entire BALDART repo (which itself has a
+// top-level `framework/` directory) into `.framework/`. So the in-consumer
+// path is `.framework/framework/templates/...` with the doubled segment.
+const TEMPLATE_PATH = path.join('.framework', 'framework', 'templates', 'baldart.config.template.yml');
+const OVERLAYS_DIR = path.join('.baldart', 'overlays');
+const SCHEMA_VERSION = 1;
+
+/**
+ * Filesystem probes — autodetection heuristics aligned with
+ * framework/agents/project-context.md § 6.
+ *
+ * Returns an object with the same shape as baldart.config.yml, populated
+ * only with detected values. Empty / undetected keys remain at template
+ * defaults and the user is prompted explicitly for them.
+ */
+function detect(cwd = process.cwd()) {
+  const exists = (p) => fs.existsSync(path.join(cwd, p));
+  const findFirst = (...candidates) => candidates.find(exists) || '';
+  const readJsonSafe = (p) => {
+    try { return JSON.parse(fs.readFileSync(path.join(cwd, p), 'utf8')); } catch { return null; }
+  };
+  const countMatches = (dir, regex) => {
+    const abs = path.join(cwd, dir);
+    if (!fs.existsSync(abs)) return 0;
+    try {
+      return fs.readdirSync(abs).filter((f) => regex.test(f)).length;
+    } catch { return 0; }
+  };
+
+  const pkg = readJsonSafe('package.json');
+  const deps = pkg ? { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) } : {};
+  const hasDep = (name) => Object.keys(deps).some((d) => d === name || d.startsWith(`${name}/`));
+
+  const detected = {
+    paths: {
+      design_system: findFirst('docs/design-system/INDEX.md') ? 'docs/design-system' : '',
+      ui_guidelines: findFirst(
+        'docs/references/ui-guidelines.md',
+        'docs/ui-guidelines.md',
+        'docs/references/brand-guidelines.md'
+      ),
+      api_index: findFirst('docs/references/api/index.md', 'docs/api/index.md'),
+      api_schemas: findFirst('docs/references/api/schemas.md', 'docs/api/schemas.md'),
+      api_errors: findFirst('docs/references/errors.md', 'docs/errors.md'),
+      components_primitives: findFirst(
+        'src/components/ui',
+        'app/components/ui',
+        'components/ui'
+      ),
+      components_root: findFirst('src/components', 'app/components', 'components'),
+      global_styles: findFirst(
+        'src/app/globals.css',
+        'app/globals.css',
+        'src/styles/globals.css',
+        'styles/globals.css'
+      ),
+      backlog_dir: exists('backlog') ? 'backlog' : '',
+      adrs_dir: countMatches('docs/decisions', /^ADR-.*\.md$/) > 0 ? 'docs/decisions' : '',
+      prd_dir: exists('docs/prd') ? 'docs/prd' : '',
+      references_dir: exists('docs/references') ? 'docs/references' : '',
+      wiki_dir: exists('docs/wiki') ? 'docs/wiki' : '',
+      e2e_tests_dir: findFirst('tests/e2e', 'e2e', 'tests/playwright', 'tests/cypress'),
+    },
+    identity: {
+      brand_name: pkg?.name || '',
+      design_philosophy: '',
+      language: 'en',
+      audience_segments: [],
+    },
+    stack: {
+      charting: {
+        canonical: ['recharts', '@nivo/heatmap', '@nivo/bar', '@nivo/line']
+          .filter((n) => hasDep(n)),
+        forbidden: [],
+        wrappers_root: findFirst('src/components/charts', 'app/components/charts'),
+      },
+      animation: {
+        canonical: ['framer-motion', 'lottie-react', 'gsap', 'motion']
+          .filter((n) => hasDep(n)),
+        forbidden: [],
+      },
+      testing: {
+        e2e: exists('playwright.config.ts') || exists('playwright.config.js')
+          ? 'playwright'
+          : exists('cypress.config.ts') || exists('cypress.config.js')
+            ? 'cypress'
+            : '',
+      },
+    },
+    features: {
+      has_design_system: exists('docs/design-system/INDEX.md'),
+      multi_tenant_theming: null, // can't be detected — leave for prompt
+      has_api_docs: !!findFirst('docs/references/api/schemas.md', 'docs/api/schemas.md'),
+      has_backlog: countMatches('backlog', /\.ya?ml$/) > 0,
+      has_adrs: countMatches('docs/decisions', /^ADR-.*\.md$/) > 0,
+      has_prd_workflow: exists('docs/prd'),
+      has_wiki_overlay: exists('docs/wiki'),
+    },
+  };
+
+  return detected;
+}
+
+/**
+ * Deep merge: existing user values WIN over detected/proposed values.
+ * Used by `baldart configure` to re-run idempotently without clobbering
+ * customizations.
+ *
+ * IMPORTANT: empty string `''` is treated as a DELIBERATE user value
+ * (the user said "this concept does not exist in my project"). Only
+ * `null` / `undefined` / missing-key fall back to the source.
+ */
+function mergePreserving(target, source) {
+  if (target === null || target === undefined) return source;
+  if (Array.isArray(target)) return target.length ? target : source;
+  if (typeof target !== 'object') return target;
+
+  const out = { ...target };
+  for (const key of Object.keys(source || {})) {
+    if (!(key in out)) {
+      out[key] = source[key];
+    } else {
+      out[key] = mergePreserving(out[key], source[key]);
+    }
+  }
+  return out;
+}
+
+function loadExisting(cwd) {
+  const full = path.join(cwd, CONFIG_FILE);
+  if (!fs.existsSync(full)) return null;
+  try {
+    return yaml.load(fs.readFileSync(full, 'utf8'));
+  } catch (err) {
+    UI.warning(`Existing ${CONFIG_FILE} is not valid YAML: ${err.message}`);
+    return null;
+  }
+}
+
+function loadTemplateSkeleton(cwd) {
+  const full = path.join(cwd, TEMPLATE_PATH);
+  if (!fs.existsSync(full)) {
+    throw new Error(
+      `Template not found at ${TEMPLATE_PATH}. Run \`npx baldart add\` first.`
+    );
+  }
+  return yaml.load(fs.readFileSync(full, 'utf8'));
+}
+
+async function promptForKey(label, defaultValue, kind = 'input') {
+  if (kind === 'confirm') {
+    return UI.confirm(label, defaultValue === true);
+  }
+  if (kind === 'select') {
+    return UI.select(label, defaultValue);
+  }
+  const answer = await UI.input(label, defaultValue || '');
+  return answer.trim();
+}
+
+async function interactivePrompts(merged, detected) {
+  UI.section('Identity');
+  merged.identity.brand_name = await promptForKey(
+    'Brand / product name',
+    merged.identity.brand_name || detected.identity.brand_name
+  );
+  merged.identity.design_philosophy = await promptForKey(
+    'Design philosophy (e.g. "Neo-Brutalism", "Minimalist") — empty for neutral',
+    merged.identity.design_philosophy
+  );
+  merged.identity.language = await promptForKey(
+    'Primary UI language (BCP-47, e.g. "en", "it")',
+    merged.identity.language || 'en'
+  );
+  const segments = await promptForKey(
+    'Audience segments (comma-separated, e.g. "merchant,customer") — empty for none',
+    (merged.identity.audience_segments || []).join(',')
+  );
+  merged.identity.audience_segments = segments
+    ? segments.split(',').map((s) => s.trim()).filter(Boolean)
+    : [];
+
+  UI.section('Features (explicit yes/no — option A: always ask)');
+  for (const flag of [
+    ['has_design_system', 'Project has a documented design system?'],
+    ['multi_tenant_theming', 'Project uses multi-tenant theming (per-tenant overrides)?'],
+    ['has_api_docs', 'Project has canonical API docs?'],
+    ['has_backlog', 'Project uses backlog-card workflow?'],
+    ['has_adrs', 'Project uses ADR workflow?'],
+    ['has_prd_workflow', 'Project uses PRD workflow (docs/prd/)?'],
+    ['has_wiki_overlay', 'Project has LLM-wiki overlay (docs/wiki/)?'],
+  ]) {
+    const [key, question] = flag;
+    const currentVal = merged.features[key];
+    const detectedVal = detected.features[key];
+    const proposedDefault = currentVal !== null && currentVal !== undefined
+      ? currentVal
+      : (detectedVal === true);
+    merged.features[key] = await promptForKey(question, proposedDefault, 'confirm');
+  }
+
+  // Path prompts — only ask for paths whose feature is enabled and value missing
+  UI.section('Paths (autodetected — confirm or override)');
+  const pathPrompts = [
+    ['design_system', 'Design-system root', () => merged.features.has_design_system],
+    ['ui_guidelines', 'UI guidelines doc', () => true],
+    ['api_index', 'API index doc', () => merged.features.has_api_docs],
+    ['api_schemas', 'API schemas doc', () => merged.features.has_api_docs],
+    ['api_errors', 'API errors doc', () => merged.features.has_api_docs],
+    ['components_primitives', 'UI primitives directory (e.g. src/components/ui)', () => true],
+    ['components_root', 'Components root directory', () => true],
+    ['global_styles', 'Global stylesheet path', () => true],
+    ['backlog_dir', 'Backlog directory', () => merged.features.has_backlog],
+    ['adrs_dir', 'ADR directory', () => merged.features.has_adrs],
+    ['prd_dir', 'PRD directory', () => merged.features.has_prd_workflow],
+    ['references_dir', 'References docs root', () => true],
+    ['wiki_dir', 'Wiki overlay directory', () => merged.features.has_wiki_overlay],
+    ['e2e_tests_dir', 'E2E tests directory', () => true],
+  ];
+
+  for (const [key, label, gate] of pathPrompts) {
+    if (!gate()) {
+      merged.paths[key] = '';
+      continue;
+    }
+    const proposed = merged.paths[key] || detected.paths[key] || '';
+    merged.paths[key] = await promptForKey(`${label}`, proposed);
+  }
+
+  UI.section('Stack (autodetected from package.json — confirm or override)');
+  const charting = merged.stack.charting;
+  const chartingCanonical = await promptForKey(
+    'Charting libraries (canonical, comma-separated)',
+    (charting.canonical || detected.stack.charting.canonical).join(',')
+  );
+  charting.canonical = chartingCanonical
+    ? chartingCanonical.split(',').map((s) => s.trim()).filter(Boolean)
+    : [];
+  const chartingForbidden = await promptForKey(
+    'Charting libraries (forbidden, comma-separated) — empty for none',
+    (charting.forbidden || []).join(',')
+  );
+  charting.forbidden = chartingForbidden
+    ? chartingForbidden.split(',').map((s) => s.trim()).filter(Boolean)
+    : [];
+  charting.wrappers_root = await promptForKey(
+    'Custom chart wrappers directory (empty if none)',
+    charting.wrappers_root || detected.stack.charting.wrappers_root || ''
+  );
+
+  const animation = merged.stack.animation;
+  const animCanonical = await promptForKey(
+    'Animation libraries (canonical, comma-separated)',
+    (animation.canonical || detected.stack.animation.canonical).join(',')
+  );
+  animation.canonical = animCanonical
+    ? animCanonical.split(',').map((s) => s.trim()).filter(Boolean)
+    : [];
+
+  merged.stack.testing.e2e = await promptForKey(
+    'E2E framework ("playwright", "cypress", or empty)',
+    merged.stack.testing.e2e || detected.stack.testing.e2e || ''
+  );
+
+  return merged;
+}
+
+/**
+ * Strip features.* flags whose value is null. We use null to signal
+ * "detection inconclusive — never written, ask user on first use".
+ * Honouring the always-ask contract (project-context.md § 3).
+ */
+function stripNullFeatures(config) {
+  if (!config || !config.features) return config;
+  const out = { ...config, features: { ...config.features } };
+  for (const k of Object.keys(out.features)) {
+    if (out.features[k] === null) {
+      delete out.features[k];
+    }
+  }
+  return out;
+}
+
+function serialize(config) {
+  const header = `# BALDART Project Configuration
+# Generated / updated by \`npx baldart configure\` — safe to edit by hand.
+# Schema docs: framework/docs/PROJECT-CONFIGURATION.md
+# Protocol:    framework/agents/project-context.md
+# This file is a CUSTOMIZABLE COPY and is never overwritten by \`baldart update\`.
+#
+# NOTE: features.* flags MUST be explicit (true | false). Any flag absent
+# from this file will prompt the user on first skill invocation.
+`;
+  return header + yaml.dump(stripNullFeatures(config), { lineWidth: 100, noRefs: true });
+}
+
+async function configure(opts = {}) {
+  const cwd = process.cwd();
+  UI.header('BALDART CONFIGURE — project context');
+
+  if (!fs.existsSync(path.join(cwd, '.framework'))) {
+    UI.error('Framework not installed. Run `npx baldart add` first.');
+    process.exit(1);
+  }
+
+  const probeSpinner = UI.spinner('Probing project structure...').start();
+  const detected = detect(cwd);
+  probeSpinner.succeed('Project structure probed');
+
+  const existing = loadExisting(cwd);
+  const template = loadTemplateSkeleton(cwd);
+  // Priority (highest wins): existing user values > detected > template defaults.
+  // mergePreserving(target, source) keeps target where set, fills from source.
+  let merged = mergePreserving(existing || {}, detected);
+  merged = mergePreserving(merged, template);
+  merged.version = SCHEMA_VERSION;
+
+  UI.box('AUTODETECTED', [
+    `Design system:   ${detected.paths.design_system || '— (none found)'}`,
+    `UI guidelines:   ${detected.paths.ui_guidelines || '— (none found)'}`,
+    `Components UI:   ${detected.paths.components_primitives || '— (none found)'}`,
+    `Backlog:         ${detected.features.has_backlog ? 'yes' : 'no'}`,
+    `ADRs:            ${detected.features.has_adrs ? 'yes' : 'no'}`,
+    `Charting libs:   ${detected.stack.charting.canonical.join(', ') || '—'}`,
+    `Animation libs:  ${detected.stack.animation.canonical.join(', ') || '—'}`,
+    `E2E framework:   ${detected.stack.testing.e2e || '—'}`,
+  ]);
+
+  if (opts.nonInteractive) {
+    UI.info('Non-interactive mode — writing autodetected values.');
+    // For features.* keys where detection returned null (inconclusive), strip
+    // them so the YAML omits the flag and the always-ask contract kicks in
+    // on first skill invocation. Honors project-context.md § 3.
+    if (merged.features && detected.features) {
+      for (const k of Object.keys(detected.features)) {
+        if (detected.features[k] === null && k in merged.features) {
+          delete merged.features[k];
+        }
+      }
+    }
+  } else {
+    const proceed = await UI.confirm(
+      existing ? 'Re-run prompts and merge into existing config?' : 'Start configuration prompts?',
+      true
+    );
+    if (!proceed) {
+      UI.info('Configure cancelled.');
+      return;
+    }
+    merged = await interactivePrompts(merged, detected);
+  }
+
+  const outPath = path.join(cwd, CONFIG_FILE);
+  fs.writeFileSync(outPath, serialize(merged), 'utf8');
+  UI.success(`Wrote ${CONFIG_FILE}`);
+
+  // Ensure overlays dir exists (user-owned)
+  const overlaysAbs = path.join(cwd, OVERLAYS_DIR);
+  if (!fs.existsSync(overlaysAbs)) {
+    fs.mkdirSync(overlaysAbs, { recursive: true });
+    fs.writeFileSync(
+      path.join(overlaysAbs, '.gitkeep'),
+      '# Skill overlays — see framework/agents/project-context.md § 5\n',
+      'utf8'
+    );
+    UI.success(`Created ${OVERLAYS_DIR}/`);
+  }
+
+  UI.box('NEXT STEPS', [
+    '• Review baldart.config.yml — values are committed to your repo',
+    '• Author skill overlays in .baldart/overlays/<skill-name>.md',
+    '  Examples: framework/templates/overlays/',
+    '• Re-run `npx baldart configure` any time to refresh',
+  ]);
+}
+
+module.exports = configure;
+module.exports.detect = detect;
+module.exports.mergePreserving = mergePreserving;