vibe-forge 0.1.0 → 0.3.0

package/docs/TODO.md

@@ -0,0 +1,65 @@
+# Vibe Forge - Future Improvements
+
+This document tracks issues identified during code reviews that are deferred for future sessions.
+
+## Security (From Aegis Review - Round 2)
+
+### Medium Priority
+- **M-1: eval() of external data in load_agents_from_json()**
+  - File: `bin/lib/config.sh` line 95
+  - Issue: If agents.json is compromised, malicious agent names could execute shell commands via `eval "$agent_data"`
+  - Fix: Add input validation in Node.js script to reject agent names containing shell metacharacters
+
+### Low Priority
+- **L-1: Windows Terminal command escaping**
+  - File: `bin/forge-spawn.sh` lines 55-57
+  - Issue: `$display_name` and `$FORGE_ROOT` not escaped for nested shell invocation
+  - Fix: Use `printf %q` for proper escaping
+
+- **L-2: Terminal escape sequences in task parsing**
+  - File: `bin/forge-daemon.sh` lines 147-149
+  - Issue: ANSI escape sequences in task files could affect terminal
+  - Fix: Add `| tr -d '\033'` to strip escape sequences
+
+- **L-3: Workflow version injection**
+  - File: `.github/workflows/publish.yml` lines 32-33
+  - Issue: Version input not validated before use in npm command
+  - Fix: Add semver regex validation
+
+## Architecture (From Sage Review - Round 2)
+
+### P1 Priority
+- **sed -i incompatibility in forge-setup.sh**
+  - Lines: 205, 249, 291, 380, 381, 384, 388
+  - Issue: macOS/BSD sed requires `sed -i ''` but script uses `sed -i`
+  - Fix: Add platform detection or create `sed_inplace()` helper
+
+- **Silent error suppression for JSON loading**
+  - Files: `bin/forge.sh` line 44, `bin/forge-spawn.sh` line 34
+  - Issue: `2>/dev/null || true` silently ignores JSON parsing errors
+  - Fix: Log warning when fallback is used
+
+- **Inconsistent exit codes**
+  - Issue: All errors exit with code 1, no differentiation
+  - Fix: Define exit code constants in `constants.sh`
+
+### P2 Priority
+- **Hardcoded agent list in cmd_help()**
+  - File: `bin/forge.sh` lines 253-260
+  - Fix: Generate dynamically using `show_available_agents()`
+
+- **Raw echo -e instead of log_* functions**
+  - File: `bin/forge-setup.sh` (multiple lines)
+  - Fix: Replace with appropriate `log_*` calls
+
+- **Duplicate color definitions in cli.js**
+  - File: `bin/cli.js` lines 24-31
+  - Fix: Document as intentional or extract to shared config
+
+## Testing (From Crucible Review - Round 2)
+
+### Low Priority Gaps
+- `show_available_agents()` not tested
+- `setup_windows_env()` not tested (hard to test in CI)
+- `colors.sh` log functions not tested (display-only)
+- CLI `init`/`update` commands not tested (side effects)

package/docs/npm-publishing.md

