claudex-setup 0.5.0 → 1.0.0

package/README.md

@@ -67,7 +67,7 @@ No install. No config. No dependencies.
 |------|--------|
 | `--verbose` | Show all recommendations (not just critical/high) |
 | `--json` | Machine-readable JSON output (for CI) |
-| `--no-insights` | Disable anonymous usage insights |
+| `--insights` | Enable anonymous usage insights (off by default) |
 
 ## Smart CLAUDE.md Generation
 
@@ -76,7 +76,7 @@ Not a generic template. The `setup` command actually analyzes your project:
 - **Reads package.json** - includes your actual test, build, lint, dev commands
 - **Detects framework** - Next.js Server Components, Django models, FastAPI Pydantic, React hooks
 - **TypeScript-aware** - detects strict mode, adds TS-specific rules
-- **Auto Mermaid diagram** - scans directories and generates architecture visualization (73% token savings)
+- **Auto Mermaid diagram** - scans directories and generates architecture visualization (Mermaid diagrams are more token-efficient than prose descriptions, per Anthropic docs)
 - **XML constraint blocks** - adds `<constraints>` and `<verification>` with context-aware rules
 - **Verification criteria** - auto-generates checklist from your actual commands
 
@@ -145,7 +145,7 @@ Already have a solid CLAUDE.md and hooks? Two things for you:
 ### Deep Review (AI-powered)
 
 ```bash
-ANTHROPIC_API_KEY=sk-ant-... npx claudex-setup deep-review
+npx claudex-setup deep-review
 ```
 
 Claude reads your actual config and gives specific feedback: what's strong, what has issues, what's missing for your stack. Not pattern matching — real analysis. Your config goes to Anthropic API only, we never see it.
@@ -172,7 +172,7 @@ These checks evaluate **quality**, not just existence. A well-configured project
 
 - **Zero dependencies** - nothing to audit
 - **Runs 100% locally** - no cloud processing
-- **Anonymous insights** - opt-in, no PII, no file contents (disable with `--no-insights`)
+- **Anonymous insights** - opt-in, no PII, no file contents (enable with `--insights`)
 - **MIT Licensed** - use anywhere
 
 ## Backed by Research

package/bin/cli.js

@@ -11,14 +11,14 @@ const flags = args.filter(a => a.startsWith('--'));
 const HELP = `
   claudex-setup v${version}
   Audit and optimize any project for Claude Code.
-  Powered by 1,107 verified techniques.
+  Backed by research from 1,107 cataloged Claude Code entries.
 
   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 without prompts
-    npx claudex-setup deep-review       AI-powered config analysis (needs API key)
+    npx claudex-setup deep-review       AI-powered config review (uses Claude Code or API key)
     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
@@ -26,7 +26,7 @@ const HELP = `
   Options:
     --verbose       Show all recommendations (not just critical/high)
     --json          Output as JSON (for CI pipelines)
-    --no-insights   Disable anonymous usage insights
+    --insights       Enable anonymous usage insights (off by default)
     --help          Show this help
     --version       Show version
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudex-setup",
-  "version": "0.5.0",
+  "version": "1.0.0",
   "description": "Audit and optimize any project for Claude Code. Powered by 1107 verified techniques.",
   "main": "src/index.js",
   "bin": {

package/src/deep-review.js

@@ -7,6 +7,7 @@
  */
 
 const https = require('https');
+const path = require('path');
 const { ProjectContext } = require('./context');
 const { STACKS } = require('./techniques');
 
@@ -189,19 +190,45 @@ function callClaude(apiKey, prompt) {
   });
 }
 
