@ipul-labs/forge 1.13.0

package/README.md

@@ -0,0 +1,273 @@
+# Forge by iPuL
+
+AI-powered code change & deploy control panel. Connect an issue tracker, let Claude propose a fix, review the diff, approve — and Forge creates the branch, commits the changes, opens the MR/PR, and monitors the CI pipeline.
+
+Built on: Claude Code CLI · GitLab / GitHub / Azure DevOps · Kubernetes
+
+---
+
+## Why Forge
+
+**The CI refinement loop is the thing.** Every other AI coding tool hands off after the PR is open. Forge keeps going: when your pipeline fails, it grabs the last 150 lines of the failed job log, feeds them back to Claude with the original fix context, generates a targeted patch, and commits it to the branch — automatically. No human has to read the stack trace, translate it into a prompt, and paste it somewhere. The loop closes itself.
+
+Everything else fills in the gaps that matter for real teams:
+
+- **No per-token cost** — Claude runs via the `claude` CLI using your existing Claude subscription, not API credits. Heavy use doesn't trigger a bill.
+- **Multi-provider** — GitLab, GitHub, and Azure DevOps are all first-class. Switch providers with a single env var; all normalized data shapes stay the same.
+- **Self-hosted** — your code never leaves your infrastructure. The backend runs wherever you deploy it; AI calls go to Anthropic (or a local gateway via OpenClaw).
+- **Two-pass analysis keeps context focused** — Claude first identifies the 6 most relevant files, then reads only those when proposing the fix. This produces sharper diffs than dumping the whole repo into one prompt.
+
+---
+
+## How it works
+
+1. **Connect** — enter your Forge token to authenticate
+2. **Pick an issue** — Forge loads open issues from your project
+3. **Analyze** — Claude reads the repo file tree, identifies relevant files, and proposes a targeted fix
+4. **Review** — inspect the diff file-by-file; refine with natural-language feedback if needed
+5. **Apply** — Forge creates a branch, commits all changes, and opens a merge/pull request
+6. **Monitor** — watch the CI pipeline run; if it fails, click "Fix with AI" to iterate
+
+---
+
+## Quick start
+
+```bash
+cp .env.example .env
+# fill in FORGE_TOKEN plus your provider credentials (see Configuration below)
+
+npm install
+npm run dev
+# open http://localhost:5000
+```
+
+### Prerequisites
+
+- Node.js 20+
+- `claude` CLI installed and authenticated (`claude auth login`)
+- Credentials for your SCM provider (see below)
+
+### Headless / CLI
+
+The `forge-agent` bin drives the same orchestrator from the terminal — one command takes an issue all the way to production:
+
+```bash
+forge-agent ship 42
+```
+
+…analyze → review → validate → apply → watch CI → merge → watch deploy → close, with a `y/N` gate at every state-changing step. See [`bin/README.md`](./bin/README.md) for a quick start, [`docs/cli.md`](./docs/cli.md) for the full command reference, and [`docs/cli-ship-workflow.md`](./docs/cli-ship-workflow.md) for the workflow design.
+
+---
+
+## Configuration
+
+### Core
+
+| Variable | Required | Description |
+|---|---|---|
+| `FORGE_TOKEN` | ✅ | Dashboard password — users enter this to access Forge |
+| `SCM_PROVIDER` | — | `gitlab` (default) · `github` · `azuredevops` |
+| `FORGE_REPOS` | — | Comma-separated repo list for multi-repo support |
+| `ANTHROPIC_API_KEY` | — | Enables live model list from Anthropic; falls back to hardcoded list |
+| `FORGE_MODEL` | — | Override default model (default: `claude-sonnet-4-6`) |
+| `VITE_FORGE_TOKEN` | — | Baked into the UI — skips the token entry form on load |
+| `K8S_CLUSTER_TOKEN` | — | K8s service account token for rollout monitoring |
+| `K8S_CLUSTER_SERVER` | — | K8s API server URL |
+| `PORT` | — | HTTP server port (default: `5001`) |
+| `OPENCLAW_GATEWAY_URL` | — | Enables OpenClaw agent backend; point at your local Gateway |
+| `OPENCLAW_TOKEN` | — | Bearer token for OpenClaw Gateway auth |
+
+### GitLab (`SCM_PROVIDER=gitlab`, default)
+
+| Variable | Required | Description |
+|---|---|---|
+| `FORGE_GITLAB_PROJECT` | ✅ | Default project path, e.g. `group/repo` |
+| `GITLAB_TOKEN` | ✅ | Personal access token with `api` + `write_repository` scopes |
+
+### GitHub (`SCM_PROVIDER=github`)
+
+| Variable | Required | Description |
+|---|---|---|
+| `GITHUB_TOKEN` | ✅ | Personal access token with `repo` + `workflow` scopes |
+| `GITHUB_OWNER` | ✅ | Organization or user, e.g. `ipul-labs` |
+| `GITHUB_REPO` | ✅ | Repository name, e.g. `web-app` |
+| `GITHUB_BASE_BRANCH` | — | Default target branch (default: `main`) |
+
+### Azure DevOps (`SCM_PROVIDER=azuredevops`)
+
+| Variable | Required | Description |
+|---|---|---|
+| `AZURE_DEVOPS_TOKEN` | ✅ | Personal access token (Full access or Code + Work Items) |
+| `AZURE_DEVOPS_ORG` | ✅ | Organization name, e.g. `ipul-labs` |
+| `AZURE_DEVOPS_PROJECT` | ✅ | Team project name, e.g. `web-app` |
+| `AZURE_DEVOPS_REPO` | — | Git repo name (defaults to project name) |
+| `AZURE_DEVOPS_BASE_BRANCH` | — | Default target branch (default: `main`) |
+
+See `.env.example` for a full annotated list.
+
+---
+
+## Multi-provider support
+
+Forge's SCM layer is a clean provider abstraction — all three providers implement the same `ScmProvider` interface and return identical normalized shapes (`NormalIssue`, `NormalMR`, `NormalPipeline`, etc.). The rest of the codebase never knows which provider is active.
+
+### Switching providers
+
+```bash
+# .env
+SCM_PROVIDER=github
+GITHUB_TOKEN=ghp_...
+GITHUB_OWNER=my-org
+GITHUB_REPO=my-repo
+```
+
+### Per-repo prefix (multi-repo mixed-provider setups)
+
+```bash
+FORGE_REPOS=gitlab:ipul/web-app,github:my-org/mobile
+```
+
+### Provider capabilities
+
+| Feature | GitLab | GitHub | Azure DevOps |
+|---|---|---|---|
+| Issues / Work Items | ✅ | ✅ | ✅ (Work Items) |
+| Multi-file commits | ✅ | ✅ (Git Data API) | ✅ (Pushes API) |
+| Merge / Pull Requests | ✅ | ✅ | ✅ |
+| CI pipelines | ✅ GitLab CI | ✅ GitHub Actions | ✅ Azure Pipelines |
+| Job log traces | ✅ | ✅ | ✅ |
+| Server-side rebase | ✅ | — | — |
+
+---
+
+## Using as an npm package
+
+Mount the Forge Express router alongside your own app:
+
+```js
+import express from "express";
+import forgeRouter from "forge-agent";
+
+const app = express();
+app.use("/api/forge", express.json(), forgeRouter);
+```
+
+The router reads all config from `process.env` — no constructor arguments needed.
+
+### Available exports
+
+```js
+import forgeRouter from "forge-agent";                    // Express router
+import { ForgeAgent } from "forge-agent/agent";           // Core pipeline class
+import { createProvider } from "forge-agent/providers";   // SCM provider factory
+```
+
+#### `ForgeAgent`
+
+```js
+const agent = new ForgeAgent({ project: "group/repo" });
+
+// Analyze an issue and stream progress events
+const result = await agent.analyzeIssue(issueIid, (event) => {
+  console.log(event); // { type: "progress" | "result" | "error" | "usage", ... }
+});
+
+// Apply the analysis: creates branch + commit + MR/PR
+const { branchName, mr } = await agent.applyFix(result);
+
+// Refine with reviewer feedback
+await agent.refineIssue(issueIid, result.changes, "use the existing logger utility");
+
+// Push to an existing branch (for CI fixes)
+await agent.commitToBranch(branchName, result);
+```
+
+#### `createProvider`
+
+```js
+import { createProvider } from "forge-agent/providers";
+
+const provider = createProvider("github:my-org/my-repo");
+
+const issues = await provider.listOpenIssues();
+const mr     = await provider.getMR(42);
+const diffs  = await provider.getMRDiffs(42);
+```
+
+---
+
+## Production deployment
+
+```bash
+npm run build          # builds Vite SPA → dist/
+NODE_ENV=production node server.js
+```
+
+Or with Docker:
+
+```bash
+docker build -t forge .
+docker run -p 5001:5001 --env-file .env forge
+```
+
+---
+
+## Architecture
+
+```
+server/
+  forge/
+    routes.js           # Express router — all /api/forge/* endpoints
+    core/
+      ForgeAgent.js     # Orchestrates the full pipeline (analyze → apply → refine)
+      claudeClient.js   # Shells out to the claude CLI for structured output
+      openclawClient.js # OpenClaw Gateway HTTP client
+      agentClient.js    # Dispatcher: routes to claudeClient or openclawClient
+      gitlabClient.js   # Legacy shim (kept for backward compatibility)
+      k8s.js            # Kubernetes client for rollout monitoring
+      providers/
+        base.js         # Abstract ScmProvider — normalized shapes + interface
+        gitlab.js       # GitLab REST API v4
+        github.js       # GitHub REST API v3 + Git Data API
+        azuredevops.js  # Azure DevOps REST API
+        index.js        # createProvider() factory
+
+src/
+  views/Forge/
+    ForgeDashboard.tsx      # Root UI component with tabbed issue/MR views
+    api.ts                  # Token management + fetch helper
+    types.ts                # Shared TypeScript types
+    utils.ts                # SSE helper + state utilities
+    components/
+      AnalysisProgress.tsx  # Streaming progress display (analyze + ci-fix modes)
+      PipelineStatus.tsx    # CI pipeline + per-job log traces
+      MRStatus.tsx          # MR conflict/rebase banner + inline diff viewer
+      OpenMRList.tsx        # All open Forge MRs with pipeline badges
+    hooks/
+      useForgeDashboard.ts  # All state, phase transitions, and API calls
+```
+
+### Two-pass analysis
+
+**Pass 1** — `identifyRelevantFiles`: Claude reads the issue + file tree, returns the max-6 most relevant paths.
+
+**Pass 2** — `proposeFix`: Claude reads the actual file contents and proposes a targeted fix as a JSON diff.
+
+Both passes use `claude --print --output-format json` so cost and service tier are tracked automatically.
+
+### CI refinement
+
+When a pipeline fails, Forge fetches the last 150 lines of each failed job's trace log and feeds them to pass 2 with an explicit "pipeline failed" framing — not generic reviewer feedback. This improves fix quality for common failures like lint errors and type errors.
+
+### Provider abstraction
+
+All three SCM providers implement `ScmProvider` from `providers/base.js`. The contract is:
+- **Normalized return types** — all methods return `NormalIssue`, `NormalMR`, `NormalPipeline`, etc., regardless of provider
+- **Instance-scoped** — each provider is instantiated with a repo string; no global state
+- **`supportsRebase`** — providers that don't support server-side rebase return `false`; the UI and API layer check this before showing the rebase button
+
+---
+
+## License
+
+MIT

