aiknowsys 0.4.1 → 0.5.0

package/lib/commands/audit.js

@@ -8,10 +8,13 @@ import chalk from 'chalk';
  */
 export async function audit(options) {
   const targetDir = path.resolve(options.dir);
+  const silent = options._silent || false;
   
-  console.log('');
-  console.log(chalk.cyan.bold('🔎 Knowledge System Audit'));
-  console.log('');
+  if (!silent) {
+    console.log('');
+    console.log(chalk.cyan.bold('🔎 Knowledge System Audit'));
+    console.log('');
+  }
   
   const issues = [];
   let warnings = 0;
@@ -21,8 +24,18 @@ export async function audit(options) {
   const agentsPath = path.join(targetDir, 'AGENTS.md');
   const changelogPath = path.join(targetDir, 'CODEBASE_CHANGELOG.md');
   
+  // Check if knowledge system exists
+  if (!fs.existsSync(essentialsPath) && !fs.existsSync(agentsPath)) {
+    if (!silent) {
+      console.log(chalk.yellow('❌ No knowledge system found in this directory'));
+      console.log(chalk.gray('   Run: npx aiknowsys init'));
+      console.log('');
+    }
+    throw new Error('No knowledge system found');
+  }
+  
   // Audit 1: Check for duplicated validation matrix
-  console.log(chalk.white('🔍 Checking for duplication issues...'));
+  if (!silent) console.log(chalk.white('🔍 Checking for duplication issues...'));
   
   if (fs.existsSync(essentialsPath) && fs.existsSync(agentsPath)) {
     const essentialsContent = fs.readFileSync(essentialsPath, 'utf-8');
@@ -34,7 +47,7 @@ export async function audit(options) {
     const hasAgentsMatrix = matrixTablePattern.test(agentsContent);
     
     if (hasEssentialsMatrix && hasAgentsMatrix) {
-      console.log(chalk.yellow('  ⚠️  Validation matrix duplicated in both files'));
+      if (!silent) console.log(chalk.yellow('  ⚠️  Validation matrix duplicated in both files'));
       issues.push({
         type: 'warning',
         category: 'DRY Violation',
@@ -43,14 +56,14 @@ export async function audit(options) {
       });
       warnings++;
     } else if (hasEssentialsMatrix) {
-      console.log(chalk.green('  ✓ Validation matrix in ESSENTIALS only (correct)'));
+      if (!silent) console.log(chalk.green('  ✓ Validation matrix in ESSENTIALS only (correct)'));
     }
   }
   
-  console.log('');
+  if (!silent) console.log('');
   
   // Audit 2: Check for generic placeholder values
-  console.log(chalk.white('📝 Checking for placeholder quality...'));
+  if (!silent) console.log(chalk.white('📝 Checking for placeholder quality...'));
   
   if (fs.existsSync(essentialsPath)) {
     const content = fs.readFileSync(essentialsPath, 'utf-8');
@@ -67,7 +80,7 @@ export async function audit(options) {
       const matches = content.match(check.pattern);
       if (matches && matches.length > 3) { // Allow a few TBDs
         if (check.severity === 'warning') {
-          console.log(chalk.yellow(`  ⚠️  ${matches.length} instances of ${check.name}`));
+          if (!silent) console.log(chalk.yellow(`  ⚠️  ${matches.length} instances of ${check.name}`));
           issues.push({
             type: 'warning',
             category: 'Incomplete Setup',
@@ -76,7 +89,13 @@ export async function audit(options) {
           });
           warnings++;
         } else {
-          console.log(chalk.cyan(`  ℹ️  ${matches.length} instances of ${check.name}`));
+          if (!silent) console.log(chalk.cyan(`  ℹ️  ${matches.length} instances of ${check.name}`));
+          issues.push({
+            type: 'info',
+            category: 'Incomplete Setup',
+            message: `${matches.length} ${check.name} found`,
+            fix: 'Complete TODO sections with actual project details'
+          });
           info++;
         }
       }
@@ -86,7 +105,7 @@ export async function audit(options) {
     const placeholderMatches = [...content.matchAll(/{{([A-Z_]+)}}/g)];
     if (placeholderMatches.length > 0) {
       const unique = [...new Set(placeholderMatches.map(m => m[1]))];
-      console.log(chalk.yellow(`  ⚠️  ${unique.length} unfilled placeholders`));
+      if (!silent) console.log(chalk.yellow(`  ⚠️  ${unique.length} unfilled placeholders`));
       issues.push({
         type: 'warning',
         category: 'Incomplete Setup',
@@ -95,27 +114,37 @@ export async function audit(options) {
       });
       warnings++;
     } else {
-      console.log(chalk.green('  ✓ All placeholders filled'));
+      if (!silent) console.log(chalk.green('  ✓ All placeholders filled'));
     }
   }
   
-  console.log('');
+  if (!silent) console.log('');
   
   // Audit 3: Check validation matrix quality
-  console.log(chalk.white('✅ Checking validation matrix quality...'));
+  if (!silent) console.log(chalk.white('✅ Checking validation matrix quality...'));
   
   if (fs.existsSync(essentialsPath)) {
     const content = fs.readFileSync(essentialsPath, 'utf-8');
     const matrixSection = content.split(/## \d*\.?\s*Validation Matrix/i)[1]?.split(/##/)[0] || '';
     
-    if (matrixSection.length > 0) {
+    if (matrixSection.length === 0) {
+      // Validation Matrix section is missing
+      if (!silent) console.log(chalk.yellow('  ⚠️  Validation Matrix section missing'));
+      issues.push({
+        type: 'warning',
+        category: 'Missing Section',
+        message: 'Validation Matrix section missing from ESSENTIALS',
+        fix: 'Add Validation Matrix section with test commands'
+      });
+      warnings++;
+    } else if (matrixSection.length > 0) {
       // Check for specific commands
       const hasTestCmd = /test|pytest|jest|vitest/i.test(matrixSection);
       const hasLintCmd = /lint|eslint|flake8|ruff/i.test(matrixSection);
       const hasTypeCmd = /type-check|mypy|tsc/i.test(matrixSection);
       
       if (!hasTestCmd) {
-        console.log(chalk.yellow('  ⚠️  No test command in validation matrix'));
+        if (!silent) console.log(chalk.yellow('  ⚠️  No test command in validation matrix'));
         issues.push({
           type: 'warning',
           category: 'Missing Validation',
@@ -124,22 +153,22 @@ export async function audit(options) {
         });
         warnings++;
       } else {
-        console.log(chalk.green('  ✓ Test command configured'));
+        if (!silent) console.log(chalk.green('  ✓ Test command configured'));
       }
       
       if (!hasLintCmd) {
-        console.log(chalk.cyan('  ℹ️  No linter configured (optional)'));
+        if (!silent) console.log(chalk.cyan('  ℹ️  No linter configured (optional)'));
         info++;
       } else {
-        console.log(chalk.green('  ✓ Linter configured'));
+        if (!silent) console.log(chalk.green('  ✓ Linter configured'));
       }
     }
   }
   
-  console.log('');
+  if (!silent) console.log('');
   
   // Audit 4: Check changelog usage
-  console.log(chalk.white('📚 Checking changelog...'));
+  if (!silent) console.log(chalk.white('📚 Checking changelog...'));
   
   if (fs.existsSync(changelogPath)) {
     const content = fs.readFileSync(changelogPath, 'utf-8');
@@ -156,70 +185,78 @@ export async function audit(options) {
     }
   }
   
-  console.log('');
+  if (!silent) console.log('');
   
   // Audit 5: Check file sizes (detect bloat)
-  console.log(chalk.white('📏 Checking file sizes...'));
+  if (!silent) console.log(chalk.white('📏 Checking file sizes...'));
   
   if (fs.existsSync(essentialsPath)) {
-    const stats = fs.statSync(essentialsPath);
-    const sizeKB = (stats.size / 1024).toFixed(1);
+    const content = fs.readFileSync(essentialsPath, 'utf-8');
+    const lineCount = content.split('\n').length;
     
-    if (stats.size > 100000) { // > 100KB
-      console.log(chalk.yellow(`  ⚠️  CODEBASE_ESSENTIALS.md is large (${sizeKB}KB)`));
+    if (lineCount > 300) {
+      if (!silent) console.log(chalk.yellow(`  ⚠️  CODEBASE_ESSENTIALS.md is large (${lineCount} lines)`));
       issues.push({
         type: 'warning',
         category: 'File Size',
-        message: `ESSENTIALS.md is ${sizeKB}KB (consider splitting)`,
+        message: `ESSENTIALS.md is ${lineCount} lines (consider splitting)`,
         fix: 'Consider using minimal template or archiving old patterns'
       });
       warnings++;
     } else {
-      console.log(chalk.green(`  ✓ CODEBASE_ESSENTIALS.md size OK (${sizeKB}KB)`));
+      if (!silent) console.log(chalk.green(`  ✓ CODEBASE_ESSENTIALS.md size OK (${lineCount} lines)`));
     }
   }
   
-  console.log('');
+  if (!silent) console.log('');
   
   // Summary
-  console.log(chalk.cyan.bold('📊 Audit Summary:'));
+  if (!silent) console.log(chalk.cyan.bold('📊 Audit Summary:'));
   
   if (issues.length === 0 && info === 0) {
-    console.log(chalk.green('  ✓ No issues found'));
+    if (!silent) console.log(chalk.green('  ✓ No issues found'));
   } else {
     if (warnings > 0) {
-      console.log(chalk.yellow(`  ⚠️  Warnings: ${warnings}`));
+      if (!silent) console.log(chalk.yellow(`  ⚠️  Warnings: ${warnings}`));
     }
     if (info > 0) {
-      console.log(chalk.cyan(`  ℹ️  Info: ${info}`));
+      if (!silent) console.log(chalk.cyan(`  ℹ️  Info: ${info}`));
     }
   }
   
-  console.log('');
+  if (!silent) console.log('');
   
   // Detailed issues
   if (issues.length > 0) {
-    console.log(chalk.cyan.bold('🔧 Issues Found:'));
-    console.log('');
+    if (!silent) console.log(chalk.cyan.bold('🔧 Issues Found:'));
+    if (!silent) console.log('');
     
     issues.forEach((issue, idx) => {
       const icon = issue.type === 'warning' ? '⚠️ ' : 'ℹ️ ';
-      console.log(chalk.white(`${idx + 1}. ${icon}${chalk.bold(issue.category)}`));
-      console.log(chalk.gray(`   ${issue.message}`));
-      console.log(chalk.cyan(`   Fix: ${issue.fix}`));
-      console.log('');
+      if (!silent) console.log(chalk.white(`${idx + 1}. ${icon}${chalk.bold(issue.category)}`));
+      if (!silent) console.log(chalk.gray(`   ${issue.message}`));
+      if (!silent) console.log(chalk.cyan(`   Fix: ${issue.fix}`));
+      if (!silent) console.log('');
     });
   }
   
   // Recommendations
   if (warnings > 0) {
-    console.log(chalk.cyan('💡 Next Steps:'));
-    console.log(chalk.white('  1. Run: npx aiknowsys sync (fix duplication)'));
-    console.log(chalk.white('  2. Complete placeholder sections'));
-    console.log(chalk.white('  3. Run: npx aiknowsys check (verify fixes)'));
-    console.log('');
+    if (!silent) console.log(chalk.cyan('💡 Next Steps:'));
+    if (!silent) console.log(chalk.white('  1. Run: npx aiknowsys sync (fix duplication)'));
+    if (!silent) console.log(chalk.white('  2. Complete placeholder sections'));
+    if (!silent) console.log(chalk.white('  3. Run: npx aiknowsys check (verify fixes)'));
+    if (!silent) console.log('');
   } else {
-    console.log(chalk.green('✅ Knowledge system is in good shape!'));
-    console.log('');
+    if (!silent) console.log(chalk.green('✅ Knowledge system is in good shape!'));
+    if (!silent) console.log('');
   }
+  
+  // Return audit results for programmatic use
+  return {
+    issues,
+    warnings,
+    info,
+    clean: warnings === 0 && issues.length === 0
+  };
 }

package/lib/commands/check.js

@@ -207,7 +207,7 @@ export async function check(options) {
   // Exit with appropriate code
   if (failed > 0) {
     console.log(chalk.red('❌ Health check failed'));
-    process.exit(1);
+    throw new Error(`Health check failed: ${failed} check(s) failed`);
   } else if (warnings > 0) {
     console.log(chalk.yellow('⚠️  Health check passed with warnings'));
   } else {

package/lib/commands/init.js

@@ -16,6 +16,26 @@ const AVAILABLE_STACKS = {
     name: 'vue-express',
     display: 'Vue 3 + Express (Full-stack monorepo with shared types)',
     description: 'Frontend + Backend + Shared packages'
+  },
+  'vue-vite': {
+    name: 'vue-vite',
+    display: 'Vue 3 + Vite (TypeScript + Vue Router + Pinia)',
+    description: 'Frontend SPA with modern tooling'
+  },
+  'express-api': {
+    name: 'express-api',
+    display: 'Express.js API (TypeScript + Prisma + PostgreSQL)',
+    description: 'Backend REST API with Node.js'
+  },
+  fastapi: {
+    name: 'fastapi',
+    display: 'FastAPI (Python + SQLAlchemy + PostgreSQL)',
+    description: 'Modern Python API framework with async support'
+  },
+  'nextjs-api': {
+    name: 'nextjs-api',
+    display: 'Next.js API (App Router + API routes + Server Actions)',
+    description: 'Next.js as a backend API framework'
   }
 };
 
@@ -588,7 +608,7 @@ export async function init(options) {
       console.log('');
       console.log(chalk.gray('   Use --list-stacks for detailed descriptions'));
       console.log('');
-      process.exit(1);
+      throw new Error(`Invalid stack: ${options.stack}`);
     }
 
     // Check if project already exists
@@ -597,7 +617,7 @@ export async function init(options) {
       console.log(chalk.yellow('⚠️  Knowledge system files already exist in this directory.'));
       console.log(chalk.gray('   Run "aiknowsys migrate" to update existing files.'));
       console.log('');
-      process.exit(1);
+      throw new Error('Project already exists');
     }
 
     const stackInfo = AVAILABLE_STACKS[options.stack];
@@ -676,7 +696,7 @@ export async function init(options) {
     } catch (error) {
       spinner.fail('Failed to copy stack template');
       console.error(chalk.red(`\n❌ Error: ${error.message}\n`));
-      process.exit(1);
+      throw error;
     }
   }
 
@@ -1035,7 +1055,7 @@ export async function init(options) {
   } catch (error) {
     spinner.fail('Failed to initialize');
     console.error(chalk.red(error.message));
-    process.exit(1);
+    throw error;
   }
 }
 

package/lib/commands/install-agents.js

@@ -9,6 +9,7 @@ export async function installAgents(options) {
   const targetDir = path.resolve(options.dir);
   const essentialsFile = options.essentials || 'CODEBASE_ESSENTIALS.md';
   const silent = options._silent || false;
+  const skipPrompts = options.yes || false;
   
   if (!silent) {
     console.log('');
@@ -54,7 +55,7 @@ export async function installAgents(options) {
     if (spinner) spinner.succeed('Agent templates installed');
     
     // Ask for project-specific guidelines (only in interactive mode)
-    if (!silent) {
+    if (!silent && !skipPrompts) {
       const { addGuidelines } = await inquirer.prompt([{
         type: 'confirm',
         name: 'addGuidelines',
@@ -97,7 +98,6 @@ export async function installAgents(options) {
   } catch (error) {
     if (spinner) spinner.fail('Failed to install agents');
     console.error(chalk.red(error.message));
-    if (!silent) process.exit(1);
     throw error;
   }
 }

package/lib/commands/install-skills.js

@@ -87,7 +87,6 @@ export async function installSkills(options) {
   } catch (error) {
     if (spinner) spinner.fail('Failed to install skills');
     console.error(chalk.red(error.message));
-    if (!silent) process.exit(1);
     throw error;
   }
 }

package/lib/commands/scan.js

@@ -286,7 +286,7 @@ export async function scan(options) {
   } catch (error) {
     spinner.fail('Scan failed');
     console.error(chalk.red(error.message));
-    process.exit(1);
+    throw error;
   }
 }
 

package/lib/commands/sync.js

@@ -9,28 +9,35 @@ import ora from 'ora';
  */
 export async function sync(options) {
   const targetDir = path.resolve(options.dir);
+  const silent = options._silent || false;
   
-  console.log('');
-  console.log(chalk.cyan.bold('🔄 Sync Validation Matrix Reference'));
-  console.log('');
+  if (!silent) {
+    console.log('');
+    console.log(chalk.cyan.bold('🔄 Sync Validation Matrix Reference'));
+    console.log('');
+  }
   
   const essentialsPath = path.join(targetDir, 'CODEBASE_ESSENTIALS.md');
   const agentsPath = path.join(targetDir, 'AGENTS.md');
   
   // Check files exist
   if (!fs.existsSync(essentialsPath)) {
-    console.log(chalk.red('❌ CODEBASE_ESSENTIALS.md not found'));
-    console.log(chalk.gray('   Run: npx aiknowsys init'));
-    process.exit(1);
+    if (!silent) {
+      console.log(chalk.red('❌ CODEBASE_ESSENTIALS.md not found'));
+      console.log(chalk.gray('   Run: npx aiknowsys init'));
+    }
+    throw new Error('CODEBASE_ESSENTIALS.md not found');
   }
   
   if (!fs.existsSync(agentsPath)) {
-    console.log(chalk.red('❌ AGENTS.md not found'));
-    console.log(chalk.gray('   Run: npx aiknowsys init'));
-    process.exit(1);
+    if (!silent) {
+      console.log(chalk.red('❌ AGENTS.md not found'));
+      console.log(chalk.gray('   Run: npx aiknowsys init'));
+    }
+    throw new Error('AGENTS.md not found');
   }
   
-  const spinner = ora('Checking validation matrix...').start();
+  const spinner = silent ? null : ora('Checking validation matrix...').start();
   
   // Read ESSENTIALS to verify validation matrix exists
   const essentialsContent = fs.readFileSync(essentialsPath, 'utf-8');
@@ -38,13 +45,15 @@ export async function sync(options) {
                                essentialsContent.includes('## Validation Matrix');
   
   if (!hasValidationMatrix) {
-    spinner.fail('Validation matrix not found in CODEBASE_ESSENTIALS.md');
-    console.log('');
-    console.log(chalk.yellow('💡 Add a Validation Matrix section to CODEBASE_ESSENTIALS.md'));
-    process.exit(1);
+    if (spinner) spinner.fail('Validation matrix not found in CODEBASE_ESSENTIALS.md');
+    if (!silent) {
+      console.log('');
+      console.log(chalk.yellow('💡 Add a Validation Matrix section to CODEBASE_ESSENTIALS.md'));
+    }
+    throw new Error('Validation matrix not found in CODEBASE_ESSENTIALS.md');
   }
   
-  spinner.text = 'Reading AGENTS.md...';
+  if (spinner) spinner.text = 'Reading AGENTS.md...';
   
   // Read AGENTS.md
   let agentsContent = fs.readFileSync(agentsPath, 'utf-8');
@@ -54,14 +63,16 @@ export async function sync(options) {
                        agentsContent.includes('CODEBASE_ESSENTIALS.md#validation-matrix');
   
   if (hasReference) {
-    spinner.succeed('Validation matrix reference already up to date');
-    console.log('');
-    console.log(chalk.green('✅ AGENTS.md correctly references CODEBASE_ESSENTIALS.md'));
-    console.log('');
+    if (spinner) spinner.succeed('Validation matrix reference already up to date');
+    if (!silent) {
+      console.log('');
+      console.log(chalk.green('✅ AGENTS.md correctly references CODEBASE_ESSENTIALS.md'));
+      console.log('');
+    }
     return;
   }
   
-  spinner.text = 'Updating AGENTS.md...';
+  if (spinner) spinner.text = 'Updating AGENTS.md...';
   
   // Find the validation matrix section in AGENTS.md
   // Look for the pattern that might have a duplicated matrix
@@ -69,17 +80,19 @@ export async function sync(options) {
   const match = agentsContent.match(validationSectionRegex);
   
   if (!match) {
-    spinner.warn('Could not find validation matrix section in AGENTS.md');
-    console.log('');
-    console.log(chalk.yellow('⚠️  Manual update required'));
-    console.log(chalk.white('Add this to your AGENTS.md validation section:'));
-    console.log('');
-    console.log(chalk.gray('**Validation Matrix:**'));
-    console.log(chalk.gray(''));
-    console.log(chalk.gray('👉 **See [CODEBASE_ESSENTIALS.md - Validation Matrix](CODEBASE_ESSENTIALS.md#validation-matrix)**'));
-    console.log(chalk.gray(''));
-    console.log(chalk.gray('The validation matrix lives in CODEBASE_ESSENTIALS.md as the single source of truth.'));
-    console.log('');
+    if (spinner) spinner.warn('Could not find validation matrix section in AGENTS.md');
+    if (!silent) {
+      console.log('');
+      console.log(chalk.yellow('⚠️  Manual update required'));
+      console.log(chalk.white('Add this to your AGENTS.md validation section:'));
+      console.log('');
+      console.log(chalk.gray('**Validation Matrix:**'));
+      console.log(chalk.gray(''));
+      console.log(chalk.gray('👉 **See [CODEBASE_ESSENTIALS.md - Validation Matrix](CODEBASE_ESSENTIALS.md#validation-matrix)**'));
+      console.log(chalk.gray(''));
+      console.log(chalk.gray('The validation matrix lives in CODEBASE_ESSENTIALS.md as the single source of truth.'));
+      console.log('');
+    }
     return;
   }
   
@@ -96,12 +109,14 @@ The validation matrix lives in CODEBASE_ESSENTIALS.md as the single source of tr
   // Write updated AGENTS.md
   fs.writeFileSync(agentsPath, agentsContent);
   
-  spinner.succeed('AGENTS.md updated');
-  console.log('');
-  console.log(chalk.green('✅ Validation matrix reference synced'));
-  console.log('');
-  console.log(chalk.cyan('💡 What changed:'));
-  console.log(chalk.white('  • AGENTS.md now references CODEBASE_ESSENTIALS.md'));
-  console.log(chalk.white('  • Update validation matrix in ESSENTIALS.md only (single source of truth)'));
-  console.log('');
+  if (spinner) spinner.succeed('AGENTS.md updated');
+  if (!silent) {
+    console.log('');
+    console.log(chalk.green('✅ Validation matrix reference synced'));
+    console.log('');
+    console.log(chalk.cyan('💡 What changed:'));
+    console.log(chalk.white('  • AGENTS.md now references CODEBASE_ESSENTIALS.md'));
+    console.log(chalk.white('  • Update validation matrix in ESSENTIALS.md only (single source of truth)'));
+    console.log('');
+  }
 }