@ipul-labs/forge 1.16.2 → 1.16.4

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@ipul-labs/forge",
-  "version": "1.16.2",
+  "version": "1.16.4",
   "description": "AI-powered code change & deploy control panel — connects Claude, GitLab, and Kubernetes",
+  "readmeFilename": "README.md",
   "type": "module",
   "main": "server/forge/routes.js",
   "bin": {
@@ -24,7 +25,8 @@
     "start": "NODE_ENV=production node server.js",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "prepack": "node -e \"const p=require('./package.json'),fs=require('fs');p.readme=fs.readFileSync('README.md','utf8');fs.writeFileSync('package.json',JSON.stringify(p,null,2)+'\\n')\""
   },
   "dependencies": {
     "@kubernetes/client-node": "^1.0.0",
@@ -77,5 +79,6 @@
     "type": "git",
     "url": "https://gitlab.com/ipul-labs/forge.git"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "readme": "# Forge by iPuL\n\nAI-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.\n\nBuilt on: Claude Code CLI · GitLab / GitHub / Azure DevOps · Kubernetes\n\n---\n\n## Why Forge\n\n**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.\n\nEverything else fills in the gaps that matter for real teams:\n\n- **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.\n- **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.\n- **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).\n- **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.\n\n---\n\n## How it works\n\n1. **Connect** — enter your Forge token to authenticate\n2. **Pick an issue** — Forge loads open issues from your project\n3. **Analyze** — Claude reads the repo file tree, identifies relevant files, and proposes a targeted fix\n4. **Review** — inspect the diff file-by-file; refine with natural-language feedback if needed\n5. **Apply** — Forge creates a branch, commits all changes, and opens a merge/pull request\n6. **Monitor** — watch the CI pipeline run; if it fails, click \"Fix with AI\" to iterate\n\n---\n\n## Getting started\n\n### Prerequisites\n\n- Node.js 20+\n- `claude` CLI installed and authenticated (`claude auth login`)\n- Credentials for your SCM provider (see [Configuration](#configuration))\n\n### Install\n\n```bash\ngit clone https://gitlab.com/ipul-labs/forge.git\ncd forge\nnpm install\n```\n\n### Configure\n\n```bash\n# Interactive setup — writes .env and ~/.forge/config.json\nnpx forge init\n```\n\nOr copy the example env and fill in the values manually:\n\n```bash\ncp .env.example .env\n# fill in FORGE_TOKEN plus your provider credentials\n```\n\n### Launch the UI\n\n```bash\nnpm run dev\n# opens http://localhost:5000 (frontend) with API on :5001\n```\n\nFor production:\n\n```bash\nnpm run build:app   # builds Vite SPA to dist/\nnpm start           # NODE_ENV=production node server.js\n```\n\n### CLI usage\n\nThe `forge` CLI drives the same orchestrator from the terminal. Install globally or use `npx`:\n\n```bash\n# Global install (adds `forge` to PATH)\nnpm install -g @ipul-labs/forge\n\n# Or run via npx from the repo\nnpx forge <command>\n```\n\n#### Interactive mode\n\nRun `forge` with no arguments to enter an interactive terminal session:\n\n```bash\nforge\n```\n\n```\n  forge v1.15.1\n\n──────────────────────────────────────────────────\n ❯ issues --limit 5\n──────────────────────────────────────────────────\n group/repo  |  agent:claude  |  v1.15.1\n```\n\nTab-completes command names. Type `use <repo>` to switch repos. Commands that error stay in the session — only `exit`, `quit`, or Ctrl+D leave.\n\n#### End-to-end: issue to production\n\n```bash\nforge ship 42\n```\n\nRuns: analyze → review → validate → apply → watch CI → merge → watch deploy → close, with a `y/N` gate at every state-changing step.\n\n#### Step-by-step commands\n\n```bash\nforge issues                   # List open issues (--label X, --mine, --limit N)\nforge issue 42                 # Show full description\nforge create-issue --title \"fix: broken widget\"  # Create a new issue\nforge analyze 42               # Run two-pass analysis, cache result\nforge show                     # Re-render cached analysis\nforge refine --feedback \"...\"  # Iterate with feedback\nforge validate                 # Run lint/typecheck/test against proposed changes\nforge apply                    # Push branch + open MR\nforge watch                    # Poll the MR pipeline\nforge ci-fix                   # Re-analyze with failed-pipeline logs\nforge merge                    # Merge the MR\nforge resolution-check         # Verify merged MR closes the issue\nforge close                    # Close the issue\nforge use group/other-repo     # Switch active repo\nforge update                   # Pull latest + reinstall dependencies\n```\n\n#### Options\n\n```\n-p, --port <n>           Port for start\n--repo <group/repo>      Primary repo\n--secondary <repo>       Additional repo (repeatable)\n--all-repos              Include every configured repo\n--model <id>             Claude model override\n--agent <name>           Agent backend: claude | openclaw\n--prompt <text>          Extra user prompt\n--json                   JSON output\n--quiet                  Suppress progress\n--yes                    Skip confirmation gates\n--validate               Run validate before apply\n```\n\n#### Diagnostics\n\n```bash\nforge doctor             # Check prerequisites (node, claude CLI, env vars)\nforge session list       # List cached sessions\nforge session clean      # Remove stale session data\n```\n\nSee [`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.\n\n---\n\n## Configuration\n\n### Core\n\n| Variable | Required | Description |\n|---|---|---|\n| `FORGE_TOKEN` | Yes | Dashboard password — also auto-fills the UI login form |\n| `FORGE_REPOS` | Yes | Comma-separated repo list; first entry is the primary project |\n| `SCM_PROVIDER` | — | `gitlab` (default) · `github` · `azuredevops` |\n| `ANTHROPIC_API_KEY` | — | Enables live model list from Anthropic; falls back to hardcoded list |\n| `FORGE_MODEL` | — | Override default model (default: `claude-sonnet-4-6`) |\n| `K8S_CLUSTER_TOKEN` | — | K8s service account token for rollout monitoring |\n| `K8S_CLUSTER_SERVER` | — | K8s API server URL |\n| `PORT` | — | HTTP server port (default: `5001`) |\n| `OPENCLAW_GATEWAY_URL` | — | Enables OpenClaw agent backend; point at your local Gateway |\n| `OPENCLAW_TOKEN` | — | Bearer token for OpenClaw Gateway auth |\n\n### Provider credentials\n\nSCM tokens can be set here **or** in the Forge Settings UI (Settings → Connections). The UI value takes precedence over env vars.\n\n#### GitLab (`SCM_PROVIDER=gitlab`, default)\n\n| Variable | Required | Description |\n|---|---|---|\n| `GITLAB_TOKEN` | Yes | Personal access token with `api` + `write_repository` scopes |\n\n#### GitHub (`SCM_PROVIDER=github`)\n\n| Variable | Required | Description |\n|---|---|---|\n| `GITHUB_TOKEN` | Yes | Personal access token with `repo` + `workflow` scopes |\n| `GITHUB_OWNER` | Yes | Organization or user, e.g. `ipul-labs` |\n| `GITHUB_REPO` | Yes | Repository name, e.g. `web-app` |\n| `GITHUB_BASE_BRANCH` | — | Default target branch (default: `main`) |\n\n#### Azure DevOps (`SCM_PROVIDER=azuredevops`)\n\n| Variable | Required | Description |\n|---|---|---|\n| `AZURE_DEVOPS_TOKEN` | Yes | Personal access token (Full access or Code + Work Items) |\n| `AZURE_DEVOPS_ORG` | Yes | Organization name, e.g. `ipul-labs` |\n| `AZURE_DEVOPS_PROJECT` | Yes | Team project name, e.g. `web-app` |\n| `AZURE_DEVOPS_REPO` | — | Git repo name (defaults to project name) |\n| `AZURE_DEVOPS_BASE_BRANCH` | — | Default target branch (default: `main`) |\n\n### Deprecated (still work as fallbacks)\n\n| Variable | Replaced by |\n|---|---|\n| `FORGE_GITLAB_PROJECT` | First entry in `FORGE_REPOS` |\n| `VITE_FORGE_TOKEN` | Auto-derived from `FORGE_TOKEN` |\n| `FORGE_REFINE_REPO_ACCESS` | Settings UI toggle (Settings → Defaults) |\n\nSee `.env.example` for a full annotated list.\n\n---\n\n## Multi-provider support\n\nForge'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.\n\n### Switching providers\n\n```bash\n# .env\nSCM_PROVIDER=github\nGITHUB_TOKEN=ghp_...\nGITHUB_OWNER=my-org\nGITHUB_REPO=my-repo\n```\n\n### Per-repo prefix (multi-repo mixed-provider setups)\n\n```bash\nFORGE_REPOS=gitlab:ipul/web-app,github:my-org/mobile\n```\n\n### Provider capabilities\n\n| Feature | GitLab | GitHub | Azure DevOps |\n|---|---|---|---|\n| Issues / Work Items | Yes | Yes | Yes (Work Items) |\n| Multi-file commits | Yes | Yes (Git Data API) | Yes (Pushes API) |\n| Merge / Pull Requests | Yes | Yes | Yes |\n| CI pipelines | Yes (GitLab CI) | Yes (GitHub Actions) | Yes (Azure Pipelines) |\n| Job log traces | Yes | Yes | Yes |\n| Server-side rebase | Yes | — | — |\n\n---\n\n## Production deployment\n\n```bash\nnpm run build:app      # builds Vite SPA to dist/\nNODE_ENV=production node server.js\n```\n\nOr with Docker:\n\n```bash\ndocker build -t forge .\ndocker run -p 5001:5001 --env-file .env forge\n```\n\n---\n\n## Architecture\n\n```\nbin/\n  forge-agent.js        # CLI entry point (forge command)\n  cli/\n    ship.js             # End-to-end orchestrator (Ink UI)\n    analyze.js          # Two-pass issue analysis\n    resolution.js       # Post-merge resolution check\n    sessionStore.js     # ~/.forge/sessions/ persistence\n    ...\n\nserver/\n  forge/\n    routes.js           # Express router — all /api/forge/* endpoints\n    core/\n      ForgeAgent.js     # Orchestrates the full pipeline (analyze -> apply -> refine)\n      claudeClient.js   # Shells out to the claude CLI for structured output\n      openclawClient.js # OpenClaw Gateway HTTP client\n      agentClient.js    # Dispatcher: routes to claudeClient or openclawClient\n      k8s.js            # Kubernetes client for rollout monitoring\n      providers/\n        base.js         # Abstract ScmProvider — normalized shapes + interface\n        gitlab.js       # GitLab REST API v4\n        github.js       # GitHub REST API v3 + Git Data API\n        azuredevops.js  # Azure DevOps REST API\n        index.js        # createProvider() factory\n\nsrc/\n  views/Forge/\n    ForgeDashboard.tsx      # Root UI component with tabbed issue/MR views\n    api.ts                  # Token management + fetch helper\n    types.ts                # Shared TypeScript types\n    utils.ts                # SSE helper + state utilities\n    components/             # Analysis progress, pipeline status, diff viewer\n    hooks/\n      useForgeDashboard.ts  # All state, phase transitions, and API calls\n```\n\n### Two-pass analysis\n\n**Pass 1** — `identifyRelevantFiles`: Claude reads the issue + file tree, returns the max-6 most relevant paths.\n\n**Pass 2** — `proposeFix`: Claude reads the actual file contents and proposes a targeted fix as a JSON diff.\n\nBoth passes use `claude --print --output-format json` so cost and service tier are tracked automatically.\n\n### CI refinement\n\nWhen 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.\n\n### Provider abstraction\n\nAll three SCM providers implement `ScmProvider` from `providers/base.js`. The contract is:\n- **Normalized return types** — all methods return `NormalIssue`, `NormalMR`, `NormalPipeline`, etc., regardless of provider\n- **Instance-scoped** — each provider is instantiated with a repo string; no global state\n- **`supportsRebase`** — providers that don't support server-side rebase return `false`; the UI and API layer check this before showing the rebase button\n\n---\n\n## Programmatic usage\n\nMount the Forge Express router or use the core classes directly:\n\n```js\nimport forgeRouter from \"@ipul-labs/forge\";             // Express router\nimport { ForgeAgent } from \"@ipul-labs/forge/agent\";    // Core pipeline class\nimport { createProvider } from \"@ipul-labs/forge/providers\"; // SCM factory\n```\n\n```js\nconst agent = new ForgeAgent({ project: \"group/repo\" });\nconst result = await agent.analyzeIssue(42, (event) => console.log(event));\nconst { branchName, mr } = await agent.applyFix(result);\n```\n\n---\n\n## License\n\nMIT\n"
 }