claudex-setup 1.1.0 → 1.3.0

package/package.json

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

package/src/audit.js

@@ -76,6 +76,21 @@ async function audit(options) {
   const earnedScore = passed.reduce((sum, r) => sum + (weights[r.impact] || 5), 0);
   const score = maxScore > 0 ? Math.round((earnedScore / maxScore) * 100) : 0;
 
+  // Detect scaffolded vs organic: if CLAUDE.md contains our version stamp, some checks
+  // are passing because WE generated them, not the user
+  const claudeMd = ctx.fileContent('CLAUDE.md') || '';
+  const isScaffolded = claudeMd.includes('Generated by claudex-setup') ||
+    claudeMd.includes('claudex-setup');
+  // Scaffolded checks: things our setup creates (CLAUDE.md, hooks, commands, agents, rules, skills)
+  const scaffoldedKeys = new Set(['claudeMd', 'mermaidArchitecture', 'verificationLoop',
+    'hooks', 'customCommands', 'multipleCommands', 'agents', 'pathRules', 'multipleRules',
+    'skills', 'hooksConfigured', 'preToolUseHook', 'postToolUseHook', 'fewShotExamples',
+    'constraintBlocks', 'xmlTags']);
+  const organicPassed = passed.filter(r => !scaffoldedKeys.has(r.key));
+  const scaffoldedPassed = passed.filter(r => scaffoldedKeys.has(r.key));
+  const organicEarned = organicPassed.reduce((sum, r) => sum + (weights[r.impact] || 5), 0);
+  const organicScore = maxScore > 0 ? Math.round((organicEarned / maxScore) * 100) : 0;
+
   // Silent mode: skip all output, just return result
   if (silent) {
     return { score, passed: passed.length, failed: failed.length, stacks, results };
@@ -100,6 +115,9 @@ async function audit(options) {
 
   // Score
   console.log(`  ${progressBar(score)} ${colorize(`${score}/100`, 'bold')}`);
+  if (isScaffolded && scaffoldedPassed.length > 0) {
+    console.log(colorize(`  Organic: ${organicScore}/100 (without claudex-setup generated files)`, 'dim'));
+  }
   console.log('');
 
   // Passed

package/src/setup.js

@@ -96,10 +96,47 @@ function detectDependencies(ctx) {
     guidelines.push('- Use Playwright for E2E tests. Keep tests in tests/ or e2e/');
   }
 
+  // tRPC
+  if (allDeps['@trpc/server'] || allDeps['@trpc/client']) {
+    guidelines.push('- Use tRPC for type-safe API calls. Define routers in server, use client hooks in components');
+  }
+
+  // Stripe
+  if (allDeps['stripe']) {
+    guidelines.push('- Use Stripe SDK for payments. Always verify webhooks with stripe.webhooks.constructEvent()');
+  }
+
+  // Resend
+  if (allDeps['resend']) {
+    guidelines.push('- Use Resend for transactional email. Define templates as React components');
+  }
+
+  // Express security
+  if (allDeps['helmet']) {
+    guidelines.push('- Helmet is configured — ensure all middleware is applied before routes');
+  }
+  if (allDeps['jsonwebtoken']) {
+    guidelines.push('- Use JWT for authentication. Always verify tokens with the correct secret/algorithm');
+  }
+  if (allDeps['bcrypt']) {
+    guidelines.push('- Use bcrypt for password hashing. Never store plaintext passwords');
+  }
+  if (allDeps['cors']) {
+    guidelines.push('- CORS is configured — restrict origins to known domains in production');
+  }
+
+  // Monorepo
+  if (allDeps['turbo'] || allDeps['turborepo']) {
+    guidelines.push('- Turborepo monorepo — use `turbo run` for all tasks. Respect package boundaries');
+  }
+  if (allDeps['nx']) {
+    guidelines.push('- Nx monorepo — use `nx affected` for incremental builds and tests');
+  }
+
   // Python
   const reqTxt = ctx.fileContent('requirements.txt') || '';
   if (reqTxt.includes('sqlalchemy')) {
-    guidelines.push('- Use SQLAlchemy for all database operations');
+    guidelines.push('- Use SQLAlchemy for database operations. Define models in models/');
   }
   if (reqTxt.includes('pydantic')) {
     guidelines.push('- Use Pydantic for data validation and serialization');
@@ -107,6 +144,15 @@ function detectDependencies(ctx) {
   if (reqTxt.includes('pytest')) {
     guidelines.push('- Use pytest for testing. Run with `python -m pytest`');
   }
+  if (reqTxt.includes('alembic')) {
+    guidelines.push('- Use Alembic for database migrations. Run `alembic upgrade head` after model changes');
+  }
+  if (reqTxt.includes('celery')) {
+    guidelines.push('- Use Celery for background tasks. Define tasks in tasks/ or services/');
+  }
+  if (reqTxt.includes('redis')) {
+    guidelines.push('- Redis is available for caching and task queues');
+  }
 
   return guidelines;
 }
@@ -342,18 +388,29 @@ function getFrameworkInstructions(stacks) {
 
   if (stackKeys.includes('rust')) {
     sections.push(`### Rust
-- Prefer Result<T, E> over unwrap/expect in library code
-- Use clippy warnings as errors
-- Derive common traits (Debug, Clone, PartialEq) where appropriate
-- Use modules to organize code; keep lib.rs/main.rs thin`);
+- Use Result<T, E> for error handling, avoid unwrap() in production code
+- Prefer &str over String for function parameters
+- Use clippy: \`cargo clippy -- -D warnings\`
+- Structure: src/lib.rs for library, src/main.rs for binary`);
   }
 
   if (stackKeys.includes('go')) {
     sections.push(`### Go
-- Follow standard project layout conventions
-- Handle all errors explicitly; no blank _ for errors
-- Use interfaces for testability and abstraction
-- Keep packages focused; avoid circular dependencies`);
+- Follow standard Go project layout (cmd/, internal/, pkg/)
+- Use interfaces for dependency injection and testability
+- Handle all errors explicitly — never ignore err returns
+- Use context.Context for cancellation and timeouts
+- Prefer table-driven tests
+- Run \`go vet\` and \`golangci-lint\` before committing`);
+  }
+
+  if (stackKeys.includes('terraform')) {
+    sections.push(`### Terraform
+- Use modules for reusable infrastructure components
+- Always run \`terraform plan\` before \`terraform apply\`
+- Store state remotely (S3 + DynamoDB, or Terraform Cloud)
+- Use variables.tf for all configurable values
+- Tag all resources consistently`);
   }
 
   const hasJS = stackKeys.some(k => ['react', 'vue', 'angular', 'nextjs', 'node', 'svelte'].includes(k));
@@ -569,38 +626,109 @@ exit 0
 `,
   }),
 
-  'commands': () => ({
-    'test.md': `Run the test suite and report results.
+  'commands': (stacks) => {
+    const stackKeys = stacks.map(s => s.key);
+    const isNext = stackKeys.includes('nextjs');
+    const isDjango = stackKeys.includes('django');
+    const isFastApi = stackKeys.includes('fastapi');
+    const isPython = stackKeys.includes('python') || isDjango || isFastApi;
+    const hasDocker = stackKeys.includes('docker');
+
+    const cmds = {};
+
+    // Test command - stack-specific
+    if (isNext) {
+      cmds['test.md'] = `Run the test suite for this Next.js project.
+
+## Steps:
+1. Run \`npm test\` (or \`npx vitest run\`)
+2. If tests fail, check for missing mocks or async issues
+3. For component tests, ensure React Testing Library patterns are used
+4. For API route tests, check request/response handling
+5. Report: total, passed, failed, coverage if available
+`;
+    } else if (isPython) {
+      cmds['test.md'] = `Run the test suite for this Python project.
+
+## Steps:
+1. Run \`python -m pytest -v\` (or the project's test command)
+2. Check for fixture issues, missing test database, or import errors
+3. If using Django: \`python manage.py test\`
+4. Report: total, passed, failed, and any tracebacks
+`;
+    } else {
+      cmds['test.md'] = `Run the test suite and report results.
 
 ## Steps:
 1. Run the project's test command
 2. If tests fail, analyze the failures
 3. Report: total, passed, failed, and any error details
-`,
-    'review.md': `Review the current changes for quality and correctness.
+`;
+    }
+
+    // Review - always generic (works well as-is)
+    cmds['review.md'] = `Review the current changes for quality and correctness.
 
 ## Steps:
 1. Run \`git diff\` to see all changes
 2. Check for: bugs, security issues, missing tests, code style
 3. Provide actionable feedback
-`,
-    'deploy.md': `Pre-deployment checklist and deployment steps.
+`;
+
+    // Deploy - stack-specific
+    if (isNext) {
+      cmds['deploy.md'] = `Pre-deployment checklist for Next.js.
+
+## Pre-deploy:
+1. Run \`git status\` — working tree must be clean
+2. Run \`npm run build\` — must succeed with no errors
+3. Run \`npm test\` — all tests pass
+4. Run \`npm run lint\` — no lint errors
+5. Check for \`console.log\` in production code
+6. Verify environment variables are set in deployment platform
+
+## Deploy:
+1. If Vercel: \`git push\` triggers auto-deploy
+2. If self-hosted: \`npm run build && npm start\`
+3. Verify: check /api/health or main page loads
+4. Tag: \`git tag -a vX.Y.Z -m "Release vX.Y.Z"\`
+`;
+    } else if (hasDocker) {
+      cmds['deploy.md'] = `Pre-deployment checklist with Docker.
 
-## Pre-deploy checks:
+## Pre-deploy:
+1. Run \`git status\` — working tree must be clean
+2. Run full test suite — all tests pass
+3. Run \`docker build -t app .\` — must succeed
+4. Run \`docker run app\` locally — smoke test
+
+## Deploy:
+1. Build: \`docker build -t registry/app:latest .\`
+2. Push: \`docker push registry/app:latest\`
+3. Deploy to target environment
+4. Verify health endpoint responds
+5. Tag: \`git tag -a vX.Y.Z -m "Release vX.Y.Z"\`
+`;
+    } else {
+      cmds['deploy.md'] = `Pre-deployment checklist.
+
+## Pre-deploy:
 1. Run \`git status\` — working tree must be clean
 2. Run full test suite — all tests must pass
-3. Run linter — no errors allowed
-4. Check for TODO/FIXME/HACK comments in changed files
-5. Verify no secrets in staged changes (\`git diff --cached\`)
-
-## Deploy steps:
-1. Confirm target environment (staging vs production)
-2. Review the diff since last deploy tag
-3. Run the deployment command
-4. Verify deployment succeeded (health check / smoke test)
-5. Tag the release: \`git tag -a vX.Y.Z -m "Release vX.Y.Z"\`
-`,
-    'fix.md': `Fix the issue described: $ARGUMENTS
+3. Run linter — no errors
+4. Verify no secrets in staged changes
+5. Review diff since last deploy
+
+## Deploy:
+1. Confirm target environment
+2. Run deployment command
+3. Verify deployment (health check)
+4. Tag: \`git tag -a vX.Y.Z -m "Release vX.Y.Z"\`
+`;
+    }
+
+    // Fix - always generic with $ARGUMENTS
+    cmds['fix.md'] = `Fix the issue described: $ARGUMENTS
 
 ## Steps:
 1. Understand the issue — read relevant code and error messages
@@ -609,8 +737,32 @@ exit 0
 4. Write or update tests to cover the fix
 5. Run the full test suite to verify no regressions
 6. Summarize what was wrong and how the fix addresses it
-`,
-  }),
+`;
+
+    // Stack-specific bonus commands
+    if (isNext) {
+      cmds['check-build.md'] = `Run Next.js build check without deploying.
+
+1. Run \`npx next build\`
+2. Check for: TypeScript errors, missing pages, broken imports
+3. Verify no "Dynamic server usage" errors in static pages
+4. Report build output size and any warnings
+`;
+    }
+
+    if (isPython && (isDjango || isFastApi)) {
+      cmds['migrate.md'] = `Run database migrations safely.
+
+1. Check current migration status${isDjango ? ': `python manage.py showmigrations`' : ''}
+2. Create new migration if schema changed${isDjango ? ': `python manage.py makemigrations`' : ''}
+3. Review the generated migration file
+4. Apply: ${isDjango ? '`python manage.py migrate`' : '`alembic upgrade head`'}
+5. Verify: check that the app starts and queries work
+`;
+    }
+
+    return cmds;
+  },
 
   'skills': () => ({
     'fix-issue/SKILL.md': `---
@@ -631,8 +783,10 @@ Fix the GitHub issue: $ARGUMENTS
     const rules = {};
     const hasTS = stacks.some(s => s.key === 'typescript');
     const hasPython = stacks.some(s => s.key === 'python');
+    const hasFrontend = stacks.some(s => ['react', 'vue', 'angular', 'svelte', 'nextjs'].includes(s.key));
+    const hasBackend = stacks.some(s => ['go', 'python', 'django', 'fastapi', 'rust', 'java'].includes(s.key));
 
-    if (hasTS || stacks.some(s => ['react', 'vue', 'angular', 'nextjs', 'node'].includes(s.key))) {
+    if (hasFrontend || (hasTS && !hasBackend)) {
       rules['frontend.md'] = `When editing JavaScript/TypeScript files (*.ts, *.tsx, *.js, *.jsx, *.vue):
 - Use functional components with hooks (React/Vue 3)
 - Add TypeScript interfaces for all props and function params
@@ -640,6 +794,16 @@ Fix the GitHub issue: $ARGUMENTS
 - Use named exports over default exports
 - Handle errors explicitly — no empty catch blocks
 - Keep component files under 200 lines; extract sub-components
+`;
+    }
+    if (hasBackend) {
+      rules['backend.md'] = `When editing backend code:
+- Handle all errors explicitly — never swallow exceptions silently
+- Validate all external input at API boundaries
+- Use dependency injection for testability
+- Keep route handlers thin — delegate to service/business logic layers
+- Log errors with sufficient context for debugging
+- Never hardcode secrets or credentials
 `;
     }
     if (hasPython) {

package/src/techniques.js

@@ -92,7 +92,7 @@ const TECHNIQUES = {
   },
 
   testCommand: {
-    id: 93,
+    id: 93001,
     name: 'CLAUDE.md contains a test command',
     check: (ctx) => {
       const md = ctx.fileContent('CLAUDE.md') || '';
@@ -106,7 +106,7 @@ const TECHNIQUES = {
   },
 
   lintCommand: {
-    id: 93,
+    id: 93002,
     name: 'CLAUDE.md contains a lint command',
     check: (ctx) => {
       const md = ctx.fileContent('CLAUDE.md') || '';
@@ -120,7 +120,7 @@ const TECHNIQUES = {
   },
 
   buildCommand: {
-    id: 93,
+    id: 93003,
     name: 'CLAUDE.md contains a build command',
     check: (ctx) => {
       const md = ctx.fileContent('CLAUDE.md') || '';
@@ -167,7 +167,7 @@ const TECHNIQUES = {
   },
 
   gitIgnoreNodeModules: {
-    id: 917,
+    id: 91701,
     name: '.gitignore blocks node_modules',
     check: (ctx) => {
       const gitignore = ctx.fileContent('.gitignore') || '';
@@ -210,7 +210,7 @@ const TECHNIQUES = {
   },
 
   multipleCommands: {
-    id: 20,
+    id: 20001,
     name: '3+ slash commands for rich workflow',
     check: (ctx) => ctx.hasDir('.claude/commands') && ctx.dirFiles('.claude/commands').length >= 3,
     impact: 'medium',
@@ -221,7 +221,7 @@ const TECHNIQUES = {
   },
 
   deployCommand: {
-    id: 20,
+    id: 20002,
     name: 'Has /deploy or /release command',
     check: (ctx) => {
       if (!ctx.hasDir('.claude/commands')) return false;
@@ -236,7 +236,7 @@ const TECHNIQUES = {
   },
 
   reviewCommand: {
-    id: 20,
+    id: 20003,
     name: 'Has /review command',
     check: (ctx) => {
       if (!ctx.hasDir('.claude/commands')) return false;
@@ -262,7 +262,7 @@ const TECHNIQUES = {
   },
 
   multipleSkills: {
-    id: 21,
+    id: 2101,
     name: '2+ skills for specialization',
     check: (ctx) => ctx.hasDir('.claude/skills') && ctx.dirFiles('.claude/skills').length >= 2,
     impact: 'medium',
@@ -284,7 +284,7 @@ const TECHNIQUES = {
   },
 
   multipleAgents: {
-    id: 22,
+    id: 2201,
     name: '2+ agents for delegation',
     check: (ctx) => ctx.hasDir('.claude/agents') && ctx.dirFiles('.claude/agents').length >= 2,
     impact: 'medium',
@@ -295,7 +295,7 @@ const TECHNIQUES = {
   },
 
   multipleRules: {
-    id: 3,
+    id: 301,
     name: '2+ rules files for granular control',
     check: (ctx) => ctx.hasDir('.claude/rules') && ctx.dirFiles('.claude/rules').length >= 2,
     impact: 'medium',
@@ -324,7 +324,7 @@ const TECHNIQUES = {
   },
 
   permissionDeny: {
-    id: 24,
+    id: 2401,
     name: 'Deny rules configured in permissions',
     check: (ctx) => {
       const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
@@ -340,7 +340,7 @@ const TECHNIQUES = {
   },
 
   noBypassPermissions: {
-    id: 24,
+    id: 2402,
     name: 'Default mode is not bypassPermissions',
     check: (ctx) => {
       const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
@@ -400,7 +400,7 @@ const TECHNIQUES = {
   },
 
   hooksInSettings: {
-    id: 88,
+    id: 8801,
     name: 'Hooks configured in settings',
     check: (ctx) => {
       const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
@@ -415,7 +415,7 @@ const TECHNIQUES = {
   },
 
   preToolUseHook: {
-    id: 88,
+    id: 8802,
     name: 'PreToolUse hook configured',
     check: (ctx) => {
       const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
@@ -430,7 +430,7 @@ const TECHNIQUES = {
   },
 
   postToolUseHook: {
-    id: 88,
+    id: 8803,
     name: 'PostToolUse hook configured',
     check: (ctx) => {
       const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
@@ -445,7 +445,7 @@ const TECHNIQUES = {
   },
 
   sessionStartHook: {
-    id: 88,
+    id: 8804,
     name: 'SessionStart hook configured',
     check: (ctx) => {
       const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
@@ -478,7 +478,7 @@ const TECHNIQUES = {
   },
 
   tailwindMention: {
-    id: 1025,
+    id: 102501,
     name: 'Tailwind CSS configured',
     check: (ctx) => {
       const pkg = ctx.fileContent('package.json') || '';
@@ -508,7 +508,7 @@ const TECHNIQUES = {
   },
 
   dockerCompose: {
-    id: 399,
+    id: 39901,
     name: 'Has docker-compose.yml',
     check: (ctx) => ctx.files.some(f => /^docker-compose\.(yml|yaml)$/i.test(f)),
     impact: 'medium',
@@ -589,7 +589,7 @@ const TECHNIQUES = {
   },
 
   editorconfig: {
-    id: 0,
+    id: 5001,
     name: 'Has .editorconfig',
     check: (ctx) => ctx.files.includes('.editorconfig'),
     impact: 'low',
@@ -600,7 +600,7 @@ const TECHNIQUES = {
   },
 
   nvmrc: {
-    id: 0,
+    id: 5002,
     name: 'Node version pinned',
     check: (ctx) => {
       if (ctx.files.includes('.nvmrc') || ctx.files.includes('.node-version')) return true;
@@ -665,7 +665,7 @@ const TECHNIQUES = {
   },
 
   multipleMcpServers: {
-    id: 18,
+    id: 1801,
     name: '2+ MCP servers for rich tooling',
     check: (ctx) => {
       const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
@@ -746,7 +746,7 @@ const TECHNIQUES = {
   },
 
   constraintBlocks: {
-    id: 96,
+    id: 9601,
     name: 'XML constraint blocks in CLAUDE.md',
     check: (ctx) => {
       const md = ctx.fileContent('CLAUDE.md') || '';
@@ -953,6 +953,8 @@ const STACKS = {
   java: { files: ['pom.xml'], content: {}, label: 'Java' },
   kotlin: { files: ['build.gradle.kts'], content: {}, label: 'Kotlin' },
   swift: { files: ['Package.swift'], content: {}, label: 'Swift' },
+  terraform: { files: ['main.tf', 'terraform'], content: {}, label: 'Terraform' },
+  kubernetes: { files: ['k8s', 'kubernetes', 'helm'], content: {}, label: 'Kubernetes' },
 };
 
 module.exports = { TECHNIQUES, STACKS };