codingbuddy-rules 4.5.0 → 5.1.0

package/bin/cli.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const RULES_DIR = path.resolve(__dirname, '..', '.ai-rules');
+
+function showHelp() {
+  console.log(
+    `
+codingbuddy - AI coding rules CLI
+
+Usage:
+  codingbuddy <command> [options]
+
+Commands:
+  init          Initialize .ai-rules in the current project
+  validate      Validate .ai-rules structure (agents JSON, rules markdown)
+  list-agents   List available specialist agents
+
+Options:
+  --help, -h    Show this help message
+  --version, -v Show version
+`.trim(),
+  );
+}
+
+function showVersion() {
+  const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf8'));
+  console.log(pkg.version);
+}
+
+function listAgents() {
+  const agentsDir = path.join(RULES_DIR, 'agents');
+  if (!fs.existsSync(agentsDir)) {
+    console.error('Error: agents directory not found at', agentsDir);
+    process.exit(1);
+  }
+
+  const files = fs
+    .readdirSync(agentsDir)
+    .filter(f => f.endsWith('.json'))
+    .sort();
+
+  console.log(`Available agents (${files.length}):\n`);
+  for (const file of files) {
+    try {
+      const agent = JSON.parse(fs.readFileSync(path.join(agentsDir, file), 'utf8'));
+      const name = agent.name || path.basename(file, '.json');
+      const desc = agent.description || '';
+      console.log(`  ${name.padEnd(30)} ${desc}`);
+    } catch {
+      console.log(`  ${path.basename(file, '.json').padEnd(30)} (parse error)`);
+    }
+  }
+}
+
+function validate() {
+  let errors = 0;
+
+  // Check .ai-rules directory exists
+  if (!fs.existsSync(RULES_DIR)) {
+    console.error('Error: .ai-rules directory not found at', RULES_DIR);
+    process.exit(1);
+  }
+
+  // Validate agents JSON
+  const agentsDir = path.join(RULES_DIR, 'agents');
+  if (fs.existsSync(agentsDir)) {
+    const jsonFiles = fs.readdirSync(agentsDir).filter(f => f.endsWith('.json'));
+    for (const file of jsonFiles) {
+      try {
+        JSON.parse(fs.readFileSync(path.join(agentsDir, file), 'utf8'));
+      } catch (e) {
+        console.error(`FAIL  agents/${file}: invalid JSON - ${e.message}`);
+        errors++;
+      }
+    }
+    console.log(`OK    agents/ - ${jsonFiles.length} JSON files valid`);
+  }
+
+  // Validate rules markdown files exist
+  const rulesDir = path.join(RULES_DIR, 'rules');
+  if (fs.existsSync(rulesDir)) {
+    const mdFiles = fs.readdirSync(rulesDir).filter(f => f.endsWith('.md'));
+    if (mdFiles.length === 0) {
+      console.error('FAIL  rules/ - no markdown files found');
+      errors++;
+    } else {
+      console.log(`OK    rules/ - ${mdFiles.length} markdown files found`);
+    }
+  } else {
+    console.error('FAIL  rules/ directory missing');
+    errors++;
+  }
+
+  // Validate schemas directory
+  const schemasDir = path.join(RULES_DIR, 'schemas');
+  if (fs.existsSync(schemasDir)) {
+    const schemaFiles = fs.readdirSync(schemasDir).filter(f => f.endsWith('.json'));
+    for (const file of schemaFiles) {
+      try {
+        JSON.parse(fs.readFileSync(path.join(schemasDir, file), 'utf8'));
+      } catch (e) {
+        console.error(`FAIL  schemas/${file}: invalid JSON - ${e.message}`);
+        errors++;
+      }
+    }
+    console.log(`OK    schemas/ - ${schemaFiles.length} JSON files valid`);
+  }
+
+  // Validate keyword-modes.json
+  const keywordModes = path.join(RULES_DIR, 'keyword-modes.json');
+  if (fs.existsSync(keywordModes)) {
+    try {
+      JSON.parse(fs.readFileSync(keywordModes, 'utf8'));
+      console.log('OK    keyword-modes.json valid');
+    } catch (e) {
+      console.error(`FAIL  keyword-modes.json: invalid JSON - ${e.message}`);
+      errors++;
+    }
+  }
+
+  if (errors > 0) {
+    console.error(`\nValidation failed with ${errors} error(s)`);
+    process.exit(1);
+  }
+  console.log('\nAll validations passed');
+}
+
+function init() {
+  const { run } = require('../lib/init');
+  run().catch(err => {
+    console.error('Error:', err.message);
+    process.exit(1);
+  });
+}
+
+// --- Main ---
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (!command || command === '--help' || command === '-h') {
+  showHelp();
+  process.exit(0);
+}
+
+if (command === '--version' || command === '-v') {
+  showVersion();
+  process.exit(0);
+}
+
+switch (command) {
+  case 'init':
+    init();
+    break;
+  case 'validate':
+    validate();
+    break;
+  case 'list-agents':
+    listAgents();
+    break;
+  default:
+    console.error(`Unknown command: ${command}\n`);
+    showHelp();
+    process.exit(1);
+}

