@aion0/forge 0.5.40 → 0.5.42

package/.forge/mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "forge": {
       "type": "sse",
-      "url": "http://localhost:8406/sse?workspaceId=656c9e65-9d73-4cb6-a065-60d966e1fc78"
+      "url": "http://localhost:8406/sse?workspaceId=6fc40ffc-3dfc-4e2d-bf93-c934d1996af2"
     }
   }
 }

package/CLAUDE.md

@@ -1,53 +1,95 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
 ## Project: Forge (@aion0/forge)
 
-### Scripts
+Self-hosted Vibe Coding platform — Next.js web UI + tmux-backed browser terminal + multi-agent workspace + Telegram bot + Cloudflare tunnel, wrapping Claude Code and other CLIs.
+
+Package manager is **pnpm** (pinned in `packageManager`). `better-sqlite3` and `node-pty` are native — `pnpm rebuild` after a Node upgrade.
+
+## Scripts
+
 ```bash
 # ── Start ──
-./start.sh              # production (kill old processes → build → start)
-./start.sh dev           # development (hot-reload)
-forge server start              # production via npm link/install
-forge server start --dev        # dev mode
-forge server start              # background by default, logs to ~/.forge/forge.log
-forge server start --foreground # foreground mode
-forge server stop               # stop default instance (port 8403)
-forge server stop --port 4000 --dir ~/.forge-staging  # stop specific instance
-forge server restart            # stop + start (safe for remote)
-forge server rebuild            # force rebuild
-forge server start --port 4000 --terminal-port 4001 --dir ~/.forge-staging
+./start.sh                       # production (kill old processes → build → start)
+./start.sh dev                   # development (hot-reload, FORGE_DEV=1 bypasses auth)
+forge server start               # production via npm link/install, background + logs to <data>/forge.log
+forge server start --foreground  # run in foreground
+forge server start --dev         # dev mode
+forge server stop                # stop default instance (port 8403)
+forge server stop --port 4000 --dir ~/.forge-staging   # stop specific instance
+forge server restart             # stop + start (safe for remote)
+forge server rebuild             # force rebuild .next
+forge server start --port 4000 --terminal-port 4001 --workspace-port 4002 --dir ~/.forge-staging
 forge server start --reset-terminal  # kill terminal server (loses tmux attach)
-forge --version                 # show version
-
-# ── Test ──
-./dev-test.sh            # test instance (port 4000, data ~/.forge-test)
+forge --reset-password           # reset admin password
+forge --version
 
-# ── Install ──
-./install.sh             # install from npm
-./install.sh --local     # install from local source (npm link + build)
+# ── Test instance ──
+./dev-test.sh                    # port 4000, data ~/.forge-test, hot-reload
 
-# ── Publish ──
-./publish.sh             # bump patch version, commit, tag
-./publish.sh minor       # bump minor
-./publish.sh 1.0.0       # explicit version
+# ── Install / Publish ──
+./install.sh                     # from npm
+./install.sh --local             # npm link + pnpm build from source
+./publish.sh [patch|minor|major|x.y.z]   # bump, generate RELEASE_NOTES.md, commit, tag, push, gh release
 npm login && npm publish --access public --otp=<code>
 
 # ── Monitor ──
-./check-forge-status.sh  # show process status + tmux sessions
-
-# ── CLI ──
-forge                    # help
-forge --version          # show version
-forge tcode              # show tunnel URL + session code
-forge tasks              # list tasks
-forge task <project> "prompt"  # submit task
-forge watch <id>         # live stream task output
+./check-forge-status.sh          # show process status + tmux sessions
+
+# ── Tests (no framework — custom tsx scripts) ──
+npx tsx lib/workspace/__tests__/workspace.test.ts
+npx tsx lib/workspace/__tests__/state-machine.test.ts
+npx tsx scripts/verify-usage.ts
+
+# ── CLI (talks to running server over HTTP) ──
+forge                            # help
+forge task <project> "prompt"    # submit a background task (--new for fresh session)
+forge tasks                      # list
+forge watch <id>                 # live stream task output
+forge tcode                      # tunnel URL + session code
 ```
 
