diff --git a/.devcontainer/CHANGELOG.md b/.devcontainer/CHANGELOG.md index 3651301..81dc6de 100644 --- a/.devcontainer/CHANGELOG.md +++ b/.devcontainer/CHANGELOG.md @@ -2,6 +2,18 @@ ## [Unreleased] +### Added + +#### Documentation +- **DevContainer CLI guide** — dedicated Getting Started page for terminal-only workflows without VS Code +- **v2 Migration Guide** — path changes, automatic migration, manual steps, breaking changes, and troubleshooting +- Documented 4 previously undocumented agents in agents.md: implementer, investigator, tester, documenter +- Added missing git-workflow and prompt-snippets to configuration.md enabledPlugins example +- Added CONFIG_SOURCE_DIR deprecation note in environment variables reference +- Added cc-orc orchestrator command to first-session launch commands table +- Tabbed client-specific instructions on the installation page +- Dedicated port forwarding reference page covering VS Code auto-detect, devcontainer-bridge, and SSH tunneling + ### Changed #### Performance @@ -14,9 +26,14 @@ - Dynamic port forwarding for all ports in VS Code — previously only port 7847 was statically forwarded; now all ports auto-forward with notification #### Documentation +- Updated **Port Forwarding reference** — VS Code dependency warning, devcontainer-bridge platform support matrix, CLI guide cross-link +- Slimmed **Installation page** — moved troubleshooting to dedicated reference page, CLI details to new CLI guide +- Full documentation review — accuracy, consistency, and completeness fixes across all 30+ pages +- Trimmed disabled ccms usage section from commands reference +- Clarified codeforge-lsp plugin description (declarative config, not "no configuration") +- Improved magic-docs agent explanation in agent-system plugin docs +- Clarified plugin count as "13 local + 1 official" in reference index - Updated prerequisites and installation docs to support all DevContainer clients (VS Code, CLI, JetBrains Gateway, DevPod, Codespaces) -- Added tabbed client-specific instructions on the installation page -- Added dedicated port forwarding reference page covering VS Code auto-detect, devcontainer-bridge, and SSH tunneling - **Ported `.devcontainer/docs/` to docs site** — migrated content from 5 legacy reference docs into the Starlight documentation site: - New **Keybindings** page (Customization) — VS Code/Claude Code shortcut conflicts and resolution options - New **Troubleshooting** page (Reference) — 12+ problem/solution entries for build, auth, plugins, and performance issues diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index af18a59..80e6b02 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -91,6 +91,14 @@ export default defineConfig({ { label: "Overview", slug: "getting-started" }, { label: "Requirements", slug: "getting-started/requirements" }, { label: "Installation", slug: "getting-started/installation" }, + { + label: "DevContainer CLI", + slug: "getting-started/devcontainer-cli", + }, + { + label: "Migrating to v2", + slug: "getting-started/migrating-to-v2", + }, { label: "Your First Session", slug: "getting-started/first-session", diff --git a/docs/src/content/docs/customization/configuration.md b/docs/src/content/docs/customization/configuration.md index 245cd00..4721fee 100644 --- a/docs/src/content/docs/customization/configuration.md +++ b/docs/src/content/docs/customization/configuration.md @@ -94,6 +94,8 @@ The `enabledPlugins` section controls which plugins are active: "notify-hook@devs-marketplace": true, "ticket-workflow@devs-marketplace": true, "codeforge-lsp@devs-marketplace": true, + "git-workflow@devs-marketplace": true, + "prompt-snippets@devs-marketplace": true, "frontend-design@claude-plugins-official": true } } diff --git a/docs/src/content/docs/features/agents.md b/docs/src/content/docs/features/agents.md index 4bb25af..75abb67 100644 --- a/docs/src/content/docs/features/agents.md +++ b/docs/src/content/docs/features/agents.md @@ -30,7 +30,7 @@ CodeForge **entirely replaces** all six built-in agents with enhanced custom spe The redirect is fully transparent — you can use either the built-in name or the custom name interchangeably. Asking Claude to "explore the codebase" triggers the same enhanced explorer agent whether the system selects the `Explore` type or the `explorer` type. -Beyond the six replacements, CodeForge adds **11 entirely new specialists** that have no built-in equivalent: architect, researcher, test-writer, refactorer, doc-writer, migrator, security-auditor, dependency-analyst, git-archaeologist, perf-profiler, debug-logs, and spec-writer. These are available only in CodeForge. +Beyond the six replacements, CodeForge adds **15 entirely new specialists** that have no built-in equivalent: debug-logs, dependency-analyst, doc-writer, documenter, git-archaeologist, implementer, investigator, migrator, perf-profiler, refactorer, researcher, security-auditor, spec-writer, tester, and test-writer. These are available only in CodeForge. :::tip[Why This Matters] The redirect happens at the hook level, not the prompt level. This means the upgrade is enforced — not suggested. Even if Claude's internal routing tries to use a stock Explore agent, the hook intercepts the call and swaps in the enhanced explorer before any code executes. The result is a strictly better agent every time, with zero user effort. @@ -122,6 +122,18 @@ A technical writing specialist that creates and maintains README files, API docu "Document the public API for the user service module. Include usage examples and parameter descriptions." ::: +### documenter + +Full Opus documentation-patterns specification-writing + +A documentation and specification lifecycle agent. Handles READMEs, API docs, inline documentation, and architectural guides alongside the full spec workflow — creating, refining, reviewing, and closing specifications. Carries 7 frontloaded skills covering both documentation patterns and all spec operations. Unlike doc-writer, the documenter works directly (no worktree isolation) and owns the spec lifecycle. Never modifies source code logic. + +**When activated:** "Document this module," "write a README," "create a spec and document the feature," specification lifecycle tasks that combine docs and specs. + +:::tip[documenter vs doc-writer] +Use **doc-writer** for pure documentation tasks (READMEs, docstrings, API docs) where worktree isolation is preferred. Use **documenter** when documentation and specification work are interleaved — it has the full spec skill set (spec-new, spec-refine, spec-review, spec-update, spec-check) built in. +::: + ### explorer Read-only Haiku @@ -158,6 +170,30 @@ A git history forensics specialist that traces code evolution, finds when bugs w "Trace the history of the authentication middleware. When was it introduced, who has modified it, and what were the major changes?" ::: +### implementer + +Full (worktree) Opus refactoring-patterns migration-patterns spec-update + +A full-stack implementation agent that handles all code modifications: writing new features, fixing bugs, refactoring existing code, and executing migrations. Runs tests after every edit via a Stop hook to catch regressions immediately. Works in a git worktree so your main branch stays clean. The broadest-scope implementation agent — use the more focused refactorer, migrator, or test-writer when the task is clearly within one domain. + +**When activated:** General implementation tasks, feature building, bug fixes, "implement this," multi-file changes that span domains. + +:::tip[Try this] +"Implement the user notification preferences feature. Add the database model, API endpoints, and update the settings page." +::: + +### investigator + +Read-only Sonnet debugging git-forensics performance-profiling dependency-management documentation-patterns ast-grep-patterns + +A comprehensive read-only research agent that consolidates six analysis domains: codebase exploration, web research, git history forensics, dependency auditing, log analysis, and performance profiling. Carries 6 frontloaded skills — more than any other agent — making it the go-to for complex investigations that cross domain boundaries. Never modifies files. + +**When activated:** Complex multi-domain investigations, "investigate why," "research and analyze," tasks that combine codebase analysis with git history or dependency research. + +:::tip[investigator vs specialists] +Use the **investigator** when an investigation spans multiple domains (e.g., "why is this slow" might need codebase analysis, git history, and performance profiling). Use a focused specialist (researcher, debug-logs, git-archaeologist, perf-profiler, dependency-analyst) when the domain is clear. +::: + ### migrator Full (worktree) Opus migration-patterns @@ -242,6 +278,18 @@ A specialist for configuring the Claude Code terminal statusline. Converts shell "Convert my current PS1 prompt to a Claude Code statusline. Include git branch, Python version, and working directory." ::: +### tester + +Full (worktree) Opus testing spec-update + +A test suite creation and verification agent. Analyzes existing code, writes comprehensive tests, and ensures all tests pass before completing via a Stop hook. Supports pytest, Vitest, Jest, Go testing, and Rust test frameworks. Works in a git worktree. Functionally equivalent to test-writer with the addition of the spec-update skill for closing the spec loop after writing tests. + +**When activated:** "Write tests for," "add test coverage," "create integration tests," test creation tasks. + +:::tip[tester vs test-writer] +These agents are nearly identical. **tester** includes the spec-update skill for spec-driven workflows. **test-writer** is the built-in replacement agent. Both produce the same quality of tests — use whichever surfaces based on your request. +::: + ### test-writer Full (worktree) Opus testing @@ -264,9 +312,12 @@ A senior test engineer that analyzes existing code and writes comprehensive test | debug-logs | Read-only | Sonnet | -- | -- | debugging | | dependency-analyst | Read-only | Haiku | -- | Yes | dependency-management | | doc-writer | Full | Opus | Worktree | -- | documentation-patterns | +| documenter | Full | Opus | -- | -- | documentation-patterns, specification-writing, spec-new, spec-update, spec-review, spec-refine, spec-check | | explorer | Read-only | Haiku | -- | -- | ast-grep-patterns | | generalist | Full | Inherited | -- | -- | spec workflow | | git-archaeologist | Read-only | Haiku | -- | -- | git-forensics | +| implementer | Full | Opus | Worktree | -- | refactoring-patterns, migration-patterns, spec-update | +| investigator | Read-only | Sonnet | -- | -- | documentation-patterns, git-forensics, performance-profiling, debugging, dependency-management, ast-grep-patterns | | migrator | Full | Opus | Worktree | -- | migration-patterns | | perf-profiler | Read-only | Sonnet | -- | Yes | performance-profiling | | refactorer | Full | Opus | Worktree | -- | refactoring-patterns | @@ -274,14 +325,15 @@ A senior test engineer that analyzes existing code and writes comprehensive test | security-auditor | Read-only | Sonnet | -- | Yes | security-checklist | | spec-writer | Read-only | Opus | -- | -- | specification-writing | | statusline-config | Full | Sonnet | -- | -- | -- | +| tester | Full | Opus | Worktree | -- | testing, spec-update | | test-writer | Full | Opus | Worktree | -- | testing | ## Access Levels at a Glance | Access Level | Agents | |-------------|--------| -| **Read-only** | architect, claude-guide, debug-logs, dependency-analyst, explorer, git-archaeologist, perf-profiler, researcher, security-auditor, spec-writer | -| **Full** | bash-exec, doc-writer, generalist, migrator, refactorer, statusline-config, test-writer | +| **Read-only** | architect, claude-guide, debug-logs, dependency-analyst, explorer, git-archaeologist, investigator, perf-profiler, researcher, security-auditor, spec-writer | +| **Full** | bash-exec, doc-writer, documenter, generalist, implementer, migrator, refactorer, statusline-config, tester, test-writer | :::note[About Model Selection] Agents use different Claude models based on task complexity. Opus handles the most demanding tasks (architecture, refactoring, test writing, migration). Sonnet covers analytical tasks that need strong reasoning (security audits, research, debugging). Haiku powers fast, focused tasks (exploration, dependency analysis, git history). The generalist inherits whichever model the main session is using. @@ -291,10 +343,10 @@ Agents use different Claude models based on task complexity. Opus handles the mo Several agents include built-in safety hooks: -- **Read-only bash guard** — The architect, explorer, security auditor, dependency analyst, and git-archaeologist all have a PreToolUse hook that blocks any Bash command that could modify files or state. +- **Read-only bash guard** — The architect, explorer, investigator, security auditor, dependency analyst, and git-archaeologist all have a PreToolUse hook that blocks any Bash command that could modify files or state. - **Git-readonly guard** — The git-archaeologist has a specialized guard that only permits read-only git subcommands (log, blame, show, diff, reflog, etc.). - **Post-edit test verification** — The refactorer runs tests automatically after every single Edit operation. If tests fail, the change is immediately reverted. -- **Stop verification** — The test-writer has a Stop hook that verifies all written tests pass before the agent completes. +- **Stop verification** — The test-writer and tester have a Stop hook that verifies all written tests pass before the agent completes. The implementer has a similar Stop hook that runs regression checks. ## Related diff --git a/docs/src/content/docs/getting-started/devcontainer-cli.md b/docs/src/content/docs/getting-started/devcontainer-cli.md new file mode 100644 index 0000000..f278f6b --- /dev/null +++ b/docs/src/content/docs/getting-started/devcontainer-cli.md @@ -0,0 +1,134 @@ +--- +title: DevContainer CLI +description: Run CodeForge from the command line without VS Code — build, connect, and manage containers using the devcontainer CLI. +sidebar: + order: 4 +--- + +The DevContainer CLI lets you build and run CodeForge containers without VS Code. Use it when you prefer terminal-only workflows, work on headless servers, or need DevContainer support in CI/CD pipelines. + +## Install the CLI + +```bash +npm install -g @devcontainers/cli +``` + +Requires Node.js 16.13+ or 18+ (when installing via npm). Verify the installation with `devcontainer --version`. + +## Build and Start + +From your project root (where `.devcontainer/` lives): + +```bash +devcontainer up --workspace-folder . +``` + +The first build takes several minutes — it pulls the base image, installs all features, and runs post-start setup. Subsequent starts reuse cached layers and complete in seconds. + +:::caution[Don't interrupt the first build] +If the build is interrupted, Docker may cache a partial state. Rebuild from scratch: +```bash +devcontainer up --workspace-folder . --remove-existing-container +``` +::: + +## Connect to the Container + +The recommended way to get a shell inside the container: + +```bash +devcontainer exec --workspace-folder . zsh +``` + +This uses the devcontainer CLI's exec command, which respects the container's configured user and environment. You can also use `docker exec` directly — run `docker ps` to find the container name: + +```bash +docker exec -it zsh +``` + +## Run Commands + +Execute commands without entering an interactive shell: + +```bash +# Run check-setup to verify the installation +devcontainer exec --workspace-folder . check-setup + +# Launch a Claude Code session +devcontainer exec --workspace-folder . cc + +# List installed tools +devcontainer exec --workspace-folder . cc-tools +``` + +## Port Forwarding + +VS Code auto-forwards container ports to your host automatically. **The CLI does not.** You need an explicit forwarding mechanism. + +:::caution[No automatic port forwarding] +Unlike VS Code, the devcontainer CLI does not auto-forward ports. Services running inside the container (like the Claude Dashboard on port 7847) won't be accessible on your host unless you set up forwarding manually. +::: + +**Recommended:** Install [devcontainer-bridge](https://github.com/bradleybeddoes/devcontainer-bridge) (`dbr`) for dynamic, automatic port forwarding that works with any terminal client. CodeForge pre-installs the container side — you only need the host daemon: + +```bash +# On your host machine +dbr host-daemon +``` + +**Alternative:** Use SSH tunneling for specific ports: + +```bash +ssh -L 7847:localhost:7847 @ +``` + +See [Port Forwarding](/reference/port-forwarding/) for the full setup guide and comparison of all forwarding mechanisms. + +## Key Differences from VS Code + +| Capability | VS Code | DevContainer CLI | +|------------|---------|------------------| +| Port forwarding | Automatic | Manual — use `dbr` or SSH tunneling | +| Extensions panel | GUI in sidebar | Not available | +| Ports panel | Visual port management | Not available — use `docker port` or `dbr` | +| Terminal management | Integrated tabs | Manual — use tmux for parallel sessions | +| File editing | Built-in editor | Use your preferred editor (vim, nano, etc.) | + +## Rebuilding + +When you change `devcontainer.json` or feature configurations, rebuild: + +```bash +# Rebuild using cached layers (fast) +devcontainer up --workspace-folder . + +# Full rebuild from scratch (slow, but fixes cache issues) +devcontainer up --workspace-folder . --remove-existing-container +``` + +## Stopping the Container + +The devcontainer CLI doesn't have a dedicated stop command. Use Docker directly: + +```bash +# Find the container name +docker ps + +# Stop the container +docker stop + +# Or stop and remove it +docker rm -f +``` + +## Tips + +- **Use tmux** for parallel sessions inside the container. CodeForge installs tmux by default — run `tmux` after connecting to get split panes and persistent sessions. +- **Connect external terminals** using the scripts in `.codeforge/scripts/` — `connect-external-terminal.sh` (macOS/Linux) or `connect-external-terminal.ps1` (Windows PowerShell). +- **Combine with `dbr`** for the closest experience to VS Code — automatic port forwarding without needing VS Code running. + +## Next Steps + +- [Your First Session](/getting-started/first-session/) — start using CodeForge with Claude Code +- [Port Forwarding](/reference/port-forwarding/) — detailed forwarding setup guide +- [Installation](/getting-started/installation/) — full installation walkthrough diff --git a/docs/src/content/docs/getting-started/first-session.md b/docs/src/content/docs/getting-started/first-session.md index 21da7fd..aa9fe06 100644 --- a/docs/src/content/docs/getting-started/first-session.md +++ b/docs/src/content/docs/getting-started/first-session.md @@ -2,7 +2,7 @@ title: First Session description: Walkthrough of your first Claude Code session inside a CodeForge DevContainer. sidebar: - order: 4 + order: 6 --- You've installed CodeForge and the container is running. Now it's time to launch your first Claude Code session and see everything in action. This guide walks you through what happens when you start a session, what to try first, and how the different systems work together. @@ -24,6 +24,7 @@ The `cc` command is a CodeForge alias that launches Claude Code with the correct | `cc` | Full CodeForge session with system prompt, plugins, and all configuration | | `claude` | Same as `cc` — an alias for convenience | | `ccw` | Writing-focused session using the writing system prompt (great for documentation) | +| `cc-orc` | Orchestrator mode — delegation-first approach, useful for complex multi-agent tasks | | `ccraw` | Raw Claude Code session with no CodeForge configuration — useful for debugging | :::tip[When to use ccraw] diff --git a/docs/src/content/docs/getting-started/index.md b/docs/src/content/docs/getting-started/index.md index faa34c6..789d440 100644 --- a/docs/src/content/docs/getting-started/index.md +++ b/docs/src/content/docs/getting-started/index.md @@ -97,6 +97,8 @@ The environment is designed to stay out of your way while quietly making everyth - [System Requirements](./requirements/) — verify your system is ready - [Installation Guide](./installation/) — detailed setup instructions +- [DevContainer CLI](./devcontainer-cli/) — run CodeForge from the terminal without VS Code +- [Migrating to v2](./migrating-to-v2/) — upgrade from v1.x to the new `.codeforge/` directory structure - [First Session](./first-session/) — walk through your first Claude Code session - [Plugins Overview](../plugins/) — explore the plugin ecosystem - [Features Overview](../features/) — browse available agents, skills, and tools diff --git a/docs/src/content/docs/getting-started/installation.md b/docs/src/content/docs/getting-started/installation.md index c38101b..c17b916 100644 --- a/docs/src/content/docs/getting-started/installation.md +++ b/docs/src/content/docs/getting-started/installation.md @@ -78,25 +78,15 @@ You can watch the build progress in the "Dev Containers" output channel in the t -Install the CLI if you haven't already: +Install the CLI and build the container: ```bash npm install -g @devcontainers/cli -``` - -Build and start the container: - -```bash devcontainer up --workspace-folder . +devcontainer exec --workspace-folder . zsh ``` -Then connect to the running container: - -```bash -docker exec -it zsh -``` - -Use `docker ps` to find the container name. For port forwarding outside VS Code, see the [Port Forwarding reference](../reference/port-forwarding/). +For the full CLI workflow — connecting, port forwarding, rebuilding, and tips — see the dedicated [DevContainer CLI guide](./devcontainer-cli/). @@ -224,94 +214,18 @@ Use `git diff .devcontainer/` after updating to review what changed before commi ## Troubleshooting -### Container fails to build - -**Symptoms:** VS Code shows a build error, or the container exits immediately. - -**Common causes and fixes:** - -- **Docker not running** — start Docker Desktop or the Docker daemon -- **Insufficient resources** — open Docker Desktop settings and allocate at least 4 GB RAM and 20 GB disk to the VM -- **Network issues** — the first build downloads several GB of images and tools; check your internet connection -- **Cached partial build** — use **Dev Containers: Rebuild Container Without Cache** to start clean - -### Tools not found after build - -**Symptoms:** Commands like `cc` return "command not found." (Note: `ccms` is currently disabled by default.) - -- Run `check-setup` to identify which tools are missing -- Check that the post-start script completed successfully (look for errors in the terminal output) -- Rebuild the container to trigger a fresh install - -### Claude Code authentication issues - -**Symptoms:** Running `cc` or `claude` prompts for authentication or returns an error. - -- Claude Code authenticates on first launch — follow the prompts to sign in -- If authentication was previously completed but stopped working, try `claude auth` to re-authenticate -- Ensure your Claude subscription is active - -### Slow container startup - -**Symptoms:** The container takes a long time to start after the initial build. - -- Subsequent starts should be fast (under 30 seconds) because Docker caches built layers -- If starts are consistently slow, check Docker resource allocation -- The `postStartCommand` runs on every start to deploy configuration files — this is normal and should complete in a few seconds - -### `npx codeforge-dev` fails - -**Symptoms:** The installer command errors out before creating `.devcontainer/`. - -- **Node.js not installed** — the installer requires Node.js 18+ and npm. Run `node --version` to check; install from [nodejs.org](https://nodejs.org/) if missing -- **Network issues** — npm needs to reach the registry to download the package. Check your connection or try `npm config set registry https://registry.npmjs.org/` -- **Permission errors** — on some systems, global npm installs need `sudo`. Try `npx --yes codeforge-dev` or install globally with `sudo npm install -g codeforge-dev` - -### VS Code doesn't show "Reopen in Container" - -**Symptoms:** You opened the project in VS Code but never see the DevContainer prompt. - -- **Extension not installed** — install `ms-vscode-remote.remote-containers` from the Extensions marketplace, then reload VS Code -- **`.devcontainer/` not at repo root** — VS Code looks for `.devcontainer/` in the workspace root folder. If your project is inside a subfolder, open that subfolder directly - -:::note[Using a different client?] -Not using VS Code? The DevContainer CLI, JetBrains Gateway, DevPod, and Codespaces all read the same `devcontainer.json`. See [Step 2](#step-2-open-in-a-devcontainer-client) for client-specific instructions. -::: -- **VS Code version** — DevContainers requires VS Code 1.85 or later. Check **Help → About** and update if needed - -### Docker permission errors (Linux) - -**Symptoms:** `docker: permission denied` or `Cannot connect to the Docker daemon` errors. - -- Add your user to the `docker` group: `sudo usermod -aG docker $USER`, then log out and back in -- Verify with `docker ps` — it should run without `sudo` -- If using Docker rootless mode, ensure the socket path is set correctly in VS Code settings - -### WSL 2 integration issues (Windows) - -**Symptoms:** Container fails to start, or Docker commands hang inside WSL. - -- Open Docker Desktop → **Settings → Resources → WSL Integration** and enable integration for your WSL distro -- Ensure WSL 2 (not WSL 1) is active: run `wsl -l -v` in PowerShell and check the VERSION column -- Restart Docker Desktop after changing WSL settings - -### Port conflicts - -**Symptoms:** The claude-dashboard or other tools fail to bind their port. - -- CodeForge's session dashboard uses **port 7847** by default. If another service uses that port, change it in `devcontainer.json` under `forwardPorts` -- To find what's using a port: `lsof -i :7847` (macOS/Linux) or `netstat -ano | findstr 7847` (Windows) - -### Container rebuilds are slow - -**Symptoms:** Rebuilding the container takes as long as the first build. +Having trouble with the build, authentication, or missing tools? See the [Troubleshooting reference](../reference/troubleshooting/) for solutions to common issues including: -- **Use "Rebuild Container"** (not "Rebuild Without Cache") for routine rebuilds — Docker reuses cached layers for unchanged steps -- **Prune unused images** to free disk space: `docker system prune -a` removes all unused images (confirm you don't need them first) -- **Check disk space** — Docker needs headroom for layer storage. If your disk is nearly full, builds may fail or slow down significantly +- Container build failures and slow builds +- `npx codeforge-dev` installation errors +- VS Code not showing the DevContainer prompt +- Claude Code authentication problems +- Docker permissions on Linux and WSL 2 integration on Windows +- Port conflicts ## Next Steps +- [DevContainer CLI](./devcontainer-cli/) — terminal-only workflow without VS Code - [First Session](./first-session/) — start using CodeForge with Claude Code - [Configuration](../customization/configuration/) — customize settings - [Plugins Overview](../plugins/) — understand what each plugin does diff --git a/docs/src/content/docs/getting-started/migrating-to-v2.md b/docs/src/content/docs/getting-started/migrating-to-v2.md new file mode 100644 index 0000000..de0e7c9 --- /dev/null +++ b/docs/src/content/docs/getting-started/migrating-to-v2.md @@ -0,0 +1,126 @@ +--- +title: Migrating to v2 +description: What changed in CodeForge v2 and how to upgrade from v1.x — configuration externalization, new file paths, and automatic migration. +sidebar: + order: 5 +--- + +CodeForge v2 externalizes user configuration from `.devcontainer/config/defaults/` to a new top-level `.codeforge/` directory. This separates your customizations from the DevContainer infrastructure, making updates cleaner and reducing merge conflicts. + +:::note[Unreleased] +v2 is the next release. The current published version is 1.14.2. This guide is forward-looking — use it when v2 ships or if you're testing from the main branch. +::: + +## What Changed + +In v1.x, user-customizable files lived inside `.devcontainer/config/defaults/`. This meant every CodeForge update touched the same directory as your customizations, making it hard to tell what changed and what you'd modified. + +v2 moves all user config to `.codeforge/` — a directory you own. CodeForge updates modify `.devcontainer/` (infrastructure) while `.codeforge/` (your customizations) stays untouched unless you change it. + +## Key Path Changes + +| v1.x Path | v2 Path | +|-----------|---------| +| `.devcontainer/config/defaults/settings.json` | `.codeforge/config/settings.json` | +| `.devcontainer/config/defaults/main-system-prompt.md` | `.codeforge/config/main-system-prompt.md` | +| `.devcontainer/config/defaults/rules/` | `.codeforge/config/rules/` | +| `.devcontainer/config/file-manifest.json` | `.codeforge/file-manifest.json` | +| `.devcontainer/connect-external-terminal.sh` | `.codeforge/scripts/connect-external-terminal.sh` | +| `.devcontainer/connect-external-terminal.ps1` | `.codeforge/scripts/connect-external-terminal.ps1` | +| `CONFIG_SOURCE_DIR` env var | `CODEFORGE_DIR` env var | + +## Automatic Migration + +On first container start after updating to v2, the migration script (`setup-migrate-codeforge.sh`) runs automatically: + +1. Detects the legacy `.devcontainer/config/defaults/` directory +2. Creates the `.codeforge/` directory structure +3. Copies all config files from `defaults/` to `.codeforge/config/` +4. Copies and rewrites `file-manifest.json` (updates internal paths) +5. Moves terminal scripts to `.codeforge/scripts/` +6. Writes a migration marker at `.codeforge/.markers/v2-migrated` + +The migration is **idempotent** — if `.codeforge/` already exists, the script skips entirely. It never overwrites existing files. + +## Manual Migration + +If you prefer to migrate by hand: + +1. **Update CodeForge:** + ```bash + npx codeforge-dev@latest + ``` + +2. **Review the new `.codeforge/` directory** created by the installer. It contains default versions of all config files. + +3. **Move your customizations** from the old paths to the new paths. Only copy files you've actually modified — the installer provides fresh defaults for everything else. + +4. **Update `.env`** if you set `CONFIG_SOURCE_DIR`: + ```bash + # Old (v1.x) + CONFIG_SOURCE_DIR=/custom/path + + # New (v2) + CODEFORGE_DIR=/custom/path + ``` + +5. **Rebuild the container:** + - **VS Code:** `Ctrl+Shift+P` → **Dev Containers: Rebuild Container** + - **CLI:** `devcontainer up --workspace-folder . --remove-existing-container` + +6. **Verify the migration:** + ```bash + check-setup + ``` + +## How Updates Work in v2 + +CodeForge v2 uses **checksum-based modification detection** to protect your customizations during updates: + +- When you run `npx codeforge-dev@latest`, the installer compares each `.codeforge/` file's SHA-256 checksum against the known default. +- **Unmodified files** are updated in place with the new default. +- **Modified files** are preserved. The new default is written as a `.default` file (e.g., `settings.json.default`) for you to review and merge manually. + +The `--force` flag triggers this smart sync. The `--reset` flag wipes `.devcontainer/` but preserves `.codeforge/` — your customizations are always safe. + +## Breaking Changes + +### `CONFIG_SOURCE_DIR` Deprecated + +The `CONFIG_SOURCE_DIR` environment variable is replaced by `CODEFORGE_DIR`. If your `.env` file still sets `CONFIG_SOURCE_DIR`, the startup script: + +1. Detects the stale variable +2. Overrides it internally to use the correct path +3. Auto-comments the line in `.env` with a deprecation warning + +No action is required — it's handled automatically. But you should update `.env` to use `CODEFORGE_DIR` to avoid the warning. + +## New Capabilities + +v2 introduces several features alongside the directory restructure: + +- **`codeforge config apply`** — CLI command to deploy config files to `~/.claude/` on demand (same operation that runs on container start) +- **`.codeforge-preserve`** — list additional files in `.codeforge/` that should be preserved during updates, beyond the defaults +- **Checksum tracking** — `.codeforge/.checksums/` stores SHA-256 hashes so the system knows which files you've modified + +## Troubleshooting + +**Migration didn't run automatically:** +- Check if `.codeforge/` already exists (the script skips if it does) +- Verify `WORKSPACE_ROOT` is set correctly (defaults to `/workspaces`) +- Run the migration script manually: `bash .devcontainer/scripts/setup-migrate-codeforge.sh` + +**Config files not deploying after migration:** +- Run `codeforge config apply` to trigger a manual deployment +- Check `.codeforge/file-manifest.json` — paths should reference `config/` (not `defaults/`) + +**Old `CONFIG_SOURCE_DIR` in `.env` causing issues:** +- Remove or comment the line — `CODEFORGE_DIR` is the v2 equivalent +- The startup script handles this automatically, but manual cleanup avoids the deprecation warning + +## Related + +- [Configuration](/customization/configuration/) — full settings reference +- [Environment Variables](/reference/environment/) — all environment variables including `CODEFORGE_DIR` +- [Changelog](/reference/changelog/) — v2.0.0 release notes +- [Architecture](/reference/architecture/) — system design and component relationships diff --git a/docs/src/content/docs/plugins/agent-system.md b/docs/src/content/docs/plugins/agent-system.md index 118dde5..72cdbde 100644 --- a/docs/src/content/docs/plugins/agent-system.md +++ b/docs/src/content/docs/plugins/agent-system.md @@ -72,7 +72,7 @@ Each redirect is a strict improvement. The custom agents carry capabilities that The redirect is fully transparent to you and to Claude. Using either name works — `Explore` and `explorer` both resolve to the same enhanced agent. :::note[The Seventh Agent Type] -Claude Code has a seventh built-in agent type, `magic-docs`, used internally for documentation updates. This agent is **not** redirected — it runs natively. All other six built-in types are intercepted and replaced. +Claude Code has a seventh built-in agent type, `magic-docs`, which handles internal documentation generation tasks within Claude Code itself. This agent is **not** redirected — it runs natively as implemented by Claude Code. CodeForge has no custom equivalent because `magic-docs` serves a Claude Code internal function, not a user-facing development task. All other six built-in types are intercepted and replaced. ::: ## Safety Mechanisms diff --git a/docs/src/content/docs/plugins/codeforge-lsp.md b/docs/src/content/docs/plugins/codeforge-lsp.md index fee4590..7bd825e 100644 --- a/docs/src/content/docs/plugins/codeforge-lsp.md +++ b/docs/src/content/docs/plugins/codeforge-lsp.md @@ -9,7 +9,7 @@ The CodeForge LSP plugin gives Claude access to the same code intelligence that ## How It Works -This is a purely declarative plugin -- it has no hooks and no scripts. It registers LSP server configurations in `plugin.json`, and Claude Code launches each server at startup if its binary is available on PATH. Missing servers are silently skipped, so the plugin never fails on a missing tool. +This is a purely declarative plugin -- it has no hook scripts and no shell scripts. All configuration lives in `plugin.json`, where it registers LSP server definitions. Claude Code launches each server at startup if its binary is available on PATH. Missing servers are silently skipped, so the plugin never fails on a missing tool. When Claude opens a file matching a registered extension, the corresponding LSP server provides rich language features for that file. @@ -87,7 +87,7 @@ If a server binary isn't installed, the plugin silently skips it. You can regist ## Plugin Structure -Unlike most CodeForge plugins, the LSP plugin contains no scripts or hooks -- just configuration: +Unlike most CodeForge plugins, the LSP plugin contains no hook scripts or shell scripts -- just declarative configuration: ``` codeforge-lsp/ diff --git a/docs/src/content/docs/reference/commands.md b/docs/src/content/docs/reference/commands.md index b3e8210..2f5f211 100644 --- a/docs/src/content/docs/reference/commands.md +++ b/docs/src/content/docs/reference/commands.md @@ -46,36 +46,6 @@ Commands for session analysis, usage tracking, and system monitoring. | `cc-tools` | List all installed CodeForge CLI tools with version info | `cc-tools` | | `dbr` | Dynamic port forwarding via devcontainer-bridge (container↔host) | `dbr` | -### ccms Usage - -:::caution[Currently Disabled] -The `ccms` feature is currently commented out in `devcontainer.json`. A replacement tool is pending. The documentation below is preserved for reference. -::: - -`ccms` is the most feature-rich analysis command. Key flags: - -```bash -# Basic search -ccms "error handling" - -# Project-scoped (recommended) -ccms --project "$(pwd)" "auth approach" - -# Filter by role -ccms -r assistant "what was decided" -ccms -r user "please fix" - -# Boolean queries -ccms "error AND connection" -ccms "(auth OR authentication) AND NOT test" - -# Time-scoped -ccms --since "1 day ago" "recent work" - -# JSON output -ccms -f json "query" -n 10 -``` - ## Code Quality Commands Pre-installed tools for linting, formatting, and code analysis. diff --git a/docs/src/content/docs/reference/environment.md b/docs/src/content/docs/reference/environment.md index e76a662..3206a05 100644 --- a/docs/src/content/docs/reference/environment.md +++ b/docs/src/content/docs/reference/environment.md @@ -94,7 +94,7 @@ These variables live in `.devcontainer/.env` and control what `setup.sh` does on | Variable | Default | Description | |----------|---------|-------------| | `CLAUDE_CONFIG_DIR` | `/home/vscode/.claude` | Where Claude Code config files are stored | -| `CODEFORGE_DIR` | (auto-detected) | Source directory for user-customizable config files (`.codeforge/`) | +| `CODEFORGE_DIR` | (auto-detected) | Source directory for user-customizable config files (`.codeforge/`). Replaces the deprecated `CONFIG_SOURCE_DIR` from v1.x. | | `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 | diff --git a/docs/src/content/docs/reference/index.md b/docs/src/content/docs/reference/index.md index 009d0fc..426cf93 100644 --- a/docs/src/content/docs/reference/index.md +++ b/docs/src/content/docs/reference/index.md @@ -70,7 +70,7 @@ These are the files you will interact with most often when configuring CodeForge | Component | Count | Details | |-----------|-------|---------| | DevContainer features | 22 | Runtimes, CLI tools, monitoring | -| Plugins | 14 | Safety, quality, workflow, intelligence | +| Plugins | 14 (13 local + 1 official) | Safety, quality, workflow, intelligence | | Agents | 21 | Specialized personas from explorer to security-auditor | | Skills | 38 | On-demand knowledge across coding, testing, frameworks | | Built-in rules | 3 | Workspace scope, spec workflow, session search | diff --git a/docs/src/content/docs/reference/port-forwarding.md b/docs/src/content/docs/reference/port-forwarding.md index a4d07ed..248c604 100644 --- a/docs/src/content/docs/reference/port-forwarding.md +++ b/docs/src/content/docs/reference/port-forwarding.md @@ -24,6 +24,10 @@ VS Code automatically detects ports opened inside the container and forwards the No setup required — ports appear in the VS Code **Ports** panel as services start. Click the local address to open in your browser. +:::caution[Requires VS Code to be running] +Port forwarding only works while VS Code is open and connected to the devcontainer. If you close VS Code or disconnect, all forwarded ports become inaccessible. For persistent port forwarding that doesn't depend on your editor, use [devcontainer-bridge](#devcontainer-bridge-dbr). +::: + :::note This only works inside VS Code and GitHub Codespaces. The `devcontainer` CLI, JetBrains Gateway, and DevPod ignore `portsAttributes` in `devcontainer.json`. ::: @@ -66,6 +70,18 @@ python -m http.server 8080 curl http://localhost:8080 ``` +### Platform Support + +| Platform | Host Daemon | Auto-Forward | Status | +|----------|-------------|--------------|--------| +| macOS | Supported | Expected to work | Not fully confirmed | +| Linux | Supported | Expected to work | Not fully confirmed | +| Windows | Not yet supported | — | Future fix planned | + +:::note +devcontainer-bridge auto-forwarding on macOS and Linux has not been fully validated across all configurations. If you encounter issues, fall back to SSH tunneling and [report the issue](https://github.com/bradleybeddoes/devcontainer-bridge/issues). Windows host daemon support is planned for a future release. +::: + ## SSH Tunneling For one-off port forwarding or environments where `dbr` isn't available, use SSH tunneling directly: @@ -85,7 +101,7 @@ This requires SSH access to the container, which is available when connecting vi | If you use... | Recommended mechanism | |---------------|----------------------| | VS Code | Auto-detect (built-in, zero config) | -| DevContainer CLI | `dbr` (dynamic, automatic) | +| DevContainer CLI | `dbr` (dynamic, automatic) — see the [CLI guide](/getting-started/devcontainer-cli/) | | JetBrains Gateway | Gateway's built-in forwarding, or `dbr` as fallback | | Codespaces | Auto-detect (built-in to Codespaces) | | DevPod | DevPod's built-in SSH tunneling, or `dbr` | diff --git a/docs/src/content/docs/reference/troubleshooting.md b/docs/src/content/docs/reference/troubleshooting.md index 67d5d8b..8bcc8a4 100644 --- a/docs/src/content/docs/reference/troubleshooting.md +++ b/docs/src/content/docs/reference/troubleshooting.md @@ -7,6 +7,24 @@ sidebar: Solutions for common issues with the CodeForge devcontainer. If your problem isn't listed here, check [GitHub Issues](https://github.com/AnExiledDev/CodeForge/issues) or open a new one. +## Installation Issues + +**Problem: `npx codeforge-dev` fails.** + +- **Node.js not installed** — the installer requires Node.js 18+ and npm. Run `node --version` to check; install from [nodejs.org](https://nodejs.org/) if missing. +- **Network issues** — npm needs to reach the registry. Check your connection or try `npm config set registry https://registry.npmjs.org/`. +- **Permission errors** — prefer `npx --yes codeforge-dev` to avoid global install permission issues. If you need global installs, configure your npm prefix or use a Node version manager (e.g., nvm) instead of `sudo`. + +**Problem: VS Code doesn't show "Reopen in Container".** + +- **Extension not installed** — install `ms-vscode-remote.remote-containers` from the Extensions marketplace, then reload VS Code. +- **`.devcontainer/` not at repo root** — VS Code looks for `.devcontainer/` in the workspace root. If your project is inside a subfolder, open that subfolder directly. +- **VS Code version** — DevContainers requires VS Code 1.85 or later. Check **Help → About** and update if needed. + +:::note[Using a different client?] +Not using VS Code? The DevContainer CLI, JetBrains Gateway, DevPod, and Codespaces all read the same `devcontainer.json`. See the [Installation guide](/getting-started/installation/#step-2-open-in-a-devcontainer-client) for client-specific instructions. +::: + ## Container Build Failures **Problem: Container fails to build during feature installation.** @@ -15,6 +33,8 @@ Solutions for common issues with the CodeForge devcontainer. If your problem isn - If a specific feature fails, disable it temporarily by setting `"version": "none"` in `devcontainer.json`. - Check internet connectivity — most features download binaries from GitHub releases. - If hitting GitHub API rate limits during build, set `GH_TOKEN` or `GITHUB_TOKEN` as an environment variable. +- **Docker not running** — start Docker Desktop or the Docker daemon. +- **Cached partial build** — use **Dev Containers: Rebuild Container Without Cache** (VS Code) or `devcontainer up --workspace-folder . --remove-existing-container` (CLI) to start clean. **Problem: Build is slow or hangs.** @@ -130,6 +150,37 @@ Any local feature can be disabled without removing it from `devcontainer.json` b - Subsequent starts skip unchanged config files (SHA-256 comparison). - Disable steps you don't need via `.env` (e.g., `SETUP_PROJECTS=false`). See [Environment Variables — Setup Variables](./environment/#setup-variables-env). +## Docker Permission Errors (Linux) + +**Problem: `docker: permission denied` or `Cannot connect to the Docker daemon`.** + +- Add your user to the `docker` group: `sudo usermod -aG docker $USER`, then log out and back in. +- Verify with `docker ps` — it should run without `sudo`. +- If using Docker rootless mode, ensure the socket path is set correctly in VS Code settings. + +## WSL 2 Integration Issues (Windows) + +**Problem: Container fails to start, or Docker commands hang inside WSL.** + +- Open Docker Desktop → **Settings → Resources → WSL Integration** and enable integration for your WSL distro. +- Ensure WSL 2 (not WSL 1) is active: run `wsl -l -v` in PowerShell and check the VERSION column. +- Restart Docker Desktop after changing WSL settings. + +## Port Conflicts + +**Problem: The claude-dashboard or other tools fail to bind their port.** + +- CodeForge's session dashboard uses **port 7847** by default. If another service uses that port, change it in `devcontainer.json` under `forwardPorts`. +- To find what's using a port: `lsof -i :7847` (macOS/Linux) or `netstat -ano | findstr 7847` (Windows). + +## Slow Rebuilds + +**Problem: Rebuilding the container takes as long as the first build.** + +- **Use "Rebuild Container"** (not "Rebuild Without Cache") for routine rebuilds — Docker reuses cached layers for unchanged steps. +- **Prune unused images** to free disk space: `docker system prune -a` removes all unused images (confirm you don't need them first). +- **Check disk space** — Docker needs headroom for layer storage. If your disk is nearly full, builds may fail or slow down significantly. + ## How to Reset 1. **Reset runtime config** — delete `~/.claude/` and restart the container. `setup-config.sh` will redeploy all files from `.codeforge/config/`. This resets the deployed copies but preserves your `.codeforge/` source files (user modifications remain intact).