package/lib/init/detect-stack.js

@@ -0,0 +1,162 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const FRONTEND_FRAMEWORKS = ['react', 'vue', 'angular', 'svelte', 'solid-js'];
+const FULLSTACK_FRAMEWORKS = ['next', 'nuxt', 'remix', 'sveltekit', 'astro'];
+const BACKEND_FRAMEWORKS = [
+  '@nestjs/core',
+  'express',
+  'fastify',
+  'koa',
+  'hapi',
+  '@hono/node-server',
+  'hono',
+];
+const MOBILE_FRAMEWORKS = ['react-native', 'expo', '@capacitor/core', 'ionic'];
+
+/**
+ * Detect tech stack from project files in the given directory.
+ * @param {string} cwd - Directory to scan
+ * @returns {{ runtime: string, language: string, frameworks: string[], category: string }}
+ */
+function detectStack(cwd) {
+  const result = {
+    runtime: 'unknown',
+    language: 'javascript',
+    frameworks: [],
+    category: 'unknown',
+  };
+
+  if (tryDetectNode(cwd, result)) return result;
+  if (tryDetectPython(cwd, result)) return result;
+  if (tryDetectGo(cwd, result)) return result;
+  if (tryDetectRust(cwd, result)) return result;
+
+  result.language = 'unknown';
+  return result;
+}
+
+function tryDetectNode(cwd, result) {
+  const pkgPath = path.join(cwd, 'package.json');
+  if (!fs.existsSync(pkgPath)) return false;
+
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  } catch {
+    return false;
+  }
+
+  result.runtime = 'node';
+
+  const allDeps = {
+    ...pkg.dependencies,
+    ...pkg.devDependencies,
+  };
+
+  // Detect language
+  if (allDeps.typescript) {
+    result.language = 'typescript';
+  }
+
+  // Detect frameworks
+  const detected = [];
+
+  for (const fw of FULLSTACK_FRAMEWORKS) {
+    if (allDeps[fw]) detected.push(fw);
+  }
+  for (const fw of FRONTEND_FRAMEWORKS) {
+    if (allDeps[fw]) detected.push(fw);
+  }
+  for (const fw of BACKEND_FRAMEWORKS) {
+    if (allDeps[fw]) {
+      const name = fw.startsWith('@nestjs') ? 'nestjs' : fw;
+      detected.push(name);
+    }
+  }
+  for (const fw of MOBILE_FRAMEWORKS) {
+    if (allDeps[fw]) detected.push(fw);
+  }
+
+  result.frameworks = detected;
+
+  // Determine category
+  if (detected.some(f => MOBILE_FRAMEWORKS.includes(f) || f === 'react-native' || f === 'expo')) {
+    result.category = 'mobile';
+  } else if (detected.some(f => FULLSTACK_FRAMEWORKS.includes(f))) {
+    result.category = 'fullstack';
+  } else if (detected.some(f => FRONTEND_FRAMEWORKS.includes(f))) {
+    result.category = 'frontend';
+  } else if (
+    detected.some(f =>
+      ['nestjs', ...BACKEND_FRAMEWORKS.map(b => (b.startsWith('@') ? 'nestjs' : b))].includes(f),
+    )
+  ) {
+    result.category = 'backend';
+  } else {
+    result.category = 'backend'; // default for Node without frameworks
+  }
+
+  return true;
+}
+
+function tryDetectPython(cwd, result) {
+  const pyprojectPath = path.join(cwd, 'pyproject.toml');
+  if (!fs.existsSync(pyprojectPath)) return false;
+
+  result.runtime = 'python';
+  result.language = 'python';
+  result.category = 'backend';
+
+  const content = fs.readFileSync(pyprojectPath, 'utf-8');
+  const pyFrameworks = {
+    django: 'django',
+    flask: 'flask',
+    fastapi: 'fastapi',
+    starlette: 'starlette',
+  };
+
+  for (const [key, name] of Object.entries(pyFrameworks)) {
+    if (content.toLowerCase().includes(key)) {
+      result.frameworks.push(name);
+    }
+  }
+
+  return true;
+}
+
+function tryDetectGo(cwd, result) {
+  const goModPath = path.join(cwd, 'go.mod');
+  if (!fs.existsSync(goModPath)) return false;
+
+  result.runtime = 'go';
+  result.language = 'go';
+  result.category = 'backend';
+
+  const content = fs.readFileSync(goModPath, 'utf-8');
+  if (content.includes('github.com/gin-gonic/gin')) result.frameworks.push('gin');
+  if (content.includes('github.com/gofiber/fiber')) result.frameworks.push('fiber');
+  if (content.includes('github.com/labstack/echo')) result.frameworks.push('echo');
+
+  return true;
+}
+
+function tryDetectRust(cwd, result) {
+  const cargoPath = path.join(cwd, 'Cargo.toml');
+  if (!fs.existsSync(cargoPath)) return false;
+
+  result.runtime = 'rust';
+  result.language = 'rust';
+  result.category = 'backend';
+
+  const content = fs.readFileSync(cargoPath, 'utf-8');
+  if (content.includes('actix-web')) result.frameworks.push('actix-web');
+  if (content.includes('axum')) result.frameworks.push('axum');
+  if (content.includes('rocket')) result.frameworks.push('rocket');
+
+  return true;
+}
+
+module.exports = { detectStack };