@@ -0,0 +1,95 @@
+# npm Publishing with OIDC Trusted Publishing
+
+This document explains how Vibe Forge publishes to npm using GitHub Actions OIDC trusted publishing - no npm tokens required.
+
+## Overview
+
+npm's [trusted publishing](https://docs.npmjs.com/trusted-publishers/) uses OpenID Connect (OIDC) to authenticate GitHub Actions workflows directly with npm. This eliminates the need to store npm tokens as secrets.
+
+## Requirements
+
+1. **npm CLI v11.5.1+** - OIDC support was added in npm 11.5.1
+2. **Public GitHub repository** - Provenance attestation only works with public repos
+3. **Trusted Publisher configured on npmjs.com** - Links your package to your GitHub repo
+
+## Setup
+
+### 1. Configure Trusted Publisher on npm
+
+1. Go to https://www.npmjs.com/package/vibe-forge/access
+2. Under "Trusted Publishers", add a new publisher:
+   - **Publisher**: GitHub Actions
+   - **Organization/user**: SpasticPalate
+   - **Repository**: vibe-forge
+   - **Workflow filename**: publish.yml
+   - **Environment name**: (leave empty)
+
+### 2. GitHub Actions Workflow
+
+The workflow requires specific permissions and npm version:
+
+```yaml
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write  # Required for OIDC token generation
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      # npm 11.5.1+ required for OIDC
+      - run: npm install -g npm@latest
+
+      - run: npm publish --provenance --access public
+```
+
+Key points:
+- `id-token: write` permission enables OIDC token generation
+- `--provenance` flag enables signed provenance attestation
+- No `NODE_AUTH_TOKEN` or `NPM_TOKEN` needed
+
+## Troubleshooting
+
+### "Access token expired or revoked" with E404
+
+**Cause**: npm CLI version is too old (< 11.5.1)
+
+**Fix**: Add `npm install -g npm@latest` before publishing
+
+### "Unsupported GitHub Actions source repository visibility: private"
+
+**Cause**: Provenance attestation only works with public repositories
+
+**Fix**: Either make the repo public, or remove `--provenance` and use a granular npm token instead
+
+### "ENEEDAUTH - need auth"
+
+**Cause**: OIDC token not being generated/used
+
+**Fix**: Ensure `id-token: write` permission is set on the job
+
+### 404 on publish despite correct setup
+
+**Cause**: Trusted Publisher configuration doesn't match workflow
+
+**Fix**: Verify on npmjs.com that:
+- Organization/user matches exactly (case-sensitive)
+- Repository name matches exactly
+- Workflow filename matches exactly (e.g., `publish.yml`)
+
+## Benefits
+
+- **No secrets to manage** - No npm tokens to rotate or accidentally expose
+- **Provenance attestation** - Packages are cryptographically signed with build info
+- **Audit trail** - Provenance is published to Sigstore transparency log
+
+## References
+
+- [npm Trusted Publishers](https://docs.npmjs.com/trusted-publishers/)
+- [npm Provenance](https://docs.npmjs.com/generating-provenance-statements/)
+- [GitHub: npm trusted publishing GA](https://github.blog/changelog/2025-07-31-npm-trusted-publishing-with-oidc-is-generally-available/)

package/docs/security.md

@@ -0,0 +1,144 @@
+# Vibe Forge Security Documentation
+
+This document explains security considerations and intentional design decisions in Vibe Forge.
+
+## The `--dangerously-skip-permissions` Flag
+
+### What It Does
+
+When starting agents, Vibe Forge uses Claude Code's `--dangerously-skip-permissions` flag:
+
+```bash
+claude --dangerously-skip-permissions --system-prompt "$system_prompt" "startup"
+```
+
+This flag disables Claude Code's permission prompts for file operations, command execution, and other actions that would normally require user confirmation.
+
+### Why We Use It
+
+Vibe Forge is designed for **terminal-native vibe coding** - a workflow where you launch multiple AI agents that work autonomously on your codebase. The typical workflow involves:
+
+1. Starting a Planning Hub that coordinates work
+2. Spawning worker agents (frontend, backend, testing, etc.) in separate terminals
+3. Agents working autonomously on assigned tasks
+4. Human review at defined checkpoints
+
+With permission prompts enabled, each agent would constantly interrupt for confirmation, breaking the autonomous workflow that makes Vibe Forge effective.
+
+### Security Mitigations
+
+We implement several security measures to offset the risks:
+
+#### 1. Agent Whitelist Validation
+
+All agent names go through strict whitelist validation before execution:
+
+```bash
+# bin/lib/constants.sh
+VALID_AGENTS=("anvil" "furnace" "crucible" ...)
+
+# bin/lib/agents.sh
+resolve_agent() {
+    local canonical="${AGENT_ALIASES[$normalized]:-}"
+    if [[ -n "$canonical" ]]; then
+        echo "$canonical"
+        return 0
+    fi
+    return 1  # Reject unknown agents
+}
+```
+
+This prevents command injection through agent names.
+
+#### 2. Path Traversal Protection
+
+Personality file paths are validated to ensure they remain within the expected directory:
+
+```bash
+get_agent_personality_path() {
+    local real_path=$(cd "$(dirname "$personality_path")" && pwd)/$(basename "$personality_path")
+    local agents_dir=$(cd "$forge_root/agents" && pwd)
+
+    if [[ "$real_path" != "$agents_dir"/* ]]; then
+        echo "Security error: Path traversal detected" >&2
+        return 1
+    fi
+}
+```
+
+#### 3. Safe JSON Parsing
+
+We use Node.js for JSON parsing instead of `grep`/`cut` which could be vulnerable to injection:
+
+```bash
+json_get_string() {
+    node -e "
+        const fs = require('fs');
+        const data = JSON.parse(fs.readFileSync('$file', 'utf8'));
+        if (data['$key'] !== undefined) console.log(String(data['$key']));
+    "
+}
+```
+
+#### 4. Daemon Security
+
+The background daemon includes multiple protections:
+
+- **Symlink protection**: Skips symlinks to prevent symlink attacks
+- **Path validation**: Verifies destinations are within FORGE_ROOT
+- **Atomic operations**: Uses temp files + move for safe writes
+- **Lock files**: Prevents multiple daemon instances
+- **Log rotation**: Bounded log growth prevents disk exhaustion
+
+### Risks to Be Aware Of
+
+Even with mitigations, understand these risks:
+
+1. **AI agents can modify any file** in your project without confirmation
+2. **AI agents can execute any command** without confirmation
+3. **Malicious prompts** could potentially be injected if context files are compromised
+4. **Network access** is unrestricted - agents could make API calls
+
+### Recommendations
+
+1. **Use in development environments only** - Don't run on production systems
+2. **Use with version control** - Git makes it easy to review and revert changes
+3. **Review at checkpoints** - Check agent work during task transitions
+4. **Understand the personality files** - They define agent behavior
+5. **Keep project context secure** - Don't include secrets in context files
+6. **Run in isolated environments** - Consider containers for sensitive projects
+
+### Alternative: Manual Approval Mode
+
+If you prefer permission prompts, you can modify the agent startup in `bin/forge.sh`:
+
+```bash
+# Change this:
+claude --dangerously-skip-permissions --system-prompt "$system_prompt" "startup"
+
+# To this (removes the flag):
+claude --system-prompt "$system_prompt" "startup"
+```
+
+Note: This will significantly impact the autonomous workflow.
+
+## Reporting Security Issues
+
+If you discover a security vulnerability in Vibe Forge:
+
+1. **Do not open a public issue**
+2. Email security concerns to the maintainers
+3. Include steps to reproduce
+4. Allow time for a fix before public disclosure
+
+## Security Checklist for Contributors
+
+When contributing to Vibe Forge:
+
+- [ ] Never pass user input directly to shell commands
+- [ ] Always validate agent names against the whitelist
+- [ ] Use safe JSON parsing (Node.js, not grep/cut)
+- [ ] Validate file paths don't traverse outside expected directories
+- [ ] Use atomic file operations where race conditions are possible
+- [ ] Add tests for security-sensitive functions
+- [ ] Document any new security considerations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-forge",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Multi-agent development orchestration system for terminal-native vibe coding",
   "keywords": [
     "vibe-coding",
@@ -31,8 +31,17 @@
     "agents/",
     "config/",
     "context/",
-    "tasks/"
+    "tasks/",
+    ".claude/",
+    "docs/"
   ],
+  "scripts": {
+    "test": "jest tests/js/",
+    "test:js": "jest tests/js/"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
   "engines": {
     "node": ">=16.0.0"
   }