claude-devkit-cli 1.0.0

package/bin/devkit.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { cli } from '../src/cli.js';
+cli(process.argv);

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "claude-devkit-cli",
+  "version": "1.0.0",
+  "description": "CLI toolkit for spec-first development with Claude Code — hooks, commands, guards, and test runners",
+  "bin": {
+    "claude-devkit": "./bin/devkit.js",
+    "claude-devkit-cli": "./bin/devkit.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "devkit",
+    "spec-first",
+    "testing",
+    "hooks",
+    "guards"
+  ],
+  "scripts": {
+    "prepublishOnly": "rm -rf templates && cp -r ../kit templates",
+    "dev": "node bin/devkit.js"
+  },
+  "license": "MIT",
+  "type": "module"
+}

package/src/cli.js

@@ -0,0 +1,72 @@
+import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(resolve(__dirname, '../package.json'), 'utf-8'));
+
+export function cli(argv) {
+  const program = new Command();
+
+  program
+    .name('claude-devkit')
+    .description('CLI toolkit for spec-first development with Claude Code')
+    .version(pkg.version);
+
+  program
+    .command('init [path]')
+    .description('Initialize a project with the dev-kit')
+    .option('-f, --force', 'Overwrite existing files')
+    .option('--only <components>', 'Install only specific components (comma-separated: hooks,commands,scripts,docs,config)')
+    .option('--adopt', 'Adopt existing kit files without overwriting (migration from setup.sh)')
+    .option('--dry-run', 'Show what would be done without making changes')
+    .action(async (path, opts) => {
+      const { initCommand } = await import('./commands/init.js');
+      await initCommand(path || '.', opts);
+    });
+
+  program
+    .command('upgrade [path]')
+    .description('Smart upgrade — preserves customized files')
+    .option('-f, --force', 'Overwrite even customized files')
+    .option('--dry-run', 'Show what would be done without making changes')
+    .action(async (path, opts) => {
+      const { upgradeCommand } = await import('./commands/upgrade.js');
+      await upgradeCommand(path || '.', opts);
+    });
+
+  program
+    .command('check [path]')
+    .description('Check if an update is available')
+    .action(async (path) => {
+      const { checkCommand } = await import('./commands/check.js');
+      await checkCommand(path || '.');
+    });
+
+  program
+    .command('list [path]')
+    .description('List installed components and their status')
+    .action(async (path) => {
+      const { listCommand } = await import('./commands/list.js');
+      await listCommand(path || '.');
+    });
+
+  program
+    .command('diff [path]')
+    .description('Show differences between installed and latest kit files')
+    .action(async (path) => {
+      const { diffCommand } = await import('./commands/diff.js');
+      await diffCommand(path || '.');
+    });
+
+  program
+    .command('remove [path]')
+    .description('Uninstall dev-kit (preserves CLAUDE.md and docs/)')
+    .action(async (path) => {
+      const { removeCommand } = await import('./commands/remove.js');
+      await removeCommand(path || '.');
+    });
+
+  program.parse(argv);
+}

package/src/commands/check.js

@@ -0,0 +1,33 @@
+import { resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { log } from '../lib/logger.js';
+import { readManifest } from '../lib/manifest.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf-8'));
+
+export async function checkCommand(path) {
+  const targetDir = resolve(path);
+  const manifest = await readManifest(targetDir);
+
+  if (!manifest) {
+    log.fail('No manifest found. Run `claude-devkit init` first.');
+    process.exit(1);
+  }
+
+  const installed = manifest.version;
+  const latest = pkg.version;
+
+  log.info(`Installed: ${installed}`);
+  log.info(`Latest:    ${latest}`);
+  log.blank();
+
+  if (installed === latest) {
+    log.pass('Up to date.');
+  } else {
+    log.warn(`Update available: ${installed} → ${latest}`);
+    console.log('Run: npx claude-devkit upgrade');
+  }
+}

package/src/commands/diff.js