package/lib/init/generate-config.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Generate codingbuddy.config.json in the target directory.
+ * @param {string} cwd - Target directory
+ * @param {{ language: string, primaryAgent: string, techStack: object }} options
+ * @returns {{ created: boolean, skipped: boolean, path: string }}
+ */
+function generateConfig(cwd, options) {
+  const configPath = path.join(cwd, 'codingbuddy.config.json');
+
+  if (fs.existsSync(configPath)) {
+    return { created: false, skipped: true, path: configPath };
+  }
+
+  const config = {
+    version: '1.0.0',
+    language: options.language || 'en',
+    primaryAgent: options.primaryAgent || 'software-engineer',
+    techStack: options.techStack || {},
+  };
+
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+
+  return { created: true, skipped: false, path: configPath };
+}
+
+module.exports = { generateConfig };

package/lib/init/index.js

@@ -0,0 +1,86 @@
+'use strict';
+
+const path = require('node:path');
+const { detectStack } = require('./detect-stack');
+const { suggestAgent } = require('./suggest-agent');
+const { generateConfig } = require('./generate-config');
+const { scaffold } = require('./scaffold');
+const { ask, select, confirm } = require('./prompt');
+
+const LANGUAGES = ['en', 'ko', 'ja', 'zh', 'es'];
+
+/**
+ * Run the codingbuddy init wizard.
+ * @param {string} [cwd=process.cwd()]
+ */
+async function run(cwd) {
+  const targetDir = cwd || process.cwd();
+
+  console.log('\n  codingbuddy init\n');
+  console.log('  Initializing codingbuddy for your project...\n');
+
+  // Step 1: Detect tech stack
+  console.log('  Detecting tech stack...');
+  const stack = detectStack(targetDir);
+
+  if (stack.runtime !== 'unknown') {
+    console.log(`  Detected: ${stack.runtime} (${stack.language})`);
+    if (stack.frameworks.length > 0) {
+      console.log(`  Frameworks: ${stack.frameworks.join(', ')}`);
+    }
+    console.log(`  Category: ${stack.category}`);
+  } else {
+    console.log('  No recognized project files found.');
+  }
+
+  // Step 2: Language selection
+  const language = await select('Select communication language:', LANGUAGES, 0);
+  console.log(`  Language: ${language}`);
+
+  // Step 3: Agent suggestion
+  const suggested = suggestAgent(stack);
+  console.log(`\n  Recommended primary agent: ${suggested}`);
+  const useAgent = await confirm(`  Use ${suggested} as primary agent?`, true);
+
+  let primaryAgent = suggested;
+  if (!useAgent) {
+    primaryAgent = await ask('  Enter agent name', 'software-engineer');
+  }
+
+  // Step 4: Generate config
+  console.log('\n  Creating codingbuddy.config.json...');
+  const configResult = generateConfig(targetDir, {
+    language,
+    primaryAgent,
+    techStack: stack,
+  });
+
+  if (configResult.skipped) {
+    console.log('  codingbuddy.config.json already exists, skipped.');
+  } else {
+    console.log('  Created codingbuddy.config.json');
+  }
+
+  // Step 5: Scaffold .ai-rules
+  const doScaffold = await confirm('  Scaffold .ai-rules/ directory with default rules?', true);
+
+  if (doScaffold) {
+    console.log('  Scaffolding .ai-rules/...');
+    const scaffoldResult = scaffold(targetDir);
+
+    if (scaffoldResult.skipped) {
+      console.log('  .ai-rules/ already exists, skipped.');
+    } else {
+      console.log(`  Created .ai-rules/ with: ${scaffoldResult.dirs.join(', ')}`);
+    }
+  }
+
+  // Done
+  console.log('\n  Done! codingbuddy is ready.\n');
+  console.log('  Next steps:');
+  console.log('    1. Review codingbuddy.config.json');
+  console.log('    2. Customize .ai-rules/ for your project');
+  console.log('    3. Start coding with your AI assistant\n');
+}
+
+module.exports = { run };

