decantr 0.9.0

package/cli/commands/doctor.js

@@ -0,0 +1,197 @@
+import { readFile, stat, access } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const cwd = process.cwd();
+
+// ── Color helpers ─────────────────────────────────────────────────
+const green = (s) => `\x1b[32m✓\x1b[0m ${s}`;
+const red = (s) => `\x1b[31m✗\x1b[0m ${s}`;
+const yellow = (s) => `\x1b[33m⚠\x1b[0m ${s}`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+
+let passes = 0;
+let warns = 0;
+let fails = 0;
+
+function pass(msg) { passes++; console.log(green(msg)); }
+function warn(msg) { warns++; console.log(yellow(msg)); }
+function fail(msg) { fails++; console.log(red(msg)); }
+
+async function fileExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJSON(path) {
+  try {
+    const raw = await readFile(path, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+// ── Checks ────────────────────────────────────────────────────────
+
+async function checkNodeVersion() {
+  const [major] = process.versions.node.split('.').map(Number);
+  if (major >= 20) {
+    pass(`Node.js ${process.versions.node} (>= 20.0.0 required)`);
+  } else {
+    fail(`Node.js ${process.versions.node} — requires >= 20.0.0`);
+  }
+}
+
+async function checkPackageJson() {
+  const pkgPath = join(cwd, 'package.json');
+  const pkg = await readJSON(pkgPath);
+  if (!pkg) {
+    fail('package.json not found');
+    return;
+  }
+  pass('package.json exists');
+
+  if (pkg.type === 'module') {
+    pass('package.json type is "module"');
+  } else {
+    warn('package.json type should be "module" for ESM support');
+  }
+
+  // Check for decantr dependency (accept both scoped and unscoped names)
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const decantrVersion = deps['decantr'] || deps['decantr'];
+  if (decantrVersion) {
+    pass(`decantr ${decantrVersion} in dependencies`);
+  } else {
+    fail('decantr not found in dependencies (expected decantr or decantr)');
+  }
+}
+
+async function checkConfig() {
+  const configPath = join(cwd, 'decantr.config.json');
+  const config = await readJSON(configPath);
+  if (!config) {
+    warn('decantr.config.json not found — using defaults');
+    return;
+  }
+  pass('decantr.config.json exists and is valid JSON');
+
+  if (config.build?.sizeBudget) {
+    pass('Size budgets configured');
+  } else {
+    warn('No size budgets configured in decantr.config.json');
+  }
+}
+
+async function checkEssence() {
+  const essPath = join(cwd, 'decantr.essence.json');
+  const ess = await readJSON(essPath);
+  if (!ess) {
+    warn('decantr.essence.json not found — run `decantr generate` or create manually');
+    return;
+  }
+  pass('decantr.essence.json exists and is valid JSON');
+
+  if (ess.terroir) pass(`Terroir: ${ess.terroir}`);
+  else if (ess.sections) pass(`Sectioned essence with ${ess.sections.length} section(s)`);
+  else warn('Essence missing terroir or sections');
+
+  if (ess.vintage?.style) pass(`Style: ${ess.vintage.style}`);
+  else if (ess.sections?.[0]?.vintage?.style) pass(`Style: ${ess.sections[0].vintage.style} (first section)`);
+  else warn('Essence missing vintage.style');
+
+  const structure = ess.structure || ess.sections?.flatMap(s => s.structure || []) || [];
+  if (structure.length > 0) {
+    pass(`Structure: ${structure.length} page(s) defined`);
+  } else {
+    warn('No pages defined in structure');
+  }
+}
+
+async function checkEntryPoint() {
+  const candidates = ['src/app.js', 'src/index.js', 'src/main.js'];
+  for (const c of candidates) {
+    if (await fileExists(join(cwd, c))) {
+      pass(`Entry point found: ${c}`);
+      return;
+    }
+  }
+  warn('No entry point found (expected src/app.js, src/index.js, or src/main.js)');
+}
+
+async function checkDirectories() {
+  const dirs = ['src', 'public'];
+  for (const d of dirs) {
+    try {
+      const s = await stat(join(cwd, d));
+      if (s.isDirectory()) {
+        pass(`${d}/ directory exists`);
+      } else {
+        fail(`${d} exists but is not a directory`);
+      }
+    } catch {
+      if (d === 'src') fail('src/ directory not found');
+      else warn(`${d}/ directory not found — optional`);
+    }
+  }
+}
+
+async function checkPublicHTML() {
+  const htmlPath = join(cwd, 'public', 'index.html');
+  if (await fileExists(htmlPath)) {
+    pass('public/index.html exists');
+    const html = await readFile(htmlPath, 'utf-8');
+    if (html.includes('type="module"')) {
+      pass('index.html loads app as ES module');
+    } else {
+      warn('index.html missing type="module" on script tag');
+    }
+  } else {
+    warn('public/index.html not found');
+  }
+}
+
+async function checkFrameworkVersion() {
+  const scopedPath = join(cwd, 'node_modules', '@decantr', 'decantr', 'package.json');
+  const unscopedPath = join(cwd, 'node_modules', 'decantr', 'package.json');
+  const pkg = await readJSON(scopedPath) || await readJSON(unscopedPath);
+  if (!pkg) {
+    warn('Cannot read installed decantr version — run npm install');
+    return;
+  }
+  const [major, minor] = pkg.version.split('.').map(Number);
+  pass(`Framework version: ${pkg.version}`);
+  if (major === 0 && minor < 4) {
+    warn(`Framework version ${pkg.version} is outdated — consider updating to latest`);
+  }
+}
+
+// ── Main ──────────────────────────────────────────────────────────
+export async function run() {
+  console.log(`\n${bold('decantr doctor')} ${dim('— checking project health')}\n`);
+
+  await checkNodeVersion();
+  await checkPackageJson();
+  await checkConfig();
+  await checkEssence();
+  await checkEntryPoint();
+  await checkDirectories();
+  await checkPublicHTML();
+  await checkFrameworkVersion();
+
+  console.log(`\n${bold('Results:')} ${green(`${passes} passed`)}${warns ? `, ${yellow(`${warns} warnings`)}` : ''}${fails ? `, ${red(`${fails} failed`)}` : ''}\n`);
+
+  if (fails > 0) {
+    console.log(`${red('Some checks failed. Fix the issues above and run again.')}\n`);
+    process.exit(1);
+  } else if (warns > 0) {
+    console.log(`${yellow('All critical checks passed, but there are warnings.')}\n`);
+  } else {
+    console.log(`${green('All checks passed! Your project is healthy.')}\n`);
+  }
+}

package/cli/commands/figma-sync.js

@@ -0,0 +1,48 @@
+import { parseArgs } from 'node:util';
+
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const GREEN = '\x1b[32m';
+const CYAN = '\x1b[36m';
+const RESET = '\x1b[0m';
+
+export async function run() {
+  const { values } = parseArgs({
+    options: {
+      token: { type: 'string' },
+      file: { type: 'string' },
+      style: { type: 'string', default: 'all' },
+      input: { type: 'string' },
+      'dry-run': { type: 'boolean', default: false },
+    },
+    strict: false,
+  });
+
+  console.log(`\n  ${BOLD}decantr figma:sync${RESET}\n`);
+
+  const { syncFigmaTokens } = await import('../../tools/figma-upload.js');
+
+  try {
+    const result = await syncFigmaTokens({
+      token: values.token,
+      file: values.file,
+      style: values.style,
+      input: values.input,
+      'dry-run': values['dry-run'],
+      cwd: process.cwd(),
+    });
+
+    if (values['dry-run']) {
+      console.log(`  ${DIM}Collections:${RESET} ${result.collections}`);
+      console.log(`  ${DIM}Variables:${RESET} ${result.variables}`);
+      console.log(`  ${DIM}Mode values:${RESET} ${result.modeValues}`);
+      console.log(`\n  ${DIM}(dry run — no changes pushed)${RESET}\n`);
+    } else {
+      console.log(`  ${GREEN}✓${RESET} Synced ${BOLD}${result.variables}${RESET} variables across ${BOLD}${result.collections}${RESET} collection(s)`);
+      console.log(`  ${GREEN}✓${RESET} ${result.modeValues} mode values set\n`);
+    }
+  } catch (e) {
+    console.error(`\n  ✗ ${e.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/cli/commands/figma-tokens.js

@@ -0,0 +1,55 @@
+import { parseArgs } from 'node:util';
+
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const GREEN = '\x1b[32m';
+const CYAN = '\x1b[36m';
+const RESET = '\x1b[0m';
+
+export async function run() {
+  const { values } = parseArgs({
+    options: {
+      style: { type: 'string', default: 'all' },
+      format: { type: 'string', default: 'dtcg' },
+      output: { type: 'string' },
+      'dry-run': { type: 'boolean', default: false },
+    },
+    strict: false,
+  });
+
+  console.log(`\n  ${BOLD}decantr figma:tokens${RESET}\n`);
+
+  const { generateFigmaTokens } = await import('../../tools/figma-tokens.js');
+
+  try {
+    const result = await generateFigmaTokens({
+      style: values.style,
+      format: values.format,
+      output: values.output,
+      'dry-run': values['dry-run'],
+      cwd: process.cwd(),
+    });
+
+    if (values['dry-run']) {
+      console.log(`  ${DIM}Styles:${RESET} ${result.styles.join(', ')}`);
+      console.log(`  ${DIM}Tokens per style:${RESET} ~${Math.round(result.tokenCount / result.styles.length)}`);
+      console.log(`  ${DIM}Shape tokens:${RESET} ${result.shapeTokenCount}`);
+      console.log(`  ${DIM}Files:${RESET}`);
+      for (const f of result.files) {
+        console.log(`    ${DIM}→${RESET} ${f}`);
+      }
+      console.log();
+    } else {
+      console.log(`  ${GREEN}✓${RESET} Generated ${BOLD}${result.tokenCount}${RESET} tokens across ${BOLD}${result.styles.length}${RESET} style(s)`);
+      console.log(`  ${GREEN}✓${RESET} ${result.shapeTokenCount} shape tokens (3 modes)`);
+      console.log(`  ${DIM}Output:${RESET} ${result.files.length} files\n`);
+      for (const f of result.files) {
+        console.log(`    ${CYAN}→${RESET} ${f}`);
+      }
+      console.log();
+    }
+  } catch (e) {
+    console.error(`\n  ✗ ${e.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/cli/commands/generate.js

@@ -0,0 +1,26 @@
+import { parseArgs } from 'node:util';
+
+export async function run() {
+  const { values } = parseArgs({
+    options: {
+      force: { type: 'boolean', default: false },
+      'dry-run': { type: 'boolean', default: false },
+      page: { type: 'string' },
+    },
+    strict: false,
+  });
+
+  const { generate } = await import('../../tools/generate.js');
+
+  try {
+    await generate({
+      cwd: process.cwd(),
+      force: values.force,
+      dryRun: values['dry-run'],
+      pageFilter: values.page || null,
+    });
+  } catch (e) {
+    console.error(`\n  ✗ ${e.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/cli/commands/init.js

@@ -0,0 +1,116 @@
+import { mkdir, writeFile, copyFile } from 'node:fs/promises';
+import { join, basename, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { welcome, success, info, heading } from '../art.js';
+import {
+  packageJson, configJson, essenceJson, indexHtml, manifestJson,
+  claudeMd, appJs, agentsMd
+} from '../../tools/init-templates.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const frameworkRoot = resolve(__dirname, '..', '..');
+
+const TEMPLATES = ['saas-dashboard', 'ecommerce', 'portfolio', 'content-site', 'landing-page'];
+
+/**
+ * Parse --template flag from process.argv.
+ * Supports: --template=name and --template name
+ */
+function parseTemplate() {
+  const args = process.argv.slice(3);
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith('--template=')) return args[i].split('=')[1];
+    if (args[i] === '--template' && args[i + 1]) return args[i + 1];
+  }
+  return null;
+}
+
+/**
+ * Create a new decantr project skeleton.
+ * User then prompts their AI to build the app.
+ */
+export async function run() {
+  const cwd = process.cwd();
+  const name = process.argv[3] && !process.argv[3].startsWith('--') ? process.argv[3] : basename(cwd);
+  const templateName = parseTemplate();
+
+  // Validate template name if provided
+  if (templateName && !TEMPLATES.includes(templateName)) {
+    console.log(`\x1b[31mError: Unknown template "${templateName}"\x1b[0m`);
+    console.log(info(`Available templates: ${TEMPLATES.join(', ')}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(welcome('0.4.0'));
+  if (templateName) {
+    console.log(heading(`Creating project from "${templateName}" template...`));
+  } else {
+    console.log(heading('Creating project skeleton...'));
+  }
+
+  // Create directories
+  const dirs = ['public', 'public/images', '.decantr', 'src', 'src/pages', 'src/components'];
+  for (const dir of dirs) {
+    await mkdir(join(cwd, dir), { recursive: true });
+  }
+
+  // Load template overrides if specified
+  let templateEssence = essenceJson;
+  let templateApp = appJs;
+  let templatePages = null;
+  if (templateName) {
+    const tmpl = await import(`../../tools/starter-templates/${templateName}/essence.js`);
+    const tmplApp = await import(`../../tools/starter-templates/${templateName}/app.js`);
+    const tmplPages = await import(`../../tools/starter-templates/${templateName}/pages.js`);
+    templateEssence = tmpl.essenceJson;
+    templateApp = tmplApp.appJs;
+    templatePages = tmplPages.pageFiles;
+  }
+
+  const files = [
+    ['package.json', packageJson(name)],
+    ['decantr.config.json', configJson(name)],
+    ['decantr.essence.json', templateEssence()],
+    ['public/index.html', indexHtml(name)],
+    ['.decantr/manifest.json', manifestJson(name)],
+    ['CLAUDE.md', claudeMd(name)],
+    ['AGENTS.md', await agentsMd()],
+    ['src/app.js', templateApp()]
+  ];
+
+  // Add template page stubs
+  if (templatePages) {
+    for (const [path, content] of templatePages()) {
+      files.push([path, content]);
+    }
+  }
+
+  for (const [path, content] of files) {
+    await writeFile(join(cwd, path), content + '\n');
+    console.log('  ' + success(path));
+  }
+
+  // Copy logo asset
+  const logoSrc = join(frameworkRoot, 'workbench', 'public', 'images', 'logo-portrait.svg');
+  const logoDest = join(cwd, 'public', 'images', 'logo-portrait.svg');
+  try {
+    await copyFile(logoSrc, logoDest);
+    console.log('  ' + success('public/images/logo-portrait.svg'));
+  } catch {
+    // Logo not found — non-fatal, welcome page still works without it
+  }
+
+  console.log('');
+  console.log(heading('Project created!'));
+  console.log(info('Next steps:'));
+  console.log('    npm install');
+  console.log('    npx decantr dev');
+  console.log('');
+  if (templateName) {
+    console.log(info(`Template "${templateName}" applied. Run decantr generate to scaffold full pages from the essence.`));
+  } else {
+    console.log(info('Then prompt your AI to build your app.'));
+  }
+  console.log('');
+}

package/cli/commands/lint.js

@@ -0,0 +1,209 @@
+/**
+ * decantr lint — Code quality gates
+ *
+ * Checks:
+ * 1. Atom validation — flags unknown `_` atoms in source files
+ * 2. Essence drift — detects divergence between essence and generated code
+ * 3. Inline style detection — flags inline styles that should be atoms
+ * 4. Pattern coverage — checks that all blend patterns are implemented
+ */
+
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join, dirname, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const registryRoot = join(__dirname, '..', '..', 'src', 'registry');
+
+export async function run() {
+  const cwd = process.cwd();
+  const errors = [];
+  const warnings = [];
+
+  console.log('\n  decantr lint\n');
+
+  // ─── 1. Essence drift detection ─────────────────────────────
+  try {
+    const essenceRaw = await readFile(join(cwd, 'decantr.essence.json'), 'utf-8');
+    const essence = JSON.parse(essenceRaw);
+    const essenceHash = createHash('md5').update(essenceRaw).digest('hex');
+
+    try {
+      const lockRaw = await readFile(join(cwd, 'decantr.lock.json'), 'utf-8');
+      const lock = JSON.parse(lockRaw);
+
+      if (lock.essenceHash !== essenceHash) {
+        warnings.push('Essence has changed since last generate — run `decantr generate` to sync');
+      }
+
+      // Check that all essence pages have corresponding files
+      const structures = Array.isArray(essence.sections)
+        ? essence.sections.flatMap(s => s.structure || [])
+        : (essence.structure || []);
+
+      for (const page of structures) {
+        try {
+          await stat(join(cwd, 'src', 'pages', `${page.id}.js`));
+        } catch {
+          warnings.push(`Page "${page.id}" in essence but no src/pages/${page.id}.js found`);
+        }
+      }
+    } catch {
+      warnings.push('No decantr.lock.json — run `decantr generate` to create');
+    }
+
+    console.log('  ✓ Essence drift check complete');
+  } catch {
+    console.log('  ○ No essence file — skipping drift check');
+  }
+
+  // ─── 2. Atom validation in source files ──────────────────────
+  const srcDir = join(cwd, 'src');
+  try {
+    const jsFiles = await collectJSFiles(srcDir);
+    const atomRegex = /_[a-zA-Z][a-zA-Z0-9\[\]]*(?:\/\d+)?/g;
+
+    // Load known atoms from registry
+    let knownAtomPrefixes;
+    try {
+      const atomsSource = await readFile(join(__dirname, '..', '..', 'src', 'css', 'atoms.js'), 'utf-8');
+      knownAtomPrefixes = extractAtomPrefixes(atomsSource);
+    } catch {
+      knownAtomPrefixes = null;
+    }
+
+    let atomErrors = 0;
+    for (const file of jsFiles) {
+      const source = await readFile(file, 'utf-8');
+      // Only check inside css() calls
+      const cssCallRegex = /css\(['"`]([^'"`]+)['"`]\)/g;
+      let match;
+      while ((match = cssCallRegex.exec(source)) !== null) {
+        const atomStr = match[1];
+        const atoms = atomStr.split(/\s+/).filter(a => a.startsWith('_'));
+        for (const atom of atoms) {
+          // Skip arbitrary value atoms like _w[100px] and responsive prefixes
+          if (atom.includes('[')) continue;
+          if (atom.includes(':')) continue;
+          // Basic validation: known prefixes
+          if (knownAtomPrefixes && !matchesKnownAtom(atom, knownAtomPrefixes)) {
+            const rel = relative(cwd, file);
+            warnings.push(`Unknown atom "${atom}" in ${rel}`);
+            atomErrors++;
+            if (atomErrors >= 20) break; // Don't flood
+          }
+        }
+        if (atomErrors >= 20) break;
+      }
+      if (atomErrors >= 20) {
+        warnings.push('... truncated (20+ atom warnings)');
+        break;
+      }
+    }
+
+    console.log(`  ✓ Atom validation: ${jsFiles.length} files scanned`);
+  } catch {
+    console.log('  ○ No src/ directory — skipping atom validation');
+  }
+
+  // ─── 3. Inline style detection ───────────────────────────────
+  try {
+    const jsFiles = await collectJSFiles(srcDir);
+    let inlineCount = 0;
+    for (const file of jsFiles) {
+      const source = await readFile(file, 'utf-8');
+      // Look for style: { ... } with static values (not functions)
+      const staticStyleRegex = /style:\s*['"`][^'"`]*(?:background|color|font|margin|padding|border|width|height|display|flex|grid)[^'"`]*['"`]/gi;
+      let match;
+      while ((match = staticStyleRegex.exec(source)) !== null) {
+        const rel = relative(cwd, file);
+        warnings.push(`Possible inline style in ${rel} — consider using atoms`);
+        inlineCount++;
+        if (inlineCount >= 10) break;
+      }
+      if (inlineCount >= 10) {
+        warnings.push('... truncated (10+ inline style warnings)');
+        break;
+      }
+    }
+    console.log(`  ✓ Inline style check complete`);
+  } catch {
+    // Already handled above
+  }
+
+  // ─── Report ─────────────────────────────────────────────────
+  if (errors.length === 0 && warnings.length === 0) {
+    console.log('\n  ✓ All checks passed\n');
+  } else {
+    if (errors.length > 0) {
+      console.error(`\n  ${errors.length} error(s):`);
+      for (const e of errors) console.error(`    ✗ ${e}`);
+    }
+    if (warnings.length > 0) {
+      console.log(`\n  ${warnings.length} warning(s):`);
+      for (const w of warnings) console.log(`    ⚠ ${w}`);
+    }
+    console.log('');
+    if (errors.length > 0) process.exitCode = 1;
+  }
+}
+
+async function collectJSFiles(dir) {
+  const files = [];
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory() && entry.name !== 'node_modules') {
+        files.push(...await collectJSFiles(full));
+      } else if (entry.name.endsWith('.js')) {
+        files.push(full);
+      }
+    }
+  } catch { /* skip inaccessible dirs */ }
+  return files;
+}
+
+function extractAtomPrefixes(atomsSource) {
+  // Extract known atom name patterns from atoms.js
+  const prefixes = new Set();
+  // Match ALIASES keys
+  const aliasRegex = /'(_[a-zA-Z]+)'/g;
+  let m;
+  while ((m = aliasRegex.exec(atomsSource)) !== null) {
+    prefixes.add(m[1]);
+  }
+  // Add common known atom bases
+  const common = [
+    '_flex', '_col', '_row', '_grid', '_gap', '_p', '_px', '_py', '_pt', '_pr', '_pb', '_pl',
+    '_m', '_mx', '_my', '_mt', '_mr', '_mb', '_ml', '_w', '_h', '_mw', '_mh', '_r', '_b',
+    '_aic', '_jcc', '_jcsb', '_jcse', '_jce', '_tc', '_tl', '_tr', '_ais', '_aie',
+    '_relative', '_absolute', '_fixed', '_sticky', '_static',
+    '_overflow', '_wfull', '_hfull', '_flex1', '_grow', '_shrink0',
+    '_heading1', '_heading2', '_heading3', '_heading4', '_heading5', '_heading6',
+    '_body', '_caption', '_textsm', '_textxs', '_bold', '_italic',
+    '_fgfg', '_fgmuted', '_fgmutedfg', '_fgprimary', '_bgbg', '_bgmuted',
+    '_nounder', '_trans', '_block', '_inline', '_inlineFlex',
+    '_borderB', '_borderT', '_borderR', '_borderL', '_bordert', '_borderb',
+    '_object', '_inset0', '_top0', '_bottom0', '_left0', '_right0',
+    '_lineClamp2', '_clamp2', '_wrap', '_flexWrap', '_rfull',
+    '_gc', '_span', '_gcaf', '_mxa', '_mxAuto',
+    '_center', '_lhrelaxed', '_fontBold',
+  ];
+  for (const c of common) prefixes.add(c);
+  return prefixes;
+}
+
+function matchesKnownAtom(atom, prefixes) {
+  if (prefixes.has(atom)) return true;
+  // Check prefix matches (e.g. _gap4 matches _gap prefix)
+  for (const prefix of prefixes) {
+    if (atom.startsWith(prefix) && atom.length > prefix.length) {
+      const suffix = atom.slice(prefix.length);
+      // Numeric suffix is always valid
+      if (/^\d+(-\d+)?$/.test(suffix)) return true;
+    }
+  }
+  return false;
+}