claudex-setup 0.5.1 → 1.0.1

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
 
@@ -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.1",
+  "version": "1.0.1",
   "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');
 
@@ -198,14 +199,21 @@ function hasClaudeCode() {
 
 async function callClaudeCode(prompt) {
   const { execSync } = require('child_process');
-  // Use claude -p (headless/print mode) - uses the user's existing Claude Code auth
-  const escaped = prompt.replace(/'/g, "'\\''");
-  const result = execSync(`claude -p '${escaped}' --output-format text`, {
-    encoding: 'utf8',
-    maxBuffer: 1024 * 1024,
-    timeout: 120000,
-  });
-  return result;
+  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) {

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

@@ -29,12 +29,20 @@ function detectScripts(ctx) {
 // Helper: detect main directories
 // ============================================================
 function detectMainDirs(ctx) {
-  const candidates = ['src', 'lib', 'app', 'pages', 'components', 'api', 'routes', 'utils', 'helpers', 'services', 'models', 'controllers', 'views', 'public', 'assets', 'config', 'tests', 'test', '__tests__', 'spec', 'scripts', 'prisma', 'db', 'middleware'];
+  const candidates = ['src', 'lib', 'app', 'pages', 'components', 'api', 'routes', 'utils', 'helpers', 'services', 'models', 'controllers', 'views', 'public', 'assets', 'config', 'tests', 'test', '__tests__', 'spec', 'scripts', 'prisma', 'db', 'middleware', 'hooks'];
+  // Also check inside src/ for nested structure (common in Next.js, React)
+  const srcNested = ['src/components', 'src/app', 'src/pages', 'src/api', 'src/lib', 'src/hooks', 'src/utils', 'src/services', 'src/models', 'src/middleware', 'src/app/api', 'app/api'];
   const found = [];
-  for (const dir of candidates) {
+  const seenNames = new Set();
+
+  for (const dir of [...candidates, ...srcNested]) {
     if (ctx.hasDir(dir)) {
       const files = ctx.dirFiles(dir);
-      found.push({ name: dir, fileCount: files.length, files: files.slice(0, 10) });
+      const displayName = dir.includes('/') ? dir : dir;
+      if (!seenNames.has(displayName)) {
+        found.push({ name: displayName, fileCount: files.length, files: files.slice(0, 10) });
+        seenNames.add(displayName);
+      }
     }
   }
   return found;
@@ -61,31 +69,63 @@ function generateMermaid(dirs, stacks) {
     return `    ${id}[${label}]`;
   }
 
-  // Entry point
-  nodes.push(addNode('Entry Point', 'round'));
+  // Detect Next.js App Router specifically
+  const hasAppRouter = dirNames.includes('app') || dirNames.includes('src/app');
+  const hasPages = dirNames.includes('pages') || dirNames.includes('src/pages');
+  const hasAppApi = dirNames.includes('app/api') || dirNames.includes('src/app/api');
+  const hasSrcComponents = dirNames.includes('src/components') || dirNames.includes('components');
+  const hasSrcHooks = dirNames.includes('src/hooks') || dirNames.includes('hooks');
+  const hasSrcLib = dirNames.includes('src/lib') || dirNames.includes('lib');
+
+  // Smart entry point based on framework
+  const isNextJs = stackKeys.includes('nextjs');
+  const isDjango = stackKeys.includes('django');
+  const isFastApi = stackKeys.includes('fastapi');
+
+  if (isNextJs) {
+    nodes.push(addNode('Next.js', 'round'));
+  } else if (isDjango) {
+    nodes.push(addNode('Django', 'round'));
+  } else if (isFastApi) {
+    nodes.push(addNode('FastAPI', 'round'));
+  } else {
+    nodes.push(addNode('Entry Point', 'round'));
+  }
+
+  const root = ids['Next.js'] || ids['Django'] || ids['FastAPI'] || ids['Entry Point'];
 
   // Detect layers
-  if (dirNames.includes('app') || dirNames.includes('pages')) {
-    nodes.push(addNode('Pages / Routes', 'default'));
-    edges.push(`    ${ids['Entry Point']} --> ${ids['Pages / Routes']}`);
+  if (hasAppRouter || hasPages) {
+    const label = hasAppRouter ? 'App Router' : 'Pages';
+    nodes.push(addNode(label, 'default'));
+    edges.push(`    ${root} --> ${ids[label]}`);
+  }
+
+  if (hasAppApi) {
+    nodes.push(addNode('API Routes', 'default'));
+    const parent = ids['App Router'] || ids['Pages'] || root;
+    edges.push(`    ${parent} --> ${ids['API Routes']}`);
   }
 
-  if (dirNames.includes('components')) {
+  if (hasSrcComponents) {
     nodes.push(addNode('Components', 'default'));
-    const parent = ids['Pages / Routes'] || ids['Entry Point'];
+    const parent = ids['App Router'] || ids['Pages'] || root;
     edges.push(`    ${parent} --> ${ids['Components']}`);
   }
 
-  if (dirNames.includes('src')) {
-    nodes.push(addNode('src/', 'default'));
-    const parent = ids['Pages / Routes'] || ids['Entry Point'];
-    edges.push(`    ${parent} --> ${ids['src/']}`);
+  if (hasSrcHooks) {
+    nodes.push(addNode('Hooks', 'default'));
+    const parent = ids['Components'] || root;
+    edges.push(`    ${parent} --> ${ids['Hooks']}`);
   }
 
-  if (dirNames.includes('lib')) {
+  if (hasSrcLib) {
     nodes.push(addNode('lib/', 'default'));
-    const parent = ids['src/'] || ids['Entry Point'];
+    const parent = ids['API Routes'] || ids['Hooks'] || ids['Components'] || root;
     edges.push(`    ${parent} --> ${ids['lib/']}`);
+  } else if (dirNames.includes('src') && !hasAppRouter && !hasPages) {
+    nodes.push(addNode('src/', 'default'));
+    edges.push(`    ${root} --> ${ids['src/']}`);
   }
 
   if (dirNames.includes('api') || dirNames.includes('routes') || dirNames.includes('controllers')) {
@@ -379,45 +419,46 @@ ${verificationSteps.join('\n')}
 - Use descriptive commit messages (why, not what)
 - Create focused PRs — one concern per PR
 - Document non-obvious decisions in code comments
+
+---
+*Generated by [claudex-setup](https://github.com/DnaFin/claudex-setup) v${require('../package.json').version} on ${new Date().toISOString().split('T')[0]}. Customize this file for your project — a hand-crafted CLAUDE.md will always be better than a generated one.*
 `;
   },
 
   '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
 # Appends to .claude/logs/file-changes.log
 
 INPUT=$(cat -)
-TOOL_NAME=$(echo "$INPUT" | grep -oP '"tool_name"\\s*:\\s*"\\K[^"]+' 2>/dev/null || echo "unknown")
-FILE_PATH=$(echo "$INPUT" | grep -oP '"file_path"\\s*:\\s*"\\K[^"]+' 2>/dev/null || echo "")
+TOOL_NAME=$(echo "$INPUT" | sed -n 's/.*"tool_name"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*/\\1/p')
+TOOL_NAME=\${TOOL_NAME:-unknown}
+FILE_PATH=$(echo "$INPUT" | sed -n 's/.*"file_path"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*/\\1/p')
 
 if [ -z "$FILE_PATH" ]; then
   exit 0
@@ -571,9 +612,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;
@@ -583,7 +634,13 @@ async function setup(options) {
 
     if (typeof result === 'string') {
       // Single file template (like CLAUDE.md)
-      const filePath = key === 'claudeMd' ? 'CLAUDE.md' : key;
+      // Map technique keys to actual file paths
+      const filePathMap = {
+        'claudeMd': 'CLAUDE.md',
+        'mermaidArchitecture': 'CLAUDE.md', // mermaid is part of CLAUDE.md, skip separate file
+      };
+      if (key === 'mermaidArchitecture') continue; // Mermaid is generated inside CLAUDE.md template
+      const filePath = filePathMap[key] || key;
       const fullPath = path.join(options.dir, filePath);
 
       if (!fs.existsSync(fullPath)) {
@@ -627,6 +684,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