package/lib/init/prompt.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const readline = require('node:readline');
+
+/**
+ * Ask a question via stdin and return the answer.
+ * @param {string} question
+ * @param {string} [defaultValue]
+ * @returns {Promise<string>}
+ */
+function ask(question, defaultValue) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const suffix = defaultValue ? ` (${defaultValue})` : '';
+
+  return new Promise(resolve => {
+    rl.question(`${question}${suffix}: `, answer => {
+      rl.close();
+      resolve(answer.trim() || defaultValue || '');
+    });
+  });
+}
+
+/**
+ * Ask user to select from a list of options.
+ * @param {string} question
+ * @param {string[]} options
+ * @param {number} [defaultIndex=0]
+ * @returns {Promise<string>}
+ */
+async function select(question, options, defaultIndex = 0) {
+  console.log(`\n${question}`);
+  options.forEach((opt, i) => {
+    const marker = i === defaultIndex ? '>' : ' ';
+    console.log(`  ${marker} ${i + 1}. ${opt}`);
+  });
+
+  const answer = await ask('Select', String(defaultIndex + 1));
+  const index = parseInt(answer, 10) - 1;
+
+  if (index >= 0 && index < options.length) {
+    return options[index];
+  }
+  return options[defaultIndex];
+}
+
+/**
+ * Ask yes/no question.
+ * @param {string} question
+ * @param {boolean} [defaultValue=true]
+ * @returns {Promise<boolean>}
+ */
+async function confirm(question, defaultValue = true) {
+  const hint = defaultValue ? 'Y/n' : 'y/N';
+  const answer = await ask(`${question} (${hint})`, '');
+
+  if (!answer) return defaultValue;
+  return answer.toLowerCase().startsWith('y');
+}
+
+module.exports = { ask, select, confirm };

