codeforge-dev 1.14.2 → 2.0.0

package/setup.js

@@ -1,19 +1,16 @@
 #!/usr/bin/env node
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (c) 2026 Marcus Krueger
 
-const fs = require("fs");
-const path = require("path");
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
 
 // ── Default preserve list ────────────────────────────────────────
-// Files in the package that should NOT overwrite user customizations.
+// Files in .devcontainer 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/defaults/ccstatusline-settings.json",
-	"config/file-manifest.json",
-	".codeforge-preserve",
-];
+// Note: .codeforge/ uses checksum-based preservation instead.
+const DEFAULT_PRESERVE = [".codeforge-preserve"];
 
 // ── copyDirectory ────────────────────────────────────────────────
 // Simple recursive copy (used for fresh install and --reset).
@@ -54,6 +51,173 @@ function loadPreserveList(devcontainerDest) {
 	return new Set([...DEFAULT_PRESERVE, ...custom]);
 }
 
+// ── computeChecksum ──────────────────────────────────────────────
+// Returns SHA-256 hex digest of a file's contents.
+function computeChecksum(filePath) {
+	return crypto
+		.createHash("sha256")
+		.update(fs.readFileSync(filePath))
+		.digest("hex");
+}
+
+// ── generateChecksums ────────────────────────────────────────────
+// Walks directory recursively, returns { relativePath: sha256hex } map.
+// Skips .checksums/ and .markers/ directories.
+function generateChecksums(dir) {
+	const checksums = {};
+
+	function walk(currentDir, relativeBase) {
+		const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+		for (const entry of entries) {
+			const fullPath = path.join(currentDir, entry.name);
+			const relativePath = relativeBase
+				? `${relativeBase}/${entry.name}`
+				: entry.name;
+
+			if (entry.isDirectory()) {
+				if (entry.name === ".checksums" || entry.name === ".markers") {
+					continue;
+				}
+				walk(fullPath, relativePath);
+			} else {
+				checksums[relativePath] = computeChecksum(fullPath);
+			}
+		}
+	}
+
+	walk(dir, "");
+	return checksums;
+}
+
+// ── writeChecksums ───────────────────────────────────────────────
+// Writes .checksums/<version>.json with version, timestamp, and file hashes.
+function writeChecksums(codeforgeDir, version, checksums) {
+	const checksumsDir = path.join(codeforgeDir, ".checksums");
+	fs.mkdirSync(checksumsDir, { recursive: true });
+	const data = {
+		version,
+		generated: new Date().toISOString(),
+		files: checksums,
+	};
+	fs.writeFileSync(
+		path.join(checksumsDir, `${version}.json`),
+		JSON.stringify(data, null, "\t") + "\n",
+	);
+}
+
+// ── readChecksums ────────────────────────────────────────────────
+// Reads latest version's checksums from .checksums/ dir.
+// Returns { files: {} } if none found.
+function readChecksums(codeforgeDir) {
+	const checksumsDir = path.join(codeforgeDir, ".checksums");
+	if (!fs.existsSync(checksumsDir)) {
+		return { files: {} };
+	}
+
+	const files = fs
+		.readdirSync(checksumsDir)
+		.filter((f) => f.endsWith(".json"))
+		.sort((a, b) => {
+			const pa = a.replace(".json", "").split(".").map(Number);
+			const pb = b.replace(".json", "").split(".").map(Number);
+			for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+				const diff = (pa[i] || 0) - (pb[i] || 0);
+				if (diff !== 0) return diff;
+			}
+			return 0;
+		});
+
+	if (files.length === 0) {
+		return { files: {} };
+	}
+
+	const latest = files[files.length - 1];
+	try {
+		return JSON.parse(
+			fs.readFileSync(path.join(checksumsDir, latest), "utf-8"),
+		);
+	} catch {
+		console.log(
+			"  Warning: Could not read checksums from " +
+				latest +
+				", treating as fresh install.",
+		);
+		return { files: {} };
+	}
+}
+
+// ── syncCodeforgeDirectory ───────────────────────────────────────
+// Checksum-aware sync for .codeforge/ directory.
+// Unmodified files get overwritten; modified files are preserved
+// and new defaults are written as <file>.default.
+function syncCodeforgeDirectory(src, dest) {
+	const stored = readChecksums(dest);
+	const stats = {
+		updated: 0,
+		preserved: 0,
+		added: 0,
+		preservedFiles: [],
+		defaultFiles: [],
+	};
+
+	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()) {
+				if (entry.name === ".checksums" || entry.name === ".markers") {
+					continue;
+				}
+				walk(srcPath, destPath, relativePath);
+				continue;
+			}
+
+			const storedHash = stored.files[relativePath];
+			const currentHash = fs.existsSync(destPath)
+				? computeChecksum(destPath)
+				: null;
+
+			if (!storedHash) {
+				// First install or new file
+				if (currentHash === null) {
+					fs.copyFileSync(srcPath, destPath);
+					stats.added++;
+				} else {
+					// File exists but no stored hash — treat as user-created
+					fs.copyFileSync(srcPath, `${destPath}.default`);
+					stats.preserved++;
+					stats.preservedFiles.push(relativePath);
+					stats.defaultFiles.push(relativePath);
+				}
+			} else if (currentHash === storedHash) {
+				// File UNMODIFIED — overwrite with new version
+				fs.copyFileSync(srcPath, destPath);
+				stats.updated++;
+			} else {
+				// File USER-MODIFIED — keep user's file, write new as .default
+				fs.copyFileSync(srcPath, `${destPath}.default`);
+				stats.preserved++;
+				stats.preservedFiles.push(relativePath);
+				stats.defaultFiles.push(relativePath);
+			}
+		}
+	}
+
+	walk(src, dest, "");
+	return stats;
+}
+
 // ── syncDirectory ────────────────────────────────────────────────
 // Selective overwrite: walks the package tree and copies files to dest.
 // - Framework files (scripts, features, plugins): always overwrite
