cc-starter 1.0.0

package/lib/scaffold.js

@@ -0,0 +1,261 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import Handlebars from 'handlebars';
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = path.join(__dirname, '..', 'template');
+
+/**
+ * Scaffold a cc-starter project into the given directory.
+ * @param {object} config - Wizard output
+ * @param {string} [cwd=process.cwd()] - Target directory
+ * @returns {Promise<{ filesCreated: number, filesSkipped: number }>}
+ */
+export async function scaffold(config, cwd = process.cwd()) {
+  let filesCreated = 0;
+  let filesSkipped = 0;
+
+  // ── 1. .claude/ directory structure ────────────────────────────────
+  const claudeDir = path.join(cwd, '.claude');
+  const claudeExists = fs.existsSync(claudeDir);
+
+  let claudeAction = 'overwrite';
+  if (claudeExists) {
+    const answer = await inquirer.prompt([{
+      type: 'list',
+      name: 'action',
+      message: 'Existing .claude/ found. What should we do?',
+      choices: [
+        { name: 'Overwrite — replace all files', value: 'overwrite' },
+        { name: 'Merge — keep existing, add missing files only', value: 'merge' },
+        { name: 'Skip — leave .claude/ untouched', value: 'skip' }
+      ]
+    }]);
+    claudeAction = answer.action;
+  }
+
+  if (claudeAction === 'skip') {
+    console.log(chalk.yellow('  ⊘ .claude/') + chalk.dim('                 skipped'));
+    filesSkipped += countFiles(path.join(TEMPLATE_DIR, 'claude'));
+  } else {
+    const result = copyClaudeDir(claudeAction, cwd);
+    filesCreated += result.created;
+    filesSkipped += result.skipped;
+  }
+
+  // ── 2. Render CLAUDE.md from Handlebars template ──────────────────
+  const claudeMdPath = path.join(cwd, 'CLAUDE.md');
+  const claudeMdExists = fs.existsSync(claudeMdPath);
+
+  let claudeMdAction = 'overwrite';
+  if (claudeMdExists) {
+    const answer = await inquirer.prompt([{
+      type: 'list',
+      name: 'action',
+      message: 'Existing CLAUDE.md found. What should we do?',
+      choices: [
+        { name: 'Overwrite — replace with cc-starter version', value: 'overwrite' },
+        { name: 'Append — add cc-starter section at the end', value: 'append' },
+        { name: 'Skip — leave CLAUDE.md untouched', value: 'skip' }
+      ]
+    }]);
+    claudeMdAction = answer.action;
+  }
+
+  if (claudeMdAction === 'skip') {
+    console.log(chalk.yellow('  ⊘ CLAUDE.md') + chalk.dim('               skipped'));
+    filesSkipped += 1;
+  } else {
+    renderClaudeMd(config, claudeMdAction, cwd);
+    filesCreated += 1;
+    console.log(chalk.green('  ✓ CLAUDE.md') + chalk.dim(`               ${claudeMdAction === 'append' ? 'appended' : 'created'}`));
+  }
+
+  // ── 3. Copy scripts/stats/ (always overwrite) ─────────────────────
+  const scriptsResult = copyScriptsStats(cwd);
+  filesCreated += scriptsResult.created;
+  console.log(chalk.green('  ✓ scripts/stats/') + chalk.dim(`          ${scriptsResult.created} files`));
+
+  // ── 4. Create .cc-starter.json (always overwrite) ──────────────────
+  const ccConfig = {
+    projectName: config.projectName,
+    hourlyRate: config.hourlyRate,
+    reportStyle: config.reportStyle,
+    createdAt: new Date().toISOString(),
+    version: '1.0.0'
+  };
+  fs.writeJsonSync(path.join(cwd, '.cc-starter.json'), ccConfig, { spaces: 2 });
+  filesCreated += 1;
+  console.log(chalk.green('  ✓ .cc-starter.json') + chalk.dim('        created'));
+
+  // ── 5. Update .gitignore ───────────────────────────────────────────
+  const gitignoreUpdated = updateGitignore(cwd);
+  if (gitignoreUpdated) {
+    filesCreated += 1;
+    console.log(chalk.green('  ✓ .gitignore') + chalk.dim('              updated'));
+  } else {
+    console.log(chalk.dim('  - .gitignore              already up to date'));
+  }
+
+  console.log();
+  console.log(chalk.bold.green(`  Done!`) + chalk.dim(` ${filesCreated} created, ${filesSkipped} skipped`));
+
+  return { filesCreated, filesSkipped };
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────
+
+/**
+ * Copy the template/claude/ tree into cwd/.claude/.
+ * In 'merge' mode, only copies files that don't already exist.
+ */
+function copyClaudeDir(action, cwd) {
+  const src = path.join(TEMPLATE_DIR, 'claude');
+  const dest = path.join(cwd, '.claude');
+  let created = 0;
+  let skipped = 0;
+
+  const subdirs = [
+    { dir: 'rules',     files: ['01-general.md', '02-code-standards.md', '03-dev-ops.md'] },
+    { dir: 'memory',    files: ['MEMORY.md'] },
+    { dir: 'project',   files: ['README.md'] },
+    { dir: 'reference', files: ['README.md'] },
+    { dir: 'commands',  files: ['kickstart.md'] },
+  ];
+
+  // Also copy settings.json at the root of .claude/
+  const rootFiles = ['settings.json'];
+
+  for (const { dir, files } of subdirs) {
+    const destDir = path.join(dest, dir);
+    fs.ensureDirSync(destDir);
+    let dirCreated = 0;
+
+    for (const file of files) {
+      const srcFile = path.join(src, dir, file);
+      const destFile = path.join(destDir, file);
+
+      if (action === 'merge' && fs.existsSync(destFile)) {
+        skipped += 1;
+        continue;
+      }
+
+      fs.copySync(srcFile, destFile);
+      dirCreated += 1;
+      created += 1;
+    }
+
+    if (dirCreated > 0) {
+      console.log(chalk.green(`  ✓ .claude/${dir}/`) + chalk.dim(`          ${dirCreated} file${dirCreated !== 1 ? 's' : ''}`));
+    } else {
+      console.log(chalk.yellow(`  ⊘ .claude/${dir}/`) + chalk.dim('          skipped (exists)'));
+    }
+  }
+
+  for (const file of rootFiles) {
+    const srcFile = path.join(src, file);
+    const destFile = path.join(dest, file);
+
+    if (action === 'merge' && fs.existsSync(destFile)) {
+      skipped += 1;
+      console.log(chalk.yellow(`  ⊘ .claude/${file}`) + chalk.dim('       skipped (exists)'));
+      continue;
+    }
+
+    fs.copySync(srcFile, destFile);
+    created += 1;
+    console.log(chalk.green(`  ✓ .claude/${file}`) + chalk.dim('       created'));
+  }
+
+  return { created, skipped };
+}
+
+/**
+ * Render CLAUDE.md from Handlebars template.
+ */
+function renderClaudeMd(config, action, cwd) {
+  const templateSrc = fs.readFileSync(path.join(TEMPLATE_DIR, 'CLAUDE.md.hbs'), 'utf-8');
+  const template = Handlebars.compile(templateSrc);
+
+  const techStack = config.techStack || { languages: [], frameworks: [] };
+  const rendered = template({
+    projectName: config.projectName,
+    techStack
+  });
+
+  const destPath = path.join(cwd, 'CLAUDE.md');
+
+  if (action === 'append') {
+    const existing = fs.readFileSync(destPath, 'utf-8');
+    const separator = '\n\n---\n\n<!-- cc-starter section -->\n';
+    fs.writeFileSync(destPath, existing + separator + rendered, 'utf-8');
+  } else {
+    fs.writeFileSync(destPath, rendered, 'utf-8');
+  }
+}
+
+/**
+ * Copy scripts/stats/ files (always overwrite).
+ */
+function copyScriptsStats(cwd) {
+  const src = path.join(TEMPLATE_DIR, 'scripts', 'stats');
+  const dest = path.join(cwd, 'scripts', 'stats');
+  fs.ensureDirSync(dest);
+
+  const files = fs.readdirSync(src).filter(f => f.endsWith('.js'));
+  for (const file of files) {
+    fs.copySync(path.join(src, file), path.join(dest, file));
+  }
+
+  return { created: files.length };
+}
+
+/**
+ * Append cc-starter entries to .gitignore if not already present.
+ * @returns {boolean} true if .gitignore was modified
+ */
+function updateGitignore(cwd) {
+  const gitignorePath = path.join(cwd, '.gitignore');
+  let content = '';
+
+  if (fs.existsSync(gitignorePath)) {
+    content = fs.readFileSync(gitignorePath, 'utf-8');
+  }
+
+  const marker = '# cc-starter';
+  if (content.includes(marker)) {
+    return false;
+  }
+
+  const block = [
+    '',
+    '# cc-starter',
+    '.vibe-stats.json',
+    'stats/report.html',
+    ''
+  ].join('\n');
+
+  // Ensure we start on a new line
+  const prefix = content.length > 0 && !content.endsWith('\n') ? '\n' : '';
+  fs.writeFileSync(gitignorePath, content + prefix + block, 'utf-8');
+  return true;
+}
+
+/**
+ * Count files recursively in a directory.
+ */
+function countFiles(dir) {
+  if (!fs.existsSync(dir)) return 0;
+  let count = 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      count += countFiles(path.join(dir, entry.name));
+    } else {
+      count += 1;
+    }
+  }
+  return count;
+}

