@claudetools/cli 0.13.12 → 0.13.15

package/dist/onboard/docs-builder.js

@@ -82,8 +82,8 @@ async function fetchAllLibraryDocs(stack, onProgress) {
     }
     const total = toFetch.length;
     onProgress?.(`Fetching documentation for ${total} libraries...`, 0, total);
-    // Fetch in parallel batches of 2 (to avoid rate limiting)
-    const batchSize = 2;
+    // Fetch in parallel batches of 5 (increased for better performance)
+    const batchSize = 5;
     for (let i = 0; i < toFetch.length; i += batchSize) {
         const batch = toFetch.slice(i, i + batchSize);
         const batchResults = await Promise.all(batch.map(async (item, batchIndex) => {
@@ -170,29 +170,60 @@ function generateLibrariesIndex(stack, libraryDocs) {
 // =============================================================================
 // Claude Inference for Doc Generation
 // =============================================================================
-async function runClaudeForDocs(prompt, projectPath, timeout = 90000) {
+async function runClaudeForDocs(prompt, projectPath, timeout = 60000 // Reduced from 90s
+) {
     return new Promise((resolve) => {
-        const proc = spawn('claude', ['--print', '--dangerously-skip-permissions', prompt], {
+        const proc = spawn('claude', [
+            '--print',
+            '--dangerously-skip-permissions',
+            '--model', 'opus',
+            '--allowedTools', 'Read,Glob,Grep,WebFetch,WebSearch',
+            '-' // Read prompt from stdin
+        ], {
             cwd: projectPath,
             stdio: ['pipe', 'pipe', 'pipe'],
-            timeout,
         });
         let stdout = '';
+        let stderr = '';
+        let timedOut = false;
         const timer = setTimeout(() => {
+            timedOut = true;
             proc.kill();
+            if (process.env.CLAUDETOOLS_DEBUG) {
+                console.error(`Claude doc gen timed out after ${timeout}ms`);
+            }
             resolve(null);
         }, timeout);
         proc.stdout?.on('data', (data) => {
             stdout += data.toString();
         });
+        proc.stderr?.on('data', (data) => {
+            stderr += data.toString();
+        });
         proc.on('close', (code) => {
             clearTimeout(timer);
-            resolve(code === 0 ? stdout.trim() : null);
+            if (timedOut)
+                return; // Already resolved
+            if (code === 0 && stdout.trim()) {
+                resolve(stdout.trim());
+            }
+            else {
+                // Always log failures to help diagnose issues
+                if (process.env.CLAUDETOOLS_DEBUG) {
+                    console.error(`Claude doc gen failed (code ${code}):`, stderr.slice(0, 500));
+                }
+                resolve(null);
+            }
         });
-        proc.on('error', () => {
+        proc.on('error', (err) => {
             clearTimeout(timer);
+            // Always log spawn errors - these indicate a real problem
+            console.error('Claude spawn error:', err.message);
             resolve(null);
         });
+        // Write prompt to stdin and close
+        proc.stdin?.write(prompt);
+        proc.stdin?.end();
     });
 }
 // =============================================================================
@@ -653,24 +684,36 @@ function generateCodingStandards(answers, stack) {
 
 ## Overview
 
-This document defines the coding standards for this project.
+This document defines the coding standards for this project. These are non-negotiable.
 
 ${answers.projectDescription ? `**Project:** ${answers.projectDescription}\n` : ''}
 
-## Language
-
-**Primary Language:** ${stack.primaryLanguage}
+## Core Principles
 
-## General Principles
+1. **Minimal Code** - Write the least code necessary. Every line must earn its place.
+2. **No Duplication** - DRY principle. If you write something twice, extract it.
+3. **Composable** - Build small, focused pieces that combine well.
+4. **Maintainable** - Code should be obvious to future readers.
+5. **No AI Slop** - No verbose comments explaining obvious code. No boilerplate.
 
-1. **Readability** - Code should be self-documenting
-2. **Simplicity** - Prefer simple solutions
-3. **Consistency** - Follow established patterns
-4. **Testability** - Write testable code
+## Language
 
-## Conventions
+**Primary Language:** ${stack.primaryLanguage}
 
-- Follow standard conventions for ${stack.primaryLanguage}
+## Anti-Patterns to AVOID
+
+| Anti-Pattern | Why It's Bad | Do This Instead |
+|--------------|--------------|------------------|
+| God components | Unmaintainable, untestable | Split into focused components |
+| Prop drilling | Brittle, verbose | Use context or composition |
+| Copy-paste code | Bugs multiply, hard to update | Extract shared utilities |
+| Premature abstraction | Adds complexity before needed | Abstract on the third use |
+| Magic numbers/strings | Unclear intent | Use named constants |
+| Deep nesting | Hard to follow | Early returns, extract functions |
+| Barrel files (index.ts exports) | Breaks tree-shaking, slow builds | Import directly from source |
+| Over-engineering | Wastes time, adds bugs | Build for current needs |
+| Comments explaining "what" | Redundant, goes stale | Code should be self-documenting |
+| Unused code | Confuses readers, bloats bundle | Delete it |
 
 ## TypeScript Guidelines
 
@@ -680,18 +723,51 @@ ${stack.primaryLanguage === 'typescript' ? `
 - Prefer interfaces for object shapes
 - Use type guards for narrowing
 - Export types alongside implementations
+- No type assertions unless absolutely necessary
 ` : 'See language-specific guidelines.'}
 
 ## Component Guidelines
 
 ${stack.frameworks.some(f => f.name.toLowerCase().includes('react')) ? `
-- Use functional components
-- Keep components small and focused
+### Structure
+- Single responsibility - one component, one job
+- Max 150-200 lines; split if larger
+- Collocate related code (styles, tests, types with component)
+
+### Props
+- Minimal and obvious props interface
+- Use destructuring in function signature
+- Default values in destructuring, not defaultProps
+
+### Logic
 - Extract reusable logic to custom hooks
+- Keep render logic simple
 - Use composition over inheritance
-- Prop types should be explicit
+- Prefer controlled components
+
+### State
+- Derive what you can, don't duplicate state
+- Keep state as local as possible
+- Single source of truth for each piece of data
 ` : ''}
 
+## Function Guidelines
+
+- Pure functions where possible (same input = same output)
+- Max 20-30 lines; extract if longer
+- Descriptive names that describe what it returns/does
+- Early returns over nested conditionals
+- One level of abstraction per function
+- No side effects in functions unless that's their explicit purpose
+
+## Performance
+
+- Measure before optimizing
+- Avoid premature optimization
+- Use lazy loading for routes and heavy components
+- Memoize expensive computations, not everything
+- Don't memoize unless you've measured a problem
+
 ## File Organization
 
 \`\`\`
@@ -703,6 +779,18 @@ src/
 ├── types/          # Type definitions
 └── utils/          # Helper functions
 \`\`\`
+
+## Code Review Checklist
+
+Before submitting code, verify:
+
+- [ ] No duplication - is this logic already elsewhere?
+- [ ] No dead code - is everything used?
+- [ ] No magic values - are constants named?
+- [ ] Clear naming - can someone understand without context?
+- [ ] Minimal - can any code be removed?
+- [ ] Tested - are edge cases covered?
+- [ ] No AI slop - no unnecessary comments or boilerplate?
 `;
 }
 function generateTestingStrategy(_answers, stack) {
@@ -901,6 +989,22 @@ export async function buildDocs(projectPath, projectName, stack, answers, option
             mkdirSync(dir, { recursive: true });
         }
     }
+    // ==========================================================================
+    // STEP 1: Fetch Context7 docs FIRST - use to inform all doc generation
+    // ==========================================================================
+    let libraryDocs = [];
+    let context7Summary = '';
+    if (stack.frameworks.length > 0 || stack.libraries.length > 0) {
+        progress('Fetching library documentation from Context7...');
+        libraryDocs = await fetchAllLibraryDocs(stack, progress);
+        // Build a summary of what we learned from Context7 for use in prompts
+        const successfulDocs = libraryDocs.filter(d => d.success);
+        if (successfulDocs.length > 0) {
+            context7Summary = successfulDocs
+                .map(d => `### ${d.name}\n${d.content.slice(0, 500)}...`)
+                .join('\n\n');
+        }
+    }
     // Generate base documents with templates
     const docs = {
         'index.md': generateDocsIndex(projectName, stack, answers),
@@ -916,8 +1020,15 @@ export async function buildDocs(projectPath, projectName, stack, answers, option
         'decisions/index.md': generateAdrIndex(),
         'decisions/template.md': generateAdrTemplate(),
     };
-    // Claude-generated documents - analyze codebase and generate actual content
-    if (useClaude) {
+    // ==========================================================================
+    // STEP 2: Claude-generated documents - analyze codebase with Context7 context
+    // ==========================================================================
+    // Skip AI analysis for empty/new projects - no code to analyse
+    if (useClaude && !stack.isEmpty) {
+        // Build context preamble from Context7 docs
+        const contextPreamble = context7Summary
+            ? `\n\n<library-context>\nThe following library documentation was fetched from Context7. Use this to inform your analysis:\n\n${context7Summary}\n</library-context>\n\n`
+            : '';
         const claudePrompts = {
             'architecture/system-design.md': `Analyze this codebase and write a System Design document. Include:
 - Overall architecture overview
@@ -1051,7 +1162,7 @@ Document actual setup or common patterns for the stack.`,
         };
         // Generate Claude-powered docs in parallel batches
         const claudeDocPaths = Object.keys(claudePrompts);
-        const batchSize = 3; // Run 3 at a time to avoid overwhelming
+        const batchSize = 7; // Run 7 at a time for better performance
         const totalClaudeDocs = claudeDocPaths.length;
         let completedDocs = 0;
         const progress = options.onProgress || (() => { });
@@ -1062,7 +1173,9 @@ Document actual setup or common patterns for the stack.`,
             const docNames = batch.map(p => p.split('/').pop()?.replace('.md', '')).join(', ');
             progress(`Analyzing: ${docNames}`, completedDocs, totalClaudeDocs);
             const results = await Promise.all(batch.map(async (docPath) => {
-                const prompt = claudePrompts[docPath];
+                // Add Context7 context to each prompt for better docs
+                const basePrompt = claudePrompts[docPath];
+                const prompt = contextPreamble + basePrompt;
                 const content = await runClaudeForDocs(prompt, projectPath);
                 return { docPath, content };
             }));
@@ -1075,7 +1188,7 @@ Document actual setup or common patterns for the stack.`,
                 }
                 else {
                     // Fallback to template if Claude fails
-                    docs[docPath] = docs[docPath] || getFallbackTemplate(docPath);
+                    docs[docPath] = docs[docPath] || getFallbackTemplate(docPath, stack, answers);
                     progress(`Fallback: ${docName}`, completedDocs, totalClaudeDocs);
                 }
             }
@@ -1083,48 +1196,47 @@ Document actual setup or common patterns for the stack.`,
         progress(`Completed ${totalClaudeDocs} documents`, totalClaudeDocs, totalClaudeDocs);
     }
     else {
-        // No Claude - use template fallbacks
+        // No Claude or empty project - use template fallbacks with stack context
+        if (stack.isEmpty) {
+            progress('New project detected - using template docs (no code to analyse)');
+        }
+        else if (!useClaude) {
+            progress('Claude CLI not available - using template docs');
+        }
         docs['architecture/system-design.md'] = generateSystemDesign(answers, stack);
         docs['architecture/data-flow.md'] = generateDataFlow(answers);
         docs['architecture/components.md'] = generateComponentArchitecture(stack);
         docs['api/index.md'] = generateApiIndex(stack);
         docs['api/endpoints.md'] = generateEndpoints();
         docs['api/schemas.md'] = generateSchemas(stack);
-        docs['api/authentication.md'] = '# Authentication\n\nAuthentication documentation to be added.\n';
-        docs['guides/contributing.md'] = '# Contributing\n\nContributing guide to be added.\n';
-        docs['reference/configuration.md'] = '# Configuration\n\nConfiguration documentation to be added.\n';
-        docs['reference/environment.md'] = '# Environment Variables\n\nEnvironment variable documentation to be added.\n';
-        docs['reference/dependencies.md'] = '# Dependencies\n\nDependency documentation to be added.\n';
+        docs['api/authentication.md'] = getFallbackTemplate('api/authentication.md', stack, answers);
+        docs['guides/contributing.md'] = getFallbackTemplate('guides/contributing.md', stack, answers);
+        docs['reference/configuration.md'] = getFallbackTemplate('reference/configuration.md', stack, answers);
+        docs['reference/environment.md'] = getFallbackTemplate('reference/environment.md', stack, answers);
+        docs['reference/dependencies.md'] = getFallbackTemplate('reference/dependencies.md', stack, answers);
         docs['patterns/coding-standards.md'] = generateCodingStandards(answers, stack);
-        docs['patterns/naming-conventions.md'] = '# Naming Conventions\n\nNaming convention documentation to be added.\n';
-        docs['patterns/file-structure.md'] = '# File Structure\n\nFile structure documentation to be added.\n';
+        docs['patterns/naming-conventions.md'] = getFallbackTemplate('patterns/naming-conventions.md', stack, answers);
+        docs['patterns/file-structure.md'] = getFallbackTemplate('patterns/file-structure.md', stack, answers);
         docs['testing/strategy.md'] = generateTestingStrategy(answers, stack);
-        docs['testing/unit-tests.md'] = '# Unit Testing\n\nUnit testing documentation to be added.\n';
-        docs['testing/integration-tests.md'] = '# Integration Testing\n\nIntegration testing documentation to be added.\n';
-        docs['testing/e2e-tests.md'] = '# E2E Testing\n\nE2E testing documentation to be added.\n';
-        docs['deployment/ci-cd.md'] = '# CI/CD Pipeline\n\nCI/CD documentation to be added.\n';
-        docs['deployment/infrastructure.md'] = '# Infrastructure\n\nInfrastructure documentation to be added.\n';
+        docs['testing/unit-tests.md'] = getFallbackTemplate('testing/unit-tests.md', stack, answers);
+        docs['testing/integration-tests.md'] = getFallbackTemplate('testing/integration-tests.md', stack, answers);
+        docs['testing/e2e-tests.md'] = getFallbackTemplate('testing/e2e-tests.md', stack, answers);
+        docs['deployment/ci-cd.md'] = getFallbackTemplate('deployment/ci-cd.md', stack, answers);
+        docs['deployment/infrastructure.md'] = getFallbackTemplate('deployment/infrastructure.md', stack, answers);
     }
     // ==========================================================================
-    // Context7: Fetch real library documentation
+    // STEP 3: Write library docs from Context7 (already fetched in step 1)
     // ==========================================================================
-    // Fetch library documentation from Context7 (if available and project has libraries)
-    let libraryDocs = [];
-    if (!stack.isEmpty && (stack.frameworks.length > 0 || stack.libraries.length > 0)) {
-        progress('Fetching library documentation from Context7...');
-        libraryDocs = await fetchAllLibraryDocs(stack, progress);
-        // Write library docs
+    if (libraryDocs.length > 0) {
         for (const libDoc of libraryDocs) {
             if (libDoc.success && libDoc.content) {
                 const libPath = `libraries/${libDoc.filename}`;
                 docs[libPath] = libDoc.content;
             }
         }
-        // Generate libraries index
         docs['libraries/index.md'] = generateLibrariesIndex(stack, libraryDocs);
     }
     else {
-        // Empty project - placeholder library index
         docs['libraries/index.md'] = `# Library Documentation
 
 No libraries detected yet.
@@ -1152,10 +1264,371 @@ Once you add dependencies to your project, run \`claudetools onboard --refresh\`
     addToGitignore(projectPath, '.claudetools/');
     return generatedDocs;
 }
-function getFallbackTemplate(docPath) {
+function getFallbackTemplate(docPath, stack, answers) {
     const title = docPath.split('/').pop()?.replace('.md', '').replace(/-/g, ' ') || 'Documentation';
     const capitalizedTitle = title.charAt(0).toUpperCase() + title.slice(1);
-    return `# ${capitalizedTitle}\n\nDocumentation to be added.\n`;
+    // Generate meaningful templates based on doc type
+    if (docPath.includes('system-design') && stack && answers) {
+        return `# System Design
+
+## Overview
+
+${answers.projectDescription || 'Project system architecture documentation.'}
+
+## Technology Stack
+
+**Language:** ${stack.primaryLanguage}
+**Package Manager:** ${stack.packageManager}
+
+${stack.frameworks.length > 0 ? `### Frameworks\n${stack.frameworks.map(f => `- **${f.name}** ${f.version} (${f.category})`).join('\n')}` : ''}
+
+${stack.libraries.length > 0 ? `### Key Libraries\n${stack.libraries.slice(0, 5).map(l => `- **${l.name}** ${l.version} (${l.category})`).join('\n')}` : ''}
+
+## Architecture Overview
+
+*Analyse the codebase to document the architecture patterns used.*
+
+## Key Components
+
+*Document the main modules and their responsibilities.*
+`;
+    }
+    if (docPath.includes('data-flow')) {
+        return `# Data Flow
+
+## Overview
+
+This document describes how data flows through the application.
+
+## Request/Response Flow
+
+\`\`\`
+Client Request → Router → Handler → Service → Data Store
+                                          ↓
+Client Response ← Handler ← Service ← Data Store
+\`\`\`
+
+## State Management
+
+*Document the state management approach used in this project.*
+
+## Data Transformations
+
+*Document key data transformation points.*
+`;
+    }
+    if (docPath.includes('components') && stack) {
+        const hasReact = stack.frameworks.some(f => ['react', 'next', 'remix'].includes(f.name.toLowerCase()));
+        return `# Component Architecture
+
+## Overview
+
+${hasReact ? 'React-based component architecture.' : 'Component-based architecture.'}
+
+## Component Structure
+
+\`\`\`
+src/
+├── components/
+│   ├── ui/        # Reusable UI components
+│   ├── layout/    # Layout components
+│   └── features/  # Feature-specific components
+└── pages/         # Page components
+\`\`\`
+
+## Component Guidelines
+
+1. **Single Responsibility** - One component, one job
+2. **Composition** - Build complex UIs from simple parts
+3. **Props** - Clear, typed interfaces
+4. **State** - Keep state local where possible
+`;
+    }
+    if (docPath.includes('endpoints')) {
+        return `# API Endpoints
+
+## Overview
+
+API endpoint documentation.
+
+## Endpoint Reference
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | /api/health | Health check |
+| GET | /api/* | List resources |
+| POST | /api/* | Create resource |
+| GET | /api/*/:id | Get resource |
+| PUT | /api/*/:id | Update resource |
+| DELETE | /api/*/:id | Delete resource |
+
+*Analyse route files to document actual endpoints.*
+`;
+    }
+    if (docPath.includes('schemas')) {
+        return `# Data Schemas
+
+## Overview
+
+Data schema and type definitions.
+
+## Core Types
+
+*Extract from type definitions in the codebase.*
+
+## Validation
+
+*Document validation approach (Zod, Yup, etc).*
+`;
+    }
+    if (docPath.includes('authentication')) {
+        return `# Authentication
+
+## Overview
+
+Authentication and authorisation implementation.
+
+## Auth Flow
+
+*Document the authentication method used (JWT, sessions, OAuth, etc).*
+
+## Protected Resources
+
+*List routes/resources requiring authentication.*
+`;
+    }
+    if (docPath.includes('configuration') && stack) {
+        return `# Configuration
+
+## Overview
+
+Project configuration documentation.
+
+## Config Files
+
+- \`package.json\` - Dependencies and scripts
+- \`tsconfig.json\` - TypeScript configuration
+${stack.frameworks.some(f => f.name === 'next') ? '- `next.config.js` - Next.js configuration\n' : ''}${stack.frameworks.some(f => f.name === 'astro') ? '- `astro.config.mjs` - Astro configuration\n' : ''}- \`.env\` - Environment variables
+
+## Build Configuration
+
+*Document build and bundler configuration.*
+`;
+    }
+    if (docPath.includes('environment')) {
+        return `# Environment Variables
+
+## Overview
+
+Environment variable documentation.
+
+## Required Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| NODE_ENV | Environment mode | development |
+
+## Optional Variables
+
+*Document optional configuration variables.*
+
+## Secrets
+
+*Never commit secrets. Use .env.local for local development.*
+`;
+    }
+    if (docPath.includes('dependencies') && stack) {
+        return `# Dependencies
+
+## Overview
+
+Project dependency documentation.
+
+## Core Dependencies
+
+${stack.frameworks.map(f => `- **${f.name}** ${f.version} - ${f.category}`).join('\n') || '*No frameworks detected*'}
+
+## Libraries
+
+${stack.libraries.map(l => `- **${l.name}** ${l.version} - ${l.category}`).join('\n') || '*No libraries detected*'}
+
+## Dev Dependencies
+
+${stack.devTools.map(t => `- **${t.name}** - ${t.category}`).join('\n') || '*No dev tools detected*'}
+`;
+    }
+    if (docPath.includes('naming-conventions')) {
+        return `# Naming Conventions
+
+## Files
+
+- **Components:** PascalCase (e.g., \`UserProfile.tsx\`)
+- **Utilities:** kebab-case (e.g., \`date-utils.ts\`)
+- **Types:** PascalCase (e.g., \`UserTypes.ts\`)
+
+## Code
+
+- **Variables:** camelCase
+- **Constants:** SCREAMING_SNAKE_CASE
+- **Functions:** camelCase (verbs: \`getUserById\`)
+- **Components:** PascalCase
+- **Types/Interfaces:** PascalCase
+
+## CSS
+
+- **Classes:** kebab-case or BEM
+`;
+    }
+    if (docPath.includes('file-structure')) {
+        return `# File Structure
+
+## Project Layout
+
+\`\`\`
+├── src/
+│   ├── components/   # UI components
+│   ├── lib/          # Utilities
+│   ├── pages/        # Pages/routes
+│   ├── services/     # API services
+│   └── types/        # Type definitions
+├── public/           # Static assets
+├── tests/            # Test files
+└── docs/             # Documentation
+\`\`\`
+
+## Conventions
+
+- Collocate related code
+- One component per file
+- Index files only for public API
+`;
+    }
+    if (docPath.includes('unit-tests')) {
+        return `# Unit Testing
+
+## Overview
+
+Unit testing documentation.
+
+## Running Tests
+
+\`\`\`bash
+npm test           # Run all tests
+npm test -- -u     # Update snapshots
+npm test -- file   # Run specific file
+\`\`\`
+
+## Writing Tests
+
+- Test one thing per test
+- Use descriptive test names
+- Arrange, Act, Assert pattern
+`;
+    }
+    if (docPath.includes('integration-tests')) {
+        return `# Integration Testing
+
+## Overview
+
+Integration testing documentation.
+
+## Approach
+
+- Test component interactions
+- Mock external services
+- Use test databases
+`;
+    }
+    if (docPath.includes('e2e-tests')) {
+        return `# E2E Testing
+
+## Overview
+
+End-to-end testing documentation.
+
+## Running E2E Tests
+
+\`\`\`bash
+npm run e2e        # Run E2E tests
+npm run e2e:ui     # With UI
+\`\`\`
+
+## Test Coverage
+
+*Document critical user flows tested.*
+`;
+    }
+    if (docPath.includes('ci-cd')) {
+        return `# CI/CD Pipeline
+
+## Overview
+
+Continuous integration and deployment configuration.
+
+## Pipeline Stages
+
+1. **Install** - Install dependencies
+2. **Lint** - Code quality checks
+3. **Test** - Run test suite
+4. **Build** - Build for production
+5. **Deploy** - Deploy to environment
+
+## Triggers
+
+- Push to main → Deploy to production
+- Pull request → Run checks
+`;
+    }
+    if (docPath.includes('infrastructure')) {
+        return `# Infrastructure
+
+## Overview
+
+Infrastructure and hosting documentation.
+
+## Hosting
+
+*Document hosting platform (Vercel, Cloudflare, AWS, etc).*
+
+## Services
+
+*Document external services and integrations.*
+`;
+    }
+    if (docPath.includes('contributing')) {
+        return `# Contributing
+
+## Getting Started
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+## Code Standards
+
+- Follow existing patterns
+- Write tests for new features
+- Update documentation
+
+## Commit Messages
+
+Use conventional commits: \`type(scope): description\`
+`;
+    }
+    // Default template
+    return `# ${capitalizedTitle}
+
+*This document will be populated based on project analysis.*
+
+## Overview
+
+*Add overview content.*
+
+## Details
+
+*Add detailed documentation.*
+`;
 }
 function addToGitignore(projectPath, entry) {
     const gitignorePath = join(projectPath, '.gitignore');