@lifeonlars/prime-yggdrasil 0.2.5 → 0.3.0

package/cli/commands/init.js

@@ -0,0 +1,288 @@
+import { existsSync, mkdirSync, copyFileSync, writeFileSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import readline from 'readline';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+function question(query) {
+  return new Promise((resolve) => rl.question(query, resolve));
+}
+
+export async function initCommand() {
+  console.log(`
+🌳 Yggdrasil Agent Infrastructure Setup
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+This will set up AI agents in your project to guide design
+system usage and prevent drift.
+`);
+
+  try {
+    // Detect project type
+    const projectType = detectProjectType();
+    console.log(`📦 Detected project type: ${projectType}`);
+    console.log('');
+
+    // Ask user preferences
+    const copyAgents = await askYesNo('Copy agent documentation to .ai/yggdrasil/? (Recommended)', true);
+    const installESLint = await askYesNo('Add ESLint config reference? (Available in Phase 3)', false);
+    const addScripts = await askYesNo('Add npm scripts to package.json?', true);
+
+    console.log('');
+    console.log('📋 Installation Plan:');
+    console.log('');
+    if (copyAgents) console.log('  ✓ Copy 4 agent specifications to .ai/yggdrasil/');
+    if (installESLint) console.log('  ✓ Add ESLint configuration (placeholder for Phase 3)');
+    if (addScripts) console.log('  ✓ Add npm scripts for validation');
+    console.log('');
+
+    const proceed = await askYesNo('Proceed with installation?', true);
+    if (!proceed) {
+      console.log('❌ Installation cancelled.');
+      rl.close();
+      return;
+    }
+
+    console.log('');
+    console.log('🚀 Installing...');
+    console.log('');
+
+    // Copy agents
+    if (copyAgents) {
+      await copyAgentFiles();
+    }
+
+    // Add ESLint config
+    if (installESLint) {
+      await createESLintConfig();
+    }
+
+    // Add scripts
+    if (addScripts) {
+      await addNpmScripts();
+    }
+
+    // Print success message
+    printSuccessMessage(copyAgents, installESLint);
+
+    rl.close();
+  } catch (error) {
+    console.error('❌ Error during installation:', error.message);
+    rl.close();
+    process.exit(1);
+  }
+}
+
+function detectProjectType() {
+  const cwd = process.cwd();
+
+  if (existsSync(join(cwd, 'next.config.js')) || existsSync(join(cwd, 'next.config.mjs'))) {
+    return 'Next.js';
+  }
+  if (existsSync(join(cwd, 'vite.config.js')) || existsSync(join(cwd, 'vite.config.ts'))) {
+    return 'Vite';
+  }
+  if (existsSync(join(cwd, 'package.json'))) {
+    return 'React/Node.js';
+  }
+  return 'Unknown';
+}
+
+async function askYesNo(question, defaultYes = true) {
+  const prompt = `${question} ${defaultYes ? '[Y/n]' : '[y/N]'}: `;
+  const answer = await questionPromise(prompt);
+  const normalized = answer.toLowerCase().trim();
+
+  if (normalized === '') return defaultYes;
+  return normalized === 'y' || normalized === 'yes';
+}
+
+function questionPromise(query) {
+  return new Promise((resolve) => rl.question(query, resolve));
+}
+
+async function copyAgentFiles() {
+  const cwd = process.cwd();
+  const targetDir = join(cwd, '.ai', 'yggdrasil');
+  const sourceDir = join(__dirname, '../templates/.ai/yggdrasil');
+
+  // Create target directory
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true });
+  }
+
+  // Copy agent files from main .ai/agents directory
+  const mainAgentsDir = join(__dirname, '../../.ai/agents');
+  const agentFiles = [
+    'block-composer.md',
+    'primeflex-guard.md',
+    'semantic-token-intent.md',
+    'drift-validator.md'
+  ];
+
+  console.log('  📄 Copying agent specifications...');
+  for (const file of agentFiles) {
+    const source = join(mainAgentsDir, file);
+    const target = join(targetDir, file);
+
+    if (existsSync(source)) {
+      copyFileSync(source, target);
+      console.log(`     ✓ ${file}`);
+    } else {
+      console.log(`     ⚠️  ${file} not found (will be available after build)`);
+    }
+  }
+
+  // Copy README
+  const readmePath = join(sourceDir, 'README.md');
+  if (existsSync(readmePath)) {
+    copyFileSync(readmePath, join(targetDir, 'README.md'));
+    console.log('     ✓ README.md');
+  }
+
+  // Copy PrimeFlex policy
+  const policySource = join(__dirname, '../../docs/PRIMEFLEX-POLICY.md');
+  if (existsSync(policySource)) {
+    copyFileSync(policySource, join(targetDir, 'PRIMEFLEX-POLICY.md'));
+    console.log('     ✓ PRIMEFLEX-POLICY.md');
+  }
+
+  console.log('');
+  console.log(`  ✅ Copied agents to ${targetDir}`);
+  console.log('');
+}
+
+async function createESLintConfig() {
+  const cwd = process.cwd();
+  const configPath = join(cwd, '.eslintrc.yggdrasil.js');
+
+  const configContent = `// Yggdrasil ESLint Configuration
+// This will be functional in Phase 3 when the ESLint plugin is published
+
+module.exports = {
+  extends: [
+    // Uncomment when @lifeonlars/eslint-plugin-yggdrasil is available (Phase 3)
+    // 'plugin:@lifeonlars/yggdrasil/recommended'
+  ],
+  rules: {
+    // Phase 3: ESLint rules will enforce:
+    // - No hardcoded colors (use semantic tokens)
+    // - No PrimeFlex on PrimeReact components
+    // - PrimeFlex allowlist (layout/spacing only)
+    // - No Tailwind classes
+    // - Valid spacing (4px grid)
+    // - Semantic tokens only
+    // - Consistent PrimeReact imports
+  }
+};
+`;
+
+  writeFileSync(configPath, configContent);
+  console.log(`  ✅ Created ${configPath}`);
+  console.log('     ⚠️  ESLint plugin will be available in Phase 3');
+  console.log('');
+}
+
+async function addNpmScripts() {
+  const cwd = process.cwd();
+  const packageJsonPath = join(cwd, 'package.json');
+
+  if (!existsSync(packageJsonPath)) {
+    console.log('  ⚠️  package.json not found, skipping script installation');
+    return;
+  }
+
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+
+  if (!packageJson.scripts) {
+    packageJson.scripts = {};
+  }
+
+  // Add scripts (placeholders for Phase 4)
+  const scriptsToAdd = {
+    'yggdrasil:validate': 'echo "⚠️  Validation command available in Phase 4. Use ESLint for now."',
+    'yggdrasil:audit': 'echo "⚠️  Audit command available in Phase 4. Use ESLint for now."'
+  };
+
+  let added = false;
+  for (const [key, value] of Object.entries(scriptsToAdd)) {
+    if (!packageJson.scripts[key]) {
+      packageJson.scripts[key] = value;
+      console.log(`  ✓ Added script: ${key}`);
+      added = true;
+    }
+  }
+
+  if (added) {
+    writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
+    console.log('');
+    console.log('  ✅ Updated package.json');
+  } else {
+    console.log('  ℹ️  Scripts already exist, skipping');
+  }
+  console.log('');
+}
+
+function printSuccessMessage(copiedAgents, addedESLint) {
+  console.log('');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('✅ Yggdrasil Agent Infrastructure Installed!');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('');
+
+  if (copiedAgents) {
+    console.log('📚 Agent Documentation:');
+    console.log('   .ai/yggdrasil/block-composer.md        - Composition planning');
+    console.log('   .ai/yggdrasil/primeflex-guard.md       - Layout constraints');
+    console.log('   .ai/yggdrasil/semantic-token-intent.md - Token selection');
+    console.log('   .ai/yggdrasil/drift-validator.md       - Policy enforcement');
+    console.log('   .ai/yggdrasil/PRIMEFLEX-POLICY.md      - PrimeFlex usage rules');
+    console.log('');
+  }
+
+  console.log('🤖 Using Agents with AI Tools:');
+  console.log('');
+  console.log('   Claude Code:');
+  console.log('   "Before implementing UI, read .ai/yggdrasil/block-composer.md');
+  console.log('    and suggest the appropriate PrimeReact components."');
+  console.log('');
+  console.log('   Cursor/Copilot:');
+  console.log('   Add .ai/yggdrasil/ to your AI context, then ask:');
+  console.log('   "Help me implement a user profile form following Yggdrasil agents."');
+  console.log('');
+
+  console.log('📖 Next Steps:');
+  console.log('');
+  console.log('   1. Read the agent documentation in .ai/yggdrasil/');
+  console.log('   2. Reference agents when implementing UI features');
+  console.log('   3. Phase 3: Install ESLint plugin for code-time validation');
+  console.log('      npm install --save-dev @lifeonlars/eslint-plugin-yggdrasil');
+  console.log('   4. Phase 4: Use validation commands');
+  console.log('      npm run yggdrasil:validate');
+  console.log('      npm run yggdrasil:audit');
+  console.log('');
+
+  console.log('📋 Agent Workflow:');
+  console.log('');
+  console.log('   Planning UI:        Block Composer Agent');
+  console.log('   Choosing layout:    PrimeFlex Guard Agent');
+  console.log('   Selecting colors:   Semantic Token Intent Agent');
+  console.log('   Validating code:    Drift Validator Agent');
+  console.log('');
+
+  console.log('🔗 Resources:');
+  console.log('');
+  console.log('   Documentation: https://github.com/lifeonlars/prime-yggdrasil');
+  console.log('   PrimeReact:    https://primereact.org/');
+  console.log('   PrimeFlex:     https://primeflex.org/');
+  console.log('');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('');
+}