@@ -0,0 +1,90 @@
+import { resolve } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import chalk from 'chalk';
+import { log } from '../lib/logger.js';
+import { readManifest } from '../lib/manifest.js';
+import { hashFile } from '../lib/hasher.js';
+import { getAllFiles, getTemplateDir } from '../lib/installer.js';
+
+export async function diffCommand(path) {
+  const targetDir = resolve(path);
+  const manifest = await readManifest(targetDir);
+
+  if (!manifest) {
+    log.fail('No manifest found. Run `claude-devkit init` first.');
+    process.exit(1);
+  }
+
+  const templateDir = getTemplateDir();
+  const allFiles = getAllFiles();
+  let hasDiffs = false;
+
+  for (const file of allFiles) {
+    const templatePath = resolve(templateDir, file);
+    const installedPath = resolve(targetDir, file);
+
+    if (!existsSync(installedPath)) {
+      // File in kit but not installed
+      console.log(chalk.cyan(`\n${file} (new in kit — not installed)`));
+      hasDiffs = true;
+      continue;
+    }
+
+    const kitHash = await hashFile(templatePath);
+    const installedHash = await hashFile(installedPath);
+
+    if (kitHash === installedHash) continue;
+
+    hasDiffs = true;
+
+    // Check if kit changed or user changed
+    const entry = manifest.files[file];
+    const kitChanged = entry && kitHash !== entry.kitHash;
+    const userChanged = entry && entry.customized;
+
+    let label = '';
+    if (kitChanged && userChanged) label = 'both kit and local changed';
+    else if (kitChanged) label = 'kit updated';
+    else if (userChanged) label = 'locally customized';
+    else label = 'differs';
+
+    console.log(chalk.bold(`\n${file}`) + chalk.gray(` (${label})`));
+    console.log('─'.repeat(60));
+
+    // Simple line-by-line diff
+    const kitContent = await readFile(templatePath, 'utf-8');
+    const installedContent = await readFile(installedPath, 'utf-8');
+    const kitLines = kitContent.split('\n');
+    const installedLines = installedContent.split('\n');
+
+    // Show a simplified diff: lines only in kit (green +), only in installed (red -)
+    const kitSet = new Set(kitLines);
+    const installedSet = new Set(installedLines);
+
+    const removed = installedLines.filter((l) => !kitSet.has(l) && l.trim());
+    const added = kitLines.filter((l) => !installedSet.has(l) && l.trim());
+
+    for (const line of removed.slice(0, 10)) {
+      console.log(chalk.red(`  - ${line}`));
+    }
+    for (const line of added.slice(0, 10)) {
+      console.log(chalk.green(`  + ${line}`));
+    }
+    if (removed.length > 10 || added.length > 10) {
+      console.log(chalk.gray(`  ... and ${Math.max(removed.length - 10, 0) + Math.max(added.length - 10, 0)} more lines`));
+    }
+  }
+
+  // Check for files in manifest not in current kit
+  for (const file of Object.keys(manifest.files)) {
+    if (!allFiles.includes(file)) {
+      console.log(chalk.yellow(`\n${file} (removed from kit)`));
+      hasDiffs = true;
+    }
+  }
+
+  if (!hasDiffs) {
+    log.pass('All files match the kit. No differences.');
+  }
+}

package/src/commands/init.js