@@ -80,7 +244,7 @@ function syncDirectory(src, dest, preserveSet) {
 			const srcPath = path.join(srcDir, entry.name);
 			const destPath = path.join(destDir, entry.name);
 			const relativePath = relativeBase
-				? relativeBase + "/" + entry.name
+				? `${relativeBase}/${entry.name}`
 				: entry.name;
 
 			if (entry.isDirectory()) {
@@ -90,7 +254,7 @@ function syncDirectory(src, dest, preserveSet) {
 
 			// Special handling for devcontainer.json: overwrite + save .bak
 			if (relativePath === "devcontainer.json" && fs.existsSync(destPath)) {
-				fs.copyFileSync(destPath, destPath + ".bak");
+				fs.copyFileSync(destPath, `${destPath}.bak`);
 				fs.copyFileSync(srcPath, destPath);
 				stats.backedUp++;
 				stats.updated++;
@@ -99,7 +263,7 @@ function syncDirectory(src, dest, preserveSet) {
 
 			// Preserved files: skip overwrite, save package version as .codeforge-new
 			if (preserveSet.has(relativePath) && fs.existsSync(destPath)) {
-				fs.copyFileSync(srcPath, destPath + ".codeforge-new");
+				fs.copyFileSync(srcPath, `${destPath}.codeforge-new`);
 				stats.preserved++;
 				stats.preservedFiles.push(relativePath);
 				continue;
@@ -123,20 +287,33 @@ function syncDirectory(src, dest, preserveSet) {
 // ── main ─────────────────────────────────────────────────────────
 function main() {
 	const args = process.argv.slice(2);
+
+	// Subcommand: config apply
+	if (args[0] === "config" && args[1] === "apply") {
+		return configApply();
+	}
+
 	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("       codeforge config apply");
 		console.log("");
 		console.log("Options:");
 		console.log(
-			"  --force, -f   Update existing .devcontainer (preserves user config)",
+			"  --force, -f     Update existing .devcontainer and .codeforge (preserves user config)",
 		);
 		console.log(
-			"  --reset       Remove all customizations and install fresh defaults",
+			"  --reset         Remove .devcontainer customizations and install fresh defaults",
+		);
+		console.log("                  (.codeforge user modifications preserved)");
+		console.log("  --help, -h      Show this help message");
+		console.log("");
+		console.log("Subcommands:");
+		console.log(
+			"  config apply    Deploy .codeforge/config/ files to ~/.claude/",
 		);
-		console.log("  --help, -h    Show this help message");
 		console.log("");
 		console.log(
 			"Without flags, installs only if .devcontainer does not exist.",
@@ -148,6 +325,11 @@ function main() {
 	const packageDir = __dirname;
 	const devcontainerSrc = path.join(packageDir, ".devcontainer");
 	const devcontainerDest = path.join(currentDir, ".devcontainer");
+	const codeforgeSrc = path.join(packageDir, ".codeforge");
+	const codeforgeDest = path.join(currentDir, ".codeforge");
+	const packageVersion = JSON.parse(
+		fs.readFileSync(path.join(packageDir, "package.json"), "utf8"),
+	).version;
 
 	console.log("");
 
@@ -161,12 +343,44 @@ function main() {
 
 	if (fs.existsSync(devcontainerDest)) {
 		if (reset) {
-			// Nuclear: delete everything and copy fresh
+			// Nuclear: delete .devcontainer 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(
+				"  Reset complete. All .devcontainer customizations removed.",
+			);
+
+			// .codeforge uses checksum-based preservation (not wipe)
+			if (fs.existsSync(codeforgeSrc)) {
+				if (fs.existsSync(codeforgeDest)) {
+					const codeforgeStats = syncCodeforgeDirectory(
+						codeforgeSrc,
+						codeforgeDest,
+					);
+					console.log("  .codeforge/ user modifications preserved.");
+					console.log(`    Updated:   ${codeforgeStats.updated} files`);
+					console.log(`    Added:     ${codeforgeStats.added} new files`);
+					console.log(
+						`    Preserved: ${codeforgeStats.preserved} user config files`,
+					);
+					if (codeforgeStats.defaultFiles.length > 0) {
+						console.log("");
+						console.log(
+							"  Review .default files for new defaults you may want to merge:",
+						);
+						for (const f of codeforgeStats.defaultFiles) {
+							console.log(`    ${f}.default`);
+						}
+					}
+				} else {
+					copyDirectory(codeforgeSrc, codeforgeDest);
+				}
+				const newChecksums = generateChecksums(codeforgeSrc);
+				writeChecksums(codeforgeDest, packageVersion, newChecksums);
+			}
+
 			console.log("");
 			printNextSteps();
 		} else if (force) {
@@ -204,6 +418,34 @@ function main() {
 				console.log("");
 			}
 
+			// .codeforge sync with checksum-based preservation
+			if (fs.existsSync(codeforgeSrc)) {
+				const codeforgeStats = syncCodeforgeDirectory(
+					codeforgeSrc,
+					codeforgeDest,
+				);
+				const newChecksums = generateChecksums(codeforgeSrc);
+				writeChecksums(codeforgeDest, packageVersion, newChecksums);
+
+				console.log("  .codeforge/ update:");
+				console.log(`    Updated:   ${codeforgeStats.updated} files`);
+				console.log(`    Added:     ${codeforgeStats.added} new files`);
+				console.log(
+					`    Preserved: ${codeforgeStats.preserved} user config files`,
+				);
+
+				if (codeforgeStats.defaultFiles.length > 0) {
+					console.log("");
+					console.log(
+						"  Review .default files for new defaults you may want to merge:",
+					);
+					for (const f of codeforgeStats.defaultFiles) {
+						console.log(`    ${f}.default`);
+					}
+				}
+				console.log("");
+			}
+
 			printNextSteps();
 		} else {
 			// No flags: error with guidance
@@ -221,6 +463,13 @@ function main() {
 
 		try {
 			copyDirectory(devcontainerSrc, devcontainerDest);
+
+			if (fs.existsSync(codeforgeSrc)) {
+				copyDirectory(codeforgeSrc, codeforgeDest);
+				const checksums = generateChecksums(codeforgeSrc);
+				writeChecksums(codeforgeDest, packageVersion, checksums);
+			}
+
 			console.log("  CodeForge DevContainer configuration installed!");
 			console.log("");
 			printNextSteps();
@@ -232,13 +481,127 @@ function main() {
 	}
 }
 
+// ── configApply ──────────────────────────────────────────────────
+// Deploys .codeforge/config/ files to ~/.claude/ using file-manifest.json.
+function configApply() {
+	const codeforgeDir =
+		process.env.CODEFORGE_DIR || path.join(process.cwd(), ".codeforge");
+	const manifest = path.join(codeforgeDir, "file-manifest.json");
+
+	if (!fs.existsSync(manifest)) {
+		console.error("Error: file-manifest.json not found at " + manifest);
+		console.error("Are you in a CodeForge project directory?");
+		process.exit(1);
+	}
+
+	const entries = JSON.parse(fs.readFileSync(manifest, "utf-8"));
+	const claudeConfigDir =
+		process.env.CLAUDE_CONFIG_DIR ||
+		path.join(process.env.HOME || "/home/vscode", ".claude");
+	const workspaceRoot = process.env.WORKSPACE_ROOT || process.cwd();
+
+	function expandVars(val) {
+		return val
+			.replace(/\$\{CLAUDE_CONFIG_DIR\}/g, claudeConfigDir)
+			.replace(/\$\{WORKSPACE_ROOT\}/g, workspaceRoot)
+			.replace(/\$\{HOME\}/g, process.env.HOME || "/home/vscode");
+	}
+
+	console.log("");
+	console.log("Applying .codeforge/config/ to Claude configuration...");
+	console.log("");
+
+	let deployed = 0;
+	let skipped = 0;
+
+	const validOverwrite = ["always", "if-changed", "never"];
+
+	for (const entry of entries) {
+		if (entry.enabled === false) {
+			skipped++;
+			continue;
+		}
+
+		if (entry.overwrite && !validOverwrite.includes(entry.overwrite)) {
+			console.log(
+				'  Warning: Unknown overwrite value "' +
+					entry.overwrite +
+					'" for ' +
+					entry.src +
+					', defaulting to "always"',
+			);
+		}
+
+		const codeforgeRoot = path.resolve(codeforgeDir);
+		const srcPath = path.resolve(codeforgeRoot, entry.src);
+		if (!srcPath.startsWith(codeforgeRoot + path.sep)) {
+			console.log(
+				"  Skip: " + entry.src + " (source path escapes .codeforge/)",
+			);
+			skipped++;
+			continue;
+		}
+		if (!fs.existsSync(srcPath)) {
+			console.log("  Skip: " + entry.src + " (not found)");
+			skipped++;
+			continue;
+		}
+
+		const homeDir = path.resolve(process.env.HOME || "/home/vscode");
+		const allowedDestRoots = [
+			path.resolve(claudeConfigDir),
+			homeDir,
+			"/usr/local",
+		];
+		const destDir = path.resolve(expandVars(entry.dest));
+		const destAllowed = allowedDestRoots.some(
+			(root) => destDir === root || destDir.startsWith(root + path.sep),
+		);
+		if (!destAllowed) {
+			console.log(
+				"  Skip: " + entry.dest + " (destination outside allowed directories)",
+			);
+			skipped++;
+			continue;
+		}
+
+		const filename = entry.destFilename || path.basename(entry.src);
+		const destPath = path.join(destDir, filename);
+		fs.mkdirSync(destDir, { recursive: true });
+
+		if (entry.overwrite === "never" && fs.existsSync(destPath)) {
+			console.log("  Skip: " + filename + " (exists, overwrite=never)");
+			skipped++;
+			continue;
+		}
+
+		if (entry.overwrite === "if-changed" && fs.existsSync(destPath)) {
+			const srcHash = computeChecksum(srcPath);
+			const destHash = computeChecksum(destPath);
+			if (srcHash === destHash) {
+				skipped++;
+				continue;
+			}
+		}
+
+		fs.copyFileSync(srcPath, destPath);
+		console.log("  Deployed: " + entry.src + " → " + destPath);
+		deployed++;
+	}
+
+	console.log("");
+	console.log(
+		"Config apply complete: " + deployed + " deployed, " + skipped + " skipped",
+	);
+}
+
 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("Documentation: .devcontainer/README.md and .codeforge/");
 	console.log("");
 }
 
@@ -255,4 +618,12 @@ if (require.main === module) {
 	main();
 }
 
-module.exports = { copyDirectory, syncDirectory, loadPreserveList, main };
+module.exports = {
+	copyDirectory,
+	syncDirectory,
+	syncCodeforgeDirectory,
+	loadPreserveList,
+	computeChecksum,
+	generateChecksums,
+	main,
+};

package/.devcontainer/docs/configuration-reference.md

@@ -1,93 +0,0 @@
-# Configuration Reference
-
-Quick reference for all CodeForge configuration options.
-
-## Which File to Edit
-
-| Task | File to Edit |
-|------|-------------|
-| Change default model | `config/defaults/settings.json` |
-| Change system prompt | `config/defaults/main-system-prompt.md` |
-| Customize keybindings | `config/defaults/keybindings.json` |
-| Control setup steps | `.env` |
-| Add custom config file | `config/file-manifest.json` |
-| Disable a feature | `devcontainer.json` (set `"version": "none"`) |
-| Disable a plugin | `config/defaults/settings.json` (remove from `enabledPlugins`) |
-| Skip a plugin install | `.env` (`PLUGIN_BLACKLIST`) |
-| Change container memory | `devcontainer.json` (`runArgs`) |
-| Add VS Code extension | `devcontainer.json` (`customizations.vscode.extensions`) |
-
-## `.env` Variables (Setup Behavior)
-
-These control what `setup.sh` does on each container start. Copy `.env.example` to `.env` and customize.
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `CLAUDE_CONFIG_DIR` | `/workspaces/.claude` | Where Claude Code config files are stored |
-| `CONFIG_SOURCE_DIR` | `(auto-detected)` | Source directory for config defaults |
-| `SETUP_CONFIG` | `true` | Copy config files per `file-manifest.json` |
-| `SETUP_ALIASES` | `true` | Add cc/claude/ccraw/cc-tools aliases to shell |
-| `SETUP_AUTH` | `true` | Configure Git/NPM auth from `.secrets` file |
-| `SETUP_PLUGINS` | `true` | Install Anthropic plugins + register local marketplace |
-| `SETUP_UPDATE_CLAUDE` | `true` | Background-update Claude Code CLI binary |
-| `SETUP_TERMINAL` | `true` | Configure VS Code Shift+Enter keybinding for Claude Code terminal |
-| `SETUP_PROJECTS` | `true` | Auto-detect projects for VS Code Project Manager |
-| `SETUP_POSTSTART` | `true` | Run post-start hooks from `/usr/local/devcontainer-poststart.d/` |
-| `PLUGIN_BLACKLIST` | `""` | Comma-separated plugin names to skip during installation |
-
-## `devcontainer.json` `remoteEnv` (Container Runtime)
-
-These environment variables are set in every terminal session inside the container.
-
-| Variable | Value | Description |
-|----------|-------|-------------|
-| `WORKSPACE_ROOT` | `/workspaces` | Workspace root directory |
-| `CLAUDE_CONFIG_DIR` | `/workspaces/.claude` | Claude Code config directory |
-| `GH_CONFIG_DIR` | `/workspaces/.gh` | GitHub CLI config directory |
-| `TMPDIR` | `/workspaces/.tmp` | Temporary files directory |
-| `CLAUDECODE` | `null` (unset) | Unsets the variable to allow nested Claude Code sessions (claude-in-claude) |
-
-## `config/file-manifest.json` (File Copy Rules)
-
-Each entry in the manifest array controls how a config file is deployed:
-
-```json
-{
-  "src": "defaults/settings.json",
-  "dest": "${CLAUDE_CONFIG_DIR}",
-  "destFilename": "settings.json",
-  "overwrite": "if-changed",
-  "enabled": true
-}
-```
-
-| Field | Required | Default | Description |
-|-------|----------|---------|-------------|
-| `src` | Yes | — | Source file path relative to `config/` |
-| `dest` | Yes | — | Destination directory (supports `${CLAUDE_CONFIG_DIR}`, `${WORKSPACE_ROOT}`) |
-| `destFilename` | No | basename of `src` | Override the destination filename |
-| `overwrite` | No | `"if-changed"` | `"always"`, `"never"`, or `"if-changed"` (sha256 comparison) |
-| `enabled` | No | `true` | Set `false` to skip this entry |
-
-## Feature Options
-
-Each feature in `devcontainer.json` supports options defined in its `devcontainer-feature.json`. Common options:
-
-| Option | Description | Used By |
-|--------|-------------|---------|
-| `version` | Tool version to install. `"none"` skips installation. | All local features |
-| `username` | Container user to install for. `"automatic"` auto-detects. | dprint, ruff, ccusage, ccburn, etc. |
-| `shells` | Which shell rc files to modify (`"both"`, `"bash"`, `"zsh"`). | ccusage, ccburn |
-
-## `.secrets` File (Authentication)
-
-Create `.devcontainer/.secrets` with tokens for automatic authentication:
-
-```bash
-GH_TOKEN=ghp_your_token_here
-GH_USERNAME=your-github-username
-GH_EMAIL=your-email@example.com
-NPM_TOKEN=npm_your_token_here
-```
-
-Environment variables with the same names take precedence over `.secrets` file values (useful for Codespaces).