package/bin/README.md

@@ -0,0 +1,210 @@
+# `forge-agent` — CLI
+
+> Type an issue, accept the suggested fix, and watch it merge to production. One command.
+
+`forge-agent` is the headless half of [Forge](../README.md). Same orchestrator the web UI uses, no browser required.
+
+---
+
+## Install
+
+```bash
+npm install -g forge-agent
+```
+
+Or run from a checkout without installing:
+
+```bash
+node bin/forge-agent.js <command>
+```
+
+You'll need:
+
+- **Node.js 20+**
+- **`claude` CLI** installed and authenticated (`claude auth login`)
+- A **GitLab / GitHub / Azure DevOps** personal access token
+
+---
+
+## First-time setup
+
+```bash
+forge-agent init        # interactive wizard — writes .env + ~/.forge/config.json
+forge-agent doctor      # confirm node, git, claude CLI, token, and config are all ready
+```
+
+`init` walks you through:
+
+1. `FORGE_TOKEN` (a generated default — accept with Enter)
+2. `PORT` (only matters if you also want the web UI)
+3. SCM provider (gitlab / github / azuredevops, arrow keys)
+4. Primary repo, then **add another?** (loop to add secondaries — needed for cross-repo features)
+5. SCM token (masked input)
+
+---
+
+## The headline command
+
+```bash
+forge-agent ship <iid>
+```
+
+Walks an issue from "open ticket" to "deployed in production" in one command, pausing for `y/N` at every step that changes shared state:
+
+```
+ship <iid>
+  ├─ analyze          (or load cached if you've already analysed)
+  ├─ review proposal  (per-file diff + summary + divergence warnings)
+  ├─ ?accept          → continue, refuse, or refine with feedback
+  ├─ validate         (lint / typecheck / test against the proposed contents)
+  ├─ ?apply           → branch + commit + open MR
+  ├─ watch CI
+  ├─ ?ci-fix          (only if the pipeline fails — re-analyse with logs, push to same branch)
+  ├─ ?merge           → merge to main
+  ├─ watch deploy     (post-merge pipeline)
+  └─ ?close issue
+```
+
+**Resumable.** If you abort or the process dies, re-run `forge-agent ship <iid>` and it picks up at the next gate (state lives in `~/.forge/sessions/`).
+
+**Confirm-by-default.** Cursor on every gate defaults to *no*. Pass `--yes` (or set `FORGE_YES=1`) for unattended mode.
+
+```bash
+forge-agent ship 42                     # interactive, all gates
+forge-agent ship 42 --all-repos         # cross-repo (web-app + api + …)
+forge-agent ship 42 --yes               # unattended, no prompts
+forge-agent ship 42 --auto              # arm auto-merge instead of merging now
+forge-agent ship 42 --skip-validate     # skip the auto-validate before apply
+```
+
+---
+
+## Discover what to work on
+
+```bash
+forge-agent issues                      # latest open issues, sorted by recency
+forge-agent issues --label feature      # filter by label
+forge-agent issues --mine               # filter by author (FORGE_USER || USER)
+forge-agent issues --json | jq .        # pipe-friendly
+forge-agent issue 42                    # full description, labels, URL
+```
+
+---
+
+## Drive each phase by hand
+
+`ship` is a thin orchestrator — every phase is also a standalone command. Useful when you want to inspect, iterate, or only do part of the flow.
+
+```bash
+forge-agent analyze 42 --all-repos      # produce + cache a fresh analysis
+forge-agent show                        # re-render the most recent analysis
+forge-agent show 42                     # ...for a specific issue
+forge-agent refine --feedback "use Resend instead of SendGrid"
+forge-agent validate                    # lint/typecheck/test the proposal
+forge-agent apply --validate            # gate apply on green validation
+forge-agent watch                       # poll the MR pipeline
+forge-agent ci-fix                      # re-analyse with failed-job logs, push to same branch
+forge-agent merge                       # confirm + merge
+forge-agent merge --auto                # arm auto-merge instead
+forge-agent resolution-check            # ask the model: did this MR actually fix the issue?
+forge-agent close                       # confirm + close the issue
+```
+
+`<iid>`-less commands resolve via the **HEAD pointer** — the most recently touched session. Like `git`'s HEAD: whatever you analysed last is what `show`/`validate`/`apply`/`watch`/`merge`/`close` operate on unless you pass an explicit `<iid>`.
+
+---
+
+## Sessions (`~/.forge/sessions/`)
+
+Each issue you work on gets a directory:
+
+```
+~/.forge/sessions/<repo>/<iid>/
+  analysis.json    last cached analyzeIssue result
+  state.json       { phase, branch, mrIid, mrUrl, lastPipelineStatus, ... }
+  events.ndjson    append-only audit log
+~/.forge/sessions/HEAD                "<repo>/<iid>" — the most recently touched session
+```
+
+Inspect and clean:
+
+```bash
+forge-agent session list                # table of all sessions, HEAD marked *
+forge-agent session list --json
+forge-agent session show                # full state of HEAD
+forge-agent session show 42             # ...for a specific issue
+forge-agent session clean 42            # remove one session
+forge-agent session clean --all         # wipe everything
+```
+
+Override the location with `FORGE_SESSIONS_PATH` (handy for CI or test isolation).
+
+---
+
+## Common workflows
+
+### Ship a small fix, fully unattended
+
+```bash
+forge-agent ship 42 --yes
+```
+
+Don't do this on prod the first time. Watch a couple of runs interactively first.
+
+### Drive review explicitly
+
+```bash
+forge-agent analyze 42 --all-repos      # produce
+forge-agent show                        # review on the same screen later
+forge-agent refine --feedback "..."     # iterate
+forge-agent ship 42                     # pick up where you left off
+```
+
+### Run from CI
+
+```bash
+FORGE_YES=1 forge-agent ship 42
+```
+
+`--json` is available on `analyze`, `issues`, `issue`, `repos list`, `session list/show`, `watch`, and `validate` — pipe-safe outputs that bypass Ink.
+
+### Recover from a failed step
+
+Just re-run the same command. State is on disk; it picks up where it left off.
+
+```bash
+forge-agent ship 42                     # if it died mid-flow, this resumes
+forge-agent ci-fix                      # if CI failed, fix it without re-running ship
+```
+
+---
+
+## Doctor & troubleshooting
+
+```bash
+forge-agent doctor
+```
+
+Sequential checklist — `node`, `git`, `claude`, `FORGE_TOKEN`, config file, frontend build. Exits non-zero if any check fails.
+
+If `analyze` is timing out (5-minute Claude CLI cap), narrow the scope:
+
+```bash
+forge-agent analyze 42 --secondary group/api    # explicit secondary instead of --all-repos
+```
+
+If `apply` says "no repos to validate against", check `forge-agent repos list` and your session's `primary` field.
+
+---
+
+## Reference
+
+- [`docs/cli.md`](../docs/cli.md) — full command reference, every flag
+- [`docs/cli-ship-workflow.md`](../docs/cli-ship-workflow.md) — design + status of the end-to-end ship workflow (per-phase delivery, decisions, risks)
+- [`../README.md`](../README.md) — the broader Forge project (web UI, server, multi-provider details)
+
+---
+
+## License
+
+MIT — same as the rest of Forge.