@codihaus/claude-skills 1.0.0 → 1.2.0

package/src/commands/init.js

@@ -20,7 +20,9 @@ import {
 import {
   getAvailableSkills,
   getInstalledSkills,
-  copySkillsToProject
+  copySkillsToProject,
+  copyKnowledgeToProject,
+  copyScriptsToProject
 } from '../utils/skills.js';
 import {
   setupSettings,
@@ -28,6 +30,11 @@ import {
   setupClaudeMd,
   updateGitignore
 } from '../utils/config.js';
+import {
+  runProjectSetup,
+  detectEnvExample,
+  hasEnvFile
+} from '../utils/project-setup.js';
 
 export async function init(options) {
   const projectPath = process.cwd();
@@ -158,7 +165,41 @@ export async function init(options) {
     process.exit(1);
   }
 
-  // Step 5: Set up settings
+  // Step 5: Copy knowledge (stacks, domains)
+  const knowledgeSpinner = ora('Installing knowledge base...').start();
+
+  try {
+    const { copied: knowledgeCopied, errors: knowledgeErrors } = await copyKnowledgeToProject(projectPath);
+
+    if (knowledgeErrors.length > 0) {
+      knowledgeSpinner.warn(`Installed ${knowledgeCopied.length} knowledge folders with ${knowledgeErrors.length} errors`);
+    } else if (knowledgeCopied.length > 0) {
+      knowledgeSpinner.succeed(`Installed knowledge: ${knowledgeCopied.join(', ')}`);
+    } else {
+      knowledgeSpinner.info('No knowledge to install');
+    }
+  } catch (e) {
+    knowledgeSpinner.warn('Failed to install knowledge');
+  }
+
+  // Step 6: Copy scripts (graph.py, etc.)
+  const scriptsSpinner = ora('Installing scripts...').start();
+
+  try {
+    const { copied: scriptsCopied, errors: scriptsErrors } = await copyScriptsToProject(projectPath);
+
+    if (scriptsErrors.length > 0) {
+      scriptsSpinner.warn(`Installed ${scriptsCopied.length} scripts with ${scriptsErrors.length} errors`);
+    } else if (scriptsCopied.length > 0) {
+      scriptsSpinner.succeed(`Installed scripts: ${scriptsCopied.join(', ')}`);
+    } else {
+      scriptsSpinner.info('No scripts to install');
+    }
+  } catch (e) {
+    scriptsSpinner.warn('Failed to install scripts');
+  }
+
+  // Step 7: Set up settings
   const settingsSpinner = ora('Setting up Claude Code configuration...').start();
 
   try {
@@ -168,7 +209,7 @@ export async function init(options) {
     settingsSpinner.warn('Failed to set up settings');
   }
 
-  // Step 6: Set up hooks
+  // Step 8: Set up hooks
   if (!options.noHooks) {
     const hooksSpinner = ora('Setting up hooks...').start();
 
@@ -184,7 +225,7 @@ export async function init(options) {
     }
   }
 
-  // Step 7: Set up CLAUDE.md
+  // Step 9: Set up CLAUDE.md
   const claudeSpinner = ora('Setting up CLAUDE.md...').start();
 
   try {
@@ -194,7 +235,7 @@ export async function init(options) {
     claudeSpinner.warn('Failed to set up CLAUDE.md');
   }
 
-  // Step 8: Update .gitignore
+  // Step 10: Update .gitignore
   const gitSpinner = ora('Updating .gitignore...').start();
 
   try {
@@ -204,15 +245,21 @@ export async function init(options) {
     gitSpinner.warn('Failed to update .gitignore');
   }
 
-  // Step 9: Check project dependencies
+  // Step 11: Project setup (package manager, .env, node version)
+  console.log('\n' + chalk.cyan('─'.repeat(40)));
+  console.log(chalk.bold('📦 Project Setup\n'));
+
+  const setupResult = await runProjectSetup(projectPath, { yes: options.yes });
+
+  // Step 12: Check skill-specific project dependencies
   if (!options.noDeps) {
     console.log('');
-    const projectSpinner = ora('Checking project dependencies...').start();
+    const projectSpinner = ora('Checking skill dependencies...').start();
     const projectDeps = await checkProjectDeps(projectPath);
     projectSpinner.stop();
 
     if (projectDeps.missing.length > 0) {
-      console.log(chalk.yellow('\n⚠️  Some optional dependencies are missing:\n'));
+      console.log(chalk.yellow('\n⚠️  Some optional dependencies for skills are missing:\n'));
 
       for (const dep of projectDeps.missing) {
         const cmd = dep.type === 'pip'
@@ -226,7 +273,7 @@ export async function init(options) {
         const { install } = await inquirer.prompt([{
           type: 'confirm',
           name: 'install',
-          message: 'Install missing dependencies now?',
+          message: 'Install missing skill dependencies now?',
           default: false
         }]);
 
@@ -240,11 +287,41 @@ export async function init(options) {
   // Done!
   console.log(chalk.green('\n✅ Claude Skills initialized successfully!\n'));
 
+  // Show startup commands if detected
+  if (setupResult.startupCommands && setupResult.startupCommands.length > 0) {
+    console.log(chalk.bold('Available commands:'));
+    console.log('');
+    for (const cmd of setupResult.startupCommands) {
+      const pm = setupResult.packageManager?.name || 'npm';
+      console.log(`  ${chalk.cyan(`${pm} run ${cmd.name}`)} - ${chalk.gray(cmd.command)}`);
+    }
+    console.log('');
+  }
+
   console.log(chalk.bold('Next steps:'));
   console.log('');
-  console.log('  1. Start Claude Code in this project');
-  console.log('  2. Try a skill: ' + chalk.cyan('/debrief "your project idea"'));
-  console.log('  3. See all skills: ' + chalk.cyan('/help'));
+
+  // Dynamic next steps based on setup
+  let stepNum = 1;
+
+  if (!setupResult.depsInstalled && setupResult.packageManager) {
+    console.log(`  ${stepNum}. Install dependencies: ${chalk.cyan(setupResult.packageManager.install)}`);
+    stepNum++;
+  }
+
+  if (!setupResult.envCreated && setupResult.packageManager) {
+    const envExample = detectEnvExample(projectPath);
+    if (envExample && !hasEnvFile(projectPath)) {
+      console.log(`  ${stepNum}. Set up environment: ${chalk.cyan(`cp ${envExample.file} .env`)} and fill in values`);
+      stepNum++;
+    }
+  }
+
+  console.log(`  ${stepNum}. Start Claude Code in this project`);
+  stepNum++;
+  console.log(`  ${stepNum}. Try a skill: ${chalk.cyan('/debrief "your project idea"')}`);
+  stepNum++;
+  console.log(`  ${stepNum}. See all skills: ${chalk.cyan('/help')}`);
   console.log('');
   console.log(chalk.gray('Docs: .claude/skills/_registry.md'));
   console.log('');

package/src/utils/project-setup.js

@@ -0,0 +1,444 @@
+/**
+ * Project Setup Utilities
+ *
+ * Detects and helps set up the development environment.
+ */
+
+import { execSync } from 'child_process';
+import fs from 'fs-extra';
+import path from 'path';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+
+/**
+ * Detect package manager from lockfile
+ */
+export function detectPackageManager(projectPath) {
+  const lockfiles = {
+    'bun.lockb': { name: 'bun', install: 'bun install' },
+    'pnpm-lock.yaml': { name: 'pnpm', install: 'pnpm install' },
+    'yarn.lock': { name: 'yarn', install: 'yarn install' },
+    'package-lock.json': { name: 'npm', install: 'npm install' }
+  };
+
+  for (const [file, pm] of Object.entries(lockfiles)) {
+    if (fs.existsSync(path.join(projectPath, file))) {
+      return pm;
+    }
+  }
+
+  // Default to npm if package.json exists
+  if (fs.existsSync(path.join(projectPath, 'package.json'))) {
+    return { name: 'npm', install: 'npm install' };
+  }
+
+  return null;
+}
+
+/**
+ * Check if node_modules exists
+ */
+export function hasNodeModules(projectPath) {
+  return fs.existsSync(path.join(projectPath, 'node_modules'));
+}
+
+/**
+ * Install project dependencies
+ */
+export async function installDeps(projectPath, pm) {
+  try {
+    execSync(pm.install, {
+      cwd: projectPath,
+      stdio: 'inherit'
+    });
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * Detect node version requirement
+ */
+export function detectNodeVersion(projectPath) {
+  const versionFiles = ['.nvmrc', '.node-version', '.tool-versions'];
+
+  for (const file of versionFiles) {
+    const filePath = path.join(projectPath, file);
+    if (fs.existsSync(filePath)) {
+      const content = fs.readFileSync(filePath, 'utf-8').trim();
+
+      // Handle .tool-versions format (asdf)
+      if (file === '.tool-versions') {
+        const match = content.match(/nodejs\s+(\S+)/);
+        if (match) {
+          return { file, version: match[1] };
+        }
+      } else {
+        // .nvmrc or .node-version - just the version
+        const version = content.replace(/^v/, '');
+        return { file, version };
+      }
+    }
+  }
+
+  // Check package.json engines
+  const pkgPath = path.join(projectPath, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    const pkg = fs.readJsonSync(pkgPath);
+    if (pkg.engines?.node) {
+      return { file: 'package.json (engines)', version: pkg.engines.node };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get current node version
+ */
+export function getCurrentNodeVersion() {
+  try {
+    return process.version.replace(/^v/, '');
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Check if current node version satisfies requirement
+ */
+export function checkNodeVersion(required, current) {
+  // Simple check - just compare major versions for now
+  const reqMajor = parseInt(required.split('.')[0]);
+  const curMajor = parseInt(current.split('.')[0]);
+
+  if (isNaN(reqMajor)) {
+    // Could be a range like >=18, just warn
+    return { ok: true, warning: `Required: ${required}, Current: ${current}` };
+  }
+
+  if (curMajor < reqMajor) {
+    return { ok: false, warning: `Required: ${required}, Current: ${current}` };
+  }
+
+  return { ok: true };
+}
+
+/**
+ * Detect .env.example and parse variables
+ */
+export function detectEnvExample(projectPath) {
+  const envExampleNames = ['.env.example', '.env.sample', '.env.template', 'example.env'];
+
+  for (const name of envExampleNames) {
+    const filePath = path.join(projectPath, name);
+    if (fs.existsSync(filePath)) {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const vars = parseEnvFile(content);
+      return { file: name, vars };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Check if .env exists
+ */
+export function hasEnvFile(projectPath) {
+  return fs.existsSync(path.join(projectPath, '.env'));
+}
+
+/**
+ * Parse env file content into variables
+ */
+export function parseEnvFile(content) {
+  const vars = [];
+  const lines = content.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Skip empty lines and comments
+    if (!trimmed || trimmed.startsWith('#')) {
+      continue;
+    }
+
+    // Parse KEY=value
+    const match = trimmed.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/i);
+    if (match) {
+      const [, key, value] = match;
+      const cleanValue = value.replace(/^["']|["']$/g, ''); // Remove quotes
+
+      vars.push({
+        key,
+        defaultValue: cleanValue || null,
+        hasDefault: cleanValue !== '',
+        isSecret: isSecretVar(key)
+      });
+    }
+  }
+
+  return vars;
+}
+
+/**
+ * Detect if variable is likely a secret
+ */
+function isSecretVar(key) {
+  const secretPatterns = [
+    /KEY$/i,
+    /SECRET$/i,
+    /TOKEN$/i,
+    /PASSWORD$/i,
+    /PASS$/i,
+    /AUTH/i,
+    /PRIVATE/i,
+    /CREDENTIAL/i
+  ];
+
+  return secretPatterns.some(pattern => pattern.test(key));
+}
+
+/**
+ * Prompt user for env values
+ */
+export async function promptEnvValues(vars, existingEnv = {}) {
+  const values = { ...existingEnv };
+  const questions = [];
+
+  for (const v of vars) {
+    // Skip if already has value
+    if (existingEnv[v.key]) {
+      continue;
+    }
+
+    const defaultVal = v.hasDefault ? v.defaultValue : undefined;
+
+    questions.push({
+      type: v.isSecret ? 'password' : 'input',
+      name: v.key,
+      message: v.isSecret
+        ? `${v.key}: (secret)`
+        : `${v.key}:`,
+      default: defaultVal,
+      transformer: (input) => {
+        if (v.isSecret && input) {
+          return '*'.repeat(input.length);
+        }
+        return input;
+      }
+    });
+  }
+
+  if (questions.length === 0) {
+    return values;
+  }
+
+  console.log(chalk.cyan('\nEnvironment variables needed:\n'));
+
+  const answers = await inquirer.prompt(questions);
+
+  return { ...values, ...answers };
+}
+
+/**
+ * Write .env file
+ */
+export function writeEnvFile(projectPath, values) {
+  const lines = [];
+
+  for (const [key, value] of Object.entries(values)) {
+    // Quote values with spaces or special chars
+    const needsQuotes = /[\s#"'`$]/.test(value);
+    const formattedValue = needsQuotes ? `"${value}"` : value;
+    lines.push(`${key}=${formattedValue}`);
+  }
+
+  const content = lines.join('\n') + '\n';
+  fs.writeFileSync(path.join(projectPath, '.env'), content);
+
+  return lines.length;
+}
+
+/**
+ * Read existing .env file
+ */
+export function readEnvFile(projectPath) {
+  const envPath = path.join(projectPath, '.env');
+  if (!fs.existsSync(envPath)) {
+    return {};
+  }
+
+  const content = fs.readFileSync(envPath, 'utf-8');
+  const vars = parseEnvFile(content);
+
+  const result = {};
+  for (const v of vars) {
+    result[v.key] = v.defaultValue || '';
+  }
+
+  return result;
+}
+
+/**
+ * Get startup commands from package.json
+ */
+export function getStartupCommands(projectPath) {
+  const pkgPath = path.join(projectPath, 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    return null;
+  }
+
+  const pkg = fs.readJsonSync(pkgPath);
+  const scripts = pkg.scripts || {};
+
+  const startupScripts = [];
+  const commonStartScripts = ['dev', 'start', 'serve', 'develop', 'start:dev'];
+
+  for (const name of commonStartScripts) {
+    if (scripts[name]) {
+      startupScripts.push({ name, command: scripts[name] });
+    }
+  }
+
+  // Also include build if exists
+  if (scripts.build) {
+    startupScripts.push({ name: 'build', command: scripts.build });
+  }
+
+  return startupScripts.length > 0 ? startupScripts : null;
+}
+
+/**
+ * Run full project setup
+ */
+export async function runProjectSetup(projectPath, options = {}) {
+  const results = {
+    packageManager: null,
+    depsInstalled: false,
+    nodeVersion: null,
+    envCreated: false,
+    startupCommands: null
+  };
+
+  // 1. Detect package manager
+  const pm = detectPackageManager(projectPath);
+  if (!pm) {
+    return results; // Not a Node.js project
+  }
+  results.packageManager = pm;
+
+  // 2. Check node version
+  const nodeReq = detectNodeVersion(projectPath);
+  if (nodeReq) {
+    const currentNode = getCurrentNodeVersion();
+    const check = checkNodeVersion(nodeReq.version, currentNode);
+    results.nodeVersion = {
+      required: nodeReq.version,
+      current: currentNode,
+      file: nodeReq.file,
+      ok: check.ok,
+      warning: check.warning
+    };
+
+    if (!check.ok) {
+      console.log(chalk.yellow(`\n⚠️  Node version mismatch`));
+      console.log(chalk.yellow(`   Required: ${nodeReq.version} (from ${nodeReq.file})`));
+      console.log(chalk.yellow(`   Current:  ${currentNode}`));
+      console.log(chalk.gray(`   Consider using nvm: nvm install ${nodeReq.version}\n`));
+    }
+  }
+
+  // 3. Install dependencies if needed
+  if (!hasNodeModules(projectPath)) {
+    if (!options.yes) {
+      const { install } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'install',
+        message: `No node_modules found. Run ${chalk.cyan(pm.install)}?`,
+        default: true
+      }]);
+
+      if (install) {
+        console.log(chalk.cyan(`\nRunning ${pm.install}...\n`));
+        results.depsInstalled = await installDeps(projectPath, pm);
+      }
+    } else {
+      console.log(chalk.cyan(`\nRunning ${pm.install}...\n`));
+      results.depsInstalled = await installDeps(projectPath, pm);
+    }
+  } else {
+    results.depsInstalled = true; // Already installed
+  }
+
+  // 4. Setup .env from example
+  // Always prompt for env values since they're required to run the app
+  const envExample = detectEnvExample(projectPath);
+  if (envExample) {
+    const hasEnv = hasEnvFile(projectPath);
+
+    if (!hasEnv) {
+      console.log(chalk.cyan(`\nFound ${envExample.file} with ${envExample.vars.length} variables`));
+
+      // Check if there are any vars that need user input (no default or secrets)
+      const needsInput = envExample.vars.some(v => !v.hasDefault || v.isSecret);
+
+      if (needsInput) {
+        const { setupEnv } = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'setupEnv',
+          message: 'Set up .env file now? (required to run the app)',
+          default: true
+        }]);
+
+        if (setupEnv) {
+          const values = await promptEnvValues(envExample.vars);
+          const count = writeEnvFile(projectPath, values);
+          console.log(chalk.green(`\n✓ Created .env with ${count} variables`));
+          results.envCreated = true;
+        }
+      } else {
+        // All vars have defaults, auto-create .env
+        const values = {};
+        for (const v of envExample.vars) {
+          values[v.key] = v.defaultValue || '';
+        }
+        const count = writeEnvFile(projectPath, values);
+        console.log(chalk.green(`✓ Created .env with ${count} variables (using defaults)`));
+        results.envCreated = true;
+      }
+    } else {
+      // Check for missing vars in existing .env
+      const existingVars = readEnvFile(projectPath);
+      const missingVars = envExample.vars.filter(v => !existingVars[v.key]);
+
+      if (missingVars.length > 0) {
+        console.log(chalk.yellow(`\n⚠️  .env exists but missing ${missingVars.length} variables from ${envExample.file}`));
+
+        const { addMissing } = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'addMissing',
+          message: 'Add missing variables?',
+          default: true
+        }]);
+
+        if (addMissing) {
+          const newValues = await promptEnvValues(missingVars, existingVars);
+          const count = writeEnvFile(projectPath, newValues);
+          console.log(chalk.green(`\n✓ Updated .env with ${count} variables`));
+          results.envCreated = true;
+        }
+      } else {
+        console.log(chalk.green(`✓ .env already configured`));
+        results.envCreated = true;
+      }
+    }
+  }
+
+  // 5. Get startup commands
+  results.startupCommands = getStartupCommands(projectPath);
+
+  return results;
+}

package/src/utils/skills.js

@@ -11,8 +11,10 @@ import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-// Path to bundled skills (in npm package)
+// Paths to bundled content (in npm package)
 const SKILLS_SOURCE = path.join(__dirname, '../../skills');
+const KNOWLEDGE_SOURCE = path.join(__dirname, '../../knowledge');
+const SCRIPTS_SOURCE = path.join(__dirname, '../../project-scripts');
 
 /**
  * Get list of all available skills
@@ -251,3 +253,87 @@ export async function checkForUpdates(projectPath) {
 
   return updates;
 }
+
+/**
+ * Copy knowledge (stacks, domains) to project
+ */
+export async function copyKnowledgeToProject(projectPath) {
+  const targetPath = path.join(projectPath, '.claude', 'knowledge');
+
+  // Check if source exists
+  if (!await fs.pathExists(KNOWLEDGE_SOURCE)) {
+    return { copied: [], errors: [{ name: 'knowledge', error: 'Source not found' }] };
+  }
+
+  // Remove existing and copy fresh
+  await fs.remove(targetPath);
+  await fs.ensureDir(targetPath);
+
+  const copied = [];
+  const errors = [];
+
+  try {
+    const items = await fs.readdir(KNOWLEDGE_SOURCE);
+
+    for (const item of items) {
+      // Skip hidden files
+      if (item.startsWith('.')) continue;
+
+      const sourcePath = path.join(KNOWLEDGE_SOURCE, item);
+      const targetItemPath = path.join(targetPath, item);
+
+      try {
+        await fs.copy(sourcePath, targetItemPath);
+        copied.push(item);
+      } catch (e) {
+        errors.push({ name: item, error: e.message });
+      }
+    }
+  } catch (e) {
+    errors.push({ name: 'knowledge', error: e.message });
+  }
+
+  return { copied, errors };
+}
+
+/**
+ * Copy scripts (graph.py, etc.) to project
+ */
+export async function copyScriptsToProject(projectPath) {
+  const targetPath = path.join(projectPath, '.claude', 'scripts');
+
+  // Check if source exists
+  if (!await fs.pathExists(SCRIPTS_SOURCE)) {
+    return { copied: [], errors: [{ name: 'scripts', error: 'Source not found' }] };
+  }
+
+  // Remove existing and copy fresh
+  await fs.remove(targetPath);
+  await fs.ensureDir(targetPath);
+
+  const copied = [];
+  const errors = [];
+
+  try {
+    const items = await fs.readdir(SCRIPTS_SOURCE);
+
+    for (const item of items) {
+      // Skip hidden files
+      if (item.startsWith('.')) continue;
+
+      const sourcePath = path.join(SCRIPTS_SOURCE, item);
+      const targetItemPath = path.join(targetPath, item);
+
+      try {
+        await fs.copy(sourcePath, targetItemPath);
+        copied.push(item);
+      } catch (e) {
+        errors.push({ name: item, error: e.message });
+      }
+    }
+  } catch (e) {
+    errors.push({ name: 'scripts', error: e.message });
+  }
+
+  return { copied, errors };
+}