@ngxtm/devkit 2.1.0 → 3.0.0

package/cli/init.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+
+/**
+ * Devkit Init - Per-Project Installation
+ *
+ * Installs devkit to the current project's .claude/ directory with:
+ * - Merged commands (from both agent-assistant and claudekit)
+ * - Tech-specific rules (based on project detection)
+ * - Skills index (for on-demand loading)
+ * - Essential hooks
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { detectProjectType, getRulesForTypes, printDetectionResults } = require('./detect');
+const { copyDir, getDirSize, validatePath } = require('./utils');
+
+const VERSION = require('../package.json').version;
+const PACKAGE_ROOT = path.join(__dirname, '..');
+
+/**
+ * Initialize devkit in a project directory
+ */
+function initProject(options = {}) {
+  const projectDir = options.path || process.cwd();
+  const claudeDir = path.join(projectDir, '.claude');
+  const isUpdate = options.update || false;
+
+  console.log('\n' + '='.repeat(60));
+  console.log('  DEVKIT v' + VERSION + (isUpdate ? ' - UPDATE' : ' - INIT'));
+  console.log('='.repeat(60));
+
+  // Check if .claude already exists
+  if (fs.existsSync(claudeDir) && !isUpdate && !options.force) {
+    console.log(`\n  .claude/ folder already exists.`);
+    console.log('  Use --force to overwrite or --update to update.\n');
+    return { success: false, reason: 'exists' };
+  }
+
+  // 1. Detect project type
+  console.log('\n  Detecting project type...');
+  const detectedTypes = detectProjectType(projectDir);
+  const rulesToInstall = getRulesForTypes(detectedTypes);
+
+  if (detectedTypes.length > 0) {
+    console.log(`  Detected: ${detectedTypes.join(', ')}`);
+    console.log(`  Rules: ${rulesToInstall.join(', ')}`);
+  } else {
+    console.log('  No specific technology detected.');
+    console.log('  Installing base commands only.');
+  }
+
+  // Create .claude directory
+  fs.mkdirSync(claudeDir, { recursive: true });
+
+  let totalFiles = 0;
+  const stats = {};
+
+  // 2. Install merged commands
+  console.log('\n  Installing components...');
+  const mergedCommandsDir = path.join(PACKAGE_ROOT, 'merged-commands');
+  const commandsDir = path.join(claudeDir, 'commands');
+
+  if (fs.existsSync(mergedCommandsDir)) {
+    const count = copyDir(mergedCommandsDir, commandsDir);
+    stats.commands = count;
+    totalFiles += count;
+    console.log(`    Commands: ${count} files`);
+  } else {
+    // Fallback to commands-claudekit if merged not available
+    const fallbackDir = path.join(PACKAGE_ROOT, 'commands-claudekit');
+    if (fs.existsSync(fallbackDir)) {
+      const count = copyDir(fallbackDir, commandsDir);
+      stats.commands = count;
+      totalFiles += count;
+      console.log(`    Commands (claudekit): ${count} files`);
+    }
+  }
+
+  // 3. Install tech-specific rules
+  const rulesDir = path.join(claudeDir, 'rules');
+  let rulesCount = 0;
+
+  for (const ruleType of rulesToInstall) {
+    const srcRulesDir = path.join(PACKAGE_ROOT, 'templates', ruleType, 'rules');
+    if (fs.existsSync(srcRulesDir)) {
+      const destRulesDir = path.join(rulesDir, ruleType);
+      const count = copyDir(srcRulesDir, destRulesDir);
+      rulesCount += count;
+    }
+  }
+
+  if (rulesCount > 0) {
+    stats.rules = rulesCount;
+    totalFiles += rulesCount;
+    console.log(`    Rules: ${rulesCount} files (${rulesToInstall.join(', ')})`);
+  }
+
+  // 4. Install essential hooks
+  const srcHooksDir = path.join(PACKAGE_ROOT, 'templates', 'base', 'hooks');
+  const hooksDir = path.join(claudeDir, 'hooks');
+
+  if (fs.existsSync(srcHooksDir)) {
+    const count = copyDir(srcHooksDir, hooksDir);
+    stats.hooks = count;
+    totalFiles += count;
+    console.log(`    Hooks: ${count} files`);
+  } else {
+    // Fallback to main hooks directory (essential only)
+    const fallbackHooks = path.join(PACKAGE_ROOT, 'hooks');
+    if (fs.existsSync(fallbackHooks)) {
+      const count = copyDir(fallbackHooks, hooksDir);
+      stats.hooks = count;
+      totalFiles += count;
+      console.log(`    Hooks: ${count} files`);
+    }
+  }
+
+  // 5. Install skills index
+  const skillsIndexSrc = path.join(PACKAGE_ROOT, 'skills-index.json');
+  const skillsIndexDest = path.join(claudeDir, 'skills-index.json');
+
+  if (fs.existsSync(skillsIndexSrc)) {
+    fs.copyFileSync(skillsIndexSrc, skillsIndexDest);
+    totalFiles++;
+    console.log(`    Skills Index: 1 file`);
+  }
+
+  // 6. Create devkit.json tracking file
+  const devkitConfig = {
+    version: VERSION,
+    detectedTypes: detectedTypes,
+    installedRules: rulesToInstall,
+    installedAt: new Date().toISOString(),
+    updatedAt: isUpdate ? new Date().toISOString() : null,
+    stats: {
+      totalFiles: totalFiles,
+      sizeKB: Math.round(getDirSize(claudeDir) / 1024)
+    }
+  };
+
+  fs.writeFileSync(
+    path.join(claudeDir, 'devkit.json'),
+    JSON.stringify(devkitConfig, null, 2)
+  );
+  totalFiles++;
+
+  // 7. Create settings.json if not exists
+  const settingsPath = path.join(claudeDir, 'settings.json');
+  if (!fs.existsSync(settingsPath)) {
+    const settings = {
+      includeCoAuthoredBy: false
+    };
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+    totalFiles++;
+  }
+
+  // Calculate total size
+  const totalSizeKB = Math.round(getDirSize(claudeDir) / 1024);
+
+  console.log('\n' + '='.repeat(60));
+  console.log('  INSTALLATION COMPLETE');
+  console.log('='.repeat(60));
+  console.log(`\n  Total: ${totalFiles} files (${totalSizeKB} KB)`);
+  console.log(`  Location: ${claudeDir}`);
+
+  console.log('\n  Available commands:');
+  console.log('    /plan        - Plan implementation');
+  console.log('    /cook        - Build a feature');
+  console.log('    /fix         - Fix issues');
+  console.log('    /code        - Start coding');
+  console.log('    /brainstorm  - Brainstorm ideas');
+
+  if (detectedTypes.length > 0) {
+    console.log(`\n  Tech-specific rules loaded for: ${detectedTypes.join(', ')}`);
+  }
+
+  console.log('\n  Restart Claude Code to use the new skills.\n');
+
+  return {
+    success: true,
+    detected: detectedTypes,
+    rules: rulesToInstall,
+    stats: {
+      files: totalFiles,
+      sizeKB: totalSizeKB
+    }
+  };
+}
+
+/**
+ * Uninstall devkit from project
+ */
+function uninstallProject(options = {}) {
+  const projectDir = options.path || process.cwd();
+  const claudeDir = path.join(projectDir, '.claude');
+
+  console.log('\n' + '='.repeat(60));
+  console.log('  DEVKIT - UNINSTALL');
+  console.log('='.repeat(60));
+
+  if (!fs.existsSync(claudeDir)) {
+    console.log('\n  No .claude/ folder found.\n');
+    return { success: false, reason: 'not_found' };
+  }
+
+  // Check if it's a devkit installation
+  const devkitConfig = path.join(claudeDir, 'devkit.json');
+  if (!fs.existsSync(devkitConfig)) {
+    console.log('\n  .claude/ exists but is not a devkit installation.');
+    console.log('  Remove manually if needed.\n');
+    return { success: false, reason: 'not_devkit' };
+  }
+
+  // Remove the directory
+  fs.rmSync(claudeDir, { recursive: true, force: true });
+  console.log(`\n  Removed: ${claudeDir}`);
+  console.log('  Devkit uninstalled successfully.\n');
+
+  return { success: true };
+}
+
+module.exports = {
+  initProject,
+  uninstallProject,
+  copyDir,
+  getDirSize
+};
+
+// Run if called directly
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const options = {
+    force: args.includes('--force') || args.includes('-f'),
+    update: args.includes('--update') || args.includes('-u'),
+    path: args.find(a => !a.startsWith('-')) || process.cwd()
+  };
+
+  if (args.includes('--uninstall')) {
+    uninstallProject(options);
+  } else {
+    initProject(options);
+  }
+}