package/cli/commands/validate.js

@@ -0,0 +1,405 @@
+import { readFileSync, readdirSync, statSync } from 'fs';
+import { join, extname } from 'path';
+
+/**
+ * Validate command - Report-only mode
+ *
+ * Scans the project for design system violations and reports them.
+ * Does NOT block builds - use for analysis and adoption phase.
+ *
+ * For autofix suggestions, use the audit command instead.
+ */
+
+// Import validation logic from ESLint rules
+// Since we can't directly import ESLint rules into CLI without ESLint dependency,
+// we'll implement simplified validation logic here that shares the same concepts
+
+const PRIMEREACT_COMPONENTS = [
+  'AutoComplete', 'Calendar', 'CascadeSelect', 'Checkbox', 'Chips', 'ColorPicker',
+  'Dropdown', 'Editor', 'FloatLabel', 'IconField', 'InputGroup', 'InputMask',
+  'InputNumber', 'InputOtp', 'InputSwitch', 'InputText', 'InputTextarea',
+  'Knob', 'Listbox', 'MultiSelect', 'Password', 'RadioButton', 'Rating',
+  'SelectButton', 'Slider', 'TreeSelect', 'TriStateCheckbox', 'ToggleButton',
+  'Button', 'SpeedDial', 'SplitButton',
+  'DataTable', 'DataView', 'OrderList', 'OrganizationChart', 'Paginator',
+  'PickList', 'Timeline', 'Tree', 'TreeTable', 'VirtualScroller',
+  'Accordion', 'AccordionTab', 'Card', 'DeferredContent', 'Divider',
+  'Fieldset', 'Panel', 'ScrollPanel', 'Splitter', 'SplitterPanel',
+  'Stepper', 'StepperPanel', 'TabView', 'TabPanel', 'Toolbar',
+  'ConfirmDialog', 'ConfirmPopup', 'Dialog', 'DynamicDialog', 'OverlayPanel',
+  'Sidebar', 'Tooltip', 'FileUpload',
+  'Breadcrumb', 'ContextMenu', 'Dock', 'Menu', 'Menubar', 'MegaMenu',
+  'PanelMenu', 'Steps', 'TabMenu', 'TieredMenu', 'Chart',
+  'Message', 'Messages', 'Toast',
+  'Carousel', 'Galleria', 'Image',
+  'Avatar', 'AvatarGroup', 'Badge', 'BlockUI', 'Chip', 'Inplace',
+  'MeterGroup', 'ProgressBar', 'ProgressSpinner', 'ScrollTop', 'Skeleton',
+  'Tag', 'Terminal'
+];
+
+const UTILITY_PATTERNS = [
+  /^bg-[a-z]+-\d+$/, /^text-[a-z]+-\d+$/, /^border-[a-z]+-\d+$/,
+  /^rounded(-[a-z]+)?(-\d+)?$/, /^shadow(-\d+)?$/,
+  /^p-\d+$/, /^m-\d+$/, /^gap-\d+$/
+];
+
+const TAILWIND_PATTERNS = [
+  /\w+-\[.+\]/, // Arbitrary values
+  /^(hover|focus|dark|sm|md|lg|xl):/, // Modifiers
+  /^space-(x|y)-\d+$/, /^ring(-\d+)?$/, /^backdrop-/
+];
+
+const HEX_COLOR = /^#[0-9a-fA-F]{3,8}$/;
+const RGB_COLOR = /rgba?\(/;
+const HSL_COLOR = /hsla?\(/;
+
+/**
+ * Validation rules
+ */
+const RULES = {
+  'no-utility-on-components': {
+    name: 'No PrimeFlex on PrimeReact Components',
+    severity: 'error',
+    check: (content, filePath) => {
+      const violations = [];
+      const lines = content.split('\n');
+
+      lines.forEach((line, index) => {
+        // Find JSX tags with className
+        PRIMEREACT_COMPONENTS.forEach(component => {
+          const regex = new RegExp(`<${component}[^>]*className=["'\`]([^"'\`]+)["'\`]`, 'g');
+          let match;
+
+          while ((match = regex.exec(line)) !== null) {
+            const classes = match[1].split(/\s+/);
+            const utilityClasses = classes.filter(c =>
+              UTILITY_PATTERNS.some(p => p.test(c))
+            );
+
+            if (utilityClasses.length > 0) {
+              violations.push({
+                line: index + 1,
+                column: match.index,
+                message: `PrimeFlex utility classes "${utilityClasses.join(', ')}" on <${component}>`,
+                suggestion: `Remove utility classes. The theme handles component styling.`
+              });
+            }
+          }
+        });
+      });
+
+      return violations;
+    }
+  },
+
+  'no-tailwind': {
+    name: 'No Tailwind CSS Classes',
+    severity: 'error',
+    check: (content, filePath) => {
+      const violations = [];
+      const lines = content.split('\n');
+
+      lines.forEach((line, index) => {
+        // Find className attributes
+        const regex = /className=["'`]([^"'`]+)["'`]/g;
+        let match;
+
+        while ((match = regex.exec(line)) !== null) {
+          const classes = match[1].split(/\s+/);
+          const tailwindClasses = classes.filter(c =>
+            TAILWIND_PATTERNS.some(p => p.test(c))
+          );
+
+          if (tailwindClasses.length > 0) {
+            violations.push({
+              line: index + 1,
+              column: match.index,
+              message: `Tailwind classes "${tailwindClasses.join(', ')}" detected`,
+              suggestion: `Use PrimeFlex for layout or semantic tokens for design.`
+            });
+          }
+        }
+      });
+
+      return violations;
+    }
+  },
+
+  'no-hardcoded-colors': {
+    name: 'No Hardcoded Colors',
+    severity: 'error',
+    check: (content, filePath) => {
+      const violations = [];
+      const lines = content.split('\n');
+
+      lines.forEach((line, index) => {
+        // Check for hex colors
+        const hexMatches = line.match(HEX_COLOR);
+        if (hexMatches) {
+          violations.push({
+            line: index + 1,
+            column: line.indexOf(hexMatches[0]),
+            message: `Hardcoded hex color "${hexMatches[0]}"`,
+            suggestion: `Use semantic token: var(--surface-neutral-primary) or var(--text-neutral-default)`
+          });
+        }
+
+        // Check for rgb/rgba
+        if (RGB_COLOR.test(line)) {
+          violations.push({
+            line: index + 1,
+            column: line.search(RGB_COLOR),
+            message: `Hardcoded RGB color detected`,
+            suggestion: `Use semantic token: var(--surface-neutral-primary)`
+          });
+        }
+
+        // Check for hsl/hsla
+        if (HSL_COLOR.test(line)) {
+          violations.push({
+            line: index + 1,
+            column: line.search(HSL_COLOR),
+            message: `Hardcoded HSL color detected`,
+            suggestion: `Use semantic token: var(--surface-neutral-primary)`
+          });
+        }
+      });
+
+      return violations;
+    }
+  },
+
+  'semantic-tokens-only': {
+    name: 'Semantic Tokens Only',
+    severity: 'warning',
+    check: (content, filePath) => {
+      const violations = [];
+      const lines = content.split('\n');
+
+      lines.forEach((line, index) => {
+        // Check for foundation tokens
+        const foundationTokens = line.match(/var\(--(blue|green|red|yellow|gray|purple|pink|indigo|teal|orange|cyan|bluegray)-\d+\)/g);
+        if (foundationTokens) {
+          foundationTokens.forEach(token => {
+            violations.push({
+              line: index + 1,
+              column: line.indexOf(token),
+              message: `Foundation token "${token}" in app code`,
+              suggestion: `Use semantic token: var(--surface-brand-primary) or var(--text-neutral-default)`
+            });
+          });
+        }
+      });
+
+      return violations;
+    }
+  },
+
+  'valid-spacing': {
+    name: 'Valid 4px Grid Spacing',
+    severity: 'warning',
+    check: (content, filePath) => {
+      const violations = [];
+      const lines = content.split('\n');
+
+      const validPx = [0, 4, 8, 12, 16, 20, 24, 28, 32];
+      const spacingProps = ['padding', 'margin', 'gap'];
+
+      lines.forEach((line, index) => {
+        spacingProps.forEach(prop => {
+          // Check for px values
+          const regex = new RegExp(`${prop}[^:]*:\\s*['"]?(\\d+)px`, 'g');
+          let match;
+
+          while ((match = regex.exec(line)) !== null) {
+            const value = parseInt(match[1], 10);
+            if (!validPx.includes(value) && value !== 1) {
+              const nearest = validPx.reduce((prev, curr) =>
+                Math.abs(curr - value) < Math.abs(prev - value) ? curr : prev
+              );
+              violations.push({
+                line: index + 1,
+                column: match.index,
+                message: `Off-grid spacing: ${value}px`,
+                suggestion: `Use nearest 4px grid value: ${nearest}px (${nearest / 16}rem)`
+              });
+            }
+          }
+        });
+
+        // Check for invalid PrimeFlex classes (p-9, p-10, etc.)
+        const invalidClasses = line.match(/[pm][trblxy]?-([9-9]\d+)/g);
+        if (invalidClasses) {
+          violations.push({
+            line: index + 1,
+            column: line.indexOf(invalidClasses[0]),
+            message: `Invalid PrimeFlex spacing: ${invalidClasses.join(', ')}`,
+            suggestion: `Use p-0 through p-8 (0-32px in 4px increments)`
+          });
+        }
+      });
+
+      return violations;
+    }
+  }
+};
+
+/**
+ * Find all relevant files in directory
+ */
+function findFiles(dir, extensions = ['.tsx', '.jsx', '.ts', '.js']) {
+  const files = [];
+
+  function walk(currentDir) {
+    try {
+      const entries = readdirSync(currentDir);
+
+      entries.forEach(entry => {
+        const fullPath = join(currentDir, entry);
+
+        // Skip node_modules, .git, dist, build
+        if (['node_modules', '.git', 'dist', 'build', '.next'].includes(entry)) {
+          return;
+        }
+
+        try {
+          const stat = statSync(fullPath);
+
+          if (stat.isDirectory()) {
+            walk(fullPath);
+          } else if (extensions.includes(extname(fullPath))) {
+            files.push(fullPath);
+          }
+        } catch (err) {
+          // Skip files we can't access
+        }
+      });
+    } catch (err) {
+      // Skip directories we can't access
+    }
+  }
+
+  walk(dir);
+  return files;
+}
+
+/**
+ * Run validation on a file
+ */
+function validateFile(filePath, rules) {
+  try {
+    const content = readFileSync(filePath, 'utf8');
+    const results = {};
+
+    Object.entries(rules).forEach(([ruleId, rule]) => {
+      const violations = rule.check(content, filePath);
+      if (violations.length > 0) {
+        results[ruleId] = {
+          rule: rule.name,
+          severity: rule.severity,
+          violations
+        };
+      }
+    });
+
+    return results;
+  } catch (err) {
+    return { error: err.message };
+  }
+}
+
+/**
+ * Format validation results
+ */
+function formatResults(results, format = 'cli') {
+  if (format === 'json') {
+    return JSON.stringify(results, null, 2);
+  }
+
+  // CLI format
+  let output = '\n';
+  let totalViolations = 0;
+  let errorCount = 0;
+  let warningCount = 0;
+
+  Object.entries(results).forEach(([filePath, fileResults]) => {
+    if (fileResults.error) {
+      output += `❌ Error reading ${filePath}: ${fileResults.error}\n`;
+      return;
+    }
+
+    const violations = Object.values(fileResults);
+    if (violations.length === 0) return;
+
+    output += `\n📄 ${filePath}\n`;
+
+    Object.entries(fileResults).forEach(([ruleId, result]) => {
+      result.violations.forEach(violation => {
+        totalViolations++;
+        const icon = result.severity === 'error' ? '❌' : '⚠️';
+        if (result.severity === 'error') errorCount++;
+        else warningCount++;
+
+        output += `  ${icon} ${result.rule}\n`;
+        output += `     Line ${violation.line}, Col ${violation.column}\n`;
+        output += `     ${violation.message}\n`;
+        output += `     💡 ${violation.suggestion}\n\n`;
+      });
+    });
+  });
+
+  if (totalViolations === 0) {
+    output += '✅ No violations found!\n\n';
+  } else {
+    output += `\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`;
+    output += `📊 Summary: ${totalViolations} violations found\n`;
+    output += `   ${errorCount} errors, ${warningCount} warnings\n\n`;
+  }
+
+  return output;
+}
+
+/**
+ * Main validate command
+ */
+export async function validateCommand(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const format = options.format || 'cli';
+  const rulesFilter = options.rules ? options.rules.split(',') : Object.keys(RULES);
+
+  console.log(`
+🌳 Yggdrasil Design System Validation
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📂 Scanning directory: ${cwd}
+🔍 Active rules: ${rulesFilter.length}
+`);
+
+  // Filter rules
+  const activeRules = {};
+  rulesFilter.forEach(ruleId => {
+    if (RULES[ruleId]) {
+      activeRules[ruleId] = RULES[ruleId];
+    }
+  });
+
+  // Find files
+  const files = findFiles(cwd);
+  console.log(`📝 Found ${files.length} files to check\n`);
+
+  // Validate files
+  const results = {};
+  files.forEach(file => {
+    const fileResults = validateFile(file, activeRules);
+    if (Object.keys(fileResults).length > 0) {
+      results[file] = fileResults;
+    }
+  });
+
+  // Output results
+  const output = formatResults(results, format);
+  console.log(output);
+
+  // Return results for programmatic use
+  return results;
+}