@ipul-labs/forge 1.14.0 → 1.15.0

package/README.md

@@ -30,32 +30,112 @@ Everything else fills in the gaps that matter for real teams:
 
 ---
 
-## Quick start
+## Getting started
+
+### Prerequisites
+
+- Node.js 20+
+- `claude` CLI installed and authenticated (`claude auth login`)
+- Credentials for your SCM provider (see [Configuration](#configuration))
+
+### Install
+
+```bash
+git clone https://gitlab.com/ipul-labs/forge.git
+cd forge
+npm install
+```
+
+### Configure
+
+```bash
+# Interactive setup — writes .env and ~/.forge/config.json
+npx forge init
+```
+
+Or copy the example env and fill in the values manually:
 
 ```bash
 cp .env.example .env
-# fill in FORGE_TOKEN plus your provider credentials (see Configuration below)
+# fill in FORGE_TOKEN plus your provider credentials
+```
 
-npm install
+### Launch the UI
+
+```bash
 npm run dev
-# open http://localhost:5000
+# opens http://localhost:5000 (frontend) with API on :5001
 ```
 
-### Prerequisites
+For production:
 
-- Node.js 20+
-- `claude` CLI installed and authenticated (`claude auth login`)
-- Credentials for your SCM provider (see below)
+```bash
+npm run build:app   # builds Vite SPA to dist/
+npm start           # NODE_ENV=production node server.js
+```
+
+### CLI usage
+
+The `forge` CLI drives the same orchestrator from the terminal. Install globally or use `npx`:
+
+```bash
+# Global install (adds `forge` to PATH)
+npm install -g @ipul-labs/forge
+
+# Or run via npx from the repo
+npx forge <command>
+```
+
+#### End-to-end: issue to production
+
+```bash
+forge ship 42
+```
 
-### Headless / CLI
+Runs: analyze → review → validate → apply → watch CI → merge → watch deploy → close, with a `y/N` gate at every state-changing step.
 
-The `forge-agent` bin drives the same orchestrator from the terminal — one command takes an issue all the way to production:
+#### Step-by-step commands
 
 ```bash
-forge-agent ship 42
+forge issues                   # List open issues (--label X, --mine, --limit N)
+forge issue 42                 # Show full description
+forge analyze 42               # Run two-pass analysis, cache result
+forge show                     # Re-render cached analysis
+forge refine --feedback "..."  # Iterate with feedback
+forge validate                 # Run lint/typecheck/test against proposed changes
+forge apply                    # Push branch + open MR
+forge watch                    # Poll the MR pipeline
+forge ci-fix                   # Re-analyze with failed-pipeline logs
+forge merge                    # Merge the MR
+forge resolution-check         # Verify merged MR closes the issue
+forge close                    # Close the issue
+```
+
+#### Options
+
+```
+-p, --port <n>           Port for start
+--repo <group/repo>      Primary repo
+--secondary <repo>       Additional repo (repeatable)
+--all-repos              Include every configured repo
+--model <id>             Claude model override
+--agent <name>           Agent backend: claude | openclaw
+--prompt <text>          Extra user prompt
+--json                   JSON output
+--quiet                  Suppress progress
+--yes                    Skip confirmation gates
+--validate               Run validate before apply
 ```
 
-…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.
+#### Diagnostics
+
+```bash
+forge doctor             # Check prerequisites (node, claude CLI, env vars)
+forge session list       # List cached sessions
+forge session clean      # Remove stale session data
+```
+
+See [`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.
 
 ---
 
@@ -65,44 +145,54 @@ forge-agent ship 42
 
 | Variable | Required | Description |
 |---|---|---|
-| `FORGE_TOKEN` | ✅ | Dashboard password — users enter this to access Forge |
+| `FORGE_TOKEN` | Yes | Dashboard password — also auto-fills the UI login form |
+| `FORGE_REPOS` | Yes | Comma-separated repo list; first entry is the primary project |
 | `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)
+### Provider credentials
+
+SCM tokens can be set here **or** in the Forge Settings UI (Settings → Connections). The UI value takes precedence over env vars.
+
+#### 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 |
+| `GITLAB_TOKEN` | Yes | Personal access token with `api` + `write_repository` scopes |
 
-### GitHub (`SCM_PROVIDER=github`)
+#### 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_TOKEN` | Yes | Personal access token with `repo` + `workflow` scopes |
+| `GITHUB_OWNER` | Yes | Organization or user, e.g. `ipul-labs` |
+| `GITHUB_REPO` | Yes | Repository name, e.g. `web-app` |
 | `GITHUB_BASE_BRANCH` | — | Default target branch (default: `main`) |
 
-### Azure DevOps (`SCM_PROVIDER=azuredevops`)
+#### 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_TOKEN` | Yes | Personal access token (Full access or Code + Work Items) |
+| `AZURE_DEVOPS_ORG` | Yes | Organization name, e.g. `ipul-labs` |
+| `AZURE_DEVOPS_PROJECT` | Yes | 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`) |
 
+### Deprecated (still work as fallbacks)
+
+| Variable | Replaced by |
+|---|---|
+| `FORGE_GITLAB_PROJECT` | First entry in `FORGE_REPOS` |
+| `VITE_FORGE_TOKEN` | Auto-derived from `FORGE_TOKEN` |
+| `FORGE_REFINE_REPO_ACCESS` | Settings UI toggle (Settings → Defaults) |
+
 See `.env.example` for a full annotated list.
 
 ---
@@ -131,75 +221,19 @@ FORGE_REPOS=gitlab:ipul/web-app,github:my-org/mobile
 
 | 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);
-```
+| Issues / Work Items | Yes | Yes | Yes (Work Items) |
+| Multi-file commits | Yes | Yes (Git Data API) | Yes (Pushes API) |
+| Merge / Pull Requests | Yes | Yes | Yes |
+| CI pipelines | Yes (GitLab CI) | Yes (GitHub Actions) | Yes (Azure Pipelines) |
+| Job log traces | Yes | Yes | Yes |
+| Server-side rebase | Yes | — | — |
 
 ---
 
 ## Production deployment
 
 ```bash
-npm run build          # builds Vite SPA → dist/
+npm run build:app      # builds Vite SPA to dist/
 NODE_ENV=production node server.js
 ```
 
@@ -215,15 +249,23 @@ docker run -p 5001:5001 --env-file .env forge
 ## Architecture
 
 ```
+bin/
+  forge-agent.js        # CLI entry point (forge command)
+  cli/
+    ship.js             # End-to-end orchestrator (Ink UI)
+    analyze.js          # Two-pass issue analysis
+    resolution.js       # Post-merge resolution check
+    sessionStore.js     # ~/.forge/sessions/ persistence
+    ...
+
 server/
   forge/
     routes.js           # Express router — all /api/forge/* endpoints
     core/
-      ForgeAgent.js     # Orchestrates the full pipeline (analyze → apply → refine)
+      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
@@ -238,11 +280,7 @@ src/
     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
+    components/             # Analysis progress, pipeline status, diff viewer
     hooks/
       useForgeDashboard.ts  # All state, phase transitions, and API calls
 ```
@@ -268,6 +306,24 @@ All three SCM providers implement `ScmProvider` from `providers/base.js`. The co
 
 ---
 
+## Programmatic usage
+
+Mount the Forge Express router or use the core classes directly:
+
+```js
+import forgeRouter from "@ipul-labs/forge";             // Express router
+import { ForgeAgent } from "@ipul-labs/forge/agent";    // Core pipeline class
+import { createProvider } from "@ipul-labs/forge/providers"; // SCM factory
+```
+
+```js
+const agent = new ForgeAgent({ project: "group/repo" });
+const result = await agent.analyzeIssue(42, (event) => console.log(event));
+const { branchName, mr } = await agent.applyFix(result);
+```
+
+---
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ipul-labs/forge",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "AI-powered code change & deploy control panel — connects Claude, GitLab, and Kubernetes",
   "type": "module",
   "main": "server/forge/routes.js",
@@ -10,26 +10,20 @@
   "exports": {
     ".": "./server/forge/routes.js",
     "./agent": "./server/forge/core/ForgeAgent.js",
-    "./gitlab": "./server/forge/core/gitlabClient.js",
-    "./ui": {
-      "import": "./dist-lib/ui.js",
-      "types": "./dist-lib/ui.d.ts"
-    },
-    "./style.css": "./dist-lib/style.css"
+    "./providers": "./server/forge/core/providers/index.js"
   },
   "files": [
     "bin",
     "server/forge",
-    "dist",
-    "dist-lib"
+    "dist"
   ],
   "scripts": {
     "dev": "trap 'kill 0' EXIT INT TERM; FORGE_NO_VITE=1 node --watch-path=./server --watch-path=./server.js server.js & vite; wait",
-    "build": "vite build --mode lib",
-    "build:app": "vite build",
-    "prepare": "npm run build",
+    "build": "vite build",
     "start": "NODE_ENV=production node server.js",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "dependencies": {
     "@kubernetes/client-node": "^1.0.0",
@@ -40,7 +34,10 @@
     "ink": "^7.0.1",
     "ink-select-input": "^6.2.0",
     "ink-spinner": "^5.0.0",
-    "ink-text-input": "^6.0.0"
+    "ink-text-input": "^6.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^7.14.1"
   },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",
@@ -52,19 +49,14 @@
     "@types/express": "^5.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
-    "@vitejs/plugin-react": "^4.3.0",
+    "@vitejs/plugin-react": "^6.0.0",
     "autoprefixer": "^10.4.20",
     "postcss": "^8.4.47",
     "semantic-release": "^25.0.3",
     "tailwindcss": "^3.4.14",
     "typescript": "^5.6.0",
-    "vite": "^5.4.0",
-    "vite-plugin-dts": "^4.3.0"
-  },
-  "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0",
-    "react-router-dom": "^7.0.0"
+    "vite": "^8.0.0",
+    "vitest": "^4.1.0"
   },
   "engines": {
     "node": ">=20.0.0"

package/server/forge/core/ForgeAgent.js

@@ -26,6 +26,7 @@ import { checkResolution, identifyRelevantFiles, proposeFix, refineOrAsk } from
 import { branchNameFor } from "./branchName.js";
 import * as configStore from "./configStore.js";
 import { ensureWorkingTree, overlayChanges } from "./localRepo.js";
+import { classifyIssue } from "./prompts.js";
 import { createProvider } from "./providers/index.js";
 import { reattributeChanges } from "./validator/attribute.js";
 
@@ -100,19 +101,26 @@ function isLikelyResumeFailure(err) {
  */
 
 const MAX_FILE_BYTES = 40_000;        // ~40 KB per file to keep the context window healthy
-const MAX_FILES_TOTAL = 12;           // hard cap across all repos
-const MAX_FILES_PER_REPO = 8;         // cap per repo so one repo can't starve another
 const CONV_PREFIX = /^(?:feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)(?:\([^)]+\))?!?:\s*/i;
 
+const FILE_CAPS = {
+	feature:  { total: 18, perRepo: 15 },
+	refactor: { total: 18, perRepo: 15 },
+	fix:      { total: 12, perRepo: 8 },
+	chore:    { total: 12, perRepo: 8 },
+};
+
 /**
  * Builds a conventional-commit subject line from the analysis. Prefers
  * `analysis.mrTitle` (the model's own commit-style summary), falling back to
- * the issue title with a `fix:` prefix when the model didn't supply one.
+ * the issue title with a prefix derived from the issue kind.
  */
 function buildCommitSubject(analysis) {
 	const mrTitle = analysis.mrTitle?.trim();
 	if (mrTitle) return mrTitle;
-	return `fix: ${analysis.issue.title.replace(CONV_PREFIX, "")}`;
+	const kind = classifyIssue(analysis.issue);
+	const prefix = kind === "feature" ? "feat" : kind === "refactor" ? "refactor" : "fix";
+	return `${prefix}: ${analysis.issue.title.replace(CONV_PREFIX, "")}`;
 }
 
 /**
@@ -194,7 +202,7 @@ export class ForgeAgent {
 	 * @param {{ project?: string, secondaryProjects?: string[], agent?: string }} [opts]
 	 */
 	constructor(opts = {}) {
-		const primary = opts.project ?? process.env.FORGE_GITLAB_PROJECT;
+		const primary = opts.project ?? configStore.getPrimaryProject();
 		if (!primary) throw new Error("ForgeAgent requires a primary project.");
 
 		const secondaries = (opts.secondaryProjects ?? [])
@@ -235,7 +243,7 @@ export class ForgeAgent {
 		const results = await Promise.all(
 			this.allRepos.map(async (repo) => {
 				try {
-					const files = await this._provider(repo).getFileTree("src", "main");
+					const files = await this._provider(repo).getFileTree("", "main");
 					return { repo, files };
 				} catch (err) {
 					emit({ type: "log", message: `Could not scan ${repo}: ${err.message}` });
@@ -315,13 +323,14 @@ export class ForgeAgent {
 	}
 
 	/** Enforces the per-repo and total caps, preserving model order. */
-	_capSelections(entries) {
+	_capSelections(entries, issueKind) {
+		const caps = FILE_CAPS[issueKind] ?? FILE_CAPS.fix;
 		const capped = [];
 		const perRepo = new Map();
 		for (const entry of entries) {
-			if (capped.length >= MAX_FILES_TOTAL) break;
+			if (capped.length >= caps.total) break;
 			const count = perRepo.get(entry.repo) ?? 0;
-			if (count >= MAX_FILES_PER_REPO) continue;
+			if (count >= caps.perRepo) continue;
 			capped.push(entry);
 			perRepo.set(entry.repo, count + 1);
 		}
@@ -350,7 +359,7 @@ export class ForgeAgent {
 	 * @param {string} [userPrompt]
 	 * @returns {Promise<AnalysisResult>}
 	 */
-	async analyzeIssue(issueIid, onProgress, model, ciContext, userPrompt, kind = "fresh", opts = {}) {
+	async analyzeIssue(issueIid, onProgress, model, ciContext, userPrompt, kind = "fresh", opts = {}, previousChanges = null) {
 		const emit = onProgress ?? (() => {});
 		const { signal } = opts;
 
@@ -391,9 +400,12 @@ export class ForgeAgent {
 			cacheReadTokens: cr1 = 0,
 		} = ident;
 
+		const issueKind = classifyIssue(issue);
+		emit({ type: "log", message: `Issue classified as: ${issueKind}` });
+
 		const normalized = this._normalizeFileSelections(rawFiles);
 		const { valid, skipped } = this._validateSelections(normalized, repoTrees);
-		const capped = this._capSelections(valid);
+		const capped = this._capSelections(valid, issueKind);
 
 		if (capped.length) {
 			emit({ type: "log", message: `Identified ${capped.length} file(s): ${capped.map((f) => `${f.repo}:${f.path}`).join(", ")}` });
@@ -413,10 +425,11 @@ export class ForgeAgent {
 
 		// Step 5 — propose fix (pass 2)
 		emit({ type: "progress", step: "generate_fix", message: msgs.generate_fix });
+		const promptRules = configStore.get().defaults?.promptRules || "";
 		const propose = await proposeFix(
 			issue,
 			fileContents,
-			{ ciContext, userPrompt, repos: this.allRepos },
+			{ ciContext, userPrompt, previousChanges, repos: this.allRepos, promptRules },
 			model,
 			this.agent,
 			{ signal },
@@ -506,10 +519,11 @@ export class ForgeAgent {
 		// the caller expects fresh changes.
 		if (ciContext) {
 			emit({ type: "progress", step: "generate_fix", message: `Fixing CI failure with ${this._agentLabel}...` });
+			const ciRefineRules = configStore.get().defaults?.promptRules || "";
 			const propose = await proposeFix(
 				issue,
 				fileContents,
-				{ feedback, previousChanges, ciContext, repos: this.allRepos },
+				{ feedback, previousChanges, ciContext, repos: this.allRepos, promptRules: ciRefineRules },
 				model,
 				this.agent,
 				{ signal },
@@ -567,6 +581,7 @@ export class ForgeAgent {
 		emit({ type: "progress", step: "generate_fix", message: `Refining fix with ${this._agentLabel}...` });
 		if (sessionId) emit({ type: "session", sessionId, resumed: resumeSession });
 
+		const refinePromptRules = configStore.get().defaults?.promptRules || "";
 		const callRefine = (sid, resume) =>
 			refineOrAsk(
 				issue,
@@ -579,6 +594,7 @@ export class ForgeAgent {
 					repoCwd,
 					repoTrees,
 					repoAccessMode: repoCwd ? "tools" : "tree",
+					promptRules: refinePromptRules,
 					...(sid ? { sessionId: sid, resumeSession: resume } : {}),
 				},
 				model,
@@ -735,7 +751,7 @@ export class ForgeAgent {
 		} = ident;
 
 		const { valid } = this._validateSelections(this._normalizeFileSelections(rawFiles), repoTrees);
-		const capped = this._capSelections(valid);
+		const capped = this._capSelections(valid, "fix");
 
 		emit({
 			type: "progress",
@@ -745,10 +761,11 @@ export class ForgeAgent {
 		const fileContents = await this._fetchFiles(capped, emit);
 
 		emit({ type: "progress", step: "generate_fix", message: `Fixing CI failure with ${this._agentLabel}...` });
+		const ciPromptRules = configStore.get().defaults?.promptRules || "";
 		const propose = await proposeFix(
 			issue,
 			fileContents,
-			{ ciContext, repos: this.allRepos },
+			{ ciContext, repos: this.allRepos, promptRules: ciPromptRules },
 			model,
 			this.agent,
 			{ signal },
@@ -859,6 +876,16 @@ export class ForgeAgent {
 		}
 
 		const provider = this._provider(repo);
+
+		// Rebase onto latest main before pushing so CI runs against current code.
+		try {
+			const mrs = await provider.listAllForgeMRs();
+			const mr = mrs.find((m) => m.source_branch === branchName);
+			if (mr && provider.supportsRebase) {
+				await provider.rebaseMR(mr.iid);
+			}
+		} catch { /* rebase failure is non-fatal — push will still work */ }
+
 		const actions = changes.map((c) => ({ action: c.action, file_path: c.file, content: c.proposed }));
 		const subject = buildCommitSubject(analysis);
 		const commitMessage = buildCommitMessage(subject, changes, analysis, "ci-fix");