codeforge-dev 1.5.8 → 1.8.0

package/README.md

@@ -37,215 +37,46 @@ npx codeforge-dev@1.2.3
 
 - **Docker Desktop** (or compatible container runtime like Podman)
 - **VS Code** with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers), or **GitHub Codespaces**
-- **Claude Code authentication** - see [Authentication](#authentication) section
+- **Claude Code authentication** — run `claude` on first start to authenticate
 
-## Quick Start
-
-1. **Open in Container**
-   - VS Code: Open the folder, then select "Reopen in Container" from the command palette
-   - Codespaces: Create a new codespace from this repository
-
-2. **Authenticate** (first time only)
-   ```bash
-   claude
-   ```
-   Follow the prompts to authenticate via browser or API key.
-
-3. **Start Claude Code**
-   ```bash
-   cc
-   ```
-
-## Authentication
-
-Claude Code supports multiple authentication methods. On first run, you'll be prompted to choose:
-
-### Browser Login (Recommended)
-
-```bash
-claude
-```
-
-Select "Login with browser" and complete authentication in your browser. This uses your Claude.ai account.
-
-### API Key
-
-For programmatic access or environments without browsers:
-
-```bash
-export ANTHROPIC_API_KEY="sk-ant-..."
-claude
-```
-
-Get an API key from [console.anthropic.com](https://console.anthropic.com/).
-
-### Credential Persistence
-
-Authentication credentials are stored in `/workspaces/.claude/` and persist across container rebuilds.
-
-For more options, see the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code).
-
-## GitHub CLI Authentication
-
-GitHub CLI (`gh`) is pre-installed for repository operations like pushing code, creating pull requests, and accessing private repositories.
-
-### Interactive Login (Recommended)
-
-```bash
-gh auth login
-```
-
-Follow the prompts:
-1. Select **GitHub.com** (or your enterprise server)
-2. Choose your preferred protocol: **HTTPS** (recommended) or **SSH**
-3. Authenticate via **browser** (easiest) or paste a personal access token
-
-### Token-Based Login
-
-For automated setups or environments without browser access:
-
-```bash
-# From a file
-gh auth login --with-token < ~/github-token.txt
-
-# From environment variable
-echo "$GITHUB_TOKEN" | gh auth login --with-token
-```
-
-Generate a token at [github.com/settings/tokens](https://github.com/settings/tokens) with appropriate scopes (typically `repo`, `read:org`).
-
-### Verifying Authentication
-
-```bash
-gh auth status
-```
-
-Expected output shows your authenticated account and token scopes.
-
-### Credential Persistence
-
-GitHub CLI credentials are automatically persisted across container rebuilds. The container is configured to store credentials in `/workspaces/.gh/` (via `GH_CONFIG_DIR`), which is part of the bind-mounted workspace.
-
-**You only need to authenticate once.** After running `gh auth login`, your credentials will survive container rebuilds and be available in future sessions.
-
-## Available Tools
+## What's Included
 
 ### Languages & Runtimes
-| Tool | Description |
-|------|-------------|
-| Python 3.14 | Base language runtime |
-| Node.js LTS | JavaScript runtime |
-| TypeScript | Via Node.js |
-
-### Package Managers
-| Tool | Description |
-|------|-------------|
-| `uv` | Fast Python package manager (pip alternative) |
-| `npm` | Node.js package manager |
-| `pip` / `pipx` | Python package installers |
-
-### Development Tools
-| Tool | Description |
-|------|-------------|
-| `gh` | GitHub CLI for repository operations |
-| `docker` | Container CLI (connects to host Docker) |
-| `git` | Version control |
-| `jq` | JSON processor |
-| `curl` | HTTP client |
-| `tmux` | Terminal multiplexer for Agent Teams split-pane sessions |
-| `biome` | Fast JS/TS/JSON/CSS formatter |
-| `agent-browser` | Headless browser automation for AI agents |
-
-### Code Intelligence
-| Tool | Description |
-|------|-------------|
-| tree-sitter | AST parsing for JavaScript, TypeScript, Python |
-| ast-grep | Structural code search and rewriting |
-| Pyright | Python language server |
-| TypeScript LSP | TypeScript/JavaScript language server |
 
-### Claude Code Tools
-| Tool | Description |
-|------|-------------|
-| `claude` | Claude Code CLI |
-| `cc` | Wrapper with auto-configuration |
-| `ccusage` | Token usage analyzer |
-| `ccstatusline` | Status line for sessions |
-| `claude-monitor` | Real-time usage tracking |
-
-## Using Claude Code
-
-### The `cc` Command
-
-The `cc` command is a wrapper that:
-- Creates a project-local `.claude/` directory if missing
-- Copies default configuration files
-- Launches Claude Code with the project's system prompt
-
-```bash
-cc                    # Start Claude Code in current directory
-cc "explain this"     # Start with an initial prompt
-```
-
-### Direct CLI
+Python 3.14, Node.js LTS, TypeScript, Go
 
-For more control, use the `claude` command directly:
-
-```bash
-claude                        # Basic invocation
-claude --help                 # View all options
-claude --resume               # Resume previous session
-```
+### Package Managers
 
-## Configuration
+`uv`, `npm`, `pip` / `pipx`
 
-### Environment Variables
+### Development Tools
 
-Edit `.devcontainer/.env` to customize behavior:
+`gh` (GitHub CLI), `docker`, `git`, `jq`, `curl`, `tmux`, `biome`, `agent-browser`
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `CLAUDE_CONFIG_DIR` | `/workspaces/.claude` | Claude configuration directory |
-| `SETUP_CONFIG` | `true` | Copy config files during setup |
-| `OVERWRITE_CONFIG` | `true` | Overwrite existing configs |
-| `SETUP_ALIASES` | `true` | Add `cc` alias to shell |
-| `SETUP_PLUGINS` | `true` | Install official plugins |
+### Code Intelligence
 
-### Claude Code Settings
+tree-sitter (JS/TS/Python), ast-grep, Pyright, TypeScript LSP
 
-Default settings are in `.devcontainer/config/settings.json`. These are copied to `/workspaces/.claude/settings.json` on first run.
+### Claude Code Tools
 
-Key defaults:
-- **Model**: Claude Opus 4-6
-- **Default mode**: Plan (prompts before executing)
-- **Max output tokens**: 128,000
+`claude`, `cc` (wrapper), `ccusage`, `ccburn`, `ccstatusline`, `claude-monitor`
 
-### System Prompt
+### Custom Features (14)
 
-The default system prompt is in `.devcontainer/config/main-system-prompt.md`. Override it by creating a `.claude/system-prompt.md` in your project directory.
+tmux, agent-browser, claude-monitor, ccusage, ccburn, ccstatusline, ast-grep, tree-sitter, lsp-servers, biome, notify-hook, mcp-qdrant, mcp-reasoner, splitrail
 
-## Custom Features
+### Agents (17) & Skills (16)
 
-CodeForge includes several custom devcontainer features:
+The `code-directive` plugin includes specialized agents (architect, explorer, test-writer, security-auditor, etc.) and domain-specific coding reference skills (fastapi, svelte5, docker, testing, etc.).
 
-| Feature | Description |
-|---------|-------------|
-| `claude-monitor` | Real-time token usage monitoring with ML predictions |
-| `ccusage` | Usage analytics CLI |
-| `ccstatusline` | Compact powerline status display |
-| `ast-grep` | Structural code search using AST patterns |
-| `tree-sitter` | Parser with JS/TS/Python grammars |
-| `lsp-servers` | Pyright and TypeScript language servers |
-| `agent-browser` | Browser automation with accessibility snapshots and screenshots |
-| `tmux` | Terminal multiplexer with Catppuccin theme for Agent Teams |
-| `biome` | Fast JS/TS/JSON/CSS formatter (global install) |
+## Quick Start
 
-## Essential Gotchas
+1. **Install**: `npx codeforge-dev`
+2. **Open in Container**: "Reopen in Container" in VS Code, or create a Codespace
+3. **Authenticate**: Run `claude` and follow prompts
+4. **Start coding**: Run `cc`
 
-- **Authentication required**: Run `claude` once to authenticate before using `cc`
-- **Plan mode default**: The container starts in "plan" mode, which prompts for approval before making changes
-- **Project-local config**: The `cc` command creates `.claude/` in your current directory for project-specific settings
-- **GitHub auth persists**: Run `gh auth login` once; credentials survive container rebuilds (stored in `/workspaces/.gh/`)
+For full usage documentation — authentication, configuration, tools, agents, and keybindings — see [`.devcontainer/README.md`](.devcontainer/README.md).
 
 ## Development
 
@@ -266,6 +97,8 @@ npm publish
 
 ## Further Reading
 
+- [Full Usage Guide](.devcontainer/README.md)
+- [Changelog](.devcontainer/CHANGELOG.md)
 - [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
 - [Dev Containers Specification](https://containers.dev/)
 - [GitHub CLI Manual](https://cli.github.com/manual/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeforge-dev",
-  "version": "1.5.8",
+  "version": "1.8.0",
   "description": "Complete development container that sets up Claude Code with modular devcontainer features, modern dev tools, and persistent configurations. Drop it into any project and get a production-ready AI development environment in minutes.",
   "main": "setup.js",
   "bin": {

package/setup.js

@@ -1,83 +1,257 @@
 #!/usr/bin/env node
 
-const fs = require('fs');
-const path = require('path');
+const fs = require("fs");
+const path = require("path");
 
+// ── Default preserve list ────────────────────────────────────────
+// Files in the package that should NOT overwrite user customizations.
+// The package version is saved as <file>.codeforge-new for diffing.
+const DEFAULT_PRESERVE = [
+	"config/defaults/settings.json",
+	"config/defaults/main-system-prompt.md",
+	"config/defaults/keybindings.json",
+	"config/file-manifest.json",
+	".codeforge-preserve",
+];
+
+// ── copyDirectory ────────────────────────────────────────────────
+// Simple recursive copy (used for fresh install and --reset).
 function copyDirectory(src, dest) {
-  if (!fs.existsSync(dest)) {
-    fs.mkdirSync(dest, { recursive: true });
-  }
-
-  const entries = fs.readdirSync(src, { withFileTypes: true });
-
-  for (const entry of entries) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-
-    if (entry.isDirectory()) {
-      copyDirectory(srcPath, destPath);
-    } else {
-      fs.copyFileSync(srcPath, destPath);
-    }
-  }
+	if (!fs.existsSync(dest)) {
+		fs.mkdirSync(dest, { recursive: true });
+	}
+
+	const entries = fs.readdirSync(src, { withFileTypes: true });
+
+	for (const entry of entries) {
+		const srcPath = path.join(src, entry.name);
+		const destPath = path.join(dest, entry.name);
+
+		if (entry.isDirectory()) {
+			copyDirectory(srcPath, destPath);
+		} else {
+			fs.copyFileSync(srcPath, destPath);
+		}
+	}
 }
 
+// ── loadPreserveList ─────────────────────────────────────────────
+// Builds the set of relative paths to preserve during --force update.
+// Combines built-in defaults with user entries from .codeforge-preserve.
+function loadPreserveList(devcontainerDest) {
+	const preserveFile = path.join(devcontainerDest, ".codeforge-preserve");
+	let custom = [];
+
+	if (fs.existsSync(preserveFile)) {
+		custom = fs
+			.readFileSync(preserveFile, "utf-8")
+			.split("\n")
+			.map((line) => line.trim())
+			.filter((line) => line && !line.startsWith("#"));
+	}
+
+	return new Set([...DEFAULT_PRESERVE, ...custom]);
+}
+
+// ── syncDirectory ────────────────────────────────────────────────
+// Selective overwrite: walks the package tree and copies files to dest.
+// - Framework files (scripts, features, plugins): always overwrite
+// - Preserved files: skip, save package version as .codeforge-new
+// - devcontainer.json: overwrite, save user's as .bak
+// - User-created files not in package: untouched (never visited)
+function syncDirectory(src, dest, preserveSet) {
+	const stats = {
+		updated: 0,
+		preserved: 0,
+		added: 0,
+		backedUp: 0,
+		preservedFiles: [],
+	};
+
+	function walk(srcDir, destDir, relativeBase) {
+		if (!fs.existsSync(destDir)) {
+			fs.mkdirSync(destDir, { recursive: true });
+		}
+
+		const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+
+		for (const entry of entries) {
+			const srcPath = path.join(srcDir, entry.name);
+			const destPath = path.join(destDir, entry.name);
+			const relativePath = relativeBase
+				? relativeBase + "/" + entry.name
+				: entry.name;
+
+			if (entry.isDirectory()) {
+				walk(srcPath, destPath, relativePath);
+				continue;
+			}
+
+			// Special handling for devcontainer.json: overwrite + save .bak
+			if (relativePath === "devcontainer.json" && fs.existsSync(destPath)) {
+				fs.copyFileSync(destPath, destPath + ".bak");
+				fs.copyFileSync(srcPath, destPath);
+				stats.backedUp++;
+				stats.updated++;
+				continue;
+			}
+
+			// Preserved files: skip overwrite, save package version as .codeforge-new
+			if (preserveSet.has(relativePath) && fs.existsSync(destPath)) {
+				fs.copyFileSync(srcPath, destPath + ".codeforge-new");
+				stats.preserved++;
+				stats.preservedFiles.push(relativePath);
+				continue;
+			}
+
+			// Framework files: always overwrite (or create if new)
+			const isNew = !fs.existsSync(destPath);
+			fs.copyFileSync(srcPath, destPath);
+			if (isNew) {
+				stats.added++;
+			} else {
+				stats.updated++;
+			}
+		}
+	}
+
+	walk(src, dest, "");
+	return stats;
+}
+
+// ── main ─────────────────────────────────────────────────────────
 function main() {
-  const args = process.argv.slice(2);
-  const force = args.includes('--force') || args.includes('-f');
-
-  const currentDir = process.cwd();
-  const packageDir = __dirname;
-  const devcontainerSrc = path.join(packageDir, '.devcontainer');
-  const devcontainerDest = path.join(currentDir, '.devcontainer');
-
-  console.log('🚀 Setting up CodeForge DevContainer...');
-
-  // Check if .devcontainer already exists
-  if (fs.existsSync(devcontainerDest)) {
-    if (force) {
-      console.log('⚠️  Removing existing .devcontainer directory...');
-      fs.rmSync(devcontainerDest, { recursive: true, force: true });
-    } else {
-      console.log('⚠️  .devcontainer directory already exists.');
-      console.log('   Use --force to overwrite, or remove it manually.');
-      process.exit(1);
-    }
-  }
-
-  // Check if source .devcontainer exists
-  if (!fs.existsSync(devcontainerSrc)) {
-    console.error('❌ Error: .devcontainer source directory not found in package.');
-    process.exit(1);
-  }
-
-  try {
-    // Copy .devcontainer directory
-    copyDirectory(devcontainerSrc, devcontainerDest);
-    
-    console.log('✅ CodeForge DevContainer configuration installed!');
-    console.log('');
-    console.log('🔧 Next steps:');
-    console.log('   1. Open this folder in VS Code');
-    console.log('   2. Select "Reopen in Container" from the command palette');
-    console.log('   3. Run: claude');
-    console.log('');
-    console.log('📚 Features included:');
-    console.log('   • Claude Code CLI with optimized tool configuration');
-    console.log('   • MCP servers: Qdrant (vector memory), Reasoner');
-    console.log('   • Development tools: Node.js LTS, Python 3.14, Git with delta');
-    console.log('   • Persistent configuration and shell history');
-    console.log('');
-    console.log('🔗 Documentation: See .devcontainer/README.md');
-
-  } catch (error) {
-    console.error('❌ Error copying .devcontainer:', error.message);
-    process.exit(1);
-  }
+	const args = process.argv.slice(2);
+	const force = args.includes("--force") || args.includes("-f");
+	const reset = args.includes("--reset");
+
+	if (args.includes("--help") || args.includes("-h")) {
+		console.log("Usage: codeforge [options]");
+		console.log("");
+		console.log("Options:");
+		console.log(
+			"  --force, -f   Update existing .devcontainer (preserves user config)",
+		);
+		console.log(
+			"  --reset       Remove all customizations and install fresh defaults",
+		);
+		console.log("  --help, -h    Show this help message");
+		console.log("");
+		console.log(
+			"Without flags, installs only if .devcontainer does not exist.",
+		);
+		process.exit(0);
+	}
+
+	const currentDir = process.cwd();
+	const packageDir = __dirname;
+	const devcontainerSrc = path.join(packageDir, ".devcontainer");
+	const devcontainerDest = path.join(currentDir, ".devcontainer");
+
+	console.log("");
+
+	// Check if source .devcontainer exists in the package
+	if (!fs.existsSync(devcontainerSrc)) {
+		console.error(
+			"Error: .devcontainer source directory not found in package.",
+		);
+		process.exit(1);
+	}
+
+	if (fs.existsSync(devcontainerDest)) {
+		if (reset) {
+			// Nuclear: delete everything and copy fresh
+			console.log("Resetting .devcontainer to package defaults...");
+			console.log("");
+			fs.rmSync(devcontainerDest, { recursive: true, force: true });
+			copyDirectory(devcontainerSrc, devcontainerDest);
+			console.log("  Reset complete. All user customizations removed.");
+			console.log("");
+			printNextSteps();
+		} else if (force) {
+			// Smart update: selective overwrite with preservation
+			console.log("Updating .devcontainer (preserving user config)...");
+			console.log("");
+
+			const preserveSet = loadPreserveList(devcontainerDest);
+			const stats = syncDirectory(
+				devcontainerSrc,
+				devcontainerDest,
+				preserveSet,
+			);
+
+			// Summary
+			console.log(`  Updated:   ${stats.updated} files`);
+			console.log(`  Added:     ${stats.added} new files`);
+			console.log(`  Preserved: ${stats.preserved} user config files`);
+			console.log("");
+
+			if (stats.backedUp > 0) {
+				console.log(
+					"  devcontainer.json updated (previous saved as devcontainer.json.bak)",
+				);
+				console.log("");
+			}
+
+			if (stats.preservedFiles.length > 0) {
+				console.log(
+					"  Review .codeforge-new files for new defaults you may want to merge:",
+				);
+				for (const file of stats.preservedFiles) {
+					console.log(`    ${file}.codeforge-new`);
+				}
+				console.log("");
+			}
+
+			printNextSteps();
+		} else {
+			// No flags: error with guidance
+			console.log(".devcontainer directory already exists.");
+			console.log("");
+			console.log("  --force   Update (preserves your config files)");
+			console.log("  --reset   Start fresh (removes all customizations)");
+			console.log("");
+			process.exit(1);
+		}
+	} else {
+		// Fresh install
+		console.log("Setting up CodeForge DevContainer...");
+		console.log("");
+
+		try {
+			copyDirectory(devcontainerSrc, devcontainerDest);
+			console.log("  CodeForge DevContainer configuration installed!");
+			console.log("");
+			printNextSteps();
+			printFeatures();
+		} catch (error) {
+			console.error("Error copying .devcontainer:", error.message);
+			process.exit(1);
+		}
+	}
+}
+
+function printNextSteps() {
+	console.log("Next steps:");
+	console.log("  1. Open this folder in VS Code");
+	console.log('  2. Select "Reopen in Container" from the command palette');
+	console.log("  3. Run: claude");
+	console.log("");
+	console.log("Documentation: .devcontainer/README.md");
+	console.log("");
+}
+
+function printFeatures() {
+	console.log("Features included:");
+	console.log("  - Claude Code CLI with optimized tool configuration");
+	console.log("  - MCP servers: Qdrant (vector memory), Reasoner");
+	console.log("  - Development tools: Node.js LTS, Python 3.14, Go, Bun");
+	console.log("  - Persistent configuration and shell history");
+	console.log("");
 }
 
 if (require.main === module) {
-  main();
+	main();
 }
 
-module.exports = { copyDirectory, main };
+module.exports = { copyDirectory, syncDirectory, loadPreserveList, main };