forgedev 1.0.0

package/CLAUDE.md

@@ -0,0 +1,38 @@
+# DevForge
+
+## WHAT
+- Node.js CLI tool for universal project scaffolding
+- ESM modules only (no require/CommonJS)
+- Dependencies: Inquirer.js (prompts), Chalk (colors), Vitest (tests)
+
+## Directory Map
+- `bin/` — CLI entry point (`devforge.js`)
+- `src/` — Core logic (index, prompts, recommender, composer, claude-configurator, uat-generator, utils)
+- `templates/` — Scaffold templates organized by category (base, frontend, backend, database, auth, testing, infra, claude-code)
+- `tests/` — Vitest test files
+- `docs/` — Reference documentation (prompt library, playbook, multi-agent verification)
+
+## HOW
+- Lint: `npx eslint . --ext .js` (when eslint is added)
+- Test: `npx vitest run`
+- Test (watch): `npx vitest`
+- Manual test: `node bin/devforge.js test-output`
+
+## Commands
+- `/project:help`, `/project:status`, `/project:next`, `/project:done` — daily workflow
+- `/project:verify-all`, `/project:audit-spec`, `/project:audit-wiring`, `/project:audit-security` — verification
+- `/project:pre-pr`, `/project:run-uat` — release workflow
+
+## Agents (all READ-ONLY, disallowedTools: Write/Edit/MultiEdit)
+- code-quality-reviewer, security-reviewer, spec-validator, production-readiness, uat-validator
+
+## RULES
+- ESM only — use `import`/`export`, never `require()`
+- All source files are plain `.js` (no TypeScript for the CLI itself)
+- Templates use `{{VARIABLE_NAME}}` placeholders — replaced via simple regex
+- Files ending in `.template` get variable substitution; all others are binary-copied
+- Template modules are composable: `templates/<category>/<stack>/` mirrors the output project structure
+- Never modify files in `docs/` — those are read-only reference documents
+- Keep `src/` files focused: each file has a single responsibility
+- The recommender is a pure function: `(serviceType, refinements) → stackConfig`
+- V1 supports 3 stacks: Next.js full-stack, FastAPI backend, polyglot (Next.js + FastAPI)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DevForge Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,246 @@
+# DevForge
+
+Universal, AI-first project scaffolding CLI. Describe what you're building, get the right stack recommended, and ship with Claude Code infrastructure pre-configured.
+
+## Quick Start
+
+```bash
+# New project — guided (for beginners)
+npx devforge new my-app
+
+# New project — shorthand
+npx devforge my-app
+
+# Add dev guardrails to existing project
+npx devforge init
+
+# Diagnose and optimize existing project
+npx devforge doctor
+```
+
+## Four Modes, Four Audiences
+
+### 1. Guided Mode (beginners & non-developers)
+
+Describe what you want in plain English. DevForge picks the stack.
+
+```
+$ npx devforge new my-app
+
+  🔨 DevForge — Let's build something.
+
+? How would you like to start?
+  💬 Describe what you want to build (recommended for beginners)
+  ⚡ I know my stack — let me pick (for developers)
+
+> Describe
+
+Tell me about what you want to build:
+> I want an app where restaurants manage their menu and customers order food
+
+  Got it! Here's what I'll set up for you:
+
+  What you'll get:
+  ├── A website where you can:
+  │   • Manage menu
+  │   • Manage orders
+  │
+  ├── User accounts (with different roles like admin and user)
+  ├── Payment processing for orders or subscriptions
+  ├── Search and filtering
+  ├── A database to store all your data
+  │
+  └── Developer tools:
+      • Code quality checks (catches errors automatically)
+      • Guided workflows (type /project:help anytime you're stuck)
+      • Testing templates
+
+? Sound right? Yes — create it!
+```
+
+Zero technical jargon. DevForge makes all the decisions. After scaffolding, generates `docs/getting-started.md` with a beginner-friendly walkthrough.
+
+### 2. Developer Mode (developers who know their stack)
+
+```
+$ npx devforge new my-app
+
+? How would you like to start?
+  ⚡ I know my stack — let me pick
+
+? What are you building? Full-stack app
+? Backend language? Python (polyglot)
+? Need authentication? Yes
+? Deployment target? Docker
+
+  Recommended stack:
+  Frontend: nextjs + typescript + tailwind + shadcn
+  Backend:  fastapi + python + sqlalchemy
+  Database: postgresql (both)
+  Auth:     both
+  Testing:  vitest + playwright + pytest
+  Deploy:   docker
+  Claude:   CLAUDE.md + hooks + skills + agents + commands
+
+? Proceed with this stack? Yes
+
+✓ Done! Your project is ready.
+```
+
+### 3. Init Mode (add guardrails to existing projects)
+
+```
+$ cd my-existing-project
+$ npx devforge init
+
+  🔨 DevForge — Adding dev guardrails
+
+  Scanning...
+
+  Detected: nextjs (typescript) + fastapi (python) + postgresql (prisma) + vitest + playwright + pytest
+
+  Installing:
+  ✓ .claude/hooks/ — auto-lint, quality gate, file protection
+  ✓ .claude/agents/ — code quality, security, spec validator
+  ✓ .claude/commands/ — help, status, next, done, audit, pre-pr
+  ✓ .claude/skills/ — framework-specific knowledge
+  ✓ docs/uat/ — acceptance test templates
+  ⊘ CLAUDE.md — exists (tip: run /project:optimize-claude-md to slim it)
+
+  Done. Type /project:help to get started.
+```
+
+Zero questions. Scans, detects, installs.
+
+### 4. Doctor Mode (diagnose & optimize existing projects)
+
+```
+$ npx devforge doctor
+
+  🔨 DevForge Doctor — Project Health Check
+
+  Scanning...
+
+  📊 Project Vitals:
+  Frontend:  nextjs (typescript)
+  Backend:   fastapi (python)
+  Database:  postgresql (sqlalchemy)
+  Testing:   vitest + playwright + pytest
+
+  Health Issues Found:
+
+  🔴 CRITICAL
+    1. CLAUDE.md is 647 lines (recommended limit: 150)
+       → Instructions are being dropped
+    2. 4 endpoints have no authentication
+       → Security vulnerability
+
+  🟡 WARNING
+    3. No health check endpoint
+    4. No UAT scenarios
+    5. 3 bare except: blocks
+
+  ? What would you like to do?
+    🚑 Fix critical issues (guided, one at a time)
+    📋 Generate a full report (save to docs/doctor-report.md)
+    ⚡ Auto-fix what's safe to auto-fix
+    📖 Just show me what to do (generates prompts for Claude Code)
+```
+
+Doctor diagnoses problems and generates the exact Claude Code prompt to fix each one.
+
+## Supported Stacks (V1)
+
+| Selection | Stack |
+|---|---|
+| Web app / Full-stack + TypeScript | Next.js 15 + Prisma + PostgreSQL + NextAuth + Vitest + Playwright |
+| API service + Python | FastAPI + SQLAlchemy 2.0 + PostgreSQL + Alembic + Pytest |
+| Full-stack + TS + Python | Next.js frontend + FastAPI backend (polyglot monorepo) |
+| AI/ML service | Polyglot full-stack with AI integration flag |
+
+## What Gets Generated
+
+Every project includes:
+
+- **Project scaffold** with working code, configs, and dependencies
+- **Health check endpoints** (`/health`, `/healthz`)
+- **Graceful shutdown handlers**
+- **Database connection retry** with exponential backoff
+- **Structured error responses** (never leaks stack traces)
+
+With Claude Code infrastructure enabled (default):
+
+- **CLAUDE.md** tailored to your stack
+- **Hooks** — auto-lint on edit, quality gate on stop
+- **Skills** — framework-specific knowledge
+- **Agents** — 5-agent verification chain
+- **Commands** — verify-all, audit-spec, audit-wiring, audit-security, pre-pr, run-uat, generate-prd, generate-uat, optimize-claude-md
+- **UAT templates** — scenario packs and CSV checklists
+- **Prompt library** — the complete development prompt library
+
+## Development
+
+```bash
+npm install
+npm test                           # run unit tests
+node bin/devforge.js test-output   # manual smoke test (guided + developer)
+node bin/devforge.js init          # test init mode (from any project dir)
+node bin/devforge.js doctor        # test doctor mode (from any project dir)
+```
+
+## Project Structure
+
+```
+devforge/
+├── bin/devforge.js              # CLI entry point
+├── src/
+│   ├── cli.js                   # Command router (new, init, doctor)
+│   ├── index.js                 # New project orchestrator (guided + developer)
+│   ├── guided.js                # Guided mode (description → stack)
+│   ├── prompts.js               # Interactive prompts (Inquirer.js)
+│   ├── recommender.js           # Service type → stack recommendation
+│   ├── composer.js              # Template composition engine
+│   ├── claude-configurator.js   # Generates .claude/ infrastructure
+│   ├── uat-generator.js         # Generates UAT templates
+│   ├── scanner.js               # Project scanner (for init + doctor)
+│   ├── init-mode.js             # Init mode orchestrator
+│   ├── doctor.js                # Doctor mode orchestrator
+│   ├── doctor-checks.js         # Diagnostic check functions
+│   ├── doctor-prompts.js        # Fix prompt generators
+│   └── utils.js                 # File ops, logging, colors
+├── templates/                   # Scaffold templates by category
+│   ├── base/                    # Every project gets this
+│   ├── frontend/nextjs/         # Next.js App Router
+│   ├── backend/fastapi/         # FastAPI + SQLAlchemy
+│   ├── database/                # Prisma, SQLAlchemy
+│   ├── auth/                    # NextAuth, JWT
+│   ├── testing/                 # Vitest, Playwright, Pytest
+│   ├── infra/                   # Docker Compose, GitHub Actions
+│   └── claude-code/             # Hooks, CLAUDE.md, skills, agents, commands
+├── tests/                       # Vitest tests
+└── docs/                        # Reference documentation
+```
+
+## Claude Code Commands
+
+| Command | What It Does |
+|---------|-------------|
+| `/project:help` | Asks your situation, gives the exact prompt |
+| `/project:status` | Project dashboard — tests, branch, changes |
+| `/project:next` | Figures out your next task |
+| `/project:done` | Verifies task completion |
+| `/project:generate-prd` | Generates a PRD with Mermaid diagrams |
+| `/project:generate-uat` | Generates UAT scenarios from codebase |
+| `/project:optimize-claude-md` | Proposes splitting an oversized CLAUDE.md |
+
+## Roadmap
+
+- [ ] Go + Gin/Chi backend
+- [ ] Rust + Axum backend
+- [ ] React + Vite SPA (frontend-only)
+- [ ] React Native / Expo mobile
+- [ ] Plugin ecosystem for community templates
+
+## License
+
+MIT

