chati-dev 4.2.1 → 4.3.0

package/src/installer/preflight.js

@@ -0,0 +1,131 @@
+/**
+ * @fileoverview Preflight system check — validates prerequisites before install.
+ *
+ * Runs BEFORE the installer wizard collects config. Checks:
+ *   1. Node.js >= 20  (mandatory — already running, so just version check)
+ *   2. npm >= 9        (mandatory)
+ *   3. Git available   (mandatory)
+ *   4. Playwright      (optional — auto-installs chromium if missing)
+ *
+ * If a mandatory check fails, the installer should abort.
+ * If an optional check fails, it warns but continues.
+ */
+
+import { execSync } from 'child_process';
+
+/**
+ * @typedef {{ name: string, status: 'pass'|'fail'|'warn', version?: string, message: string }} PreflightCheck
+ * @typedef {{ passed: boolean, checks: PreflightCheck[] }} PreflightResult
+ */
+
+/**
+ * Run all preflight checks.
+ *
+ * @param {{ silent?: boolean }} options
+ * @returns {Promise<PreflightResult>}
+ */
+export async function runPreflightCheck(options = {}) {
+  const checks = [];
+  let mandatoryFailed = false;
+
+  // 1. Node.js >= 20 — we're already running Node, just check version
+  const nodeVersion = process.version;
+  const nodeMajor = parseInt(nodeVersion.replace('v', '').split('.')[0], 10);
+  if (nodeMajor >= 20) {
+    checks.push({ name: 'node', status: 'pass', version: nodeVersion, message: `Node.js ${nodeVersion}` });
+  } else {
+    checks.push({ name: 'node', status: 'fail', version: nodeVersion, message: `Node.js ${nodeVersion} — requires >= 20.0.0` });
+    mandatoryFailed = true;
+  }
+
+  // 2. npm >= 9
+  try {
+    const npmVersion = execSync('npm --version', { encoding: 'utf-8', timeout: 10000 }).trim();
+    const npmMajor = parseInt(npmVersion.split('.')[0], 10);
+    if (npmMajor >= 9) {
+      checks.push({ name: 'npm', status: 'pass', version: npmVersion, message: `npm v${npmVersion}` });
+    } else {
+      checks.push({ name: 'npm', status: 'fail', version: npmVersion, message: `npm v${npmVersion} — requires >= 9.0.0` });
+      mandatoryFailed = true;
+    }
+  } catch {
+    checks.push({ name: 'npm', status: 'fail', message: 'npm not found' });
+    mandatoryFailed = true;
+  }
+
+  // 3. Git
+  try {
+    const gitOut = execSync('git --version', { encoding: 'utf-8', timeout: 10000 }).trim();
+    const gitVersion = gitOut.replace('git version ', '');
+    checks.push({ name: 'git', status: 'pass', version: gitVersion, message: `Git ${gitVersion}` });
+  } catch {
+    checks.push({ name: 'git', status: 'fail', message: 'Git not found — install from https://git-scm.com' });
+    mandatoryFailed = true;
+  }
+
+  // 4. Playwright (optional — auto-install chromium if missing)
+  const playwrightCheck = await checkPlaywright(options);
+  checks.push(playwrightCheck);
+
+  return {
+    passed: !mandatoryFailed,
+    checks,
+  };
+}
+
+/**
+ * Check if Playwright + chromium browser are available.
+ * If Playwright is installed but chromium is missing, auto-install it.
+ * If Playwright itself is missing, try to install it via npx.
+ *
+ * @param {{ silent?: boolean }} options
+ * @returns {Promise<PreflightCheck>}
+ */
+async function checkPlaywright(options = {}) {
+  // Try importing playwright
+  let pw;
+  try {
+    pw = await import('playwright');
+  } catch {
+    // Playwright not installed — try to install via npx
+    if (!options.silent) {
+      process.stderr.write('  Installing Playwright chromium (required for visual analysis)...\n');
+    }
+    try {
+      execSync('npx playwright install chromium', {
+        stdio: options.silent ? 'ignore' : 'inherit',
+        timeout: 120000,
+      });
+      // Verify installation succeeded
+      try {
+        pw = await import('playwright');
+      } catch {
+        return { name: 'playwright', status: 'warn', message: 'Playwright install attempted but import still fails — visual features disabled' };
+      }
+    } catch {
+      return { name: 'playwright', status: 'warn', message: 'Playwright not available — visual features (reference capture, QA-Visual) disabled' };
+    }
+  }
+
+  // Playwright module found — verify chromium browser is installed
+  try {
+    const browser = await pw.chromium.launch({ headless: true });
+    const version = browser.version();
+    await browser.close();
+    return { name: 'playwright', status: 'pass', version, message: `Playwright chromium ${version}` };
+  } catch {
+    // Browser missing — auto-install
+    if (!options.silent) {
+      process.stderr.write('  Installing Playwright chromium browser...\n');
+    }
+    try {
+      execSync('npx playwright install chromium', {
+        stdio: options.silent ? 'ignore' : 'inherit',
+        timeout: 120000,
+      });
+      return { name: 'playwright', status: 'pass', message: 'Playwright chromium installed' };
+    } catch {
+      return { name: 'playwright', status: 'warn', message: 'Playwright chromium install failed — visual features disabled' };
+    }
+  }
+}