package/lib/init/scaffold.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_SOURCE = path.resolve(__dirname, '../../.ai-rules');
+
+// Directories to always scaffold
+const SCAFFOLD_DIRS = ['rules', 'agents'];
+// Top-level files to always copy
+const SCAFFOLD_FILES = ['README.md'];
+
+/**
+ * Scaffold .ai-rules/ structure in the target directory.
+ * @param {string} cwd - Target directory
+ * @param {{ source?: string }} options
+ * @returns {{ skipped: boolean, dirs: string[], targetPath: string }}
+ */
+function scaffold(cwd, options = {}) {
+  const source = options.source || DEFAULT_SOURCE;
+  const targetDir = path.join(cwd, '.ai-rules');
+
+  if (fs.existsSync(targetDir)) {
+    return { skipped: true, dirs: [], targetPath: targetDir };
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  const copiedDirs = [];
+
+  // Copy directories
+  for (const dir of SCAFFOLD_DIRS) {
+    const srcDir = path.join(source, dir);
+    if (fs.existsSync(srcDir)) {
+      copyDirRecursive(srcDir, path.join(targetDir, dir));
+      copiedDirs.push(dir);
+    }
+  }
+
+  // Copy top-level files
+  for (const file of SCAFFOLD_FILES) {
+    const srcFile = path.join(source, file);
+    if (fs.existsSync(srcFile)) {
+      fs.copyFileSync(srcFile, path.join(targetDir, file));
+    }
+  }
+
+  return { skipped: false, dirs: copiedDirs, targetPath: targetDir };
+}
+
+function copyDirRecursive(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+module.exports = { scaffold };

package/lib/init/suggest-agent.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const AGENT_MAP = {
+  mobile: 'mobile-developer',
+  frontend: 'frontend-developer',
+  fullstack: 'software-engineer',
+};
+
+const RUNTIME_AGENTS = {
+  rust: 'systems-developer',
+  go: 'backend-developer',
+  python: 'backend-developer',
+};
+
+const DATA_SCIENCE_FRAMEWORKS = [
+  'pandas',
+  'numpy',
+  'scipy',
+  'jupyter',
+  'tensorflow',
+  'pytorch',
+  'scikit-learn',
+];
+
+/**
+ * Suggest the best primary agent based on detected tech stack.
+ * @param {{ runtime: string, category: string, frameworks: string[] }} stack
+ * @returns {string} Agent name (e.g. 'frontend-developer')
+ */
+function suggestAgent(stack) {
+  // Data science detection for Python
+  if (
+    stack.runtime === 'python' &&
+    stack.frameworks.some(f => DATA_SCIENCE_FRAMEWORKS.includes(f))
+  ) {
+    return 'data-scientist';
+  }
+
+  // Category-based mapping
+  if (AGENT_MAP[stack.category]) {
+    return AGENT_MAP[stack.category];
+  }
+
+  // Runtime-based mapping
+  if (RUNTIME_AGENTS[stack.runtime]) {
+    return RUNTIME_AGENTS[stack.runtime];
+  }
+
+  // Backend Node.js
+  if (stack.runtime === 'node' && stack.category === 'backend') {
+    return 'backend-developer';
+  }
+
+  return 'software-engineer';
+}
+
+module.exports = { suggestAgent };

package/package.json

@@ -1,13 +1,21 @@
 {
   "name": "codingbuddy-rules",
-  "version": "4.5.0",
+  "version": "5.1.0",
   "description": "AI coding rules for consistent practices across AI assistants",
   "main": "index.js",
   "types": "index.d.ts",
+  "bin": {
+    "codingbuddy": "./bin/cli.js"
+  },
+  "scripts": {
+    "test": "node --test __tests__/**/*.test.js"
+  },
   "files": [
     "index.js",
     "index.d.ts",
-    ".ai-rules"
+    ".ai-rules",
+    "bin",
+    "lib"
   ],
   "keywords": [
     "ai",