create-claude-webapp 1.0.0

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "create-claude-webapp",
+  "version": "1.0.0",
+  "packageManager": "npm@10.8.2",
+  "description": "TypeScript boilerplate with skills and sub-agents for Claude Code. Prevents context exhaustion through role-based task splitting.",
+  "keywords": [
+    "typescript",
+    "boilerplate",
+    "template",
+    "starter",
+    "scaffolding",
+    "cli",
+    "claude-code",
+    "anthropic",
+    "ai-development",
+    "llm-development",
+    "skills",
+    "sub-agents",
+    "agentic",
+    "workflow",
+    "multi-agent"
+  ],
+  "author": "Sven Malvik",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/svenmalvik/claude-boilerplate-4-web.git"
+  },
+  "bin": {
+    "create-claude-webapp": "bin/create-project.js"
+  },
+  "scripts": {
+    "build": "tsc && tsc-alias",
+    "build:backend": "tsc && tsc-alias",
+    "build:frontend": "vite build",
+    "dev": "tsx src/index.ts",
+    "dev:frontend": "vite",
+    "watch": "tsx watch src/index.ts",
+    "preview": "vite preview",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "test:coverage:summary": "node scripts/show-coverage.js",
+    "test:coverage:clean": "rm -rf coverage .vitest-cache",
+    "test:coverage:fresh": "npm run test:coverage:clean && npm run test:coverage",
+    "test:watch": "vitest",
+    "format": "biome format --write src",
+    "format:check": "biome format src",
+    "lint": "biome lint src",
+    "lint:fix": "biome lint --write src",
+    "check": "biome check src",
+    "check:fix": "biome check --write src",
+    "check:unused": "node scripts/check-unused-exports.js",
+    "check:unused:all": "ts-prune --project tsconfig.json --ignore 'src/index.ts|__tests__|test|vitest'",
+    "check:deps": "madge --circular --extensions ts src",
+    "check:deps:graph": "madge --extensions ts --image graph.svg src",
+    "check:code": "npm run check && npm run check:unused && npm run check:deps && npm run build",
+    "check:all": "npm run check:code && npm run test",
+    "cleanup:processes": "bash ./scripts/cleanup-test-processes.sh",
+    "test:safe": "npm test && npm run cleanup:processes",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.0.0",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "c8": "^10.1.3",
+    "fast-check": "^4.3.0",
+    "husky": "^9.1.7",
+    "jsdom": "^25.0.0",
+    "lint-staged": "^16.1.0",
+    "madge": "^8.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "ts-node": "^10.9.1",
+    "ts-prune": "^0.10.3",
+    "tsc-alias": "^1.8.7",
+    "tsx": "^4.19.4",
+    "typescript": "^5.0.0",
+    "vite": "^5.0.0",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "lint-staged": {
+    "src/**/*.{ts,tsx}": [
+      "biome check --write --no-errors-on-unmatched",
+      "biome format --write --no-errors-on-unmatched"
+    ]
+  }
+}

