codeforge-dev 1.4.0

package/.devcontainer/features/README.md

@@ -0,0 +1,113 @@
+# CodeForge DevContainer Features
+
+This directory contains DevContainer Features for AI coding agent environments. These features follow the [DevContainer Features specification](https://containers.dev/implementors/features/) and can be published to OCI registries for distribution.
+
+## Available Features
+
+### mcp-qdrant
+Vector database integration via Qdrant MCP server. Enables semantic search, embeddings management, and RAG workflows.
+
+**Status**: ✅ Complete
+**Documentation**: [mcp-qdrant/README.md](./mcp-qdrant/README.md)
+
+## Feature Structure
+
+Each feature follows this structure:
+
+```
+feature-name/
+├── devcontainer-feature.json   # Feature metadata and options
+├── install.sh                  # Installation script (executable)
+└── README.md                   # Feature documentation
+```
+
+## Development Workflow
+
+### Creating a New Feature
+
+1. **Create directory**: `mkdir features/feature-name`
+2. **Add metadata**: Create `devcontainer-feature.json`
+3. **Write installer**: Create `install.sh` (make executable)
+4. **Document**: Create `README.md`
+5. **Test locally**: Reference in devcontainer.json
+
+### Local Testing
+
+To test a feature locally before publishing:
+
+```json
+{
+  "features": {
+    "./features/feature-name": {
+      "option1": "value1"
+    }
+  }
+}
+```
+
+### Publishing Features
+
+Features will be published to GitHub Container Registry (GHCR):
+
+```
+ghcr.io/yourorg/codeforge-features/feature-name:1
+```
+
+**Publishing workflow** (future):
+- Push to main branch
+- GitHub Actions builds and publishes
+- Tags create versioned releases
+
+## Feature Guidelines
+
+### Granularity
+- **One feature = One tool/service**
+- Bundle only if tools are always used together
+- See project README for guidance
+
+### Options
+- Use clear, descriptive option names
+- Provide sensible defaults
+- Support environment variable substitution: `"${env:VAR}"`
+- Document all options in README
+
+### Installation
+- Must be idempotent (safe to run multiple times)
+- Check if already installed before installing
+- Use appropriate user (not always root)
+- Clean up on failure
+
+### Configuration
+- Generate necessary config files
+- Provide helper scripts for manual setup
+- Print clear installation summary
+- Show next steps to user
+
+## Migration from Modules
+
+CodeForge modules are being converted to DevContainer Features:
+
+| Old Module | New Feature | Status |
+|-----------|-------------|---------|
+| mcp_qdrant | mcp-qdrant | ✅ Complete |
+| mcp_browser | mcp-browser | 🔜 Planned |
+| mcp_sourcerer | mcp-sourcerer | 🔜 Planned |
+| mcp_reasoner | mcp-reasoner | 🔜 Planned |
+| mcp_obsidian | mcp-obsidian | 🔜 Planned |
+| mcp_code_runner | mcp-code-runner | 🔜 Planned |
+
+## Resources
+
+- [DevContainer Features Specification](https://containers.dev/implementors/features/)
+- [Feature Authoring Guide](https://containers.dev/guide/author-a-feature)
+- [Feature Best Practices](https://containers.dev/guide/feature-authoring-best-practices)
+- [CodeForge Documentation](../../README.md)
+
+## Contributing
+
+Features are part of the CodeForge project. See main repository for contribution guidelines.
+
+---
+
+**Status**: Active Development
+**Last Updated**: 2025-11-11

package/.devcontainer/features/agent-browser/README.md

@@ -0,0 +1,65 @@
+# agent-browser
+
+Headless browser automation CLI for AI agents from [Vercel Labs](https://github.com/vercel-labs/agent-browser).
+
+## Features
+
+- Accessibility tree snapshots for AI navigation
+- Screenshots and PDF capture
+- Element interaction (click, fill, select)
+- Cookie and localStorage management
+- Network interception
+
+## Usage
+
+```bash
+# Basic workflow
+agent-browser open https://example.com
+agent-browser snapshot          # Get accessibility tree
+agent-browser click @e2         # Click element by reference
+agent-browser fill @e3 "text"   # Fill input
+agent-browser screenshot page.png
+agent-browser close
+
+# Cookie management (for authenticated sessions)
+agent-browser cookie set "session=abc123; domain=.example.com"
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `version` | `latest` | npm package version |
+| `username` | `automatic` | Container user |
+
+## WSL/Devcontainer Usage
+
+Two modes work in containerized environments:
+
+### Headless Mode (Default)
+
+Uses bundled Chromium in the container—no display needed. Works out of the box:
+
+```bash
+agent-browser open https://example.com
+agent-browser snapshot
+agent-browser close
+```
+
+### Host Chrome Connection
+
+Connect to Chrome running on your host machine via CDP (Chrome DevTools Protocol):
+
+1. Start Chrome on host with remote debugging:
+   ```bash
+   chrome --remote-debugging-port=9222
+   # or on macOS:
+   /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
+   ```
+
+2. Connect from container:
+   ```bash
+   agent-browser connect 9222
+   ```
+
+This is useful when the container's bundled Chromium is insufficient (e.g., specific browser extensions needed).

package/.devcontainer/features/agent-browser/devcontainer-feature.json

@@ -0,0 +1,23 @@
+{
+  "id": "agent-browser",
+  "version": "1.0.0",
+  "name": "agent-browser",
+  "description": "Headless browser automation CLI for AI agents (Vercel Labs)",
+  "documentationURL": "https://github.com/vercel-labs/agent-browser",
+  "options": {
+    "version": {
+      "type": "string",
+      "description": "agent-browser npm package version",
+      "default": "latest"
+    },
+    "username": {
+      "type": "string",
+      "description": "Container user to install for",
+      "default": "automatic"
+    }
+  },
+  "installsAfter": [
+    "ghcr.io/devcontainers/features/common-utils:2",
+    "ghcr.io/devcontainers/features/node:1"
+  ]
+}

package/.devcontainer/features/agent-browser/install.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+set -euo pipefail
+
+VERSION="${VERSION:-latest}"
+USERNAME="${USERNAME:-automatic}"
+
+# Set headless as default for containers (bundled Chromium, no display needed)
+export AGENT_BROWSER_HEADLESS=true
+
+echo "[agent-browser] Starting installation..."
+echo "[agent-browser] Version: ${VERSION}"
+
+# Source nvm if available
+if [ -f /usr/local/share/nvm/nvm.sh ]; then
+    source /usr/local/share/nvm/nvm.sh
+fi
+
+# Validate npm is available
+if ! command -v npm &>/dev/null; then
+    echo "[agent-browser] ERROR: npm not available"
+    echo "  Ensure node feature is installed first"
+    exit 1
+fi
+
+# Detect user
+if [ "${USERNAME}" = "auto" ] || [ "${USERNAME}" = "automatic" ]; then
+    if [ -n "${_REMOTE_USER:-}" ]; then
+        USERNAME="${_REMOTE_USER}"
+    elif getent passwd vscode >/dev/null 2>&1; then
+        USERNAME="vscode"
+    elif getent passwd node >/dev/null 2>&1; then
+        USERNAME="node"
+    elif getent passwd codespace >/dev/null 2>&1; then
+        USERNAME="codespace"
+    else
+        USERNAME="root"
+    fi
+fi
+
+echo "[agent-browser] Installing for user: ${USERNAME}"
+
+# Install via npm
+if [ "${VERSION}" = "latest" ]; then
+    NPM_PACKAGE="agent-browser"
+else
+    NPM_PACKAGE="agent-browser@${VERSION}"
+fi
+
+npm install -g "${NPM_PACKAGE}" 2>/dev/null || {
+    echo "[agent-browser] WARNING: Global install failed, trying user install"
+    su - "${USERNAME}" -c "npm install -g ${NPM_PACKAGE}" 2>/dev/null || true
+}
+
+# Download Chromium and install system dependencies
+echo "[agent-browser] Installing Chromium and system dependencies..."
+agent-browser install --with-deps 2>/dev/null || {
+    echo "[agent-browser] WARNING: Chromium install with deps failed, trying without --with-deps"
+    agent-browser install 2>/dev/null || true
+}
+
+# Install Playwright browsers and dependencies
+echo "[agent-browser] Installing Playwright browsers..."
+npx playwright install --with-deps 2>/dev/null || {
+    echo "[agent-browser] WARNING: Playwright install with deps failed, trying without --with-deps"
+    npx playwright install 2>/dev/null || true
+}
+
+echo "[agent-browser] Installed: $(agent-browser --version 2>/dev/null || echo 'unknown')"
+echo "[agent-browser] Installation complete"
+echo ""
+echo "Usage:"
+echo "  agent-browser open <url>     # Open a page"
+echo "  agent-browser snapshot       # Get accessibility tree"
+echo "  agent-browser screenshot     # Capture screenshot"
+echo "  agent-browser close          # Close browser"
+echo ""
+echo "Host Chrome connection (if container browser insufficient):"
+echo "  # Start Chrome on host with: chrome --remote-debugging-port=9222"
+echo "  agent-browser connect 9222"

package/.devcontainer/features/ast-grep/README.md

@@ -0,0 +1,24 @@
+# ast-grep (Feature)
+
+Installs [ast-grep](https://ast-grep.github.io/) CLI via npm for structural code search, lint, and rewriting using AST matching.
+
+## Usage
+
+```json
+{
+  "features": {
+    "./features/ast-grep": {}
+  }
+}
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `version` | string | `latest` | @ast-grep/cli npm package version |
+| `username` | string | `automatic` | Container user to install for |
+
+## Dependencies
+
+Requires Node.js: `ghcr.io/devcontainers/features/node:1`

package/.devcontainer/features/ast-grep/devcontainer-feature.json

@@ -0,0 +1,24 @@
+{
+  "id": "ast-grep",
+  "version": "1.0.0",
+  "name": "ast-grep",
+  "description": "Installs ast-grep CLI for structural code search, lint, and rewriting using AST matching",
+  "maintainer": "AnExiledDev",
+  "documentationURL": "https://ast-grep.github.io/",
+  "options": {
+    "version": {
+      "type": "string",
+      "description": "@ast-grep/cli npm package version (e.g., 'latest', '0.31.1')",
+      "default": "latest"
+    },
+    "username": {
+      "type": "string",
+      "description": "Container user to install for",
+      "default": "automatic"
+    }
+  },
+  "installsAfter": [
+    "ghcr.io/devcontainers/features/common-utils:2",
+    "ghcr.io/devcontainers/features/node:1"
+  ]
+}

package/.devcontainer/features/ast-grep/install.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+set -euo pipefail
+
+VERSION="${VERSION:-latest}"
+USERNAME="${USERNAME:-automatic}"
+
+echo "[ast-grep] Starting installation..."
+echo "[ast-grep] Version: ${VERSION}"
+
+# Source nvm if available
+if [ -f /usr/local/share/nvm/nvm.sh ]; then
+    source /usr/local/share/nvm/nvm.sh
+fi
+
+# Validate npm is available
+if ! command -v npm &>/dev/null; then
+    echo "[ast-grep] ERROR: npm not available"
+    echo "  Ensure node feature is installed first"
+    exit 1
+fi
+
+# Detect user
+if [ "${USERNAME}" = "auto" ] || [ "${USERNAME}" = "automatic" ]; then
+    if [ -n "${_REMOTE_USER:-}" ]; then
+        USERNAME="${_REMOTE_USER}"
+    elif getent passwd vscode >/dev/null 2>&1; then
+        USERNAME="vscode"
+    elif getent passwd node >/dev/null 2>&1; then
+        USERNAME="node"
+    elif getent passwd codespace >/dev/null 2>&1; then
+        USERNAME="codespace"
+    else
+        USERNAME="root"
+    fi
+fi
+
+echo "[ast-grep] Installing for user: ${USERNAME}"
+
+# Install via npm
+if [ "${VERSION}" = "latest" ]; then
+    NPM_PACKAGE="@ast-grep/cli"
+else
+    NPM_PACKAGE="@ast-grep/cli@${VERSION}"
+fi
+
+npm install -g "${NPM_PACKAGE}" 2>/dev/null || {
+    echo "[ast-grep] WARNING: Global install failed, trying user install"
+    su - "${USERNAME}" -c "npm install -g ${NPM_PACKAGE}" 2>/dev/null || true
+}
+
+echo "[ast-grep] Installed: $(ast-grep --version 2>/dev/null || echo 'unknown')"

package/.devcontainer/features/ccstatusline/README.md

@@ -0,0 +1,296 @@
+# ccstatusline Feature
+
+A DevContainer Feature that installs and configures [ccstatusline](https://github.com/sirmalloc/ccstatusline) - a compact powerline status line for Claude Code with essential metrics.
+
+## Quick Start
+
+```json
+{
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {},
+    "ghcr.io/devcontainers/features/common-utils:2": {},
+    "./features/ccstatusline": {}
+  }
+}
+```
+
+**Note:** This feature requires Node.js and common-utils features to be installed first.
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `username` | string | `automatic` | User to install for (auto-detects: vscode, node, codespace, or root) |
+
+## Display Format
+
+### Line 1: Core Metrics
+```
+Model: Opus 4.1 ▶ Ctx: 58.5k ▶ main ▶ (+19, -2) ▶ v1.0.86
+```
+
+- **Model** (maroon bg, white text, bold): Current AI model
+- **Context** (gold bg, black text, bold): Context window size
+- **Git Branch** (blue bg, white text): Active branch
+- **Git Changes** (pink bg, white text): Lines added/removed
+- **Version** (light pink bg, white text): Claude Code version
+
+### Line 2: Location & Cost
+```
+cwd: .../workspaces/project ▶ Cost: $0.39
+```
+
+- **Working Directory** (gold bg, black text): Current directory path
+- **Session Cost** (gold bg, black text, bold): Total session cost in USD
+
+All widgets connected with powerline arrows for a seamless, professional appearance.
+
+## What This Feature Installs
+
+- **ccstatusline npm package**: Installed on-demand via `npx` (not globally)
+- **Configuration file**: `~/.config/ccstatusline/settings.json` with powerline theme
+- **Claude Code integration**: Automatically updates `.claude/settings.json`
+- **Disk Usage**: Minimal (~2MB when cached by npx)
+
+## Requirements
+
+This feature has explicit dependencies that **must** be installed first:
+
+```json
+{
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {},
+    "ghcr.io/devcontainers/features/common-utils:2": {},
+    "./features/ccstatusline": {}
+  }
+}
+```
+
+**Required:**
+- **Node.js + npm/npx**: For running ccstatusline package
+- **jq**: For safe JSON generation (from common-utils)
+
+The feature will validate these are present and exit with an error if missing.
+
+## Features
+
+- ✅ **Powerline Mode**: Seamless arrow separators between widgets
+- ✅ **Compact Layout**: 2 clean lines with essential metrics
+- ✅ **7 Key Widgets**: Model, context, git status, version, directory, cost
+- ✅ **Vibrant Colors**: High-contrast truecolor (24-bit hex) optimized for dark terminals
+- ✅ **Automatic Integration**: Auto-configures `.claude/settings.json`
+- ✅ **Idempotent**: Safe to run multiple times
+- ✅ **Multi-user**: Automatically detects container user
+
+## Post-Installation Steps
+
+### ✅ Configuration is Automatic
+
+This feature automatically:
+1. Creates `~/.config/ccstatusline/settings.json` with powerline configuration
+2. Configures `.claude/settings.json` to use ccstatusline
+
+**No manual steps required!**
+
+### Verify It Worked
+
+**1. Check configuration:**
+```bash
+cat ~/.config/ccstatusline/settings.json | jq .
+```
+
+**2. Test manually:**
+```bash
+echo '{"model":{"display_name":"Test Model"}}' | npx -y ccstatusline@latest
+```
+
+You should see formatted output with powerline styling.
+
+**3. Check Claude Code integration:**
+```bash
+cat /workspaces/.claude/settings.json | jq '.statusLine'
+```
+
+Should show:
+```json
+{
+  "type": "command",
+  "command": "npx -y ccstatusline@latest"
+}
+```
+
+## Customization
+
+### Modify Configuration After Installation
+
+Edit the configuration file:
+```bash
+vim ~/.config/ccstatusline/settings.json
+```
+
+**Important:** Changes to runtime config are lost on container rebuild. To persist changes, modify the feature's `install.sh` file where the JSON is generated (lines 60-80).
+
+### Widget Configuration Format
+
+Widgets are configured in the `lines` array:
+
+```json
+{
+  "id": "unique-id",
+  "type": "widget-type",
+  "color": "#FFFFFF",     // Foreground (hex)
+  "bgColor": "#000000",   // Background (hex)
+  "bold": true            // Optional: bold text
+}
+```
+
+### Available Widget Types
+
+**Session Metrics:**
+- `model` - Current AI model
+- `session-clock` - Session elapsed time
+- `session-cost` - Total session cost (USD)
+- `block-timer` - Block execution time
+- `output-style` - Current output style
+
+**Context Tracking:**
+- `context-length` - Context window size
+- `context-percentage` - Context usage percentage
+- `context-percentage-usable` - Usable context percentage
+
+**Token Metrics:**
+- `tokens-input` - Input tokens
+- `tokens-output` - Output tokens
+- `tokens-cached` - Cached tokens
+- `tokens-total` - Total tokens
+
+**Git Integration:**
+- `git-branch` - Current branch
+- `git-changes` - Lines added/removed
+- `git-worktree` - Git worktree info
+
+**Other:**
+- `cwd` - Current working directory
+- `version` - Claude Code version
+- `custom-text` - Static text
+- `custom-command` - Command output
+
+### Color Scheme
+
+The default powerline theme uses:
+
+- **Maroon** (`#9B4F5C`): Model name - bold, authoritative
+- **Gold** (`#FFD700`): Context, directory, cost - attention-grabbing
+- **Blue** (`#4A90E2`): Git branch - clear, standard
+- **Pink/Magenta** (`#D888C8`, `#E8A8C8`): Git changes and version - distinctive
+- **White** (`#FFFFFF`): Text on dark backgrounds
+- **Black** (`#1E1E1E`): Text on gold background
+
+All colors selected for excellent readability on dark terminal themes with proper contrast ratios.
+
+## Troubleshooting
+
+### Status Line Doesn't Appear
+
+**Symptom:** Claude Code starts but no status line visible
+
+**Solution:**
+```bash
+# 1. Verify config exists
+cat ~/.config/ccstatusline/settings.json | jq .
+
+# 2. Test manually
+echo '{"model":{"display_name":"Test"}}' | npx -y ccstatusline@latest
+
+# 3. Check Claude Code settings
+cat /workspaces/.claude/settings.json | jq '.statusLine'
+
+# 4. Manually run auto-config if needed
+configure-ccstatusline-auto
+
+# 5. Restart Claude Code
+```
+
+### Installation Fails: "npm/npx not available"
+
+**Cause:** Node.js feature not installed first
+
+**Solution:**
+```json
+{
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {},
+    "./features/ccstatusline": {}
+  }
+}
+```
+
+### Installation Fails: "jq not available"
+
+**Cause:** common-utils feature not installed
+
+**Solution:**
+```json
+{
+  "features": {
+    "ghcr.io/devcontainers/features/common-utils:2": {},
+    "./features/ccstatusline": {}
+  }
+}
+```
+
+### Display Issues (Broken Arrows, Colors)
+
+**Cause:** Terminal doesn't support powerline fonts or truecolor
+
+**Solutions:**
+1. Install powerline fonts in your terminal
+2. Check terminal supports 24-bit color (truecolor)
+3. For VS Code: Ensure using a powerline-compatible font like "Cascadia Code PL" or "MesloLGS NF"
+
+### Performance Issues (Slow Refresh)
+
+**Cause:** `npx` downloads package on each run
+
+**Solution:** Install globally for faster execution:
+```bash
+npm install -g ccstatusline@latest
+```
+
+Then update `.claude/settings.json`:
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "ccstatusline"
+  }
+}
+```
+
+### Permission Errors
+
+**Symptom:** "Permission denied" on config file
+
+**Solution:**
+```bash
+# Check ownership
+ls -la ~/.config/ccstatusline/settings.json
+
+# Fix if needed (replace 'vscode' with your username)
+sudo chown -R vscode:vscode ~/.config/ccstatusline/
+```
+
+## Resources
+
+- [ccstatusline GitHub](https://github.com/sirmalloc/ccstatusline)
+- [ccstatusline npm package](https://www.npmjs.com/package/ccstatusline)
+- [Claude Code Documentation](https://docs.claude.com/en/docs/claude-code/statusline)
+- [Powerline Fonts](https://github.com/powerline/fonts)
+
+## License
+
+This feature configuration is MIT licensed. The ccstatusline package has its own license (see npm package).
+
+---
+
+**Part of your DevContainer Features collection**

package/.devcontainer/features/ccstatusline/devcontainer-feature.json

@@ -0,0 +1,19 @@
+{
+  "id": "ccstatusline",
+  "version": "1.0.0",
+  "name": "ccstatusline",
+  "description": "Compact powerline status line for Claude Code with essential metrics",
+  "maintainer": "AnExiledDev",
+  "documentationURL": "https://github.com/sirmalloc/ccstatusline",
+  "options": {
+    "username": {
+      "type": "string",
+      "description": "Container user to install for",
+      "default": "automatic"
+    }
+  },
+  "installsAfter": [
+    "ghcr.io/devcontainers/features/node:1",
+    "ghcr.io/devcontainers/features/common-utils:2"
+  ]
+}