package/cli/update.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+
+/**
+ * Devkit Update - Update existing installation
+ *
+ * Re-detects project type and updates rules accordingly.
+ * Preserves user customizations where possible.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const { detectProjectType, getRulesForTypes } = require('./detect');
+const { initProject } = require('./init');
+const { copyDir, getDirSize, parseJsonFile } = require('./utils');
+
+const VERSION = require('../package.json').version;
+const PACKAGE_ROOT = path.join(__dirname, '..');
+
+/**
+ * Check for npm package updates
+ */
+function checkForUpdates() {
+  try {
+    const result = execSync('npm view @ngxtm/devkit version', {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+    return result.trim();
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Update devkit installation
+ */
+function updateProject(options = {}) {
+  const projectDir = options.path || process.cwd();
+  const claudeDir = path.join(projectDir, '.claude');
+  const configPath = path.join(claudeDir, 'devkit.json');
+
+  console.log('\n' + '='.repeat(60));
+  console.log('  DEVKIT - UPDATE');
+  console.log('='.repeat(60));
+
+  // Check if devkit is installed
+  if (!fs.existsSync(configPath)) {
+    console.log('\n  No devkit installation found.');
+    console.log('  Run: devkit init\n');
+    return { success: false, reason: 'not_installed' };
+  }
+
+  // Read current config with error handling
+  const config = parseJsonFile(configPath);
+  if (!config) {
+    console.log('\n  Error: devkit.json is corrupted.');
+    console.log('  Try reinitializing with: devkit init --force\n');
+    return { success: false, reason: 'corrupted_config' };
+  }
+  console.log(`\n  Current version: ${config.version}`);
+  console.log(`  Installed: ${new Date(config.installedAt).toLocaleDateString()}`);
+
+  // Check for package updates
+  console.log('\n  Checking for updates...');
+  const latestVersion = checkForUpdates();
+
+  if (latestVersion && latestVersion !== VERSION) {
+    console.log(`  New version available: ${latestVersion}`);
+    console.log('  Run: npm update -g @ngxtm/devkit');
+    console.log('  Then: devkit update\n');
+  } else if (latestVersion) {
+    console.log(`  Package is up to date (${VERSION})`);
+  } else {
+    console.log('  Could not check for updates (offline?)');
+  }
+
+  // Re-detect project type
+  console.log('\n  Re-detecting project type...');
+  const newDetected = detectProjectType(projectDir);
+  const oldDetected = config.detectedTypes || [];
+
+  // Find differences
+  const added = newDetected.filter(t => !oldDetected.includes(t));
+  const removed = oldDetected.filter(t => !newDetected.includes(t));
+  const unchanged = newDetected.filter(t => oldDetected.includes(t));
+
+  if (added.length > 0) {
+    console.log(`  New tech detected: ${added.join(', ')}`);
+  }
+  if (removed.length > 0) {
+    console.log(`  Removed: ${removed.join(', ')}`);
+  }
+  if (unchanged.length > 0) {
+    console.log(`  Unchanged: ${unchanged.join(', ')}`);
+  }
+  if (added.length === 0 && removed.length === 0) {
+    console.log('  No changes in detected technologies.');
+  }
+
+  // Update rules if needed
+  if (added.length > 0 || options.force) {
+    const newRules = getRulesForTypes(added);
+    const rulesDir = path.join(claudeDir, 'rules');
+
+    console.log('\n  Installing new rules...');
+
+    for (const ruleType of newRules) {
+      const srcRulesDir = path.join(PACKAGE_ROOT, 'templates', ruleType, 'rules');
+      if (fs.existsSync(srcRulesDir)) {
+        const destRulesDir = path.join(rulesDir, ruleType);
+        const count = copyDir(srcRulesDir, destRulesDir);
+        console.log(`    ${ruleType}: ${count} files`);
+      }
+    }
+  }
+
+  // Remove old rules if needed and user agrees
+  if (removed.length > 0 && options.clean) {
+    const rulesDir = path.join(claudeDir, 'rules');
+
+    console.log('\n  Removing old rules...');
+
+    for (const ruleType of removed) {
+      const ruleDir = path.join(rulesDir, ruleType);
+      if (fs.existsSync(ruleDir)) {
+        fs.rmSync(ruleDir, { recursive: true, force: true });
+        console.log(`    Removed: ${ruleType}`);
+      }
+    }
+  }
+
+  // Update commands if --force
+  if (options.force) {
+    console.log('\n  Updating commands...');
+    const mergedCommandsDir = path.join(PACKAGE_ROOT, 'merged-commands');
+    const commandsDir = path.join(claudeDir, 'commands');
+
+    if (fs.existsSync(mergedCommandsDir)) {
+      // Backup existing
+      const backupDir = path.join(claudeDir, 'commands.backup');
+      if (fs.existsSync(commandsDir)) {
+        fs.renameSync(commandsDir, backupDir);
+      }
+
+      const count = copyDir(mergedCommandsDir, commandsDir);
+      console.log(`    Commands: ${count} files`);
+
+      // Remove backup
+      if (fs.existsSync(backupDir)) {
+        fs.rmSync(backupDir, { recursive: true, force: true });
+      }
+    }
+  }
+
+  // Update config
+  const newConfig = {
+    ...config,
+    version: VERSION,
+    detectedTypes: newDetected,
+    installedRules: getRulesForTypes(newDetected),
+    updatedAt: new Date().toISOString(),
+    stats: {
+      totalFiles: config.stats?.totalFiles || 0,
+      sizeKB: Math.round(getDirSize(claudeDir) / 1024)
+    }
+  };
+
+  fs.writeFileSync(configPath, JSON.stringify(newConfig, null, 2));
+
+  console.log('\n' + '='.repeat(60));
+  console.log('  UPDATE COMPLETE');
+  console.log('='.repeat(60));
+  console.log(`\n  Size: ${newConfig.stats.sizeKB} KB`);
+  console.log(`  Detected: ${newDetected.join(', ') || 'generic'}\n`);
+
+  return {
+    success: true,
+    added,
+    removed,
+    detected: newDetected
+  };
+}
+
+/**
+ * Show project status
+ */
+function showStatus(options = {}) {
+  const projectDir = options.path || process.cwd();
+  const claudeDir = path.join(projectDir, '.claude');
+  const configPath = path.join(claudeDir, 'devkit.json');
+
+  console.log('\n' + '='.repeat(60));
+  console.log('  DEVKIT - STATUS');
+  console.log('='.repeat(60));
+
+  if (!fs.existsSync(configPath)) {
+    console.log('\n  No devkit installation found.');
+    console.log('  Run: devkit init\n');
+    return { installed: false };
+  }
+
+  const config = parseJsonFile(configPath);
+  if (!config) {
+    console.log('\n  Error: devkit.json is corrupted.');
+    console.log('  Try reinitializing with: devkit init --force\n');
+    return { installed: false, corrupted: true };
+  }
+
+  console.log(`\n  Version: ${config.version}`);
+  console.log(`  Installed: ${new Date(config.installedAt).toLocaleDateString()}`);
+  if (config.updatedAt) {
+    console.log(`  Updated: ${new Date(config.updatedAt).toLocaleDateString()}`);
+  }
+  console.log(`\n  Detected: ${config.detectedTypes?.join(', ') || 'none'}`);
+  console.log(`  Rules: ${config.installedRules?.join(', ') || 'none'}`);
+  console.log(`  Size: ${config.stats?.sizeKB || 'unknown'} KB\n`);
+
+  return { installed: true, config };
+}
+
+module.exports = {
+  updateProject,
+  showStatus,
+  checkForUpdates
+};
+
+// Run if called directly
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const options = {
+    force: args.includes('--force') || args.includes('-f'),
+    clean: args.includes('--clean') || args.includes('-c'),
+    path: args.find(a => !a.startsWith('-')) || process.cwd()
+  };
+
+  if (args.includes('--status')) {
+    showStatus(options);
+  } else {
+    updateProject(options);
+  }
+}

package/cli/utils.js

@@ -0,0 +1,195 @@
+/**
+ * Shared Utilities for Devkit CLI
+ *
+ * Common functions used across CLI modules.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Copy directory recursively
+ * @param {string} src - Source directory
+ * @param {string} dest - Destination directory
+ * @param {Object} options - Options
+ * @param {string[]} options.exclude - Patterns to exclude
+ * @param {Set} options.visited - Visited directories (for cycle detection)
+ * @param {number} options.depth - Current depth (max 50)
+ * @returns {number} - Number of files copied
+ */
+function copyDir(src, dest, options = {}) {
+  const { exclude = [], visited = new Set(), depth = 0 } = options;
+
+  // Prevent infinite recursion
+  if (depth > 50) return 0;
+
+  if (!fs.existsSync(src)) return 0;
+
+  // Detect symlink cycles
+  try {
+    const realSrc = fs.realpathSync(src);
+    if (visited.has(realSrc)) return 0;
+    visited.add(realSrc);
+  } catch (e) {
+    return 0;
+  }
+
+  fs.mkdirSync(dest, { recursive: true });
+  let count = 0;
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    // Skip hidden files, tests, node_modules by default
+    if (entry.name.startsWith('.') ||
+        entry.name === '__tests__' ||
+        entry.name === 'tests' ||
+        entry.name === 'node_modules') {
+      continue;
+    }
+
+    // Check custom exclusions
+    if (exclude.some(pattern => entry.name.includes(pattern))) {
+      continue;
+    }
+
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      count += copyDir(srcPath, destPath, { exclude, visited, depth: depth + 1 });
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+      count++;
+    }
+  }
+
+  return count;
+}
+
+/**
+ * Get directory size in KB
+ * @param {string} dir - Directory path
+ * @param {Set} visited - Visited directories (for cycle detection)
+ * @param {number} depth - Current depth (max 50)
+ * @returns {number} - Size in bytes
+ */
+function getDirSize(dir, visited = new Set(), depth = 0) {
+  // Prevent infinite recursion
+  if (depth > 50) return 0;
+
+  if (!fs.existsSync(dir)) return 0;
+
+  // Detect symlink cycles
+  try {
+    const realDir = fs.realpathSync(dir);
+    if (visited.has(realDir)) return 0;
+    visited.add(realDir);
+  } catch (e) {
+    return 0;
+  }
+
+  let size = 0;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const entryPath = path.join(dir, entry.name);
+    try {
+      if (entry.isDirectory()) {
+        size += getDirSize(entryPath, visited, depth + 1);
+      } else {
+        size += fs.statSync(entryPath).size;
+      }
+    } catch (e) {
+      // Skip unreadable files
+    }
+  }
+
+  return size;
+}
+
+/**
+ * Safely parse JSON file
+ * @param {string} filePath - Path to JSON file
+ * @param {*} defaultValue - Default value if parsing fails
+ * @returns {*} - Parsed JSON or default value
+ */
+function parseJsonFile(filePath, defaultValue = null) {
+  try {
+    if (!fs.existsSync(filePath)) {
+      return defaultValue;
+    }
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(content);
+  } catch (e) {
+    console.error(`Warning: Failed to parse ${path.basename(filePath)}: ${e.message}`);
+    return defaultValue;
+  }
+}
+
+/**
+ * Validate and resolve path
+ * @param {string} inputPath - User-provided path
+ * @param {boolean} mustExist - Whether path must exist
+ * @returns {string|null} - Resolved absolute path or null if invalid
+ */
+function validatePath(inputPath, mustExist = false) {
+  if (!inputPath) return null;
+
+  try {
+    const resolved = path.resolve(inputPath);
+
+    if (mustExist && !fs.existsSync(resolved)) {
+      console.error(`Error: Path does not exist: ${resolved}`);
+      return null;
+    }
+
+    // Check if it's a directory when it exists
+    if (fs.existsSync(resolved) && !fs.statSync(resolved).isDirectory()) {
+      console.error(`Error: Path is not a directory: ${resolved}`);
+      return null;
+    }
+
+    return resolved;
+  } catch (e) {
+    console.error(`Error: Invalid path: ${inputPath}`);
+    return null;
+  }
+}
+
+/**
+ * Get all files and directories from a path recursively
+ * @param {string} dir - Directory to scan
+ * @param {string} basePath - Base path for relative paths
+ * @returns {{files: string[], dirs: string[]}} - Files and directories
+ */
+function getAllEntries(dir, basePath = '') {
+  const entries = { files: [], dirs: [] };
+
+  if (!fs.existsSync(dir)) return entries;
+
+  const items = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const item of items) {
+    const relativePath = path.join(basePath, item.name);
+
+    if (item.isDirectory()) {
+      entries.dirs.push(relativePath);
+      const subEntries = getAllEntries(path.join(dir, item.name), relativePath);
+      entries.files.push(...subEntries.files);
+      entries.dirs.push(...subEntries.dirs);
+    } else {
+      entries.files.push(relativePath);
+    }
+  }
+
+  return entries;
+}
+
+module.exports = {
+  copyDir,
+  getDirSize,
+  parseJsonFile,
+  validatePath,
+  getAllEntries
+};