package/scripts/check-unused-exports.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+/**
+ * Unused exports checker script
+ * Filters out "used in module" from ts-prune output to show only truly unused exports
+ */
+
+const { execSync } = require('child_process')
+
+try {
+  // Run ts-prune
+  const output = execSync(
+    'npx ts-prune --project tsconfig.json --ignore "src/index.ts|__tests__|test|vitest"',
+    { encoding: 'utf8' }
+  )
+
+  // Process each line
+  const lines = output.split('\n').filter(line => line.trim())
+  const results = {
+    usedInModule: [],
+    trulyUnused: [],
+    total: 0
+  }
+
+  for (const line of lines) {
+    if (line.includes(' - ')) {
+      results.total++
+      if (line.includes('(used in module)')) {
+        results.usedInModule.push(line)
+      } else {
+        results.trulyUnused.push(line)
+      }
+    }
+  }
+
+  // Display results
+  console.log('=== Unused Exports Analysis ===\n')
+  
+  if (results.trulyUnused.length > 0) {
+    console.log(`🔴 Truly unused exports: ${results.trulyUnused.length}`)
+    console.log('─'.repeat(50))
+    results.trulyUnused.forEach(line => console.log(line))
+    console.log('')
+  } else {
+    console.log('✅ No truly unused exports found\n')
+  }
+
+  if (results.usedInModule.length > 0) {
+    console.log(`⚠️ Used only in module (unnecessary exports): ${results.usedInModule.length}`)
+    console.log('─'.repeat(50))
+    results.usedInModule.forEach(line => console.log(line))
+    console.log('')
+  } else {
+    console.log('✅ No unnecessary internal exports found\n')
+  }
+
+  // Summary
+  console.log('=== Summary ===')
+  console.log(`Total unnecessary exports: ${results.total}`)
+  console.log(`├── Truly unused: ${results.trulyUnused.length} (delete immediately)`)
+  console.log(`└── Used in module only: ${results.usedInModule.length} (remove export keyword)`)
+
+  // Exit code
+  process.exit(results.trulyUnused.length > 0 ? 1 : 0)
+
+} catch (error) {
+  console.error('Error occurred:', error.message)
+  process.exit(1)
+}

package/scripts/cleanup-test-processes.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+
+# Vitest process cleanup script
+# Check and remove zombie processes after test execution
+
+echo "🔍 Checking for remaining test processes..."
+
+# Vitest process check
+VITEST_PROCESSES=$(ps aux | grep vitest | grep -v grep || true)
+if [ -n "$VITEST_PROCESSES" ]; then
+    echo "⚠️  Found vitest processes:"
+    echo "$VITEST_PROCESSES"
+    echo "🔥 Killing vitest processes..."
+    pkill -f vitest
+    echo "✅ Vitest processes cleaned up"
+else
+    echo "✅ No vitest processes found"
+fi
+
+# Node test process check
+NODE_TEST_PROCESSES=$(ps aux | grep "node.*test" | grep -v grep || true)
+if [ -n "$NODE_TEST_PROCESSES" ]; then
+    echo "⚠️  Found node test processes:"
+    echo "$NODE_TEST_PROCESSES"
+    echo "🔥 Killing node test processes..."
+    pkill -f "node.*test"
+    echo "✅ Node test processes cleaned up"
+else
+    echo "✅ No node test processes found"
+fi
+
+echo "🧹 Process cleanup completed!"

