@ipul-labs/forge 1.13.0

package/server/forge/core/gitlabClient.js

@@ -0,0 +1,340 @@
+/**
+ * server/forge/core/gitlabClient.js
+ *
+ * Thin wrapper around the GitLab REST API v4.
+ * All calls use process.env.GITLAB_TOKEN for auth and
+ * process.env.FORGE_GITLAB_PROJECT for the default project path.
+ *
+ * Required env vars:
+ *   GITLAB_TOKEN          — personal access token or CI job token
+ *   FORGE_GITLAB_PROJECT  — project path, e.g. "ipul/web-app"
+ */
+
+const GITLAB_API = "https://gitlab.com/api/v4";
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+function authHeaders() {
+	return {
+		"PRIVATE-TOKEN": process.env.GITLAB_TOKEN,
+		"Content-Type": "application/json",
+	};
+}
+
+async function request(path, options = {}) {
+	const url = `${GITLAB_API}${path}`;
+	const res = await fetch(url, {
+		...options,
+		headers: { ...authHeaders(), ...options.headers },
+	});
+
+	if (!res.ok) {
+		const text = await res.text().catch(() => "");
+		throw new Error(`GitLab ${res.status} on ${path}: ${text}`);
+	}
+
+	return res.json();
+}
+
+function encodeProject(project) {
+	return encodeURIComponent(project ?? process.env.FORGE_GITLAB_PROJECT);
+}
+
+// ─── Issues ───────────────────────────────────────────────────────────────────
+
+/**
+ * Returns open issues for the project, newest first.
+ * @param {string} [project]
+ */
+export async function createIssue(title, description = "", project) {
+	return request(
+		`/projects/${encodeProject(project)}/issues`,
+		{
+			method: "POST",
+			body: JSON.stringify({ title, description }),
+		},
+	);
+}
+
+export async function updateIssue(issueIid, { title, description }, project) {
+	return request(`/projects/${encodeProject(project)}/issues/${issueIid}`, {
+		method: "PUT",
+		body: JSON.stringify({ title, description }),
+	});
+}
+
+export async function closeIssue(issueIid, project) {
+	return request(`/projects/${encodeProject(project)}/issues/${issueIid}`, {
+		method: "PUT",
+		body: JSON.stringify({ state_event: "close" }),
+	});
+}
+
+export async function listOpenIssues(project) {
+	return request(
+		`/projects/${encodeProject(project)}/issues?state=opened&order_by=updated_at&per_page=25`,
+	);
+}
+
+/**
+ * Returns a single issue by internal ID (iid).
+ * @param {number} issueIid
+ * @param {string} [project]
+ */
+export async function getIssue(issueIid, project) {
+	return request(
+		`/projects/${encodeProject(project)}/issues/${issueIid}`,
+	);
+}
+
+// ─── Repository ───────────────────────────────────────────────────────────────
+
+/**
+ * Returns the recursive file tree under `srcPath`.
+ * Filters to source files only (skips build artifacts, lock files, etc.).
+ * @param {string} [srcPath]
+ * @param {string} [ref]
+ * @param {string} [project]
+ */
+export async function getFileTree(srcPath = "src", ref = "main", project) {
+	const proj = encodeProject(project);
+	const allItems = [];
+	let page = 1;
+
+	while (true) {
+		const items = await request(
+			`/projects/${proj}/repository/tree` +
+				`?path=${srcPath}&recursive=true&ref=${ref}&per_page=100&page=${page}`,
+		);
+		allItems.push(...items);
+		if (items.length < 100) break;
+		page++;
+	}
+
+	return allItems
+		.filter((item) => item.type === "blob")
+		.filter((item) => /\.(ts|tsx|js|jsx|json|css|yaml|yml|md)$/.test(item.path))
+		.map((item) => item.path);
+}
+
+/**
+ * Returns the decoded UTF-8 content of a single file.
+ * @param {string} filePath
+ * @param {string} [ref]
+ * @param {string} [project]
+ */
+export async function getFileContent(filePath, ref = "main", project) {
+	const encoded = encodeURIComponent(filePath);
+	const data = await request(
+		`/projects/${encodeProject(project)}/repository/files/${encoded}?ref=${ref}`,
+	);
+	return Buffer.from(data.content, "base64").toString("utf-8");
+}
+
+// ─── Mutations ────────────────────────────────────────────────────────────────
+
+/**
+ * Creates a new branch from `ref`.
+ * @param {string} branchName
+ * @param {string} [ref]
+ * @param {string} [project]
+ */
+export async function createBranch(branchName, ref = "main", project) {
+	return request(
+		`/projects/${encodeProject(project)}/repository/branches`,
+		{
+			method: "POST",
+			body: JSON.stringify({ branch: branchName, ref }),
+		},
+	);
+}
+
+/**
+ * Commits multiple file changes in a single commit.
+ * @param {string} branch
+ * @param {string} commitMessage
+ * @param {Array<{action: string, file_path: string, content: string}>} actions
+ * @param {string} [project]
+ */
+export async function commitFiles(branch, commitMessage, actions, project) {
+	return request(
+		`/projects/${encodeProject(project)}/repository/commits`,
+		{
+			method: "POST",
+			body: JSON.stringify({ branch, commit_message: commitMessage, actions }),
+		},
+	);
+}
+
+/**
+ * Opens a merge request from `sourceBranch` into `targetBranch`.
+ * @param {{ sourceBranch: string, targetBranch?: string, title: string, description?: string }} opts
+ * @param {string} [project]
+ */
+export async function createMR(
+	{ sourceBranch, targetBranch = "main", title, description = "" },
+	project,
+) {
+	return request(
+		`/projects/${encodeProject(project)}/merge_requests`,
+		{
+			method: "POST",
+			body: JSON.stringify({
+				source_branch: sourceBranch,
+				target_branch: targetBranch,
+				title,
+				description,
+				remove_source_branch: true,
+			}),
+		},
+	);
+}
+
+/**
+ * Returns open MRs created by Forge for a specific issue (branch prefix forge/issue-{iid}-).
+ * @param {number} issueIid
+ * @param {string} [project]
+ */
+/**
+ * Returns all open MRs created by Forge (branch prefix forge/).
+ * Includes head_pipeline for quick status display.
+ * @param {string} [project]
+ */
+export async function listAllForgeMRs(project) {
+	const all = await request(
+		`/projects/${encodeProject(project)}/merge_requests?state=opened&per_page=50`,
+	);
+	return all.filter((mr) => mr.source_branch?.startsWith("forge/"));
+}
+
+export async function listForgeMRsForIssue(issueIid, project) {
+	const all = await request(
+		`/projects/${encodeProject(project)}/merge_requests?state=opened&per_page=50`,
+	);
+	return all.filter((mr) =>
+		mr.source_branch?.startsWith(`forge/issue-${issueIid}-`),
+	);
+}
+
+/**
+ * Returns merged MRs created by Forge for a specific issue.
+ * @param {number} issueIid
+ * @param {string} [project]
+ */
+export async function listMergedForgeMRsForIssue(issueIid, project) {
+	const all = await request(
+		`/projects/${encodeProject(project)}/merge_requests?state=merged&per_page=50`,
+	);
+	return all.filter((mr) =>
+		mr.source_branch?.startsWith(`forge/issue-${issueIid}-`),
+	);
+}
+
+// ─── Jobs ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Returns the plain-text trace (log output) for a single job.
+ * @param {number} jobId
+ * @param {string} [project]
+ */
+export async function getJobTrace(jobId, project) {
+	const proj = encodeProject(project);
+	const url = `${GITLAB_API}/projects/${proj}/jobs/${jobId}/trace`;
+	const res = await fetch(url, { headers: authHeaders() });
+	if (!res.ok) {
+		const text = await res.text().catch(() => "");
+		throw new Error(`GitLab ${res.status} on jobs/${jobId}/trace: ${text}`);
+	}
+	return res.text();
+}
+
+// ─── MR detail + rebase ───────────────────────────────────────────────────────
+
+/**
+ * Returns a single MR with full detail including conflict/rebase status.
+ * @param {number} mrIid
+ * @param {string} [project]
+ */
+export async function getMR(mrIid, project) {
+	return request(
+		`/projects/${encodeProject(project)}/merge_requests/${mrIid}`,
+	);
+}
+
+/**
+ * Triggers a rebase of the MR source branch onto the target branch.
+ * @param {number} mrIid
+ * @param {string} [project]
+ */
+export async function rebaseMR(mrIid, project) {
+	return request(
+		`/projects/${encodeProject(project)}/merge_requests/${mrIid}/rebase`,
+		{ method: "PUT" },
+	);
+}
+
+/**
+ * Returns the diff for a merge request (all changed files).
+ * @param {number} mrIid
+ * @param {string} [project]
+ */
+export async function getMRDiffs(mrIid, project) {
+	const proj = encodeProject(project);
+	const allDiffs = [];
+	let page = 1;
+	while (true) {
+		const items = await request(
+			`/projects/${proj}/merge_requests/${mrIid}/diffs?per_page=20&page=${page}`,
+		);
+		allDiffs.push(...items);
+		if (items.length < 20) break;
+		page++;
+	}
+	return allDiffs;
+}
+
+// ─── Pipelines ────────────────────────────────────────────────────────────────
+
+/**
+ * Returns all pipelines associated with an MR.
+ * @param {number} mrIid
+ * @param {string} [project]
+ */
+export async function getMRPipelines(mrIid, project) {
+	return request(
+		`/projects/${encodeProject(project)}/merge_requests/${mrIid}/pipelines`,
+	);
+}
+
+/**
+ * Returns a single pipeline with full status detail.
+ * @param {number} pipelineId
+ * @param {string} [project]
+ */
+export async function getPipeline(pipelineId, project) {
+	return request(
+		`/projects/${encodeProject(project)}/pipelines/${pipelineId}`,
+	);
+}
+
+/**
+ * Returns all jobs for a pipeline.
+ * @param {number} pipelineId
+ * @param {string} [project]
+ */
+export async function getPipelineJobs(pipelineId, project) {
+	return request(
+		`/projects/${encodeProject(project)}/pipelines/${pipelineId}/jobs`,
+	);
+}
+
+/**
+ * Returns pipelines that ran on a specific commit SHA.
+ * @param {string} sha
+ * @param {string} [project]
+ */
+export async function getProjectPipelinesBySha(sha, project) {
+	return request(
+		`/projects/${encodeProject(project)}/pipelines?sha=${encodeURIComponent(sha)}&per_page=5`,
+	);
+}