package/bin/devforge.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { parseCommand } from '../src/cli.js';
+
+parseCommand(process.argv.slice(2));

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "forgedev",
+  "version": "1.0.0",
+  "description": "Universal, AI-first project scaffolding CLI with Claude Code infrastructure",
+  "type": "module",
+  "bin": {
+    "forgedev": "bin/devforge.js",
+    "devforge": "bin/devforge.js"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "scaffolding",
+    "cli",
+    "project-generator",
+    "claude-code",
+    "ai-first"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "@inquirer/prompts": "^7.10.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.1.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/claude-configurator.js

@@ -0,0 +1,260 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ROOT_DIR, ensureDir, writeFile, readTemplate, replaceVars, log } from './utils.js';
+
+const CLAUDE_TEMPLATES_DIR = path.join(ROOT_DIR, 'templates', 'claude-code');
+const DOCS_DIR = path.join(ROOT_DIR, 'docs');
+
+export async function generateClaudeConfig(outputDir, stackConfig, options = {}) {
+  const vars = buildClaudeVars(stackConfig);
+
+  if (!options.skipClaudeMd) {
+    generateClaudeMd(outputDir, stackConfig, vars);
+  }
+  generateHooks(outputDir, stackConfig, { merge: options.mergeSettings });
+  generateSkills(outputDir, stackConfig);
+  generateAgents(outputDir, stackConfig, vars);
+  generateCommands(outputDir, stackConfig, vars);
+  copyPromptLibrary(outputDir);
+}
+
+function buildClaudeVars(config) {
+  const vars = {
+    PROJECT_NAME: config.projectName,
+    PROJECT_NAME_PASCAL: config.projectName.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(''),
+  };
+
+  if (config.stackId === 'nextjs-fullstack') {
+    vars.STACK_SUMMARY = 'Next.js 15 (App Router) + TypeScript + Tailwind CSS + Prisma + PostgreSQL';
+    vars.LINT_COMMAND = 'npx eslint .';
+    vars.TYPE_CHECK_COMMAND = 'npx tsc --noEmit';
+    vars.TEST_COMMAND = 'npx vitest run';
+    vars.BUILD_COMMAND = 'npm run build';
+    vars.DEV_COMMAND = 'npm run dev';
+    vars.DIR_MAP = `- src/app/ — Next.js App Router pages and API routes
+- src/lib/ — Shared utilities, database client, error handling
+- src/components/ — React components
+- prisma/ — Database schema and migrations
+- e2e/ — Playwright E2E tests`;
+  } else if (config.stackId === 'fastapi-backend') {
+    vars.STACK_SUMMARY = 'FastAPI + Python + SQLAlchemy 2.0 + PostgreSQL + Alembic';
+    vars.LINT_COMMAND = 'ruff check .';
+    vars.TYPE_CHECK_COMMAND = 'pyright';
+    vars.TEST_COMMAND = 'pytest';
+    vars.BUILD_COMMAND = 'docker build -t app .';
+    vars.DEV_COMMAND = 'uvicorn app.main:app --reload';
+    vars.DIR_MAP = `- backend/app/ — FastAPI application
+- backend/app/api/ — API route handlers
+- backend/app/core/ — Config, security, error handling
+- backend/app/db/ — Database session and models
+- backend/app/models/ — SQLAlchemy models
+- backend/app/schemas/ — Pydantic schemas
+- backend/tests/ — Pytest tests
+- backend/alembic/ — Database migrations`;
+  } else if (config.stackId === 'polyglot-fullstack') {
+    vars.STACK_SUMMARY = 'Next.js 15 (frontend) + FastAPI (backend) + PostgreSQL';
+    vars.LINT_COMMAND = 'cd frontend && npx eslint . && cd ../backend && ruff check .';
+    vars.TYPE_CHECK_COMMAND = 'cd frontend && npx tsc --noEmit';
+    vars.TEST_COMMAND = 'cd frontend && npx vitest run && cd ../backend && pytest';
+    vars.BUILD_COMMAND = 'docker compose build';
+    vars.DEV_COMMAND = 'docker compose up';
+    vars.DIR_MAP = `- frontend/ — Next.js 15 App Router application
+- frontend/src/app/ — Pages and API routes
+- frontend/src/lib/ — Shared utilities
+- backend/ — FastAPI application
+- backend/app/api/ — API route handlers
+- backend/app/core/ — Config, security, error handling
+- backend/app/db/ — Database session and models
+- e2e/ — Playwright E2E tests`;
+  }
+
+  // Build skills list for CLAUDE.md reference
+  const skillsList = [];
+  if (config.frontend?.framework === 'nextjs') {
+    skillsList.push('- `@.claude/skills/nextjs/` — Next.js patterns and conventions');
+    skillsList.push('- `@.claude/skills/security-web/` — Frontend security practices');
+  }
+  if (config.backend?.framework === 'fastapi') {
+    skillsList.push('- `@.claude/skills/fastapi/` — FastAPI patterns and conventions');
+    skillsList.push('- `@.claude/skills/security-api/` — API security practices');
+  }
+  if (config.testing?.e2e === 'playwright') {
+    skillsList.push('- `@.claude/skills/playwright/` — E2E testing patterns');
+  }
+  if (config.ai) {
+    skillsList.push('- `@.claude/skills/ai-prompts/` — AI/LLM prompt patterns');
+  }
+  vars.SKILLS_LIST = skillsList.length > 0 ? skillsList.join('\n') : '- (none generated)';
+
+  return vars;
+}
+
+function generateClaudeMd(outputDir, config, vars) {
+  // Read base template
+  const basePath = path.join(CLAUDE_TEMPLATES_DIR, 'claude-md', 'base.md');
+  let content = readTemplate(basePath);
+
+  // Read stack-specific section
+  let stackSection = '';
+  if (config.stackId === 'nextjs-fullstack') {
+    stackSection = readTemplate(path.join(CLAUDE_TEMPLATES_DIR, 'claude-md', 'nextjs.md'));
+  } else if (config.stackId === 'fastapi-backend') {
+    stackSection = readTemplate(path.join(CLAUDE_TEMPLATES_DIR, 'claude-md', 'fastapi.md'));
+  } else if (config.stackId === 'polyglot-fullstack') {
+    stackSection = readTemplate(path.join(CLAUDE_TEMPLATES_DIR, 'claude-md', 'fullstack.md'));
+  }
+
+  content = content.replace('{{STACK_SPECIFIC_RULES}}', stackSection);
+  content = replaceVars(content, vars);
+
+  writeFile(path.join(outputDir, 'CLAUDE.md'), content);
+}
+
+function generateHooks(outputDir, config, options = {}) {
+  let hookFile;
+  let scriptFiles = ['guard-protected-files.sh'];
+
+  if (config.stackId === 'nextjs-fullstack') {
+    hookFile = 'typescript.json';
+    scriptFiles.push('autofix-typescript.sh');
+  } else if (config.stackId === 'fastapi-backend') {
+    hookFile = 'python.json';
+    scriptFiles.push('autofix-python.sh');
+  } else if (config.stackId === 'polyglot-fullstack') {
+    hookFile = 'polyglot.json';
+    scriptFiles.push('autofix-polyglot.sh');
+  }
+
+  const settingsPath = path.join(outputDir, '.claude', 'settings.json');
+
+  if (options.merge && fs.existsSync(settingsPath)) {
+    // Merge hooks into existing settings.json
+    const existing = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+    const incoming = JSON.parse(readTemplate(path.join(CLAUDE_TEMPLATES_DIR, 'hooks', hookFile)));
+    const merged = deepMergeSettings(existing, incoming);
+    writeFile(settingsPath, JSON.stringify(merged, null, 2));
+  } else {
+    const hookPath = path.join(CLAUDE_TEMPLATES_DIR, 'hooks', hookFile);
+    const content = readTemplate(hookPath);
+    writeFile(settingsPath, content);
+  }
+
+  // Copy hook scripts
+  const hooksDir = path.join(outputDir, '.claude', 'hooks');
+  ensureDir(hooksDir);
+  for (const script of scriptFiles) {
+    const srcPath = path.join(CLAUDE_TEMPLATES_DIR, 'hooks', 'scripts', script);
+    if (fs.existsSync(srcPath)) {
+      fs.copyFileSync(srcPath, path.join(hooksDir, script));
+    }
+  }
+}
+
+function deepMergeSettings(existing, incoming) {
+  const merged = { ...existing };
+  if (incoming.hooks) {
+    merged.hooks = merged.hooks || {};
+    for (const [hookType, hookArr] of Object.entries(incoming.hooks)) {
+      if (!merged.hooks[hookType]) {
+        merged.hooks[hookType] = hookArr;
+      } else {
+        // Append incoming hooks that don't already exist (by command)
+        const existingCommands = new Set(
+          merged.hooks[hookType].flatMap(h => (h.hooks || []).map(hk => hk.command))
+        );
+        for (const hook of hookArr) {
+          const isNew = (hook.hooks || []).some(hk => !existingCommands.has(hk.command));
+          if (isNew) {
+            merged.hooks[hookType].push(hook);
+          }
+        }
+      }
+    }
+  }
+  return merged;
+}
+
+function generateSkills(outputDir, config) {
+  const skillsToInclude = [];
+
+  if (config.frontend?.framework === 'nextjs') {
+    skillsToInclude.push('nextjs');
+    skillsToInclude.push('security-web');
+  }
+  if (config.backend?.framework === 'fastapi') {
+    skillsToInclude.push('fastapi');
+    skillsToInclude.push('security-api');
+  }
+  if (config.testing?.e2e === 'playwright') {
+    skillsToInclude.push('playwright');
+  }
+  if (config.ai) {
+    skillsToInclude.push('ai-prompts');
+  }
+
+  for (const skill of skillsToInclude) {
+    const srcPath = path.join(CLAUDE_TEMPLATES_DIR, 'skills', skill, 'SKILL.md');
+    if (fs.existsSync(srcPath)) {
+      const destPath = path.join(outputDir, '.claude', 'skills', skill, 'SKILL.md');
+      ensureDir(path.dirname(destPath));
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function generateAgents(outputDir, config, vars) {
+  const agentsDir = path.join(CLAUDE_TEMPLATES_DIR, 'agents');
+  const agents = [
+    'code-quality-reviewer.md',
+    'security-reviewer.md',
+    'spec-validator.md',
+    'production-readiness.md',
+    'uat-validator.md',
+  ];
+
+  for (const agent of agents) {
+    const srcPath = path.join(agentsDir, agent);
+    if (fs.existsSync(srcPath)) {
+      let content = readTemplate(srcPath);
+      content = replaceVars(content, vars);
+      writeFile(path.join(outputDir, '.claude', 'agents', agent), content);
+    }
+  }
+}
+
+function generateCommands(outputDir, config, vars) {
+  const commandsDir = path.join(CLAUDE_TEMPLATES_DIR, 'commands');
+  const commands = [
+    'help.md',
+    'status.md',
+    'next.md',
+    'done.md',
+    'verify-all.md',
+    'audit-spec.md',
+    'audit-wiring.md',
+    'audit-security.md',
+    'pre-pr.md',
+    'run-uat.md',
+    'generate-prd.md',
+    'generate-uat.md',
+    'optimize-claude-md.md',
+  ];
+
+  for (const cmd of commands) {
+    const srcPath = path.join(commandsDir, cmd);
+    if (fs.existsSync(srcPath)) {
+      let content = readTemplate(srcPath);
+      content = replaceVars(content, vars);
+      writeFile(path.join(outputDir, '.claude', 'commands', cmd), content);
+    }
+  }
+}
+
+function copyPromptLibrary(outputDir) {
+  const srcPath = path.join(DOCS_DIR, '01-universal-prompt-library.md');
+  if (fs.existsSync(srcPath)) {
+    const destPath = path.join(outputDir, 'docs', 'prompt-library.md');
+    ensureDir(path.dirname(destPath));
+    fs.copyFileSync(srcPath, destPath);
+  }
+}