@@ -0,0 +1,232 @@
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { log } from '../lib/logger.js';
+import { detectProject } from '../lib/detector.js';
+import { readManifest, writeManifest, createManifest, setFileEntry } from '../lib/manifest.js';
+import { hashFile } from '../lib/hasher.js';
+import {
+  getAllFiles, getFilesForComponents, installFile,
+  ensurePlaceholderDir, setPermissions, fillTemplate,
+  verifySettingsJson, PLACEHOLDER_DIRS, COMPONENTS,
+  getTemplateDir,
+} from '../lib/installer.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf-8'));
+
+export async function initCommand(path, opts) {
+  const targetDir = resolve(path);
+
+  if (!existsSync(targetDir)) {
+    log.fail(`Directory not found: ${targetDir}`);
+    process.exit(1);
+  }
+
+  log.info(`claude-devkit v${pkg.version}`);
+  log.info(`Target: ${targetDir}`);
+  log.blank();
+
+  // --- Adopt mode ---
+  if (opts.adopt) {
+    await adoptExisting(targetDir);
+    return;
+  }
+
+  // --- Prerequisites ---
+  let warnings = 0;
+
+  if (!commandExists('git')) {
+    log.fail('Git not found — required');
+    process.exit(1);
+  }
+
+  if (!commandExists('node')) {
+    log.warn('Node.js not found — file-guard.js hook requires it');
+    warnings++;
+  }
+
+  if (!existsSync(resolve(targetDir, '.git'))) {
+    log.warn('Not a git repository. Some features need git.');
+    warnings++;
+  }
+
+  // --- Determine files to install ---
+  let components = Object.keys(COMPONENTS);
+  if (opts.only) {
+    components = opts.only.split(',').map((c) => c.trim());
+    const valid = Object.keys(COMPONENTS);
+    for (const c of components) {
+      if (!valid.includes(c)) {
+        log.fail(`Unknown component: ${c}. Valid: ${valid.join(', ')}`);
+        process.exit(1);
+      }
+    }
+  }
+
+  const files = opts.only ? getFilesForComponents(components) : getAllFiles();
+
+  // --- Dry run ---
+  if (opts.dryRun) {
+    log.info('Dry run — no changes will be made');
+    log.blank();
+    for (const file of files) {
+      const dst = resolve(targetDir, file);
+      if (existsSync(dst) && !opts.force) {
+        log.skip(`${file} (exists)`);
+      } else {
+        log.copy(`${file} (would copy)`);
+      }
+    }
+    return;
+  }
+
+  // --- Install files ---
+  console.log('--- Installing ---');
+
+  const manifest = createManifest(pkg.version, null, components);
+  let copied = 0;
+  let skipped = 0;
+
+  for (const file of files) {
+    const result = await installFile(file, targetDir, { force: opts.force });
+    if (result === 'copied') copied++;
+    else skipped++;
+
+    // Record in manifest
+    const templatePath = resolve(getTemplateDir(), file);
+    const installedPath = resolve(targetDir, file);
+    const kitHash = await hashFile(templatePath);
+    let installedHash = kitHash;
+    try {
+      installedHash = await hashFile(installedPath);
+    } catch { /* file might not exist if skipped */ }
+    setFileEntry(manifest, file, kitHash, installedHash);
+  }
+
+  // Placeholder directories
+  for (const dir of PLACEHOLDER_DIRS) {
+    await ensurePlaceholderDir(dir, targetDir);
+  }
+
+  // --- Permissions ---
+  await setPermissions(targetDir);
+
+  // --- Project detection ---
+  log.blank();
+  console.log('--- Detecting project ---');
+
+  const projectInfo = detectProject(targetDir);
+  if (projectInfo) {
+    log.info(`Detected: ${projectInfo.lang} (${projectInfo.framework})`);
+    log.info(`Source: ${projectInfo.srcDir} | Tests: ${projectInfo.testDir}`);
+    manifest.projectType = { lang: projectInfo.lang, framework: projectInfo.framework };
+
+    await fillTemplate(targetDir, projectInfo);
+    log.info('Updated CLAUDE.md with project info');
+
+    // Re-hash CLAUDE.md after template fill
+    try {
+      const claudeHash = await hashFile(resolve(targetDir, '.claude/CLAUDE.md'));
+      if (manifest.files['.claude/CLAUDE.md']) {
+        manifest.files['.claude/CLAUDE.md'].installedHash = claudeHash;
+        manifest.files['.claude/CLAUDE.md'].customized = false; // Template fill is not "customization"
+      }
+    } catch { /* */ }
+  } else {
+    log.warn('Could not detect project type. Fill in CLAUDE.md manually.');
+    warnings++;
+  }
+
+  // --- Write manifest ---
+  await writeManifest(targetDir, manifest);
+
+  // --- Verification ---
+  log.blank();
+  console.log('--- Verification ---');
+
+  if (await verifySettingsJson(targetDir)) {
+    log.pass('settings.json is valid JSON');
+  } else {
+    log.fail('settings.json is invalid JSON');
+  }
+
+  // --- Summary ---
+  log.blank();
+  console.log('=== Setup Complete ===');
+  log.blank();
+  console.log('Installed:');
+  console.log('  .claude/CLAUDE.md          — Project rules (review and customize)');
+  console.log('  .claude/settings.json      — Hook configuration');
+  console.log('  .claude/hooks/             — 6 guards (file, path, glob, comment, sensitive, self-review)');
+  console.log('  .claude/commands/          — /plan, /test, /fix, /review, /commit, /challenge');
+  console.log('  scripts/build-test.sh      — Universal test runner');
+  console.log('  docs/WORKFLOW.md           — Workflow reference');
+  log.blank();
+  console.log(`  ${copied} files copied, ${skipped} skipped`);
+  log.blank();
+  console.log('Next steps:');
+  console.log('  1. Review .claude/CLAUDE.md — ensure project info is correct');
+  console.log('  2. Write your first spec:   docs/specs/<feature>.md');
+  console.log('  3. Generate test plan:      /plan docs/specs/<feature>.md');
+  console.log('  4. Start coding + testing:  /test');
+  log.blank();
+
+  if (warnings > 0) {
+    console.log(`⚠ ${warnings} warning(s) above — review before proceeding.`);
+  }
+}
+
+/**
+ * Adopt existing kit files (migration from setup.sh).
+ * Scans for existing files and generates a manifest without overwriting.
+ */
+async function adoptExisting(targetDir) {
+  log.info('Adopting existing kit files...');
+  log.blank();
+
+  const allFiles = getAllFiles();
+  const manifest = createManifest(pkg.version, null, Object.keys(COMPONENTS));
+  let adopted = 0;
+
+  for (const file of allFiles) {
+    const installedPath = resolve(targetDir, file);
+    const templatePath = resolve(getTemplateDir(), file);
+
+    if (!existsSync(installedPath)) continue;
+
+    const installedHash = await hashFile(installedPath);
+    let kitHash;
+    try {
+      kitHash = await hashFile(templatePath);
+    } catch {
+      kitHash = installedHash; // Template doesn't exist, treat as matching
+    }
+    setFileEntry(manifest, file, kitHash, installedHash);
+    log.adopt(file);
+    adopted++;
+  }
+
+  // Detect project
+  const projectInfo = detectProject(targetDir);
+  if (projectInfo) {
+    manifest.projectType = { lang: projectInfo.lang, framework: projectInfo.framework };
+    log.info(`Detected: ${projectInfo.lang} (${projectInfo.framework})`);
+  }
+
+  await writeManifest(targetDir, manifest);
+  log.blank();
+  log.pass(`Manifest created for ${adopted} existing files. Future upgrades will work.`);
+}
+
+function commandExists(cmd) {
+  try {
+    execSync(`command -v ${cmd}`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/commands/list.js

@@ -0,0 +1,50 @@
+import { resolve } from 'node:path';
+import chalk from 'chalk';
+import { log } from '../lib/logger.js';
+import { readManifest, refreshCustomizationStatus } from '../lib/manifest.js';
+
+export async function listCommand(path) {
+  const targetDir = resolve(path);
+  const manifest = await readManifest(targetDir);
+
+  if (!manifest) {
+    log.fail('No manifest found. Run `claude-devkit init` first.');
+    process.exit(1);
+  }
+
+  // Refresh hashes to get accurate customization status
+  await refreshCustomizationStatus(targetDir, manifest);
+
+  log.info(`claude-devkit v${manifest.version} — installed ${manifest.installedAt.split('T')[0]}`);
+  if (manifest.projectType) {
+    log.info(`Project: ${manifest.projectType.lang} (${manifest.projectType.framework})`);
+  }
+  log.blank();
+
+  // Table header
+  const fileCol = 40;
+  console.log(
+    chalk.bold('File'.padEnd(fileCol)) + chalk.bold('Status')
+  );
+  console.log('─'.repeat(fileCol) + '  ' + '─'.repeat(12));
+
+  let totalFiles = 0;
+  let customized = 0;
+
+  for (const [file, entry] of Object.entries(manifest.files)) {
+    totalFiles++;
+    let status;
+    if (entry.installedHash === null) {
+      status = chalk.red('deleted');
+    } else if (entry.customized) {
+      status = chalk.yellow('customized');
+      customized++;
+    } else {
+      status = chalk.green('up-to-date');
+    }
+    console.log(file.padEnd(fileCol) + status);
+  }
+
+  log.blank();
+  console.log(`${totalFiles} files | ${customized} customized`);
+}

package/src/commands/remove.js

@@ -0,0 +1,74 @@
+import { resolve, join } from 'node:path';
+import { unlink, rmdir, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { log } from '../lib/logger.js';
+import { readManifest } from '../lib/manifest.js';
+
+const PRESERVE = [
+  '.claude/CLAUDE.md',
+];
+
+const PRESERVE_DIRS = [
+  'docs/',
+];
+
+export async function removeCommand(path) {
+  const targetDir = resolve(path);
+  const manifest = await readManifest(targetDir);
+
+  if (!manifest) {
+    log.fail('No manifest found. Nothing to remove.');
+    process.exit(1);
+  }
+
+  log.info('Removing claude-devkit files...');
+  log.blank();
+
+  // Remove tracked files (except preserved)
+  for (const file of Object.keys(manifest.files)) {
+    const fullPath = join(targetDir, file);
+
+    // Check if preserved
+    if (PRESERVE.includes(file)) {
+      log.keep(file);
+      continue;
+    }
+
+    // Check if in preserved directory
+    if (PRESERVE_DIRS.some((dir) => file.startsWith(dir))) {
+      log.keep(file);
+      continue;
+    }
+
+    if (existsSync(fullPath)) {
+      await unlink(fullPath);
+      log.del(file);
+    }
+  }
+
+  // Remove manifest itself
+  const manifestPath = join(targetDir, '.claude/.devkit-manifest.json');
+  if (existsSync(manifestPath)) {
+    await unlink(manifestPath);
+    log.del('.claude/.devkit-manifest.json');
+  }
+
+  // Clean up empty directories
+  const dirsToClean = [
+    '.claude/hooks',
+    '.claude/commands',
+    'scripts',
+  ];
+
+  for (const dir of dirsToClean) {
+    const fullPath = join(targetDir, dir);
+    try {
+      await rmdir(fullPath);
+    } catch {
+      // Not empty or doesn't exist
+    }
+  }
+
+  log.blank();
+  log.pass('Removed. CLAUDE.md and docs/ preserved.');
+}