decantr 0.9.0

package/cli/commands/test.js

@@ -0,0 +1,38 @@
+import { spawn } from 'node:child_process';
+import { glob } from 'node:fs';
+import { join } from 'node:path';
+
+export async function run() {
+  const cwd = process.cwd();
+  const args = process.argv.slice(3);
+  const watch = args.includes('--watch');
+
+  const testArgs = ['--test'];
+  if (watch) testArgs.push('--watch');
+
+  // Find test files
+  const testFiles = [];
+  const pattern = join(cwd, 'test', '**', '*.test.js');
+
+  // Use node:fs glob (Node 22+)
+  const { glob: fsGlob } = await import('node:fs/promises');
+  for await (const file of fsGlob(pattern)) {
+    testFiles.push(file);
+  }
+
+  if (testFiles.length === 0) {
+    console.log('No test files found in test/**/*.test.js');
+    return;
+  }
+
+  testArgs.push(...testFiles);
+
+  const child = spawn('node', testArgs, {
+    cwd,
+    stdio: 'inherit'
+  });
+
+  child.on('exit', (code) => {
+    process.exit(code || 0);
+  });
+}

package/cli/commands/validate.js

@@ -0,0 +1,354 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export async function run() {
+  const cwd = process.cwd();
+  const essencePath = join(cwd, 'decantr.essence.json');
+  const configPath = join(cwd, 'decantr.config.json');
+  const registryRoot = join(__dirname, '..', '..', 'src', 'registry');
+
+  // Read essence
+  let essence;
+  try {
+    essence = JSON.parse(await readFile(essencePath, 'utf-8'));
+  } catch (e) {
+    console.error('  ✗ decantr.essence.json not found or invalid JSON');
+    console.error('    Run the CLARIFY stage to create your project essence.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const errors = [];
+  const warnings = [];
+
+  // Detect schema form
+  const isSectioned = Array.isArray(essence.sections);
+  const isSimple = typeof essence.terroir === 'string' || essence.terroir === null;
+
+  if (!isSectioned && !isSimple) {
+    errors.push('Essence must have either "terroir" (simple) or "sections" (sectioned)');
+  }
+
+  // Known archetypes
+  const KNOWN_ARCHETYPES = ['ecommerce', 'saas-dashboard', 'portfolio', 'content-site', 'docs-explorer', 'financial-dashboard', 'recipe-community'];
+
+  // Known styles
+  const KNOWN_STYLES = ['auradecantism', 'clean', 'retro', 'glassmorphism', 'command-center'];
+
+  // Validate vintage
+  function validateVintage(vintage, prefix) {
+    if (!vintage) return;
+    if (vintage.style && !KNOWN_STYLES.includes(vintage.style)) {
+      warnings.push(`${prefix}vintage.style "${vintage.style}" is not a built-in style (may be registered via registerStyle()). Built-in: ${KNOWN_STYLES.join(', ')}`);
+    }
+    if (vintage.mode && !['light', 'dark', 'auto'].includes(vintage.mode)) {
+      errors.push(`${prefix}vintage.mode must be light|dark|auto, got "${vintage.mode}"`);
+    }
+  }
+
+  // Valid responsive breakpoints for blend items
+  const VALID_BREAKPOINTS = ['sm', 'md', 'lg', 'xl', '2xl'];
+
+  // Validate blend item depth (Gap 2.3)
+  function validateBlendItems(blend, pageId, prefix) {
+    if (!Array.isArray(blend)) return;
+    for (let i = 0; i < blend.length; i++) {
+      const item = blend[i];
+      if (typeof item === 'string') continue;
+      if (item && typeof item === 'object' && !item.cols && item.pattern) continue; // v2 preset ref
+
+      if (item && typeof item === 'object' && item.cols) {
+        // Validate breakpoint
+        if (item.at != null) {
+          if (!VALID_BREAKPOINTS.includes(item.at)) {
+            errors.push(`${prefix}Page "${pageId}": blend row ${i} has invalid breakpoint "${item.at}". Valid: ${VALID_BREAKPOINTS.join(', ')}`);
+          }
+        }
+
+        // Validate span values
+        if (item.span != null) {
+          if (typeof item.span !== 'object' || Array.isArray(item.span)) {
+            errors.push(`${prefix}Page "${pageId}": blend row ${i} "span" must be an object mapping column IDs to weights`);
+          } else {
+            for (const [key, value] of Object.entries(item.span)) {
+              // Validate span values are positive integers
+              if (!Number.isInteger(value) || value < 1) {
+                errors.push(`${prefix}Page "${pageId}": blend row ${i} span["${key}"] must be a positive integer, got ${JSON.stringify(value)}`);
+              }
+              // Validate span keys match cols entries
+              if (!item.cols.includes(key)) {
+                errors.push(`${prefix}Page "${pageId}": blend row ${i} span key "${key}" does not match any cols entry. Cols: ${item.cols.join(', ')}`);
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Validate structure entries
+  function validateStructure(structure, prefix) {
+    if (!Array.isArray(structure)) return;
+    for (const page of structure) {
+      if (!page.id) errors.push(`${prefix}structure entry missing "id"`);
+      if (!page.skeleton) warnings.push(`${prefix}structure entry "${page.id || '?'}" missing "skeleton"`);
+      if (!page.blend && !page.patterns) warnings.push(`${prefix}structure entry "${page.id || '?'}" missing "blend"`);
+      // Validate blend item depth
+      if (page.blend) validateBlendItems(page.blend, page.id || '?', prefix);
+    }
+  }
+
+  if (isSectioned) {
+    // Sectioned validation
+    const sectionPaths = new Set();
+    for (const section of essence.sections) {
+      if (!section.id) errors.push('Section missing "id"');
+      if (!section.path) errors.push(`Section "${section.id || '?'}" missing "path"`);
+      if (section.path && sectionPaths.has(section.path)) {
+        errors.push(`Duplicate section path: "${section.path}"`);
+      }
+      if (section.path) sectionPaths.add(section.path);
+
+      if (section.terroir && !KNOWN_ARCHETYPES.includes(section.terroir)) {
+        errors.push(`Section "${section.id}": terroir "${section.terroir}" is not a known archetype`);
+      }
+
+      validateVintage(section.vintage, `Section "${section.id || '?'}": `);
+      validateStructure(section.structure, `Section "${section.id || '?'}": `);
+    }
+
+    // Check shared_tannins not duplicated in sections
+    if (Array.isArray(essence.shared_tannins)) {
+      for (const section of essence.sections) {
+        if (Array.isArray(section.tannins)) {
+          for (const t of section.tannins) {
+            if (essence.shared_tannins.includes(t)) {
+              warnings.push(`Tannin "${t}" is in both shared_tannins and section "${section.id}"`);
+            }
+          }
+        }
+      }
+    }
+  } else {
+    // Simple validation
+    if (essence.terroir && !KNOWN_ARCHETYPES.includes(essence.terroir)) {
+      errors.push(`terroir "${essence.terroir}" is not a known archetype. Known: ${KNOWN_ARCHETYPES.join(', ')}`);
+    }
+    validateVintage(essence.vintage, '');
+    validateStructure(essence.structure, '');
+  }
+
+  // Vessel validation
+  if (essence.vessel) {
+    if (essence.vessel.type && !['spa', 'mpa'].includes(essence.vessel.type)) {
+      warnings.push(`vessel.type "${essence.vessel.type}" is unusual (expected spa|mpa)`);
+    }
+    if (essence.vessel.routing && !['hash', 'history'].includes(essence.vessel.routing)) {
+      errors.push(`vessel.routing must be hash|history, got "${essence.vessel.routing}"`);
+    }
+  }
+
+  // Version field validation (Gap 2.5)
+  if (essence.version != null) {
+    if (typeof essence.version !== 'string') {
+      errors.push('version must be a string (semver format, e.g. "1.0.0")');
+    } else if (!/^\d+\.\d+\.\d+$/.test(essence.version)) {
+      warnings.push(`version "${essence.version}" is not standard semver (expected "X.Y.Z")`);
+    }
+  } else {
+    warnings.push('No "version" field in essence. Consider adding a semver version (e.g. "1.0.0") to track essence evolution.');
+  }
+
+  // Cork validation
+  if (essence.cork && typeof essence.cork !== 'object') {
+    errors.push('cork must be an object');
+  }
+
+  // Cross-reference with config
+  try {
+    const config = JSON.parse(await readFile(configPath, 'utf-8'));
+    const essenceStyle = isSectioned ? null : essence.vintage?.style;
+    const essenceMode = isSectioned ? null : essence.vintage?.mode;
+
+    if (essenceStyle && config.style && essenceStyle !== config.style) {
+      warnings.push(`Style mismatch: essence="${essenceStyle}", config="${config.style}". Essence is authoritative.`);
+    }
+    if (essenceMode && config.mode && essenceMode !== config.mode) {
+      warnings.push(`Mode mismatch: essence="${essenceMode}", config="${config.mode}". Essence is authoritative.`);
+    }
+
+    // Validate icons config
+    if (config.icons != null) {
+      if (typeof config.icons !== 'object' || Array.isArray(config.icons)) {
+        errors.push('icons must be an object');
+      } else if (config.icons.library != null && typeof config.icons.library !== 'string') {
+        errors.push('icons.library must be a string');
+      } else if (config.icons.library) {
+        const KNOWN_LIBS = ['lucide', 'heroicons', 'material', 'fontawesome', 'phosphor', 'tabler', 'feather'];
+        if (!KNOWN_LIBS.includes(config.icons.library)) {
+          warnings.push(`icons.library "${config.icons.library}" is not a recognized library (known: ${KNOWN_LIBS.join(', ')}). LLM code generation will use it as-is.`);
+        }
+      }
+    }
+  } catch {
+    // No config file — that's fine
+  }
+
+  // ─── Archetype inheritance validation ─────────────────────────
+  // If an archetype uses `extends`, verify the chain is valid
+  try {
+    const archetypeIdx = JSON.parse(await readFile(join(registryRoot, 'archetypes', 'index.json'), 'utf-8'));
+    const knownArchetypeIds = new Set(Object.keys(archetypeIdx.archetypes || {}));
+
+    // Load all archetypes to check extends chains
+    const archetypeData = {};
+    for (const [aid, meta] of Object.entries(archetypeIdx.archetypes || {})) {
+      try {
+        archetypeData[aid] = JSON.parse(await readFile(join(registryRoot, 'archetypes', meta.file), 'utf-8'));
+      } catch { /* skip unreadable */ }
+    }
+
+    for (const [aid, arch] of Object.entries(archetypeData)) {
+      if (!arch.extends) continue;
+
+      // Check that extends references an existing archetype
+      if (!knownArchetypeIds.has(arch.extends)) {
+        errors.push(`Archetype "${aid}": extends "${arch.extends}" is not a known archetype. Known: ${[...knownArchetypeIds].join(', ')}`);
+        continue;
+      }
+
+      // Check for circular inheritance by following the chain
+      const visited = new Set();
+      let current = aid;
+      let depth = 0;
+      while (current && depth < 10) {
+        if (visited.has(current)) {
+          errors.push(`Archetype "${aid}": circular inheritance detected: ${[...visited, current].join(' → ')}`);
+          break;
+        }
+        visited.add(current);
+        const currentArch = archetypeData[current];
+        current = currentArch?.extends || null;
+        depth++;
+      }
+      if (depth >= 10) {
+        errors.push(`Archetype "${aid}": inheritance chain exceeds depth limit (10)`);
+      }
+    }
+  } catch {
+    // Archetype registry not accessible — skip inheritance validation
+  }
+
+  // ─── Generate prerequisites ───────────────────────────────────
+
+  // Collect all structures for validation
+  const allStructures = isSectioned
+    ? essence.sections.flatMap(s => s.structure || [])
+    : (essence.structure || []);
+
+  // Warn on empty structure
+  if (allStructures.length === 0) {
+    warnings.push('No pages in structure — `decantr generate` will have nothing to produce');
+  }
+
+  // Check patterns in blend arrays exist in registry (supports v2 preset references)
+  try {
+    const patternFiles = await readdir(join(registryRoot, 'patterns'));
+    const knownPatterns = new Set(patternFiles.filter(f => f.endsWith('.json') && f !== 'index.json').map(f => f.replace('.json', '')));
+
+    // Load pattern index for preset validation
+    let patternIndex = {};
+    try {
+      const indexData = JSON.parse(await readFile(join(registryRoot, 'patterns', 'index.json'), 'utf-8'));
+      patternIndex = indexData.patterns || {};
+    } catch { /* skip */ }
+
+    function validateBlendRef(ref, pageId) {
+      if (typeof ref === 'string') {
+        if (!knownPatterns.has(ref)) {
+          warnings.push(`Page "${pageId}": pattern "${ref}" in blend not found in registry`);
+        }
+      } else if (ref && ref.pattern) {
+        // v2 preset reference: { pattern, preset, as }
+        if (!knownPatterns.has(ref.pattern)) {
+          warnings.push(`Page "${pageId}": pattern "${ref.pattern}" in blend not found in registry`);
+        } else if (ref.preset && patternIndex[ref.pattern]?.presets) {
+          if (!patternIndex[ref.pattern].presets.includes(ref.preset)) {
+            warnings.push(`Page "${pageId}": preset "${ref.preset}" not found on pattern "${ref.pattern}". Known presets: ${patternIndex[ref.pattern].presets.join(', ')}`);
+          }
+        }
+      }
+    }
+
+    for (const page of allStructures) {
+      const blend = page.blend || page.patterns || [];
+      for (const item of blend) {
+        if (typeof item === 'string') {
+          validateBlendRef(item, page.id);
+        } else if (item.pattern) {
+          // v2 preset reference at top level
+          validateBlendRef(item, page.id);
+        } else if (item.cols) {
+          for (const col of item.cols) {
+            validateBlendRef(col, page.id);
+          }
+        }
+      }
+    }
+  } catch {
+    // Registry not accessible — skip pattern validation
+  }
+
+  // Check skeletons referenced exist
+  try {
+    const skeletonsData = JSON.parse(await readFile(join(registryRoot, 'skeletons.json'), 'utf-8'));
+    const knownSkeletons = new Set(Object.keys(skeletonsData.skeletons || {}));
+
+    for (const page of allStructures) {
+      if (page.skeleton && !knownSkeletons.has(page.skeleton)) {
+        warnings.push(`Page "${page.id}": skeleton "${page.skeleton}" not found in skeletons.json`);
+      }
+    }
+  } catch {
+    // skeletons.json not accessible — skip
+  }
+
+  // Check recipe referenced in vintage exists
+  const allVintages = isSectioned
+    ? essence.sections.map(s => s.vintage).filter(Boolean)
+    : (essence.vintage ? [essence.vintage] : []);
+
+  try {
+    const registryFiles = await readdir(registryRoot);
+    const knownRecipes = new Set(
+      registryFiles.filter(f => f.startsWith('recipe-') && f.endsWith('.json')).map(f => f.replace('recipe-', '').replace('.json', ''))
+    );
+
+    for (const vintage of allVintages) {
+      if (vintage.recipe && !knownRecipes.has(vintage.recipe)) {
+        warnings.push(`Recipe "${vintage.recipe}" referenced in vintage not found in registry. Known: ${[...knownRecipes].join(', ')}`);
+      }
+    }
+  } catch {
+    // Registry not accessible — skip
+  }
+
+  // Report
+  if (errors.length === 0 && warnings.length === 0) {
+    const mode = isSectioned ? `sectioned (${essence.sections.length} sections)` : `simple (${essence.terroir || 'unset'})`;
+    console.log(`  ✓ Essence valid — ${mode}`);
+  } 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}`);
+    }
+    if (errors.length > 0) process.exitCode = 1;
+  }
+}

package/cli/index.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+
+import { parseArgs } from 'node:util';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { loadPlugins, runHook } from '../src/plugins/index.js';
+
+const { positionals } = parseArgs({ allowPositionals: true, strict: false });
+const command = positionals[0];
+
+// Load project config and plugins for commands that benefit from them
+const cwd = process.cwd();
+let _config = null;
+
+async function getConfig() {
+  if (_config) return _config;
+  try {
+    const raw = await readFile(join(cwd, 'decantr.config.json'), 'utf-8');
+    _config = JSON.parse(raw);
+  } catch {
+    _config = {};
+  }
+  // Load plugins from config
+  await loadPlugins(_config, { cwd });
+  return _config;
+}
+
+switch (command) {
+  case 'init':
+    await import('./commands/init.js').then(m => m.run());
+    break;
+  case 'dev':
+    await getConfig();
+    await runHook('onDev', { cwd, command });
+    await import('./commands/dev.js').then(m => m.run());
+    break;
+  case 'build':
+    await getConfig();
+    await runHook('onBuild', { cwd, command });
+    await import('./commands/build.js').then(m => m.run());
+    break;
+  case 'test':
+    await import('./commands/test.js').then(m => m.run());
+    break;
+  case 'validate':
+    await import('./commands/validate.js').then(m => m.run());
+    break;
+  case 'lint':
+    await import('./commands/lint.js').then(m => m.run());
+    break;
+  case 'a11y':
+    await import('./commands/a11y.js').then(m => m.run());
+    break;
+  case 'audit':
+    if (process.argv.includes('--a11y')) {
+      await import('./commands/a11y.js').then(m => m.run());
+    } else {
+      await import('./commands/audit.js').then(m => m.run());
+    }
+    break;
+  case 'generate':
+    await getConfig();
+    await runHook('onGenerate', { cwd, command });
+    await import('./commands/generate.js').then(m => m.run());
+    break;
+  case 'mcp':
+    await import('./commands/mcp.js').then(m => m.run());
+    break;
+  case 'figma:tokens':
+    await import('./commands/figma-tokens.js').then(m => m.run());
+    break;
+  case 'figma:sync':
+    await import('./commands/figma-sync.js').then(m => m.run());
+    break;
+  case 'migrate':
+    await import('./commands/migrate.js').then(m => m.run());
+    break;
+  case 'doctor':
+    await import('./commands/doctor.js').then(m => m.run());
+    break;
+  default: {
+    const { art } = await import('./art.js');
+    console.log(art());
+    console.log(`
+  \x1b[1mdecantr\x1b[0m v0.9.0 \x1b[2m— AI-first web framework\x1b[0m
+
+  \x1b[1mCommands:\x1b[0m
+    init       Create a new decantr project
+    dev        Start development server
+    build      Build for production
+    test       Run tests
+    validate   Validate decantr.essence.json
+    lint       Code quality gates (atoms, essence drift, inline styles)
+    generate   Generate code from decantr.essence.json
+    a11y       Accessibility audit (8 WCAG rules, static analysis)
+    audit      Audit project: framework coverage, quality, bundle size
+    mcp        Start MCP server (stdio transport) for AI tool integration
+    migrate    Migrate decantr.essence.json between versions
+    figma:tokens  Export design tokens in W3C DTCG / Figma format
+    doctor     Check project health and environment
+    figma:sync    Push tokens to Figma file via REST API
+
+  \x1b[1mUsage:\x1b[0m
+    npx decantr init
+    npx decantr dev
+    npx decantr build
+    npx decantr test [--watch]
+    npx decantr generate [--force] [--dry-run] [--page <id>]
+    npx decantr migrate [--dry-run] [--target=<version>]
+`);
+    break;
+  }
+}

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "decantr",
+  "version": "0.9.0",
+  "type": "module",
+  "description": "AI-first web framework with signal-based reactivity, atomic CSS, and a structured registry of 100+ components.",
+  "homepage": "https://decantr.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/decantr-ai/decantr"
+  },
+  "author": "David Aimi",
+  "license": "MIT",
+  "keywords": [
+    "web-framework",
+    "ai-first",
+    "mcp",
+    "mcp-server",
+    "components",
+    "design-system",
+    "atomic-css"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "src/",
+    "cli/",
+    "tools/",
+    "types/",
+    "reference/",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "mcpName": "decantr.ai/decantr",
+  "bin": {
+    "decantr": "./cli/index.js"
+  },
+  "scripts": {
+    "dev": "decantr dev",
+    "build": "decantr build",
+    "test": "decantr test"
+  },
+  "exports": {
+    "./core": "./src/core/index.js",
+    "./tags": "./src/tags/index.js",
+    "./css": "./src/css/index.js",
+    "./state": "./src/state/index.js",
+    "./state/store": "./src/state/store.js",
+    "./state/arrays": "./src/state/arrays.js",
+    "./state/devtools": "./src/state/devtools.js",
+    "./state/middleware": "./src/state/middleware.js",
+    "./data": "./src/data/index.js",
+    "./router": "./src/router/index.js",
+    "./components": "./src/components/index.js",
+    "./form": "./src/form/index.js",
+    "./chart": "./src/chart/index.js",
+    "./test": "./src/test/index.js",
+    "./plugins": "./src/plugins/index.js",
+    "./i18n": "./src/i18n/index.js",
+    "./ssr": "./src/ssr/index.js",
+    "./tannins/auth": "./src/tannins/auth.js",
+    "./styles/clean": "./src/css/styles/addons/clean.js",
+    "./styles/retro": "./src/css/styles/addons/retro.js",
+    "./styles/glassmorphism": "./src/css/styles/addons/glassmorphism.js",
+    "./styles/command-center": "./src/css/styles/addons/command-center.js",
+    "./styles/clay": "./src/css/styles/addons/clay.js",
+    "./styles/liquid-glass": "./src/css/styles/addons/liquid-glass.js",
+    "./styles/dopamine": "./src/css/styles/addons/dopamine.js",
+    "./styles/prismatic": "./src/css/styles/addons/prismatic.js",
+    "./styles/bioluminescent": "./src/css/styles/addons/bioluminescent.js",
+    "./styles/editorial": "./src/css/styles/addons/editorial.js",
+    "./explorer/patterns.js": "./src/explorer/patterns.js",
+    "./explorer/icons.js": "./src/explorer/icons.js",
+    "./explorer/tokens.js": "./src/explorer/tokens.js",
+    "./explorer/foundations.js": "./src/explorer/foundations.js",
+    "./explorer/archetypes.js": "./src/explorer/archetypes.js",
+    "./explorer/charts.js": "./src/explorer/charts.js",
+    "./explorer/shells.js": "./src/explorer/shells.js",
+    "./explorer/recipes.js": "./src/explorer/recipes.js",
+    "./explorer/tools.js": "./src/explorer/tools.js",
+    "./explorer/components.js": "./src/explorer/components.js",
+    "./explorer/atoms.js": "./src/explorer/atoms.js",
+    "./explorer/styles.js": "./src/explorer/styles.js"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1"
+  }
+}