claude-devkit-cli 1.0.0

package/src/commands/upgrade.js

@@ -0,0 +1,108 @@
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { copyFile as fsCopyFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { log } from '../lib/logger.js';
+import { hashFile } from '../lib/hasher.js';
+import { readManifest, writeManifest, setFileEntry, refreshCustomizationStatus } from '../lib/manifest.js';
+import { getAllFiles, getTemplateDir, setPermissions } 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 upgradeCommand(path, opts) {
+  const targetDir = resolve(path);
+  const manifest = await readManifest(targetDir);
+
+  if (!manifest) {
+    log.fail('No manifest found. Run `claude-devkit init` first, or `claude-devkit init --adopt` to adopt existing files.');
+    process.exit(1);
+  }
+
+  // Refresh customization status by re-hashing installed files
+  await refreshCustomizationStatus(targetDir, manifest);
+
+  log.info(`claude-devkit upgrade: ${manifest.version} → ${pkg.version}`);
+  log.blank();
+
+  if (opts.dryRun) {
+    log.info('Dry run — no changes will be made');
+    log.blank();
+  }
+
+  const templateDir = getTemplateDir();
+  const allFiles = getAllFiles();
+
+  let updated = 0;
+  let skippedCustomized = 0;
+  let added = 0;
+  let unchanged = 0;
+
+  for (const file of allFiles) {
+    const templatePath = resolve(templateDir, file);
+    const installedPath = resolve(targetDir, file);
+    const currentKitHash = await hashFile(templatePath);
+    const entry = manifest.files[file];
+
+    if (!entry) {
+      // New file in kit — install it
+      if (!opts.dryRun) {
+        await mkdir(dirname(installedPath), { recursive: true });
+        await fsCopyFile(templatePath, installedPath);
+        setFileEntry(manifest, file, currentKitHash, currentKitHash);
+      }
+      log.copy(`${file} (new)`);
+      added++;
+      continue;
+    }
+
+    const kitChanged = currentKitHash !== entry.kitHash;
+
+    if (!kitChanged) {
+      log.same(file);
+      unchanged++;
+      continue;
+    }
+
+    // Kit has changed
+    if (entry.customized && !opts.force) {
+      log.skip(`${file} (customized — use --force to overwrite)`);
+      skippedCustomized++;
+      continue;
+    }
+
+    // Kit changed, user hasn't customized (or --force) → update
+    if (!opts.dryRun) {
+      await mkdir(dirname(installedPath), { recursive: true });
+      await fsCopyFile(templatePath, installedPath);
+      setFileEntry(manifest, file, currentKitHash, currentKitHash);
+    }
+    log.copy(file);
+    updated++;
+  }
+
+  // Check for files in manifest that no longer exist in kit
+  for (const file of Object.keys(manifest.files)) {
+    if (!allFiles.includes(file)) {
+      log.warn(`${file} — no longer in kit (keeping)`);
+    }
+  }
+
+  // Update manifest
+  if (!opts.dryRun) {
+    manifest.version = pkg.version;
+    manifest.updatedAt = new Date().toISOString();
+    await setPermissions(targetDir);
+    await writeManifest(targetDir, manifest);
+  }
+
+  // Summary
+  log.blank();
+  log.pass(`Updated ${updated}, added ${added}, unchanged ${unchanged}, skipped ${skippedCustomized} customized.`);
+
+  if (skippedCustomized > 0) {
+    log.warn(`${skippedCustomized} customized file(s) skipped. Run with --force to overwrite.`);
+  }
+}

package/src/lib/detector.js

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Auto-detect project type from marker files.
+ * @param {string} targetDir
+ * @returns {{ lang: string, framework: string, srcDir: string, testDir: string } | null}
+ */
+export function detectProject(targetDir) {
+  const has = (file) => existsSync(join(targetDir, file));
+  const hasGlob = (ext) => {
+    try {
+      return readdirSync(targetDir).some((f) => f.endsWith(ext));
+    } catch {
+      return false;
+    }
+  };
+  const packageContains = (str) => {
+    try {
+      return readFileSync(join(targetDir, 'package.json'), 'utf-8').includes(str);
+    } catch {
+      return false;
+    }
+  };
+  const gemfileContains = (str) => {
+    try {
+      return readFileSync(join(targetDir, 'Gemfile'), 'utf-8').includes(str);
+    } catch {
+      return false;
+    }
+  };
+
+  // Swift (SPM)
+  if (has('Package.swift')) {
+    return { lang: 'Swift', framework: 'XCTest (SPM)', srcDir: 'Sources', testDir: 'Tests' };
+  }
+
+  // Swift (Xcode)
+  if (hasGlob('.xcworkspace') || hasGlob('.xcodeproj')) {
+    return { lang: 'Swift', framework: 'XCTest (Xcode)', srcDir: 'Sources', testDir: 'Tests' };
+  }
+
+  // Node.js / TypeScript
+  if (has('package.json')) {
+    let framework = 'npm test';
+    if (has('vitest.config.ts') || has('vitest.config.js') || has('vitest.config.mts') || packageContains('"vitest"')) {
+      framework = 'Vitest';
+    } else if (has('jest.config.ts') || has('jest.config.js') || has('jest.config.mjs') || packageContains('"jest"')) {
+      framework = 'Jest';
+    }
+    const testDir = existsSync(join(targetDir, '__tests__')) ? '__tests__' : 'tests';
+    return { lang: 'TypeScript/JavaScript', framework, srcDir: 'src', testDir };
+  }
+
+  // Python
+  if (has('pyproject.toml') || has('setup.py') || has('pytest.ini')) {
+    return { lang: 'Python', framework: 'pytest', srcDir: 'src', testDir: 'tests' };
+  }
+
+  // Rust
+  if (has('Cargo.toml')) {
+    return { lang: 'Rust', framework: 'cargo test', srcDir: 'src', testDir: 'tests' };
+  }
+
+  // Go
+  if (has('go.mod')) {
+    return { lang: 'Go', framework: 'go test', srcDir: '.', testDir: '.' };
+  }
+
+  // Java/Kotlin (Gradle)
+  if (has('build.gradle') || has('build.gradle.kts')) {
+    return { lang: 'Java/Kotlin', framework: 'Gradle', srcDir: 'src/main', testDir: 'src/test' };
+  }
+
+  // Java (Maven)
+  if (has('pom.xml')) {
+    return { lang: 'Java', framework: 'Maven', srcDir: 'src/main', testDir: 'src/test' };
+  }
+
+  // C# (.NET)
+  if (hasGlob('.sln')) {
+    return { lang: 'C#', framework: '.NET (dotnet test)', srcDir: 'src', testDir: 'tests' };
+  }
+
+  // Ruby
+  if (has('Gemfile')) {
+    const framework = gemfileContains('rspec') ? 'RSpec' : 'Minitest';
+    const testDir = framework === 'RSpec' ? 'spec' : 'test';
+    return { lang: 'Ruby', framework, srcDir: 'lib', testDir };
+  }
+
+  return null;
+}

package/src/lib/hasher.js

@@ -0,0 +1,21 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+
+/**
+ * Compute SHA-256 hash of a file.
+ * @param {string} filePath
+ * @returns {Promise<string>} hex digest
+ */
+export async function hashFile(filePath) {
+  const content = await readFile(filePath);
+  return createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Compute SHA-256 hash of a string/buffer.
+ * @param {string|Buffer} content
+ * @returns {string} hex digest
+ */
+export function hashContent(content) {
+  return createHash('sha256').update(content).digest('hex');
+}

package/src/lib/installer.js

@@ -0,0 +1,175 @@
+import { copyFile as fsCopyFile, mkdir, readFile, writeFile, access, constants } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { chmod } from 'node:fs/promises';
+import { log } from './logger.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Component → file mappings.
+ */
+export const COMPONENTS = {
+  hooks: [
+    '.claude/hooks/file-guard.js',
+    '.claude/hooks/path-guard.sh',
+    '.claude/hooks/comment-guard.js',
+    '.claude/hooks/glob-guard.js',
+    '.claude/hooks/self-review.sh',
+    '.claude/hooks/sensitive-guard.sh',
+  ],
+  commands: [
+    '.claude/commands/plan.md',
+    '.claude/commands/test.md',
+    '.claude/commands/fix.md',
+    '.claude/commands/review.md',
+    '.claude/commands/commit.md',
+    '.claude/commands/challenge.md',
+  ],
+  config: [
+    '.claude/settings.json',
+    '.claude/CLAUDE.md',
+  ],
+  scripts: [
+    'scripts/build-test.sh',
+  ],
+  docs: [
+    'docs/WORKFLOW.md',
+  ],
+};
+
+/**
+ * Placeholder directories to create.
+ */
+export const PLACEHOLDER_DIRS = [
+  'docs/specs',
+  'docs/test-plans',
+];
+
+/**
+ * Files that need +x permission.
+ */
+export const EXECUTABLE_FILES = [
+  'scripts/build-test.sh',
+  '.claude/hooks/path-guard.sh',
+  '.claude/hooks/self-review.sh',
+  '.claude/hooks/sensitive-guard.sh',
+];
+
+/**
+ * Get path to kit (templates) directory.
+ * Published package: cli/templates/  |  Dev mode: ../kit/
+ */
+export function getTemplateDir() {
+  const bundled = resolve(__dirname, '../../templates');
+  if (existsSync(bundled)) return bundled;
+  return resolve(__dirname, '../../../kit');
+}
+
+/**
+ * Get all files for the given component list.
+ * @param {string[]} components - e.g. ['hooks', 'commands']
+ * @returns {string[]} relative file paths
+ */
+export function getFilesForComponents(components) {
+  const files = [];
+  for (const comp of components) {
+    if (COMPONENTS[comp]) {
+      files.push(...COMPONENTS[comp]);
+    }
+  }
+  return files;
+}
+
+/**
+ * Get all installable files (all components).
+ */
+export function getAllFiles() {
+  return Object.values(COMPONENTS).flat();
+}
+
+/**
+ * Copy a single file from templates to target.
+ * @returns {string} 'copied' | 'skipped'
+ */
+export async function installFile(relativePath, targetDir, { force = false } = {}) {
+  const src = join(getTemplateDir(), relativePath);
+  const dst = join(targetDir, relativePath);
+
+  if (existsSync(dst) && !force) {
+    log.skip(`${relativePath} (exists, use --force to overwrite)`);
+    return 'skipped';
+  }
+
+  await mkdir(dirname(dst), { recursive: true });
+  await fsCopyFile(src, dst);
+  log.copy(relativePath);
+  return 'copied';
+}
+
+/**
+ * Create a placeholder directory with .gitkeep.
+ */
+export async function ensurePlaceholderDir(dir, targetDir) {
+  const fullPath = join(targetDir, dir);
+  if (existsSync(fullPath)) {
+    log.skip(`${dir}/ (exists)`);
+    return;
+  }
+  await mkdir(fullPath, { recursive: true });
+  await writeFile(join(fullPath, '.gitkeep'), '');
+  log.make(`${dir}/`);
+}
+
+/**
+ * Set executable permissions on relevant files.
+ */
+export async function setPermissions(targetDir) {
+  for (const file of EXECUTABLE_FILES) {
+    const fullPath = join(targetDir, file);
+    try {
+      await chmod(fullPath, 0o755);
+    } catch {
+      // File might not exist if component not installed
+    }
+  }
+}
+
+/**
+ * Fill [CUSTOMIZE] placeholders in CLAUDE.md with detected project info.
+ */
+export async function fillTemplate(targetDir, projectInfo) {
+  if (!projectInfo) return;
+
+  const claudeMdPath = join(targetDir, '.claude/CLAUDE.md');
+  try {
+    let content = await readFile(claudeMdPath, 'utf-8');
+    content = content
+      .replace(/\[CUSTOMIZE\] Language:.*/, `**Language:** ${projectInfo.lang}`)
+      .replace(/\[CUSTOMIZE\] Test framework:.*/, `**Test framework:** ${projectInfo.framework}`)
+      .replace(/\[CUSTOMIZE\] Source directory:.*/, `**Source directory:** ${projectInfo.srcDir}`)
+      .replace(/\[CUSTOMIZE\] Test directory:.*/, `**Test directory:** ${projectInfo.testDir}`)
+      // Also handle the format without [CUSTOMIZE] prefix
+      .replace(/\*\*Language:\*\* \[CUSTOMIZE\]/, `**Language:** ${projectInfo.lang}`)
+      .replace(/\*\*Test framework:\*\* \[CUSTOMIZE\]/, `**Test framework:** ${projectInfo.framework}`)
+      .replace(/\*\*Source directory:\*\* \[CUSTOMIZE\]/, `**Source directory:** ${projectInfo.srcDir}`)
+      .replace(/\*\*Test directory:\*\* \[CUSTOMIZE\]/, `**Test directory:** ${projectInfo.testDir}`);
+    await writeFile(claudeMdPath, content);
+  } catch {
+    // CLAUDE.md might not exist
+  }
+}
+
+/**
+ * Verify settings.json is valid JSON.
+ */
+export async function verifySettingsJson(targetDir) {
+  try {
+    const raw = await readFile(join(targetDir, '.claude/settings.json'), 'utf-8');
+    JSON.parse(raw);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/lib/logger.js

@@ -0,0 +1,16 @@
+import chalk from 'chalk';
+
+export const log = {
+  info:  (msg) => console.log(chalk.blue('[INFO]'), msg),
+  pass:  (msg) => console.log(chalk.green('[PASS]'), msg),
+  fail:  (msg) => console.log(chalk.red('[FAIL]'), msg),
+  warn:  (msg) => console.log(chalk.yellow('[WARN]'), msg),
+  skip:  (msg) => console.log(chalk.gray('[SKIP]'), msg),
+  copy:  (msg) => console.log(chalk.cyan('[COPY]'), msg),
+  del:   (msg) => console.log(chalk.red('[DEL]'), ' ', msg),
+  keep:  (msg) => console.log(chalk.green('[KEEP]'), msg),
+  make:  (msg) => console.log(chalk.cyan('[MAKE]'), msg),
+  adopt: (msg) => console.log(chalk.magenta('[ADOPT]'), msg),
+  same:  (msg) => console.log(chalk.gray('[SAME]'), msg),
+  blank: ()    => console.log(),
+};

package/src/lib/manifest.js

@@ -0,0 +1,79 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { hashFile } from './hasher.js';
+
+const MANIFEST_FILE = '.claude/.devkit-manifest.json';
+
+/**
+ * Read manifest from target directory.
+ * @returns {object|null}
+ */
+export async function readManifest(targetDir) {
+  try {
+    const raw = await readFile(join(targetDir, MANIFEST_FILE), 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write manifest to target directory.
+ */
+export async function writeManifest(targetDir, manifest) {
+  const filePath = join(targetDir, MANIFEST_FILE);
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, JSON.stringify(manifest, null, 2) + '\n');
+}
+
+/**
+ * Create a new empty manifest.
+ */
+export function createManifest(version, projectType, components) {
+  const now = new Date().toISOString();
+  return {
+    version,
+    installedAt: now,
+    updatedAt: now,
+    projectType: projectType || null,
+    components: components || ['hooks', 'commands', 'scripts', 'docs'],
+    files: {},
+  };
+}
+
+/**
+ * Add or update a file entry in the manifest.
+ */
+export function setFileEntry(manifest, relativePath, kitHash, installedHash) {
+  manifest.files[relativePath] = {
+    kitHash,
+    installedHash: installedHash || kitHash,
+    customized: installedHash ? installedHash !== kitHash : false,
+  };
+}
+
+/**
+ * Check if a file has been customized by the user.
+ */
+export function isCustomized(manifest, relativePath) {
+  const entry = manifest?.files?.[relativePath];
+  if (!entry) return false;
+  return entry.customized;
+}
+
+/**
+ * Refresh customization status by re-hashing installed files.
+ */
+export async function refreshCustomizationStatus(targetDir, manifest) {
+  for (const [relativePath, entry] of Object.entries(manifest.files)) {
+    try {
+      const currentHash = await hashFile(join(targetDir, relativePath));
+      entry.installedHash = currentHash;
+      entry.customized = currentHash !== entry.kitHash;
+    } catch {
+      // File was deleted
+      entry.installedHash = null;
+      entry.customized = true;
+    }
+  }
+}

package/templates/.claude/CLAUDE.md

@@ -0,0 +1,74 @@
+# Project Rules
+
+## Spec-First Development
+
+Every change follows this cycle: **SPEC → TEST PLAN → CODE + TESTS → BUILD PASS**.
+
+- Business logic specs live in `docs/specs/`
+- Test plans live in `docs/test-plans/`
+- Never write code before the spec exists. Never auto-modify specs from code.
+- Specs are the source of truth. If code contradicts the spec, the code is wrong.
+
+## Workflow Quick Reference
+
+| Trigger | Commands | Details |
+|---------|----------|---------|
+| New feature | `/plan` → code in chunks → `/test` each chunk | Start with spec or description |
+| Update feature | Update spec first → `/plan` (update plan) → code → `/test` | Spec changes before code changes |
+| Bug fix | `/fix "description"` | Test-first: write failing test → fix → green |
+| Remove feature | Mark spec as removed → delete code + tests → build pass | Run full suite after removal |
+| Stress-test plan | `/challenge` | Adversarial review before coding (optional) |
+| Pre-merge check | `/review` | Diff-based quality gate |
+| Commit changes | `/commit` | Secret scan + conventional commit |
+
+For detailed workflow steps, templates, and decision trees, see `docs/WORKFLOW.md`.
+
+## Testing
+
+- **Run tests:** `bash scripts/build-test.sh [--filter PATTERN]`
+- **Auto-detects:** Swift, Node, Python, Rust, Go, Java, C#, Ruby
+- **Compile/typecheck BEFORE running tests.** Catch syntax errors early.
+- **Max 3 fix loops** for test failures. If tests still fail after 3 attempts, stop and report.
+- **NEVER fix production code** to make a test pass — ask the user first.
+- **No mocks, fakes, stubs, or cheats** to pass builds. Real implementations only.
+  Test doubles are acceptable only when they replace external services (APIs, databases)
+  that cannot run locally.
+
+## Project Info
+
+> Fill these in when setting up the project (or let `setup.sh` do it automatically).
+
+- **Language:** [CUSTOMIZE]
+- **Test framework:** [CUSTOMIZE]
+- **Source directory:** [CUSTOMIZE]
+- **Test directory:** [CUSTOMIZE]
+
+## Conventions
+
+- **Commits:** Conventional format — `type(scope): description`
+  Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `perf`, `build`, `ci`
+- **File naming:** Descriptive enough that AI tools understand the purpose from the path alone.
+  Prefer kebab-case for new files (e.g., `user-authentication-service.ts`).
+- **Dates in filenames:** Use `$(date +%Y-%m-%d)` — never guess dates.
+- **Specs & test plans naming:**
+  - kebab-case, lowercase: `user-auth.md`, `file-sync.md`
+  - Feature name, not module name: `user-auth.md` not `AuthService.md`
+  - Spec and test plan share the SAME name: `docs/specs/user-auth.md` ↔ `docs/test-plans/user-auth.md`
+  - Short (2-3 words): `payment-flow.md` not `payment-processing-with-stripe-integration.md`
+  - No prefix/suffix: `user-auth.md` not `spec-user-auth.md`
+
+## Forbidden
+
+These patterns are never acceptable in this project:
+
+- `any` / `Any` type without explicit justification in a comment
+- Force unwrap (`!`) or force cast (`as!`) without a preceding guard
+- Hardcoded secrets, API keys, tokens, or credentials in source files
+- Mocks or fake data used solely to make tests pass
+- `git push --force` to main or master branches
+- Editing generated files, vendor directories, or lock files
+- Committing `.env` files, certificates, or private keys
+- Ignoring compiler/linter warnings without documented reason
+- Replacing real code with placeholder comments like `// ... existing code ...`
+- Renaming parameters to `_param` instead of actually fixing unused parameter issues
+- Reading or writing `.env`, `.pem`, `.key`, or other sensitive files (use `.env.example` for templates)