package/scripts/post-setup.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+/**
+ * Initialize git repository
+ */
+function initGit() {
+  try {
+    console.log('🔧 Initializing git repository...');
+    execSync('git init', { stdio: 'inherit' });
+    
+    console.log('📝 Creating initial commit...');
+    execSync('git add -A', { stdio: 'inherit' });
+    execSync('git commit -m "Initial commit from AI Coding Project Boilerplate"', { stdio: 'inherit' });
+    
+    return true;
+  } catch (error) {
+    console.warn('⚠️  Git initialization skipped (git might not be installed)');
+    return false;
+  }
+}
+
+/**
+ * Clean up files that shouldn't be in the user's project
+ */
+function cleanupFiles() {
+  console.log('🧹 Cleaning up setup files...');
+  
+  const filesToRemove = [
+    'bin/create-project.js',
+    'templates/.gitignore.template',
+    'scripts/setup-project.js',
+    'scripts/post-setup.js'
+  ];
+  
+  const dirsToRemove = [
+    'bin',
+    'templates'
+  ];
+  
+  // Remove files
+  for (const file of filesToRemove) {
+    const filePath = path.join(process.cwd(), file);
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+    }
+  }
+  
+  // Remove empty directories
+  for (const dir of dirsToRemove) {
+    const dirPath = path.join(process.cwd(), dir);
+    if (fs.existsSync(dirPath)) {
+      try {
+        fs.rmdirSync(dirPath);
+      } catch (e) {
+        // Directory might not be empty, ignore
+      }
+    }
+  }
+}
+
+/**
+ * Show next steps to the user
+ */
+function showNextSteps() {
+  const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+  const projectName = packageJson.name;
+  
+  console.log('\n🎉 Project setup completed successfully!\n');
+  console.log('📋 Next steps:\n');
+  console.log(`   cd ${projectName}`);
+  console.log('   npm install');
+  console.log('   npm run dev\n');
+  console.log('🌐 Language switching:\n');
+  console.log('   npm run lang:ja   # Switch to Japanese');
+  console.log('   npm run lang:en   # Switch to English\n');
+  console.log('📖 Available commands:\n');
+  console.log('   npm run dev         # Start development');
+  console.log('   npm run build       # Build for production');
+  console.log('   npm run test        # Run tests');
+  console.log('   npm run check:all   # Run all quality checks\n');
+  console.log('Happy coding! 🚀\n');
+}
+
+/**
+ * Main post-setup process
+ */
+function main() {
+  try {
+    // Initialize git repository
+    initGit();
+    
+    // Clean up setup-specific files
+    cleanupFiles();
+    
+    // Show next steps
+    showNextSteps();
+  } catch (error) {
+    console.error(`❌ Post-setup failed: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+// Run post-setup
+if (require.main === module) {
+  main();
+}

package/scripts/setup-project.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Get command line arguments
+const projectName = process.argv[2];
+
+if (!projectName) {
+  console.error('❌ Project name is required');
+  process.exit(1);
+}
+
+const sourceRoot = path.join(__dirname, '..');
+const targetRoot = path.resolve(process.cwd(), projectName);
+
+// Files and directories to exclude from copying
+const excludeList = [
+  'node_modules',
+  '.git',
+  'dist',
+  'coverage',
+  '.vitest-cache',
+  'tmp',
+  '.claudelang',
+  'docs/rules',
+  'docs/guides/sub-agents.md',
+  'bin', // Exclude bin directory for production use
+  'templates' // Exclude templates directory for production use
+];
+
+// Files to process with template replacements
+const templateFiles = [
+  'package.json',
+  'README.md'
+];
+
+/**
+ * Recursively copy directory with exclusions
+ */
+function copyDirectory(source, target, projectName, rootSource = source) {
+  if (!fs.existsSync(source)) {
+    return;
+  }
+
+  // Create target directory
+  if (!fs.existsSync(target)) {
+    fs.mkdirSync(target, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(source, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const sourcePath = path.join(source, entry.name);
+    const targetPath = path.join(target, entry.name);
+    const relativePath = path.relative(rootSource, sourcePath);
+
+    // Check if should exclude
+    const shouldExclude = excludeList.some(exclude => {
+      const excludePath = path.normalize(exclude);
+      const relativeNormalized = path.normalize(relativePath);
+      return relativeNormalized === excludePath || relativeNormalized.startsWith(excludePath + path.sep);
+    });
+
+    if (shouldExclude) {
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      copyDirectory(sourcePath, targetPath, projectName, rootSource);
+    } else {
+      // Check if it's a template file that needs processing
+      if (templateFiles.includes(entry.name)) {
+        processTemplateFile(sourcePath, targetPath, projectName);
+      } else {
+        fs.copyFileSync(sourcePath, targetPath);
+      }
+    }
+  }
+}
+
+/**
+ * Process template files with replacements
+ */
+function processTemplateFile(source, target, projectName) {
+  let content = fs.readFileSync(source, 'utf8');
+
+  // Replace placeholders based on file
+  const fileName = path.basename(source);
+  
+  if (fileName === 'package.json') {
+    const packageJson = JSON.parse(content);
+    packageJson.name = projectName;
+    packageJson.version = '0.1.0';
+    packageJson.description = `${projectName} - AI-powered TypeScript project`;
+    
+    // Remove bin field for user projects
+    delete packageJson.bin;
+    
+    // Remove scripts related to package maintenance
+    delete packageJson.scripts['lang:status'];
+    delete packageJson.scripts.postinstall;
+    
+    content = JSON.stringify(packageJson, null, 2);
+  } else if (fileName === 'README.md') {
+    // Replace project name in README
+    content = content.replace(/claude-boilerplate-4-web/g, projectName);
+    content = content.replace(/AI Coding Project Boilerplate/g, projectName);
+  }
+
+  fs.writeFileSync(target, content);
+}
+
+/**
+ * Main setup process
+ */
+async function setupProject() {
+  try {
+    console.log('📁 Creating project directory...');
+    fs.mkdirSync(targetRoot, { recursive: true });
+
+    console.log('📋 Copying project files...');
+    copyDirectory(sourceRoot, targetRoot, projectName);
+
+    // Change to project directory
+    process.chdir(targetRoot);
+
+    console.log('🔧 Running post-setup tasks...');
+    const postSetupScript = path.join(sourceRoot, 'scripts', 'post-setup.js');
+    if (fs.existsSync(postSetupScript)) {
+      execSync(`node ${postSetupScript}`, { stdio: 'inherit', cwd: targetRoot });
+    }
+
+    console.log('✅ Project setup completed!');
+  } catch (error) {
+    console.error(`❌ Setup failed: ${error.message}`);
+    
+    // Cleanup on failure
+    if (fs.existsSync(targetRoot)) {
+      console.log('🧹 Cleaning up...');
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+    
+    process.exit(1);
+  }
+}
+
+// Run setup
+setupProject();

package/scripts/show-coverage.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+const fs = require('fs')
+const path = require('path')
+
+const coverageFile = path.join(__dirname, '..', 'coverage', 'coverage-final.json')
+
+if (!fs.existsSync(coverageFile)) {
+  console.error('❌ Coverage report not found.')
+  console.error('   Please run npm run test:coverage first.')
+  process.exit(1)
+}
+
+try {
+  const coverage = JSON.parse(fs.readFileSync(coverageFile, 'utf8'))
+  
+  let totalStatements = 0
+  let coveredStatements = 0
+  let totalBranches = 0
+  let coveredBranches = 0
+  let totalFunctions = 0
+  let coveredFunctions = 0
+  let totalLines = 0
+  let coveredLines = 0
+
+  Object.values(coverage).forEach(file => {
+    totalStatements += file.s ? Object.keys(file.s).length : 0
+    coveredStatements += file.s ? Object.values(file.s).filter(count => count > 0).length : 0
+    
+    totalBranches += file.b ? Object.values(file.b).flat().length : 0
+    coveredBranches += file.b ? Object.values(file.b).flat().filter(count => count > 0).length : 0
+    
+    totalFunctions += file.f ? Object.keys(file.f).length : 0
+    coveredFunctions += file.f ? Object.values(file.f).filter(count => count > 0).length : 0
+    
+    totalLines += file.l ? Object.keys(file.l).length : 0
+    coveredLines += file.l ? Object.values(file.l).filter(count => count > 0).length : 0
+  })
+
+  const statementsCoverage = totalStatements > 0 ? ((coveredStatements / totalStatements) * 100).toFixed(2) : '0.00'
+  const branchesCoverage = totalBranches > 0 ? ((coveredBranches / totalBranches) * 100).toFixed(2) : '0.00'
+  const functionsCoverage = totalFunctions > 0 ? ((coveredFunctions / totalFunctions) * 100).toFixed(2) : '0.00'
+  const linesCoverage = totalLines > 0 ? ((coveredLines / totalLines) * 100).toFixed(2) : '0.00'
+
+  console.log('\n📊 Test Coverage Summary')
+  console.log('═══════════════════════════════════════')
+  console.log(`  Statements : ${statementsCoverage.padStart(6)}% (${coveredStatements}/${totalStatements})`)
+  console.log(`  Branches   : ${branchesCoverage.padStart(6)}% (${coveredBranches}/${totalBranches})`)
+  console.log(`  Functions  : ${functionsCoverage.padStart(6)}% (${coveredFunctions}/${totalFunctions})`)
+  console.log(`  Lines      : ${linesCoverage.padStart(6)}% (${coveredLines}/${totalLines})`)
+  console.log('═══════════════════════════════════════')
+
+  // Assessment against 80% target
+  const allMetrics = [
+    parseFloat(statementsCoverage),
+    parseFloat(branchesCoverage),
+    parseFloat(functionsCoverage),
+    parseFloat(linesCoverage)
+  ]
+  
+  const failedMetrics = allMetrics.filter(metric => metric < 80).length
+
+  if (failedMetrics === 0) {
+    console.log('\n✅ All metrics achieved the 80% target!')
+  } else {
+    console.log('\n⚠️  Some metrics have not reached the 80% target.')
+    console.log('   Please check coverage/index.html for details.')
+  }
+  console.log()
+
+} catch (error) {
+  console.error('❌ Failed to read coverage report:', error.message)
+  process.exit(1)
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Application entry point
+ *
+ * This file serves as a usage example for the boilerplate.
+ * In actual projects, implement your application-specific logic here.
+ */
+
+console.log('Hello from TypeScript boilerplate!')
+
+// Add your project-specific implementation here
+export {}

package/templates/.gitignore.template

@@ -0,0 +1,52 @@
+# Dependencies
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Build artifacts
+dist/
+build/
+*.tsbuildinfo
+
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Log files
+logs
+*.log
+
+# Runtime data
+.nyc_output
+coverage
+test-output.json
+
+# IDE and editor specific files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS specific files
+.DS_Store
+Thumbs.db
+
+# Temporary files
+*.tmp
+*.temp
+tmp/
+
+# Work plans (excluded from commits)
+docs/plans/*
+!docs/plans/template-*.md
+
+# Work plan tasks (auto-generated)
+docs/plans/tasks/
+
+# Multi-language related (dynamically generated by npm scripts)
+.claudelang

package/tsconfig.json

@@ -0,0 +1,50 @@
+{
+  "compilerOptions": {
+    // Basic configuration
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "types": ["node"],
+    "baseUrl": ".",  // Use project root as reference
+    "paths": {
+      "src/*": ["src/*"]
+    },
+    
+    // Output configuration
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+    
+    // Strict type checking (this is important!)
+    "strict": true,                          // Enable all strict checks
+    "noImplicitAny": true,                   // Prohibit implicit any
+    "strictNullChecks": true,                // Strict null/undefined checks
+    "strictFunctionTypes": true,             // Strict function type checks
+    "strictBindCallApply": true,             // Strict bind/call/apply checks
+    "strictPropertyInitialization": true,    // Strict property initialization checks
+    "noImplicitThis": true,                  // Prohibit implicit this
+    "alwaysStrict": true,                    // Always enable strict mode
+    
+    // Additional safety checks (currently disabled in this PR)
+    "noUncheckedIndexedAccess": true,       // Safety checks for index access
+    "exactOptionalPropertyTypes": true,      // Strict type checking for optional properties
+    "noPropertyAccessFromIndexSignature": true, // Prohibit property access from index signature
+    
+    // Error detection
+    "noFallthroughCasesInSwitch": true,     // Prohibit fallthrough in switch statements
+    "noImplicitReturns": true,              // Prohibit implicit returns
+    "noImplicitOverride": true,             // Require override keyword
+    "noUnusedLocals": true,                 // Detect unused local variables
+    "noUnusedParameters": true,             // Detect unused parameters
+    
+    // Module resolution
+    "esModuleInterop": true,
+    "skipLibCheck": true,                    // Skip type checking of declaration files (build optimization)
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.spec.ts", "**/*.test.ts"]
+}