claudex-setup 0.2.0 → 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,14 +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                  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
 `;
@@ -45,7 +48,20 @@ async function main() {
   };
 
   try {
-    if (command === 'setup') {
+    if (command === 'badge') {
+      const { getBadgeMarkdown } = require('../src/badge');
+      const result = await audit({ ...options, silent: true });
+      console.log(getBadgeMarkdown(result.score));
+      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 {
       await audit(options);

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "claudex-setup",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Audit and optimize any project for Claude Code. Powered by 1107 verified techniques.",
   "main": "src/index.js",
   "bin": {
     "claudex-setup": "bin/cli.js"
   },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "scripts": {
     "start": "node bin/cli.js",
     "test": "node test/run.js"
@@ -25,7 +31,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/DnaFin/claudex"
+    "url": "git+https://github.com/DnaFin/claudex-setup.git"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/audit.js

@@ -4,6 +4,7 @@
 
 const { TECHNIQUES, STACKS } = require('./techniques');
 const { ProjectContext } = require('./context');
+const { getBadgeMarkdown } = require('./badge');
 
 const COLORS = {
   reset: '\x1b[0m',
@@ -27,7 +28,24 @@ function progressBar(score, max = 100, width = 20) {
   return colorize('█'.repeat(filled), color) + colorize('░'.repeat(empty), 'dim');
 }
 
+const EFFORT_ORDER = { critical: 0, high: 1, medium: 2 };
+
+function getQuickWins(failed) {
+  // Quick wins = medium impact items first (easiest), then high, sorted by name length (shorter = simpler)
+  return [...failed]
+    .sort((a, b) => {
+      const effortA = EFFORT_ORDER[a.impact] ?? 3;
+      const effortB = EFFORT_ORDER[b.impact] ?? 3;
+      // Prefer medium (easiest to fix), then high, then critical
+      if (effortA !== effortB) return effortB - effortA;
+      // Tie-break by fix length (shorter fix description = likely simpler)
+      return (a.fix || '').length - (b.fix || '').length;
+    })
+    .slice(0, 3);
+}
+
 async function audit(options) {
+  const silent = options.silent || false;
   const ctx = new ProjectContext(options.dir);
   const stacks = ctx.detectStacks(STACKS);
   const results = [];
@@ -54,9 +72,14 @@ async function audit(options) {
   const earnedScore = passed.reduce((sum, r) => sum + (weights[r.impact] || 5), 0);
   const score = Math.round((earnedScore / maxScore) * 100);
 
+  // Silent mode: skip all output, just return result
+  if (silent) {
+    return { score, passed: passed.length, failed: failed.length, stacks, results };
+  }
+
   if (options.json) {
     console.log(JSON.stringify({ score, stacks, passed: passed.length, failed: failed.length, results }, null, 2));
-    return;
+    return { score, passed: passed.length, failed: failed.length, stacks, results };
   }
 
   // Display results
@@ -115,6 +138,18 @@ async function audit(options) {
     console.log('');
   }
 
+  // Quick wins
+  if (failed.length > 0) {
+    const quickWins = getQuickWins(failed);
+    console.log(colorize('  ⚡ Quick wins (easiest fixes first)', 'magenta'));
+    for (let i = 0; i < quickWins.length; i++) {
+      const r = quickWins[i];
+      console.log(`     ${i + 1}. ${colorize(r.name, 'bold')}`);
+      console.log(colorize(`        → ${r.fix}`, 'dim'));
+    }
+    console.log('');
+  }
+
   // Summary
   console.log(colorize('  ─────────────────────────────────────', 'dim'));
   console.log(`  ${colorize(`${passed.length}/${results.length}`, 'bold')} checks passing`);
@@ -123,12 +158,14 @@ async function audit(options) {
     console.log(`  Run ${colorize('npx claudex-setup setup', 'bold')} to fix automatically`);
   }
 
+  console.log('');
+  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/naorp/claudex-setup', 'dim'));
+  console.log(colorize('  https://github.com/DnaFin/claudex-setup', 'dim'));
   console.log('');
 
-  return { score, passed: passed.length, failed: failed.length, stacks };
+  return { score, passed: passed.length, failed: failed.length, stacks, results };
 }
 
 module.exports = { audit };

package/src/badge.js

@@ -0,0 +1,13 @@
+function getBadgeUrl(score) {
+  const color = score >= 80 ? 'brightgreen' : score >= 60 ? 'yellow' : score >= 40 ? 'orange' : 'red';
+  const label = encodeURIComponent('Claude Code Ready');
+  const message = encodeURIComponent(`${score}/100`);
+  return `https://img.shields.io/badge/${label}-${message}-${color}`;
+}
+
+function getBadgeMarkdown(score) {
+  const url = getBadgeUrl(score);
+  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 };