+function hasClaudeCode() {
+  try {
+    require('child_process').execSync('claude --version', { stdio: 'ignore' });
+    return true;
+  } catch { return false; }
+}
+
+async function callClaudeCode(prompt) {
+  const { execSync } = require('child_process');
+  const os = require('os');
+  const fs = require('fs');
+  const tmpFile = path.join(os.tmpdir(), `claudex-review-${Date.now()}.txt`);
+  fs.writeFileSync(tmpFile, prompt, 'utf8');
+  try {
+    const result = execSync(`claude -p --output-format text < "${tmpFile}"`, {
+      encoding: 'utf8',
+      maxBuffer: 1024 * 1024,
+      timeout: 120000,
+      shell: true,
+    });
+    return result;
+  } finally {
+    try { fs.unlinkSync(tmpFile); } catch {}
+  }
+}
+
 async function deepReview(options) {
   const apiKey = process.env.ANTHROPIC_API_KEY;
-  if (!apiKey) {
-    console.log('');
-    console.log(c('  Deep Review requires an Anthropic API key.', 'bold'));
+  const hasClaude = hasClaudeCode();
+
+  if (!apiKey && !hasClaude) {
     console.log('');
-    console.log('  Set it with:');
-    console.log(c('    export ANTHROPIC_API_KEY=sk-ant-...', 'green'));
+    console.log(c('  Deep Review needs Claude Code or an API key.', 'bold'));
     console.log('');
-    console.log(c('  Or on Windows:', 'dim'));
-    console.log(c('    set ANTHROPIC_API_KEY=sk-ant-...', 'green'));
+    console.log('  Option A (recommended): Install Claude Code, then run this command.');
+    console.log(c('    npm install -g @anthropic-ai/claude-code', 'green'));
     console.log('');
-    console.log(c('  Your key is sent directly to Anthropic API. We never see or store it.', 'dim'));
+    console.log('  Option B: Set an API key:');
+    console.log(c('    export ANTHROPIC_API_KEY=sk-ant-...', 'green'));
     console.log('');
     process.exit(1);
   }
@@ -236,7 +263,20 @@ async function deepReview(options) {
 
   try {
     const prompt = buildPrompt(config);
-    const review = await callClaude(apiKey, prompt);
+    let review;
+    let method;
+
+    if (hasClaude) {
+      method = 'Claude Code (your existing subscription)';
+      console.log(c('  Using: Claude Code (no API key needed)', 'green'));
+      console.log('');
+      review = await callClaudeCode(prompt);
+    } else {
+      method = 'Anthropic API (your key)';
+      console.log(c('  Using: Anthropic API', 'dim'));
+      console.log('');
+      review = await callClaude(apiKey, prompt);
+    }
 
     // Format output
     const lines = review.split('\n');
@@ -264,8 +304,8 @@ async function deepReview(options) {
 
     console.log('');
     console.log(c('  ─────────────────────────────────────', 'dim'));
-    console.log(c('  Reviewed by Claude Sonnet 4.6 via Anthropic API', 'dim'));
-    console.log(c('  Your config was sent to api.anthropic.com only. We never see it.', 'dim'));
+    console.log(c(`  Reviewed via ${method}`, 'dim'));
+    console.log(c('  Your config stays between you and Anthropic. We never see it.', 'dim'));
     console.log('');
   } catch (err) {
     console.log(c(`  Error: ${err.message}`, 'red'));

package/src/insights.js

@@ -25,14 +25,10 @@ const INSIGHTS_ENDPOINT = 'https://claudex-insights.claudex.workers.dev/v1/repor
 const TIMEOUT_MS = 3000;
 
 function shouldCollect() {
-  // Respect opt-out
-  if (process.env.CLAUDEX_NO_INSIGHTS === '1') return false;
-  if (process.argv.includes('--no-insights')) return false;
-
-  // Don't collect in CI
-  if (process.env.CI || process.env.GITHUB_ACTIONS) return false;
-
-  return true;
+  // Opt-IN: only collect if user explicitly enables
+  if (process.env.CLAUDEX_INSIGHTS === '1') return true;
+  if (process.argv.includes('--insights')) return true;
+  return false;
 }
 
 function buildPayload(auditResult) {

package/src/interactive.js

@@ -102,7 +102,7 @@ async function interactive(options) {
   console.log('');
 
   // Run setup in auto mode
-  await setup({ ...options, auto: true });
+  await setup({ ...options, auto: true, only: toFix });
 
   console.log('');
   console.log(c('  Done! Run `npx claudex-setup` to see your new score.', 'green'));

package/src/setup.js

@@ -384,32 +384,29 @@ ${verificationSteps.join('\n')}
 
   'hooks': () => ({
     'on-edit-lint.sh': `#!/bin/bash
-# PostToolUse hook - auto-check after file edits
-# Customize the linter command for your project
-TIMESTAMP=$(date +"%Y-%m-%d %H:%M:%S")
-echo "[$TIMESTAMP] File changed: $(cat -)" >> .claude/logs/changes.txt
+# PostToolUse hook - runs linter after file edits
+# Detects which linter is available and runs it
+
+if command -v npx &>/dev/null; then
+  if [ -f "package.json" ] && grep -q '"lint"' package.json 2>/dev/null; then
+    npm run lint --silent 2>/dev/null
+  elif [ -f ".eslintrc" ] || [ -f ".eslintrc.js" ] || [ -f ".eslintrc.json" ] || [ -f "eslint.config.js" ]; then
+    npx eslint --fix . --quiet 2>/dev/null
+  fi
+elif command -v ruff &>/dev/null; then
+  ruff check --fix . 2>/dev/null
+fi
 `,
     'protect-secrets.sh': `#!/bin/bash
-# PreToolUse hook - warn before touching sensitive files
-# Prevents accidental reads/writes to files containing secrets
-
+# PreToolUse hook - blocks reads of secret files
 INPUT=$(cat -)
-FILE=$(echo "$INPUT" | grep -oP '"file_path"\\s*:\\s*"\\K[^"]+' 2>/dev/null || echo "")
+FILE_PATH=$(echo "$INPUT" | sed -n 's/.*"file_path"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*/\\1/p')
 
-if [ -z "$FILE" ]; then
+if echo "$FILE_PATH" | grep -qiE '\\.env$|\\.env\\.|secrets/|credentials|\\.pem$|\\.key$'; then
+  echo '{"decision": "block", "reason": "Blocked: accessing secret/credential files is not allowed."}'
   exit 0
 fi
-
-BASENAME=$(basename "$FILE")
-
-case "$BASENAME" in
-  .env|.env.*|*.pem|*.key|credentials.json|secrets.yaml|secrets.yml)
-    echo "WARN: Attempting to access sensitive file: $BASENAME"
-    echo "This file may contain secrets. Proceed with caution."
-    ;;
-esac
-
-exit 0
+echo '{"decision": "allow"}'
 `,
     'log-changes.sh': `#!/bin/bash
 # PostToolUse hook - logs all file changes with timestamps
@@ -571,9 +568,19 @@ async function setup(options) {
   let created = 0;
   let skipped = 0;
 
+  let failedWithTemplates = [];
   for (const [key, technique] of Object.entries(TECHNIQUES)) {
     if (technique.passed || technique.check(ctx)) continue;
     if (!technique.template) continue;
+    failedWithTemplates.push({ key, technique });
+  }
+
+  // Filter by 'only' list if provided (interactive wizard selections)
+  if (options.only && options.only.length > 0) {
+    failedWithTemplates = failedWithTemplates.filter(r => options.only.includes(r.key));
+  }
+
+  for (const { key, technique } of failedWithTemplates) {
 
     const template = TEMPLATES[technique.template];
     if (!template) continue;
@@ -627,6 +634,41 @@ async function setup(options) {
     }
   }
 
+  // Auto-register hooks in settings if hooks were created but no settings exist
+  const hooksDir = path.join(options.dir, '.claude/hooks');
+  const settingsPath = path.join(options.dir, '.claude/settings.json');
+  if (fs.existsSync(hooksDir) && !fs.existsSync(settingsPath)) {
+    const hookFiles = fs.readdirSync(hooksDir).filter(f => f.endsWith('.sh'));
+    if (hookFiles.length > 0) {
+      const settings = {
+        hooks: {
+          PostToolUse: [{
+            matcher: "Write|Edit",
+            hooks: hookFiles.filter(f => f !== 'protect-secrets.sh').map(f => ({
+              type: "command",
+              command: `bash .claude/hooks/${f}`,
+              timeout: 10
+            }))
+          }]
+        }
+      };
+      // Add protect-secrets as PreToolUse if it exists
+      if (hookFiles.includes('protect-secrets.sh')) {
+        settings.hooks.PreToolUse = [{
+          matcher: "Read|Write|Edit",
+          hooks: [{
+            type: "command",
+            command: "bash .claude/hooks/protect-secrets.sh",
+            timeout: 5
+          }]
+        }];
+      }
+      fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf8');
+      console.log(`  \x1b[32m✅\x1b[0m Created .claude/settings.json (hooks registered)`);
+      created++;
+    }
+  }
+
   console.log('');
   if (created === 0 && skipped > 0) {
     console.log('  \x1b[32m✅\x1b[0m Your project is already well configured!');

package/src/techniques.js

@@ -766,11 +766,16 @@ const TECHNIQUES = {
   channelsAwareness: {
     id: 1102,
     name: 'Claude Code Channels awareness',
-    check: () => true, // informational
+    check: (ctx) => {
+      const md = ctx.fileContent('CLAUDE.md') || '';
+      const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
+      const settingsStr = JSON.stringify(settings || {});
+      return md.toLowerCase().includes('channel') || settingsStr.includes('channel');
+    },
     impact: 'low',
-    rating: 4,
+    rating: 3,
     category: 'features',
-    fix: 'Claude Code Channels (v2.1.80+) lets you control sessions from Telegram/Discord/iMessage.',
+    fix: 'Claude Code Channels (v2.1.80+) bridges Telegram/Discord/iMessage to your session.',
     template: null
   },
 
@@ -801,7 +806,8 @@ const TECHNIQUES = {
     id: 2002,
     name: 'CLAUDE.md is concise (under 200 lines)',
     check: (ctx) => {
-      const md = ctx.fileContent('CLAUDE.md') || '';
+      const md = ctx.fileContent('CLAUDE.md');
+      if (!md) return false; // no CLAUDE.md = not passing
       return md.split('\n').length <= 200;
     },
     impact: 'medium',
@@ -815,7 +821,8 @@ const TECHNIQUES = {
     id: 2003,
     name: 'CLAUDE.md has no obvious contradictions',
     check: (ctx) => {
-      const md = ctx.fileContent('CLAUDE.md') || '';
+      const md = ctx.fileContent('CLAUDE.md');
+      if (!md || md.length < 50) return false; // no CLAUDE.md or too short = not passing
       // Check for common contradictions
       const hasNever = /never.*always|always.*never/i.test(md);
       const hasBothStyles = /use tabs/i.test(md) && /use spaces/i.test(md);
@@ -921,7 +928,8 @@ const TECHNIQUES = {
     id: 2009,
     name: 'No deprecated patterns detected',
     check: (ctx) => {
-      const md = ctx.fileContent('CLAUDE.md') || '';
+      const md = ctx.fileContent('CLAUDE.md');
+      if (!md) return false; // no CLAUDE.md = not passing
       // Check for patterns deprecated in Claude 4.x
       const deprecated = [
         'prefill', // deprecated in 4.6