package/server/forge/core/jobs.js

@@ -0,0 +1,180 @@
+/**
+ * server/forge/core/jobs.js
+ *
+ * Unified in-memory job store with event buffering + multi-subscriber replay.
+ *
+ * Why this exists: SSE endpoints like refine / ci-fix / validate / analyze
+ * run a long task and stream events to one EventSource. If the browser
+ * reloads or React re-mounts the component, that stream dies. Before this
+ * module, the job also died — its state was deleted the moment the stream
+ * was consumed, so there was nothing to reconnect to.
+ *
+ * With this store:
+ *   1. `createJob(type, runner)` starts the runner immediately in the
+ *      background and buffers every event it emits.
+ *   2. `subscribe(id, handler)` replays the buffer synchronously, then wires
+ *      the handler to future events until the job is terminal.
+ *   3. A reconnecting client gets the full history on reconnect and then
+ *      live events — identical to if it had been watching all along.
+ *
+ * Process-restart survival is out of scope for v1 (Map is in-memory only).
+ */
+
+const TTL_MS = 10 * 60 * 1000;
+const SWEEP_INTERVAL_MS = 60 * 1000;
+
+const jobs = new Map();
+let sweeper = null;
+
+function ensureSweeper() {
+	if (sweeper) return;
+	sweeper = setInterval(() => {
+		const now = Date.now();
+		for (const [id, job] of jobs) {
+			if (job.expiresAt && job.expiresAt <= now && job.subscribers.size === 0) {
+				jobs.delete(id);
+			}
+		}
+	}, SWEEP_INTERVAL_MS);
+	sweeper.unref?.();
+}
+
+function newId(prefix) {
+	return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+/**
+ * Create and start a job. `runner` is an async function that receives
+ * `(send, signal)` — any value it returns is captured as `doneResult`.
+ * A terminal `done`, `error`, or `cancelled` event is emitted automatically
+ * when runner settles; runners must not emit those themselves.
+ *
+ * The `signal` is an `AbortSignal` that fires when a client calls `cancelJob`.
+ * Runners should forward it to any subprocess / fetch / SDK call that
+ * supports AbortSignal so the underlying work actually stops (and API/CLI
+ * costs aren't incurred for work the user no longer wants).
+ */
+export function createJob(type, runner, { idPrefix = type } = {}) {
+	ensureSweeper();
+	const id = newId(idPrefix);
+	const controller = new AbortController();
+	const job = {
+		id,
+		type,
+		status: "running",
+		events: [],
+		doneResult: undefined,
+		error: null,
+		createdAt: Date.now(),
+		finishedAt: null,
+		expiresAt: null,
+		subscribers: new Set(),
+		controller,
+	};
+	jobs.set(id, job);
+
+	const send = (event) => {
+		job.events.push(event);
+		for (const sub of job.subscribers) {
+			try { sub(event); } catch { /* subscriber errors don't break fanout */ }
+		}
+	};
+
+	(async () => {
+		try {
+			const result = await runner(send, controller.signal);
+			if (job.status === "cancelled") return;
+			job.doneResult = result ?? null;
+			job.status = "done";
+			send({ type: "done" });
+		} catch (e) {
+			if (job.status === "cancelled") return;
+			// If the runner threw because of our own abort, prefer the cancelled
+			// terminal over a misleading error event.
+			if (controller.signal.aborted) {
+				job.status = "cancelled";
+				send({ type: "cancelled" });
+				return;
+			}
+			job.status = "error";
+			job.error = e?.message ?? String(e);
+			send({ type: "error", message: job.error });
+		} finally {
+			job.finishedAt = Date.now();
+			job.expiresAt = job.finishedAt + TTL_MS;
+		}
+	})();
+
+	return id;
+}
+
+/**
+ * Cancel a running job. Aborts the signal, emits a terminal `cancelled`
+ * event, and marks the job non-running. No-op if the job is already
+ * terminal or doesn't exist — returns whether a cancel was actually issued.
+ */
+export function cancelJob(id) {
+	const job = jobs.get(id);
+	if (!job) return false;
+	if (job.status !== "running") return false;
+	job.status = "cancelled";
+	try {
+		job.controller.abort();
+	} catch { /* ignore */ }
+	// Emit the terminal *before* the runner's catch block runs, so reconnecting
+	// clients always see a cancellation event in the buffer.
+	job.events.push({ type: "cancelled" });
+	for (const sub of job.subscribers) {
+		try { sub({ type: "cancelled" }); } catch { /* ignore */ }
+	}
+	job.finishedAt = Date.now();
+	job.expiresAt = job.finishedAt + TTL_MS;
+	return true;
+}
+
+export function getJob(id) {
+	return jobs.get(id) ?? null;
+}
+
+/**
+ * Replay buffered events to `handler`, then subscribe for live events until
+ * the job reaches terminal state. Returns an `unsubscribe` function, or
+ * `null` if the job doesn't exist.
+ *
+ * The terminal `done`/`error` event is part of the buffered replay — callers
+ * that want to end the response on terminal should check for it inside
+ * their handler.
+ */
+export function subscribe(id, handler) {
+	const job = jobs.get(id);
+	if (!job) return null;
+
+	for (const e of job.events) {
+		try { handler(e); } catch { /* ignore */ }
+	}
+
+	if (job.status !== "running") {
+		return () => {};
+	}
+
+	job.subscribers.add(handler);
+	return () => { job.subscribers.delete(handler); };
+}
+
+/**
+ * Public status snapshot — safe to send to clients. Excludes the event
+ * buffer (potentially large) and subscribers (not serialisable).
+ */
+export function snapshot(id) {
+	const job = jobs.get(id);
+	if (!job) return null;
+	return {
+		id: job.id,
+		type: job.type,
+		status: job.status,
+		createdAt: job.createdAt,
+		finishedAt: job.finishedAt,
+		error: job.error,
+		eventCount: job.events.length,
+	};
+}

package/server/forge/core/k8s.js

@@ -0,0 +1,54 @@
+import * as k8s from "@kubernetes/client-node";
+
+let kc = new k8s.KubeConfig();
+
+function loadConfig() {
+	kc = new k8s.KubeConfig();
+	const token = process.env.K8S_CLUSTER_TOKEN;
+	const server = process.env.K8S_CLUSTER_SERVER;
+
+	if (token && server) {
+		kc.loadFromOptions({
+			clusters: [{ name: "cluster", server, skipTLSVerify: process.env.K8S_SKIP_TLS_VERIFY === "true" }],
+			users: [{ name: "admin", token }],
+			contexts: [{ name: "default", cluster: "cluster", user: "admin" }],
+			currentContext: "default",
+		});
+	} else {
+		kc.loadFromDefault();
+	}
+}
+
+loadConfig();
+
+function getAppsApi() {
+	return kc.makeApiClient(k8s.AppsV1Api);
+}
+
+function formatDeployment(dep) {
+	const containers = dep.spec?.template?.spec?.containers || [];
+	const status = dep.status || {};
+	return {
+		name: dep.metadata?.name,
+		namespace: dep.metadata?.namespace,
+		image: containers[0]?.image || "unknown",
+		replicas: {
+			desired: dep.spec?.replicas || 0,
+			ready: status.readyReplicas || 0,
+			available: status.availableReplicas || 0,
+			unavailable: status.unavailableReplicas || 0,
+			updated: status.updatedReplicas || 0,
+		},
+		conditions: (status.conditions || []).map((c) => ({
+			type: c.type,
+			status: c.status,
+			message: c.message,
+		})),
+	};
+}
+
+export async function listDeployments(namespace) {
+	const api = getAppsApi();
+	const res = await api.listNamespacedDeployment({ namespace });
+	return (res.items || []).map(formatDeployment);
+}

package/server/forge/core/localRepo.js

@@ -0,0 +1,136 @@
+/**
+ * server/forge/core/localRepo.js
+ *
+ * Shared helpers for maintaining a shallow working clone of a repo under
+ * ~/.forge/cache/<repo>/ and overlaying proposed file changes onto it.
+ *
+ * Used by:
+ *   - validator.js → run lint/typecheck/test against the overlaid tree
+ *   - ForgeAgent.refineIssue → give the refine model real Read/Glob/Grep access
+ *     against the current state of the working tree (FORGE_REFINE_REPO_ACCESS)
+ *
+ * Scope matches validator v1: GitLab HTTPS clones only. GitHub / Azure DevOps
+ * raise a clear "not supported yet" error so the caller can fall back cleanly.
+ */
+
+import { spawn } from "child_process";
+import fs from "fs/promises";
+import os from "os";
+import path from "path";
+
+const CACHE_ROOT = process.env.FORGE_VALIDATE_CACHE
+	?? path.join(os.homedir(), ".forge", "cache");
+
+function runGit(args, opts = {}, onLog) {
+	return new Promise((resolve) => {
+		const proc = spawn("git", args, {
+			...opts,
+			env: { ...process.env, ...(opts.env ?? {}), FORCE_COLOR: "0", NO_COLOR: "1", TERM: "dumb" },
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+		const lines = [];
+		const collect = (buf) => {
+			for (const raw of buf.toString().split("\n")) {
+				const line = raw.replace(/\r$/, "");
+				if (!line) continue;
+				lines.push(line);
+				onLog?.(line);
+			}
+		};
+		proc.stdout.on("data", collect);
+		proc.stderr.on("data", collect);
+		proc.on("error", (err) => resolve({ code: -1, output: lines.join("\n"), error: err.message }));
+		proc.on("close", (code) => resolve({ code: code ?? -1, output: lines.join("\n"), error: null }));
+	});
+}
+
+async function exists(p) {
+	try { await fs.access(p); return true; } catch { return false; }
+}
+
+function sanitizeRepo(repo) {
+	return repo.replace(/[^a-zA-Z0-9_./-]/g, "_");
+}
+
+function gitlabCloneUrl(project) {
+	const token = process.env.GITLAB_TOKEN;
+	if (!token) throw new Error("GITLAB_TOKEN is required to clone the repo locally.");
+	return `https://oauth2:${token}@gitlab.com/${project}.git`;
+}
+
+function resolveCloneUrl(repoInput) {
+	const colon = repoInput.indexOf(":");
+	if (colon > 0) {
+		const prefix = repoInput.slice(0, colon).toLowerCase();
+		if (prefix === "gitlab") return gitlabCloneUrl(repoInput.slice(colon + 1));
+		if (prefix === "github" || prefix === "azuredevops" || prefix === "azure") {
+			throw new Error(`Local clone for ${prefix} repos isn't supported yet — GitLab only.`);
+		}
+	}
+	return gitlabCloneUrl(repoInput);
+}
+
+export function cachePathFor(repo) {
+	return path.join(CACHE_ROOT, sanitizeRepo(repo));
+}
+
+/**
+ * Ensures the repo is cloned and reset to a clean branch at origin/main.
+ * Reuses any existing clone under ~/.forge/cache/<repo>/.
+ *
+ * @param {string} repo        Repo id (may carry a "gitlab:" prefix)
+ * @param {string} branchName  Workspace branch to check out
+ * @param {(msg: string) => void} [onLog]
+ * @returns {Promise<string>}  Absolute path to the working tree
+ */
+export async function ensureWorkingTree(repo, branchName, onLog) {
+	const dir = cachePathFor(repo);
+	const hasRepo = await exists(path.join(dir, ".git"));
+	const log = (m) => onLog?.(m);
+
+	if (!hasRepo) {
+		log(`Cloning ${repo} → ${dir}`);
+		await fs.mkdir(dir, { recursive: true });
+		const clone = await runGit(["clone", "--depth=1", resolveCloneUrl(repo), dir], {}, onLog);
+		if (clone.code !== 0) throw new Error(`git clone failed (code ${clone.code})`);
+	} else {
+		log(`Reusing clone at ${dir}`);
+	}
+
+	const fetch = await runGit(["fetch", "--depth=1", "origin", "main"], { cwd: dir }, onLog);
+	if (fetch.code !== 0) throw new Error(`git fetch failed (code ${fetch.code})`);
+
+	const reset = await runGit(["reset", "--hard", "origin/main"], { cwd: dir }, onLog);
+	if (reset.code !== 0) throw new Error(`git reset failed (code ${reset.code})`);
+	await runGit(["clean", "-fd"], { cwd: dir }, onLog);
+
+	const checkout = await runGit(["checkout", "-B", branchName], { cwd: dir }, onLog);
+	if (checkout.code !== 0) throw new Error(`git checkout ${branchName} failed (code ${checkout.code})`);
+
+	return dir;
+}
+
+/**
+ * Writes proposed file contents into the working tree (or deletes files for
+ * action="delete"). Refuses paths that escape the clone directory.
+ *
+ * @param {string} dir
+ * @param {Array<{file: string, action: 'create'|'modify'|'delete', proposed?: string}>} changes
+ * @param {(msg: string) => void} [onLog]
+ */
+export async function overlayChanges(dir, changes, onLog) {
+	for (const c of changes) {
+		const full = path.join(dir, c.file);
+		if (!full.startsWith(dir + path.sep) && full !== dir) {
+			throw new Error(`Refusing to write outside clone dir: ${c.file}`);
+		}
+		if (c.action === "delete") {
+			await fs.rm(full, { force: true });
+			onLog?.(`- ${c.file}`);
+		} else {
+			await fs.mkdir(path.dirname(full), { recursive: true });
+			await fs.writeFile(full, c.proposed ?? "");
+			onLog?.(`+ ${c.file} (${c.action})`);
+		}
+	}
+}