-### Key Paths
-- Data: `~/.forge/` (settings, db, password, terminal-state, flows, bin)
-- npm package: `@aion0/forge`
-- GitHub: `github.com/aiwatching/forge`
+The CLI (`cli/mw.ts`) reaches the server at `http://localhost:${MW_URL port or 3000}`. Set `MW_URL` if the server is not on the default port.
+
+## Architecture
+
+### Process model
+Forge runs as **four cooperating processes**, normally launched by `bin/forge-server.mjs`:
+
+| Process | Port (default) | Responsibility |
+|---|---|---|
+| `next-server` (web UI + API) | 8403 | Next.js app — UI, REST/SSE APIs, auth |
+| `lib/terminal-standalone.ts` | 8404 | WebSocket ↔ tmux pty bridge for browser terminals |
+| `lib/workspace-standalone.ts` | 8405 (+ MCP 8406) | Workspace daemon + MCP server — **exclusive writer of workspace `state.json`** |
+| `lib/telegram-standalone.ts` | — | Telegram bot polling loop |
+
+Each forked service is spawned with a `--forge-port=<webPort>` instance tag. `forge-server.mjs`'s `cleanupOrphans()` uses this tag to kill *this* instance's stale processes and legacy untagged orphans while leaving other instances alone. When adding a new standalone, keep the tag forwarded.
+
+### Dev mode vs production mode
+- `FORGE_EXTERNAL_SERVICES=1` tells Next.js (`lib/init.ts`) **not** to spawn terminal/telegram/workspace — `forge-server.mjs` manages them. This is set automatically by `forge-server.mjs` in prod/background/dev.
+- Plain `pnpm dev` (or `./dev-test.sh`) sets it to `0` — `lib/init.ts` becomes the process supervisor and spawns the standalones itself. Use this when iterating on Next.js only.
+- `FORGE_DEV=1` (set by `./start.sh dev`) **bypasses login in `middleware.ts`** — never set in production.
+
+### Data layout (`lib/dirs.ts`)
+- `getConfigDir()` → `~/.forge/` — shared across instances, holds `bin/` (cloudflared).
+- `getDataDir()` → `FORGE_DATA_DIR` env var, or `--dir` flag, or `~/.forge/data/` — **per-instance** settings, sqlite (`workflow.db`), encrypted key, flows, logs, workspaces.
+- A one-time migration on startup moves the legacy flat `~/.forge/*` layout into `~/.forge/data/*` (also handled in `forge-server.mjs`). If touching paths, check both places.
+
+### `lib/init.ts` side effects
+First API request per Next.js worker triggers `ensureInitialized()` (guarded by a global Symbol). It migrates secrets, auto-detects CLI agents (`which claude`), installs Forge's skills into `~/.claude/skills/`, syncs `lib/help-docs/` to `<dataDir>/help/`, and starts the task runner / session watcher / pipeline scheduler. Anything you add here runs on every cold worker — keep it idempotent.
+
+### Workspace orchestration (`lib/workspace/`)
+- `orchestrator.ts` (3400 lines) is the core DAG engine; `manager.ts` is a singleton cache of orchestrators keyed by workspace ID (HMR-safe via `globalThis.__forgeOrchestrators`).
+- `persistence.ts` exports `loadWorkspace` / `listWorkspaces` etc. but **intentionally does not export `saveWorkspace`** — all mutations must go through the workspace daemon's HTTP API to avoid multi-writer races. Respect this when adding new mutators.
+- `agent-bus.ts` = inter-agent messages (notifications + tickets); `agent-worker.ts` = per-agent loop; `backends/{api,cli}-backend.ts` = API vs CLI execution; `watch-manager.ts` = autonomous file/git/command monitoring.
+
+### Settings & secrets
+`lib/settings.ts` reads/writes `<dataDir>/settings.yaml`. Fields listed in `SECRET_FIELDS` (`lib/crypto.ts`) are auto-encrypted with AES-256-GCM using `<dataDir>/.encrypt-key`. `lib/init.ts#migrateSecrets` re-encrypts any plaintext secret on startup.
+
+## Help Docs Rule
 