package/src/installer/provider-overlay.js

@@ -32,7 +32,7 @@ import { adaptFrameworkFile, ADAPTABLE_FILES } from '../config/framework-adapter
  */
 export function generateProviderOverlays(targetDir, frameworkSource, primaryProvider, allProviders) {
   const result = { generated: [], skipped: [] };
-  const frameworkDir = join(targetDir, 'chati.dev');
+  const frameworkDir = join(targetDir, '.chati.dev');
 
   for (const provider of allProviders) {
     if (provider === primaryProvider) {
@@ -74,9 +74,9 @@ export function generateProviderOverlays(targetDir, frameworkSource, primaryProv
  */
 export function resolveOverlayPath(projectDir, relativePath, provider) {
   // Check overlay first
-  const overlayPath = join(projectDir, 'chati.dev', '.adapted', provider, relativePath);
+  const overlayPath = join(projectDir, '.chati.dev', '.adapted', provider, relativePath);
   if (existsSync(overlayPath)) return overlayPath;
 
   // Fallback to main chati.dev/
-  return join(projectDir, 'chati.dev', relativePath);
+  return join(projectDir, '.chati.dev', relativePath);
 }

package/src/installer/scaffold-applier.js

@@ -0,0 +1,358 @@
+/**
+ * src/installer/scaffold-applier.js
+ *
+ * Applies a scaffold preset (e.g. motion-premium) to a user project. Reads
+ * the preset's scaffold.yaml, resolves placeholder values (from an existing
+ * brand.ts or the yaml's defaults), writes each template's resolved content
+ * to the target path, and emits .chati/scaffold-manifest.json for later
+ * upgrade diffing.
+ *
+ * Design (see .planning/scaffold-premium-v1.md, Decisions 1 and 3):
+ *   - Copy-on-apply, NOT on install. The installer only copies the scaffold
+ *     SOURCE files to .chati.dev/scaffold/; this module is invoked when the
+ *     orchestrator or CLI user decides to apply.
+ *   - Placeholder resolution is install-time and one-shot. Re-running the
+ *     applier after the user edited brand.ts is the documented --sync-brand
+ *     workflow (stub in v1; see TODO below).
+ *   - First-apply never overwrites existing files — a safe default. A
+ *     dedicated upgrade path (scaffold --upgrade, future) uses hash diffing
+ *     via brownfield-upgrader.js.
+ */
+
+import {
+  readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync,
+} from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import yaml from 'js-yaml';
+import { hashContent } from './file-hasher.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Resolution chain for the scaffold source directory.
+//   1. Installed framework in the target project:        {targetDir}/.chati.dev/scaffold/
+//   2. npm-bundled framework next to this file:          {pkgRoot}/framework/scaffold/
+//   3. Monorepo canonical framework (dev only):          {repoRoot}/chati.dev/scaffold/
+const BUNDLED_SCAFFOLD = join(__dirname, '..', '..', 'framework', 'scaffold');
+const MONOREPO_SCAFFOLD = join(__dirname, '..', '..', '..', '..', 'chati.dev', 'scaffold');
+
+/**
+ * Resolve the directory containing scaffold presets for a given project.
+ * Preference: installed > bundled > monorepo.
+ *
+ * @param {string} [targetDir] - Project root (looks for installed .chati.dev/)
+ * @returns {string} Absolute path to the scaffold root
+ * @throws {Error} If no candidate exists on disk
+ */
+export function resolveScaffoldSource(targetDir) {
+  if (targetDir) {
+    const installed = join(targetDir, '.chati.dev', 'scaffold');
+    if (existsSync(installed)) return installed;
+  }
+  if (existsSync(BUNDLED_SCAFFOLD)) return BUNDLED_SCAFFOLD;
+  if (existsSync(MONOREPO_SCAFFOLD)) return MONOREPO_SCAFFOLD;
+  throw new Error(
+    'Could not locate scaffold source directory. Checked: ' +
+    [
+      targetDir ? join(targetDir, '.chati.dev', 'scaffold') : null,
+      BUNDLED_SCAFFOLD,
+      MONOREPO_SCAFFOLD,
+    ].filter(Boolean).join(', ')
+  );
+}
+
+/**
+ * List available scaffold presets at a given scaffold source directory.
+ *
+ * @param {string} scaffoldSourceDir - From resolveScaffoldSource()
+ * @returns {Array<{ id: string, version: string, description: string }>}
+ */
+export function listPresets(scaffoldSourceDir) {
+  if (!existsSync(scaffoldSourceDir)) return [];
+  const out = [];
+  for (const name of readdirSync(scaffoldSourceDir)) {
+    const presetDir = join(scaffoldSourceDir, name);
+    let s;
+    try { s = statSync(presetDir); } catch { continue; }
+    if (!s.isDirectory()) continue;
+    const yamlPath = join(presetDir, 'scaffold.yaml');
+    if (!existsSync(yamlPath)) continue;
+    try {
+      const parsed = yaml.load(readFileSync(yamlPath, 'utf-8'));
+      out.push({
+        id:          parsed.id || name,
+        version:     parsed.version || '0.0.0',
+        description: parsed.description || '',
+      });
+    } catch { /* skip unparseable */ }
+  }
+  return out;
+}
+
+/**
+ * Load and parse scaffold.yaml for a specific preset.
+ *
+ * @param {string} scaffoldSourceDir - From resolveScaffoldSource()
+ * @param {string} preset - Preset id (e.g. 'motion-premium')
+ * @returns {object} Parsed manifest with an injected `sourceDir` property
+ * @throws {Error} If preset or scaffold.yaml is not found
+ */
+export function loadScaffoldManifest(scaffoldSourceDir, preset) {
+  const presetDir = join(scaffoldSourceDir, preset);
+  const yamlPath = join(presetDir, 'scaffold.yaml');
+  if (!existsSync(yamlPath)) {
+    throw new Error(`Scaffold preset "${preset}" not found at ${presetDir}`);
+  }
+  const parsed = yaml.load(readFileSync(yamlPath, 'utf-8'));
+  return { ...parsed, sourceDir: presetDir };
+}
+
+/**
+ * Replace {{PLACEHOLDER}} tokens in template content with resolved values.
+ * Unmatched placeholders are left intact (aids debugging — a missed value
+ * shows up as a visible {{FOO}} in the generated file rather than silently
+ * empty).
+ *
+ * @param {string} templateContent
+ * @param {Record<string, string>} values
+ * @returns {string}
+ */
+export function resolvePlaceholders(templateContent, values) {
+  return templateContent.replace(/\{\{([A-Z_][A-Z0-9_]*)\}\}/g, (match, key) => {
+    return Object.prototype.hasOwnProperty.call(values, key) ? values[key] : match;
+  });
+}
+
+/**
+ * Parse a brand.ts source file and extract brand.colors values.
+ * Regex-based and tolerant of formatting variations. Not a full TypeScript
+ * parser — assumes the brand.ts shape shipped by the scaffold (object
+ * literal with `colors: { key: 'value', ... } as const`).
+ *
+ * @param {string} source - brand.ts file content
+ * @returns {Record<string, string>} { primary: '#...', primaryRgb: '...', ... }
+ */
+export function parseBrandTs(source) {
+  // Match `colors: { ... }` and capture the body non-greedily.
+  // The body is bounded by its own closing brace at the same indent level.
+  const colorsMatch = source.match(/colors\s*:\s*\{([\s\S]*?)^\s*\}/m);
+  if (!colorsMatch) return {};
+  const body = colorsMatch[1];
+  const out = {};
+  // Match lines like:  primary: '#7C3AED',   or   primaryRgb: "124, 58, 237",
+  const pairRe = /([a-zA-Z_][\w]*)\s*:\s*['"]([^'"]+)['"]/g;
+  let m;
+  while ((m = pairRe.exec(body)) !== null) {
+    out[m[1]] = m[2];
+  }
+  return out;
+}
+
+/**
+ * Map camelCase brand.colors keys to UPPER_SNAKE placeholder names, using
+ * the scaffold.yaml `placeholders` block as the authority on source paths.
+ *
+ * @param {Record<string, string>} brandColors
+ * @param {object} placeholdersMap - scaffold.yaml `placeholders`
+ * @returns {Record<string, string>}
+ */
+export function mapBrandToPlaceholders(brandColors, placeholdersMap) {
+  const out = {};
+  for (const [phKey, phDef] of Object.entries(placeholdersMap || {})) {
+    const pathMatch = phDef && phDef.source && phDef.source.match(/^brand\.colors\.(\w+)$/);
+    if (!pathMatch) continue;
+    const colorKey = pathMatch[1];
+    if (Object.prototype.hasOwnProperty.call(brandColors, colorKey)) {
+      out[phKey] = brandColors[colorKey];
+    }
+  }
+  return out;
+}
+
+/**
+ * Resolve the full set of placeholder values for a project.
+ *
+ * Strategy (per scaffold.yaml brand_sources, in priority order):
+ *   1. Defaults from scaffold.yaml — always the baseline
+ *   2. Parsed values from {projectDir}/lib/brand.ts — if present
+ *   3. Caller-supplied overrides — highest priority
+ *
+ * Interactive prompt (brand_sources entry `type: interactive`) is NOT
+ * implemented in v1 — the applier is always non-interactive and falls
+ * through to defaults if no brand source exists.
+ *
+ * @param {string} projectDir
+ * @param {object} scaffoldManifest - From loadScaffoldManifest
+ * @param {Record<string, string>} [overrides]
+ * @returns {{ values: Record<string, string>, source: string }}
+ */
+export function resolveBrandValues(projectDir, scaffoldManifest, overrides = {}) {
+  const placeholdersMap = scaffoldManifest.placeholders || {};
+  const values = {};
+  for (const [k, v] of Object.entries(placeholdersMap)) {
+    if (v && v.default !== undefined) values[k] = v.default;
+  }
+
+  let source = 'defaults';
+  const brandTsPath = join(projectDir, 'lib', 'brand.ts');
+  if (existsSync(brandTsPath)) {
+    try {
+      const brandColors = parseBrandTs(readFileSync(brandTsPath, 'utf-8'));
+      const mapped = mapBrandToPlaceholders(brandColors, placeholdersMap);
+      if (Object.keys(mapped).length > 0) {
+        Object.assign(values, mapped);
+        source = 'lib/brand.ts';
+      }
+    } catch { /* keep defaults on parse failure */ }
+  }
+
+  if (Object.keys(overrides).length > 0) {
+    Object.assign(values, overrides);
+    source = source === 'defaults' ? 'overrides' : `${source} + overrides`;
+  }
+
+  return { values, source };
+}
+
+/**
+ * Apply a scaffold preset to a project directory.
+ *
+ * First-apply semantics:
+ *   - Existing target files are SKIPPED (never overwritten without --force).
+ *   - Fresh files are written with placeholders resolved.
+ *   - A scaffold-manifest.json is written to .chati/ recording hashes,
+ *     source template names, phase, override class, and the placeholder
+ *     values used. The manifest is the input for future upgrade runs.
+ *
+ * Dry-run semantics:
+ *   - No files written (neither targets nor manifest).
+ *   - Return value describes what WOULD happen.
+ *
+ * @param {object} opts
+ * @param {string} opts.projectDir - Target project root
+ * @param {string} opts.scaffoldSourceDir - From resolveScaffoldSource()
+ * @param {string} opts.preset - Preset id
+ * @param {Record<string, string>} [opts.values] - Placeholder overrides
+ * @param {boolean} [opts.dryRun=false]
+ * @param {boolean} [opts.force=false] - Overwrite existing files
+ * @returns {{
+ *   preset: string,
+ *   version: string,
+ *   applied: string[],
+ *   skipped: Array<{ target: string, reason: string }>,
+ *   placeholders: Record<string, string>,
+ *   brandSource: string,
+ *   dryRun: boolean,
+ *   manifestPath: string | null,
+ * }}
+ */
+export function applyScaffold(opts) {
+  const {
+    projectDir,
+    scaffoldSourceDir,
+    preset,
+    values: overrides = {},
+    dryRun = false,
+    force = false,
+  } = opts;
+
+  if (!projectDir) throw new Error('applyScaffold: projectDir is required');
+  if (!scaffoldSourceDir) throw new Error('applyScaffold: scaffoldSourceDir is required');
+  if (!preset) throw new Error('applyScaffold: preset is required');
+
+  const manifest = loadScaffoldManifest(scaffoldSourceDir, preset);
+  const { values, source: brandSource } = resolveBrandValues(projectDir, manifest, overrides);
+
+  const applied = [];
+  const skipped = [];
+  const manifestFiles = {};
+
+  for (const fileSpec of manifest.files || []) {
+    const sourcePath = join(manifest.sourceDir, fileSpec.source);
+    const targetPath = join(projectDir, fileSpec.target);
+
+    if (!existsSync(sourcePath)) {
+      skipped.push({ target: fileSpec.target, reason: 'source-missing' });
+      continue;
+    }
+    if (existsSync(targetPath) && !force) {
+      skipped.push({ target: fileSpec.target, reason: 'already-exists' });
+      continue;
+    }
+
+    const raw = readFileSync(sourcePath, 'utf-8');
+    const resolved = resolvePlaceholders(raw, values);
+
+    if (!dryRun) {
+      mkdirSync(dirname(targetPath), { recursive: true });
+      writeFileSync(targetPath, resolved, 'utf-8');
+    }
+
+    manifestFiles[fileSpec.target] = {
+      hash:     hashContent(resolved),
+      source:   fileSpec.source,
+      phase:    fileSpec.phase,
+      override: fileSpec.override,
+    };
+    applied.push(fileSpec.target);
+  }
+
+  let manifestPath = null;
+  if (!dryRun) {
+    manifestPath = join(projectDir, '.chati', 'scaffold-manifest.json');
+    mkdirSync(dirname(manifestPath), { recursive: true });
+    const manifestBody = {
+      scaffold:     manifest.id,
+      version:      manifest.version,
+      appliedAt:    new Date().toISOString(),
+      brandSource,
+      placeholders: values,
+      files:        manifestFiles,
+    };
+    writeFileSync(manifestPath, JSON.stringify(manifestBody, null, 2) + '\n', 'utf-8');
+  }
+
+  return {
+    preset:       manifest.id,
+    version:      manifest.version,
+    applied,
+    skipped,
+    placeholders: values,
+    brandSource,
+    dryRun,
+    manifestPath,
+  };
+}
+
+/**
+ * Stub: re-resolve brand placeholders against an existing scaffold apply.
+ * Not implemented in v1. The workflow is documented in the motion-premium
+ * README — users edit brand.ts, then manually reconcile globals.css OR
+ * wait for this command to ship.
+ *
+ * @returns {never}
+ */
+export function syncBrand() {
+  throw new Error(
+    'scaffold --sync-brand is not yet implemented. ' +
+    'Edit the --color-* block in app/globals.css manually to reflect ' +
+    'brand.ts changes, or wait for the next scaffold-applier release.'
+  );
+}
+
+/**
+ * Stub: upgrade an existing scaffold apply to a newer preset version.
+ * Not implemented in v1. Design exists: will reuse brownfield-upgrader's
+ * hash-diff logic, compare stored hashes in scaffold-manifest.json with
+ * current on-disk hashes, classify files as preserved (user-modified) vs
+ * upgradable (scaffold-owned), and apply the diff.
+ *
+ * @returns {never}
+ */
+export function upgradeScaffold() {
+  throw new Error(
+    'scaffold --upgrade is not yet implemented. The manifest written by ' +
+    'applyScaffold is forward-compatible — a future version will diff ' +
+    'stored hashes against current files and apply minimal updates.'
+  );
+}