package/lib/wizard.js

@@ -0,0 +1,99 @@
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import { readFileSync } from 'fs';
+import { basename, resolve } from 'path';
+import {
+  PLUGIN_PRESETS,
+  ALL_PLUGINS,
+  REPORT_STYLES,
+  DEFAULT_HOURLY_RATE
+} from './constants.js';
+
+/**
+ * Detect project name from package.json or fall back to folder name.
+ */
+function detectProjectName() {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve('package.json'), 'utf-8'));
+    if (pkg.name) return pkg.name;
+  } catch {
+    // no package.json — fall through
+  }
+  return basename(resolve('.'));
+}
+
+/**
+ * Interactive setup wizard.
+ * @param {string[]} techStack - Auto-detected technologies (e.g. ['Node.js', 'TypeScript', 'React'])
+ * @returns {Promise<{projectName: string, hourlyRate: number, reportStyle: string, plugins: object[], techStack: string[]}>}
+ */
+export async function wizard(techStack = []) {
+  console.log();
+  console.log(chalk.bold.cyan('  cc-starter') + chalk.dim(' — project kickstart wizard'));
+  console.log();
+
+  if (techStack.length > 0) {
+    console.log(chalk.dim('  Detected tech stack: ') + chalk.yellow(techStack.join(', ')));
+    console.log();
+  }
+
+  const defaultName = detectProjectName();
+
+  const answers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'projectName',
+      message: 'Project name:',
+      default: defaultName
+    },
+    {
+      type: 'number',
+      name: 'hourlyRate',
+      message: 'Hourly rate for COCOMO estimation (\u20ac):',
+      default: DEFAULT_HOURLY_RATE
+    },
+    {
+      type: 'list',
+      name: 'reportStyle',
+      message: 'Report style:',
+      choices: Object.entries(REPORT_STYLES).map(([key, val]) => ({
+        name: val.label,
+        value: key
+      }))
+    },
+    {
+      type: 'list',
+      name: 'pluginPreset',
+      message: 'Plugin preset:',
+      choices: [
+        { name: `Minimal  — ${PLUGIN_PRESETS.minimal.length} plugin`,  value: 'minimal' },
+        { name: `Standard — ${PLUGIN_PRESETS.standard.length} plugins`, value: 'standard' },
+        { name: `Full     — ${PLUGIN_PRESETS.full.length} plugins`,     value: 'full' },
+        { name: 'Custom   — pick individual plugins',                   value: 'custom' }
+      ]
+    },
+    {
+      type: 'checkbox',
+      name: 'customPlugins',
+      message: 'Select plugins:',
+      when: (ans) => ans.pluginPreset === 'custom',
+      choices: ALL_PLUGINS.map((p) => ({
+        name: `${p.name} ${chalk.dim('— ' + p.desc)}`,
+        value: p,
+        checked: false
+      }))
+    }
+  ]);
+
+  const plugins = answers.pluginPreset === 'custom'
+    ? answers.customPlugins || []
+    : PLUGIN_PRESETS[answers.pluginPreset];
+
+  return {
+    projectName: answers.projectName,
+    hourlyRate: answers.hourlyRate,
+    reportStyle: answers.reportStyle,
+    plugins,
+    techStack
+  };
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "cc-starter",
+  "version": "1.0.0",
+  "description": "Claude Code Project Kickstart — scaffolds an optimized dev environment with token-saving scripts, COCOMO estimation, and interactive plugin setup",
+  "type": "module",
+  "bin": {
+    "cc-starter": "bin/cc-starter.js"
+  },
+  "keywords": [
+    "claude-code",
+    "cli",
+    "scaffold",
+    "starter-kit",
+    "vibe-coding",
+    "token-savings",
+    "cocomo",
+    "developer-tools"
+  ],
+  "author": "Lars Fanter",
+  "license": "MIT",
+  "dependencies": {
+    "inquirer": "^9.2.0",
+    "chalk": "^5.3.0",
+    "fs-extra": "^11.2.0",
+    "handlebars": "^4.7.8"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/template/CLAUDE.md.hbs

@@ -0,0 +1,44 @@
+# CLAUDE.md - {{projectName}}
+
+## Project Overview
+**Project:** {{projectName}}
+{{#if techStack.languages.length}}
+**Languages:** {{#each techStack.languages}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}
+{{/if}}
+{{#if techStack.frameworks.length}}
+**Frameworks:** {{#each techStack.frameworks}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}
+{{/if}}
+
+---
+
+## Quick Reference
+
+### Token-Saving Scripts
+```bash
+node scripts/stats/vibe-code.js help       # Code analysis (save ~90% tokens)
+node scripts/stats/vibe-code.js types <f>   # Extract types/interfaces
+node scripts/stats/vibe-code.js tree [dir]  # Clean directory tree
+node scripts/stats/vibe-code.js imports <f> # Show imports
+node scripts/stats/vibe-code.js funcs <f>   # Function signatures
+```
+
+### Project Statistics
+```bash
+node scripts/stats/cocomo.js                # Project cost estimation
+node scripts/stats/project-report.js        # HTML statistics report
+node scripts/stats/vibe-stats.js report     # Token savings report
+```
+
+### Rules
+See `.claude/rules/` for working rules:
+- `01-general.md` — Task tracking, planning, verification
+- `02-code-standards.md` — Code quality, security, testing
+- `03-dev-ops.md` — Git, environment, deployment
+
+### Memory System
+Persistent memory across sessions in `.claude/memory/`.
+Index: `.claude/memory/MEMORY.md`
+
+---
+
+*Generated by [cc-starter](https://www.npmjs.com/package/cc-starter)*

package/template/claude/commands/kickstart.md

@@ -0,0 +1,16 @@
+---
+name: kickstart
+description: Re-run cc-starter setup or upgrade existing configuration
+---
+
+To update your cc-starter configuration, run in your terminal:
+
+```bash
+npx cc-starter
+```
+
+This will:
+- Update rules to the latest version
+- Add any missing scripts
+- Install new plugins
+- Regenerate CLAUDE.md if desired

package/template/claude/memory/MEMORY.md

@@ -0,0 +1,11 @@
+# Project Memory
+
+This is the memory index for this project. Claude Code uses this to persist knowledge across sessions.
+
+## How It Works
+- Each memory is stored as a separate .md file in this directory
+- This file (MEMORY.md) is the index — keep it concise
+- Memory types: user, feedback, project, reference
+
+## Memories
+<!-- Add memory entries below as they are created -->

package/template/claude/project/README.md

@@ -0,0 +1,7 @@
+# Project Context
+
+Add project-specific information here that Claude should know about:
+- Architecture decisions
+- Team conventions
+- External service details
+- Database schema notes

package/template/claude/reference/README.md

@@ -0,0 +1,7 @@
+# Reference Documentation
+
+Add pointers to reference material here:
+- API documentation links
+- Design system guides
+- Architecture diagrams
+- External tool documentation

package/template/claude/rules/01-general.md

@@ -0,0 +1,36 @@
+# General Working Rules
+
+## 1. Task Tracking
+For tasks with **3+ steps** ALWAYS:
+- Use task tracking to manage work items
+- Create each step as a task BEFORE starting
+- Mark each task as completed immediately when done
+
+## 2. Keep Documentation Modular
+- Don't create sprawling status files
+- Updates belong in the matching doc (feature docs, architecture docs)
+- Keep a clean separation of concerns
+
+## 3. Before Coding
+- When unclear: Ask first, then implement
+- When multiple approaches exist: Present options and wait for decision
+
+## 4. When Things Go Wrong: STOP & Re-plan
+- If an approach isn't working: **Stop immediately**, don't keep pushing
+- Re-plan instead of repeating the same mistake
+- Find root causes — no temporary workarounds or hacks
+- Ask yourself: "Is this the elegant solution or a quick-fix?"
+
+## 5. Verification: Diff Against Main Before "Done"
+- Before claiming "done": run `git diff main` to check all changes are intentional
+- Ask yourself: "Would a staff engineer approve this?"
+- Build must be green
+- No unintended changes in unrelated files
+
+## 6. Design Documentation
+When making design decisions, document the process:
+- Summary of final decisions
+- Questions asked with options and chosen answers
+- Reasoning for each choice
+- Technical details
+- Open points

package/template/claude/rules/02-code-standards.md

@@ -0,0 +1,23 @@
+# Code Standards
+
+## Security First
+- Never commit secrets, API keys, or credentials
+- Validate all external input
+- Use parameterized queries for databases
+- Follow OWASP Top 10 guidelines
+
+## Code Quality
+- Write self-documenting code with clear naming
+- Keep functions focused (single responsibility)
+- Prefer composition over inheritance
+- Handle errors explicitly — no silent catches
+
+## Testing
+- Write tests for new features and bug fixes
+- Test edge cases and error paths
+- Don't mock what you don't own — use integration tests where possible
+
+## Internationalization (if applicable)
+- No hardcoded user-facing strings
+- Use your project's i18n solution consistently
+- Keep translation files in sync across locales

package/template/claude/rules/03-dev-ops.md

@@ -0,0 +1,20 @@
+# DevOps & Deployment Rules
+
+## Git Discipline
+- Separate concerns in commits (app code vs. infrastructure vs. docs)
+- Write descriptive commit messages explaining WHY, not just WHAT
+- Never force-push to main/master without team agreement
+
+## Environment Variables
+- New env vars must be documented
+- Never commit .env files with real values
+- Provide .env.example with placeholder values
+
+## Port Management
+- Stick to one dev server port — don't spawn multiple
+- Kill orphan processes before starting new dev servers
+
+## Build Verification
+- Always run build/lint before committing
+- Fix warnings, don't suppress them
+- Keep CI/CD pipeline green

package/template/claude/settings.json

@@ -0,0 +1,4 @@
+{
+  "enabledPlugins": {},
+  "alwaysThinkingEnabled": true
+}