-### Help Docs Rule
 When adding or changing a feature, check if `lib/help-docs/` needs updating. Each file covers one module:
 - `00-overview.md` — install, start, data paths
 - `01-settings.md` — all settings fields
@@ -62,12 +104,18 @@ When adding or changing a feature, check if `lib/help-docs/` needs updating. Eac
 - `10-troubleshooting.md` — common issues
 - `11-workspace.md` — multi-agent workspace (smiths, daemon, request docs)
 - `12-usage.md` — token usage analytics and cost tracking
-If a feature change affects user-facing behavior, update the corresponding help doc in the same commit.
 
-### Architecture
-- `forge-server.mjs` starts: Next.js + terminal-standalone + telegram-standalone
-- `pnpm dev` / `start.sh dev` starts: Next.js (init.ts spawns terminal + telegram)
-- `FORGE_EXTERNAL_SERVICES=1` → init.ts skips spawning (forge-server manages them)
+If a feature change affects user-facing behavior, update the corresponding help doc in the same commit. These docs are also served to the in-app Help AI — `lib/help-docs/CLAUDE.md` is its system prompt.
+
+## Commit conventions
+
+`publish.sh` groups release notes by prefix: `feat:`, `fix:`, `perf:`, `refactor:`, `docs:`. Anything else lands in "Other". Use these prefixes for anything you want surfaced in release notes.
+
+## Key paths
+
+- Data: `~/.forge/data/` (override with `FORGE_DATA_DIR` or `--dir`)
+- npm package: `@aion0/forge`
+- GitHub: `github.com/aiwatching/forge`
 
 ## Obsidian Vault
 Location: /Users/zliu/MyDocuments/obsidian-project/Projects/Bastion

package/RELEASE_NOTES.md

@@ -1,12 +1,8 @@
-# Forge v0.5.40
+# Forge v0.5.42
 
-Released: 2026-04-14
+Released: 2026-04-23
 
-## Changes since v0.5.38
+## Changes since v0.5.41
 
-### Other
-- v0.5.39
-- add option to disable claude modification
 
-
-**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.5.38...v0.5.40
+**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.5.41...v0.5.42

package/app/api/git/route.ts

@@ -1,6 +1,6 @@
 import { NextResponse, type NextRequest } from 'next/server';
