claudex-setup 0.2.1 → 0.3.0

package/README.md

@@ -206,7 +206,7 @@ npx claudex-setup --help             # Show help
 
 ## Backed by Research
 
-Every check and template is derived from the [CLAUDEX](https://github.com/DnaFin/claudex) research catalog — a systematic audit of 1,107 verified Claude Code techniques across 13 research categories. This includes findings from all 73 official Claude Code documentation pages, community reports, and hands-on experiments.
+Every check and template is derived from the [CLAUDEX](https://github.com/DnaFin/claudex-setup) research catalog — a systematic audit of 1,107 verified Claude Code techniques across 13 research categories. This includes findings from all 73 official Claude Code documentation pages, community reports, and hands-on experiments.
 
 The knowledge base is continuously updated. Run `npx claudex-setup` periodically to pick up new checks and improved templates.
 

package/bin/cli.js

@@ -14,15 +14,17 @@ const HELP = `
   Powered by 1,107 verified techniques.
 
   Usage:
-    npx claudex-setup              Run audit on current directory
-    npx claudex-setup audit        Same as above
-    npx claudex-setup setup        Apply recommended configuration
-    npx claudex-setup setup --auto Apply all recommendations without prompts
-    npx claudex-setup badge        Generate shields.io badge markdown
+    npx claudex-setup                  Run audit on current directory
+    npx claudex-setup audit            Same as above
+    npx claudex-setup setup            Apply recommended configuration
+    npx claudex-setup setup --auto     Apply all without prompts
+    npx claudex-setup interactive      Step-by-step guided wizard
+    npx claudex-setup watch            Monitor changes and re-audit live
+    npx claudex-setup badge            Generate shields.io badge markdown
 
   Options:
-    --verbose    Show detailed analysis
-    --json       Output as JSON
+    --verbose    Show all recommendations (not just critical/high)
+    --json       Output as JSON (for CI pipelines)
     --help       Show this help
     --version    Show version
 `;
@@ -53,6 +55,12 @@ async function main() {
       console.log('');
       console.log('Add this to your README.md');
       process.exit(0);
+    } else if (command === 'interactive' || command === 'wizard') {
+      const { interactive } = require('../src/interactive');
+      await interactive(options);
+    } else if (command === 'watch') {
+      const { watch } = require('../src/watch');
+      await watch(options);
     } else if (command === 'setup') {
       await setup(options);
     } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudex-setup",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Audit and optimize any project for Claude Code. Powered by 1107 verified techniques.",
   "main": "src/index.js",
   "bin": {
@@ -31,7 +31,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/DnaFin/claudex.git"
+    "url": "git+https://github.com/DnaFin/claudex-setup.git"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/audit.js

@@ -162,7 +162,7 @@ async function audit(options) {
   console.log(`  Add to README: ${getBadgeMarkdown(score)}`);
   console.log('');
   console.log(colorize('  Powered by CLAUDEX - 1,107 verified Claude Code techniques', 'dim'));
-  console.log(colorize('  https://github.com/DnaFin/claudex', 'dim'));
+  console.log(colorize('  https://github.com/DnaFin/claudex-setup', 'dim'));
   console.log('');
 
   return { score, passed: passed.length, failed: failed.length, stacks, results };

package/src/badge.js

@@ -7,7 +7,7 @@ function getBadgeUrl(score) {
 
 function getBadgeMarkdown(score) {
   const url = getBadgeUrl(score);
-  return `[![Claude Code Ready](${url})](https://github.com/DnaFin/claudex)`;
+  return `[![Claude Code Ready](${url})](https://github.com/DnaFin/claudex-setup)`;
 }
 
 module.exports = { getBadgeUrl, getBadgeMarkdown };

package/src/interactive.js

@@ -0,0 +1,111 @@
+/**
+ * Interactive mode - guides users step-by-step through Claude Code setup.
+ * Uses Node.js readline (zero dependencies).
+ */
+
+const readline = require('readline');
+const { TECHNIQUES, STACKS } = require('./techniques');
+const { ProjectContext } = require('./context');
+const { setup } = require('./setup');
+
+const COLORS = {
+  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+  red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m',
+  blue: '\x1b[36m', magenta: '\x1b[35m',
+};
+const c = (text, color) => `${COLORS[color] || ''}${text}${COLORS.reset}`;
+
+function ask(rl, question) {
+  return new Promise(resolve => rl.question(question, resolve));
+}
+
+async function interactive(options) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ctx = new ProjectContext(options.dir);
+  const stacks = ctx.detectStacks(STACKS);
+
+  console.log('');
+  console.log(c('  ╔═══════════════════════════════════════╗', 'magenta'));
+  console.log(c('  ║   claudex-setup interactive wizard    ║', 'magenta'));
+  console.log(c('  ╚═══════════════════════════════════════╝', 'magenta'));
+  console.log('');
+
+  if (stacks.length > 0) {
+    console.log(c(`  Detected stack: ${stacks.map(s => s.label).join(', ')}`, 'blue'));
+  }
+  console.log(c(`  Working directory: ${options.dir}`, 'dim'));
+  console.log('');
+
+  // Run audit silently
+  const results = [];
+  for (const [key, technique] of Object.entries(TECHNIQUES)) {
+    results.push({ key, ...technique, passed: technique.check(ctx) });
+  }
+  const failed = results.filter(r => !r.passed);
+  const passed = results.filter(r => r.passed);
+
+  console.log(`  ${c(`${passed.length}/${results.length}`, 'bold')} checks already passing.`);
+  console.log(`  ${c(String(failed.length), 'yellow')} improvements available.`);
+  console.log('');
+
+  if (failed.length === 0) {
+    console.log(c('  Your project is fully optimized for Claude Code!', 'green'));
+    rl.close();
+    return;
+  }
+
+  // Group by priority
+  const critical = failed.filter(r => r.impact === 'critical');
+  const high = failed.filter(r => r.impact === 'high');
+  const medium = failed.filter(r => r.impact === 'medium');
+  const groups = [
+    { label: 'Critical', color: 'red', items: critical },
+    { label: 'High Impact', color: 'yellow', items: high },
+    { label: 'Recommended', color: 'blue', items: medium },
+  ].filter(g => g.items.length > 0);
+
+  const toFix = [];
+
+  for (const group of groups) {
+    console.log(c(`  ── ${group.label} (${group.items.length}) ──`, group.color));
+    console.log('');
+
+    for (const item of group.items) {
+      console.log(`  ${c(item.name, 'bold')}`);
+      console.log(c(`  ${item.fix}`, 'dim'));
+      const answer = await ask(rl, c('  Fix this? (y/n/q) ', 'magenta'));
+
+      if (answer.toLowerCase() === 'q') {
+        console.log('');
+        console.log(c('  Stopping wizard.', 'dim'));
+        break;
+      }
+      if (answer.toLowerCase() === 'y' || answer.toLowerCase() === '') {
+        toFix.push(item.key);
+        console.log(c('  → Will fix', 'green'));
+      } else {
+        console.log(c('  → Skipped', 'dim'));
+      }
+      console.log('');
+    }
+  }
+
+  rl.close();
+
+  if (toFix.length === 0) {
+    console.log(c('  No changes selected.', 'dim'));
+    return;
+  }
+
+  console.log('');
+  console.log(c(`  Applying ${toFix.length} fixes...`, 'bold'));
+  console.log('');
+
+  // Run setup in auto mode
+  await setup({ ...options, auto: true });
+
+  console.log('');
+  console.log(c('  Done! Run `npx claudex-setup` to see your new score.', 'green'));
+}
+
+module.exports = { interactive };

package/src/watch.js

@@ -0,0 +1,101 @@
+/**
+ * Watch mode - monitors project for Claude Code config changes and re-audits.
+ * Uses Node.js fs.watch (zero dependencies).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { audit } = require('./audit');
+
+const COLORS = {
+  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+  green: '\x1b[32m', yellow: '\x1b[33m', blue: '\x1b[36m',
+};
+const c = (text, color) => `${COLORS[color] || ''}${text}${COLORS.reset}`;
+
+const WATCH_PATHS = [
+  'CLAUDE.md',
+  '.claude',
+  '.gitignore',
+  'package.json',
+  'tsconfig.json',
+  '.github',
+];
+
+async function watch(options) {
+  console.log('');
+  console.log(c('  claudex-setup watch mode', 'bold'));
+  console.log(c('  ═══════════════════════════════════════', 'dim'));
+  console.log(c(`  Watching: ${options.dir}`, 'dim'));
+  console.log(c('  Press Ctrl+C to stop', 'dim'));
+  console.log('');
+
+  // Initial audit
+  let lastScore = null;
+  try {
+    const result = await audit({ ...options, silent: true });
+    lastScore = result.score;
+    console.log(`  ${c('Initial score:', 'bold')} ${scoreColor(result.score)}`);
+    console.log(`  ${result.passed} / ${result.passed + result.failed} checks passing`);
+    console.log('');
+  } catch (e) {
+    console.log(c(`  Initial audit failed: ${e.message}`, 'dim'));
+  }
+
+  // Watch relevant paths
+  const watchers = [];
+  let debounceTimer = null;
+
+  for (const watchPath of WATCH_PATHS) {
+    const fullPath = path.join(options.dir, watchPath);
+    try {
+      const watcher = fs.watch(fullPath, { recursive: true }, (eventType, filename) => {
+        // Debounce: wait 500ms after last change
+        clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(async () => {
+          const timestamp = new Date().toLocaleTimeString();
+          console.log(c(`  [${timestamp}] Change detected: ${filename || watchPath}`, 'dim'));
+
+          try {
+            const result = await audit({ ...options, silent: true });
+            const delta = lastScore !== null ? result.score - lastScore : 0;
+            const arrow = delta > 0 ? c(`+${delta}`, 'green') : delta < 0 ? c(String(delta), 'yellow') : '';
+
+            console.log(`  Score: ${scoreColor(result.score)} ${arrow}  (${result.passed}/${result.passed + result.failed} passing)`);
+
+            if (result.score > lastScore) {
+              console.log(c('  Nice improvement!', 'green'));
+            } else if (result.score < lastScore) {
+              console.log(c('  Score dropped - check what changed.', 'yellow'));
+            }
+            lastScore = result.score;
+            console.log('');
+          } catch (e) {
+            // Ignore transient errors during file saves
+          }
+        }, 500);
+      });
+      watchers.push(watcher);
+    } catch (e) {
+      // Path doesn't exist yet - that's fine
+    }
+  }
+
+  if (watchers.length === 0) {
+    console.log(c('  No watchable paths found. Create CLAUDE.md or .claude/ to start.', 'yellow'));
+    return;
+  }
+
+  console.log(c(`  Watching ${watchers.length} paths for changes...`, 'dim'));
+  console.log('');
+
+  // Keep alive
+  await new Promise(() => {});
+}
+
+function scoreColor(score) {
+  const color = score >= 70 ? 'green' : score >= 40 ? 'yellow' : 'dim';
+  return c(`${score}/100`, color);
+}
+
+module.exports = { watch };