-import { execSync, exec } from 'node:child_process';
-import { existsSync, readdirSync } from 'node:fs';
+import { execSync, execFileSync, exec } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { promisify } from 'node:util';
@@ -78,23 +78,41 @@ export async function POST(req: NextRequest) {
 
   if (action === 'clone') {
     // Clone a repo into a project root
-    if (!repoUrl) return NextResponse.json({ error: 'repoUrl required' }, { status: 400 });
+    if (!repoUrl || typeof repoUrl !== 'string') {
+      return NextResponse.json({ error: 'repoUrl required' }, { status: 400 });
+    }
     const settings = loadSettings();
     const roots = (settings.projectRoots || []).map(r => r.replace(/^~/, homedir()));
-    const cloneTarget = targetDir || roots[0];
-    if (!cloneTarget) return NextResponse.json({ error: 'No project root configured' }, { status: 400 });
+    const expandedTarget = typeof targetDir === 'string' ? targetDir.replace(/^~/, homedir()) : undefined;
+    // If caller specified targetDir, it must be under a configured project root
+    if (expandedTarget && !roots.some(r => expandedTarget === r || expandedTarget.startsWith(r + '/'))) {
+      return NextResponse.json({ error: 'targetDir must be under a configured project root' }, { status: 400 });
+    }
+    const cloneTarget = expandedTarget || roots[0];
+    if (!cloneTarget) return NextResponse.json({ error: 'No project root configured — add one in Settings' }, { status: 400 });
 
     try {
-      const output = execSync(`git clone "${repoUrl}"`, {
+      if (!existsSync(cloneTarget)) mkdirSync(cloneTarget, { recursive: true });
+      // execFileSync avoids shell interpolation; GIT_TERMINAL_PROMPT=0 makes git fail fast
+      // instead of hanging for credentials when there is no TTY.
+      const output = execFileSync('git', ['clone', '--', repoUrl], {
         cwd: cloneTarget,
         encoding: 'utf-8',
-        timeout: 60000,
+        timeout: 120000,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
       });
-      // Extract cloned dir name from URL
       const repoName = repoUrl.split('/').pop()?.replace(/\.git$/, '') || 'repo';
       return NextResponse.json({ ok: true, path: join(cloneTarget, repoName), output });
     } catch (e: any) {
-      return NextResponse.json({ error: e.message }, { status: 500 });
+      // Surface git's real message (stderr) so the UI can show "Repository not found",
+      // "Authentication failed", etc. — not a bare "Command failed".
+      const stderr = (e.stderr ? e.stderr.toString() : '').trim();
+      const msg = stderr || e.message || 'git clone failed';
+      console.error('[git] clone failed:', msg);
+      // User-caused failures (bad URL, auth, already exists) → 400; infra failures → 500
+      const isUserError = /not found|authentication|could not read username|already exists|invalid|permission denied/i.test(msg);
+      return NextResponse.json({ error: msg }, { status: isUserError ? 400 : 500 });
     }
   }
 

package/bin/forge-server.mjs

@@ -108,6 +108,45 @@ if (!getArg('--dir')) {
 
 mkdirSync(DATA_DIR, { recursive: true });
 
+// ── tmux check (required for browser terminals) ──
+if (!isStop) {
+  try {
+    execSync('command -v tmux', { stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch {
+    console.error('[forge] tmux is required but was not found on PATH.');
+    console.error('[forge] Install it with one of:');
+    if (process.platform === 'darwin') {
+      console.error('    brew install tmux');
+    } else if (process.platform === 'linux') {
+      console.error('    sudo apt install -y tmux          # Debian/Ubuntu');
+      console.error('    sudo dnf install -y tmux          # Fedora/RHEL');
+      console.error('    sudo pacman -S tmux               # Arch');
+    } else {
+      console.error('    See https://github.com/tmux/tmux/wiki/Installing');
+    }
+    console.error('[forge] Then re-run: forge server start');
+    process.exit(1);
+  }
+}
+
+// ── Agent CLI check (warn-only — API-only profiles still work) ──
+if (!isStop) {
+  const has = (bin) => {
+    try { execSync(`command -v ${bin}`, { stdio: ['ignore', 'pipe', 'pipe'] }); return true; }
+    catch { return false; }
+  };
+  const hasClaude = has('claude');
+  const hasCodex = has('codex');
+  const hasAider = has('aider');
+  if (!hasClaude && !hasCodex && !hasAider) {
+    console.warn('[forge] ⚠️  No agent CLI found (claude / codex / aider).');
+    console.warn('[forge] Forge needs at least one to drive terminals, tasks, and workspace agents.');
+    console.warn('[forge] Install Claude Code:  npm install -g @anthropic-ai/claude-code');
+    console.warn('[forge] Install Codex:        https://github.com/openai/codex#installation');
+    console.warn('[forge] Or configure API-only profiles in Settings after login.');
+  }
+}
+
 // ── Load <data-dir>/.env.local ──
 const envFile = join(DATA_DIR, '.env.local');
 if (existsSync(envFile)) {

package/install.sh

@@ -7,6 +7,46 @@
 
 set -e
 
+# tmux is required for browser terminals — warn early if missing
+if ! command -v tmux >/dev/null 2>&1; then
+  echo "[forge] ⚠️  tmux not found — Forge terminals won't work without it."
+  case "$(uname -s)" in
+    Darwin)
+      echo "[forge] Install: brew install tmux"
+      if command -v brew >/dev/null 2>&1; then
+        read -r -p "[forge] Run 'brew install tmux' now? [y/N] " reply
+        case "$reply" in [yY]*) brew install tmux ;; esac
+      fi
+      ;;
+    Linux)
+      if command -v apt-get >/dev/null 2>&1; then
+        echo "[forge] Install: sudo apt install -y tmux"
+      elif command -v dnf >/dev/null 2>&1; then
+        echo "[forge] Install: sudo dnf install -y tmux"
+      elif command -v pacman >/dev/null 2>&1; then
+        echo "[forge] Install: sudo pacman -S tmux"
+      else
+        echo "[forge] Install tmux via your distro's package manager."
+      fi
+      ;;
+    *)
+      echo "[forge] See https://github.com/tmux/tmux/wiki/Installing"
+      ;;
+  esac
+  echo ""
+fi
+
+# Agent CLI check — at least one of claude / codex / aider is needed
+if ! command -v claude >/dev/null 2>&1 \
+   && ! command -v codex >/dev/null 2>&1 \
+   && ! command -v aider >/dev/null 2>&1; then
+  echo "[forge] ⚠️  No agent CLI found (claude / codex / aider)."
+  echo "[forge] Install Claude Code:  npm install -g @anthropic-ai/claude-code"
+  echo "[forge] Install Codex:        https://github.com/openai/codex#installation"
+  echo "[forge] Or configure API-only profiles in Settings after login."
+  echo ""
+fi
+
 if [ "$1" = "local" ] || [ "$1" = "--local" ]; then
   echo "[forge] Installing from local source..."
   npm uninstall -g @aion0/forge 2>/dev/null || true

package/next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/dev/types/routes.d.ts";
+import "./.next/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aion0/forge",
-  "version": "0.5.40",
+  "version": "0.5.42",
   "description": "Unified AI workflow platform — multi-model task orchestration, persistent sessions, web terminal, remote access",
   "type": "module",
   "scripts": {

package/start.sh

@@ -24,6 +24,29 @@ export PORT=${PORT:-8403}
 export TERMINAL_PORT=${TERMINAL_PORT:-8404}
 export WORKSPACE_PORT=${WORKSPACE_PORT:-8405}
 
+# pnpm is the pinned package manager (see package.json#packageManager).
+# Try corepack first (ships with Node 16.9+), then fall back to a prompt.
+if ! command -v pnpm >/dev/null 2>&1; then
+  if command -v corepack >/dev/null 2>&1; then
+    echo "[forge] pnpm not found — enabling via corepack..."
+    corepack enable 2>/dev/null || true
+    corepack prepare pnpm@latest --activate 2>/dev/null || true
+  fi
+fi
+if ! command -v pnpm >/dev/null 2>&1; then
+  echo "[forge] pnpm is required but was not found on PATH."
+  echo "[forge] Install it with:"
+  echo "    npm install -g pnpm"
+  echo "[forge] Then re-run: ./start.sh ${1:-}"
+  exit 1
+fi
+
+# Install dependencies if node_modules is missing or the next binary isn't built
+if [ ! -x node_modules/.bin/next ]; then
+  echo "[forge] node_modules missing — running pnpm install..."
+  pnpm install || exit 1
+fi
+
 if [ "$1" = "dev" ]; then
   export FORGE_DEV=1
   pnpm dev

package/.forge/agent-context.json

@@ -1,6 +0,0 @@
-{
-  "workspaceId": "656c9e65-9d73-4cb6-a065-60d966e1fc78",
-  "agentId": "engineer-1774920478256",
-  "agentLabel": "Engineer",
-  "forgePort": 8403
-}