@ipul-labs/forge 1.13.0

package/server/forge/core/agentClient.js

@@ -0,0 +1,36 @@
+/**
+ * server/forge/core/agentClient.js
+ *
+ * Thin dispatcher — routes agent calls to the selected backend (claude | openclaw).
+ * ForgeAgent always calls this instead of importing claudeClient directly.
+ *
+ * The trailing `opts` argument may carry `{ signal }` — when present, it is
+ * forwarded to the backend so a cancelled job tears down the underlying CLI
+ * subprocess or HTTP request instead of running to completion.
+ */
+
+import * as claude from "./claudeClient.js";
+import * as openclaw from "./openclawClient.js";
+
+/**
+ * @param {string} [agent] - "claude" | "openclaw"
+ */
+function backend(agent) {
+	return agent === "openclaw" ? openclaw : claude;
+}
+
+export function identifyRelevantFiles(issue, fileTree, model, agent, opts) {
+	return backend(agent).identifyRelevantFiles(issue, fileTree, model, opts);
+}
+
+export function proposeFix(issue, fileContents, options, model, agent, opts) {
+	return backend(agent).proposeFix(issue, fileContents, options, model, opts);
+}
+
+export function refineOrAsk(issue, fileContents, options, model, agent, onEvent, opts) {
+	return backend(agent).refineOrAsk(issue, fileContents, options, model, onEvent, opts);
+}
+
+export function checkResolution(issue, diffs, model, agent, opts) {
+	return backend(agent).checkResolution(issue, diffs, model, opts);
+}

package/server/forge/core/branchName.js

@@ -0,0 +1,41 @@
+/**
+ * server/forge/core/branchName.js
+ *
+ * Shared branch-name derivation so the validator's local workspace checkout
+ * and the provider's remote branch end up on the same name — "follow the code
+ * change intention, no timestamps".
+ */
+
+const CONV_PREFIX = /^(?:feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)(?:\([^)]+\))?!?:\s*/i;
+
+const MAX_SLUG_LEN = 32;
+
+export function slugifyIntent(text) {
+	const stripped = String(text || "")
+		.replace(CONV_PREFIX, "")
+		.toLowerCase()
+		.normalize("NFKD")
+		.replace(/[^\w\s-]/g, "")
+		.trim()
+		.replace(/[\s_]+/g, "-")
+		.replace(/-+/g, "-")
+		.replace(/^-+|-+$/g, "");
+	if (stripped.length <= MAX_SLUG_LEN) return stripped;
+	// Truncate on a word boundary so the branch name reads like a phrase,
+	// not a mid-word cutoff ("...div-attri"). Fall back to hard cut if the
+	// first word is already too long.
+	const hardCut = stripped.slice(0, MAX_SLUG_LEN);
+	const lastDash = hardCut.lastIndexOf("-");
+	const soft = lastDash > 0 ? hardCut.slice(0, lastDash) : hardCut;
+	return soft.replace(/-+$/g, "");
+}
+
+/**
+ * Branch name derives from the *issue title* rather than the model's mrTitle,
+ * so the branch stays stable across refines / CI-fix loops (which rewrite
+ * mrTitle to describe the latest edit instead of the overall change body).
+ */
+export function branchNameFor(issueIid, analysis) {
+	const slug = slugifyIntent(analysis?.issue?.title || analysis?.mrTitle || "");
+	return slug ? `forge/issue-${issueIid}-${slug}` : `forge/issue-${issueIid}`;
+}

package/server/forge/core/claudeClient.js

@@ -0,0 +1,356 @@
+/**
+ * server/forge/core/claudeClient.js
+ *
+ * Shells out to the `claude` CLI (Claude Code) instead of the Anthropic SDK.
+ * Uses your Claude Code subscription — no separate API credits needed.
+ *
+ * Requires: `claude` CLI installed and authenticated (`claude auth login`)
+ *
+ * Quota headers are NOT available via the CLI — see `quotaClient.js` for a
+ * user-triggered probe that hits the Messages API once to read them.
+ */
+
+import { spawn } from "child_process";
+import {
+	SELECT_FILES_SCHEMA,
+	PROPOSE_FIX_SCHEMA,
+	REFINE_OR_ASK_SCHEMA,
+	RESOLUTION_CHECK_SCHEMA,
+	buildIdentifyFilesPrompt,
+	buildProposeFixPrompt,
+	buildRefineOrAskPrompt,
+	buildRefineResumePrompt,
+	buildCheckResolutionPrompt,
+} from "./prompts.js";
+
+// FORGE_MODEL env var overrides the default. Set to a cheaper model to reduce cost.
+// e.g. FORGE_MODEL=claude-haiku-4-5-20251001
+const MODEL = process.env.FORGE_MODEL ?? "claude-sonnet-4-6";
+const FALLBACK_MODEL = process.env.FORGE_FALLBACK_MODEL ?? "claude-haiku-4-5-20251001";
+const CLAUDE_BIN = process.env.CLAUDE_BIN ?? "claude";
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+function extractJSON(text) {
+	const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/);
+	if (fenced) return JSON.parse(fenced[1].trim());
+	const start = text.indexOf("{");
+	const end = text.lastIndexOf("}");
+	if (start !== -1 && end !== -1) return JSON.parse(text.slice(start, end + 1));
+	throw new Error("No JSON found in response");
+}
+
+function shortenPath(p, cwd) {
+	if (!p || typeof p !== "string") return p;
+	if (cwd && p.startsWith(cwd + "/")) return p.slice(cwd.length + 1);
+	if (cwd && p === cwd) return ".";
+	return p;
+}
+
+/**
+ * Translate a stream-json `tool_use` block into a user-friendly one-line log.
+ * Returns null for tools we don't want to surface (filters out noise).
+ */
+function formatToolUse(block, cwd) {
+	const name = block?.name;
+	const input = block?.input ?? {};
+	switch (name) {
+		case "Read": {
+			const path = shortenPath(input.file_path, cwd);
+			return path ? `Reading ${path}` : null;
+		}
+		case "Glob": {
+			if (!input.pattern) return null;
+			const where = input.path ? ` in ${shortenPath(input.path, cwd)}` : "";
+			return `Globbing ${input.pattern}${where}`;
+		}
+		case "Grep": {
+			if (!input.pattern) return null;
+			const where = input.path ? ` in ${shortenPath(input.path, cwd)}` : "";
+			return `Grepping ${JSON.stringify(input.pattern)}${where}`;
+		}
+		default:
+			return null;
+	}
+}
+
+async function runClaude(prompt, jsonSchema, systemPrompt, model, options = {}) {
+	const { cwd, allowedTools, onEvent, sessionId, resumeSession, signal } = options;
+	if (signal?.aborted) {
+		const err = new Error("Claude CLI call cancelled before start.");
+		err.name = "AbortError";
+		throw err;
+	}
+	const streaming = typeof onEvent === "function";
+	const args = [
+		"--print",
+		"--output-format", streaming ? "stream-json" : "json",
+		...(streaming ? ["--verbose"] : []),
+		"--model", model ?? MODEL,
+		"--fallback-model", FALLBACK_MODEL,
+		// Kill every tool by default: without this, Claude sometimes picks up
+		// TodoWrite/Task/WebSearch and spends turns on them, returning
+		// stop_reason=end_turn with an empty result. When the caller explicitly
+		// passes allowedTools (e.g. refine with repo access), allow only those.
+		// NOTE: we can't use `--bare` — it disables keychain/OAuth reads, which
+		// breaks the Claude Code subscription auth path.
+		...(allowedTools?.length
+			? ["--allowed-tools", allowedTools.join(",")]
+			: ["--tools", ""]),
+		// Skip user/project/local settings (hooks, agents, CLAUDE.md cascade,
+		// auto-mode, memory). Loading those was causing extra turns that came
+		// back with stop_reason=end_turn and result="". Verified: same prompt
+		// goes from failing at turns=2/3 → passing at turns=1 with this flag.
+		"--setting-sources", "",
+	];
+
+	// Session continuity for multi-turn refine:
+	//   resumeSession=true → --resume <uuid> (replays the conversation so Claude
+	//     keeps its prior reasoning, tool-call history, and prompt cache).
+	//   sessionId without resume → --session-id <uuid> (first turn; fixes the
+	//     UUID so subsequent turns can resume by the id we own).
+	if (resumeSession && sessionId) {
+		args.push("--resume", sessionId);
+	} else if (sessionId) {
+		args.push("--session-id", sessionId);
+	}
+
+	// NOTE: we deliberately do NOT pass --json-schema anymore. The CLI's schema
+	// validator rejects the model's first turn and retries on a second turn; if
+	// that also fails, we get stop_reason=end_turn with result="". The prompts
+	// already tell Claude to emit raw JSON and `extractJSON` is lenient enough
+	// to unwrap a stray fence or preamble. We validate shape on our side instead.
+	void jsonSchema;
+	// On resume, the system prompt is baked into the session from the first
+	// turn — re-passing it would stack a second system message.
+	if (systemPrompt && !resumeSession) args.push("--system-prompt", systemPrompt);
+
+	return new Promise((resolve, reject) => {
+		// Strip ANTHROPIC_API_KEY so the CLI uses the OAuth session
+		// (Claude Code subscription) rather than falling back to API credits.
+		const { ANTHROPIC_API_KEY: _removed, ...cleanEnv } = process.env;
+		const proc = spawn(CLAUDE_BIN, args, {
+			env: { ...cleanEnv, FORCE_COLOR: "0" },
+			stdio: ["pipe", "pipe", "pipe"],
+			...(cwd ? { cwd } : {}),
+		});
+
+		let stdout = "";
+		let stderr = "";
+		let streamBuffer = "";
+		let streamedResult = null;
+
+		const timer = setTimeout(() => {
+			proc.kill();
+			reject(new Error("claude CLI timed out after 5 minutes"));
+		}, 300_000);
+
+		// External abort (e.g. user cancelled the analysis). Kill the subprocess
+		// so we stop billing the subscription / token window for work the user
+		// has already discarded.
+		const onAbort = () => {
+			try { proc.kill(); } catch { /* ignore */ }
+			clearTimeout(timer);
+			const err = new Error("Claude CLI call cancelled.");
+			err.name = "AbortError";
+			reject(err);
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+		proc.on("close", () => { signal?.removeEventListener("abort", onAbort); });
+
+		proc.stdout.on("data", (d) => {
+			stdout += d;
+			if (!streaming) return;
+			streamBuffer += d.toString("utf8");
+			let nl;
+			while ((nl = streamBuffer.indexOf("\n")) !== -1) {
+				const line = streamBuffer.slice(0, nl).trim();
+				streamBuffer = streamBuffer.slice(nl + 1);
+				if (!line) continue;
+				let evt;
+				try { evt = JSON.parse(line); } catch { continue; }
+				if (evt.type === "assistant") {
+					const blocks = evt.message?.content ?? [];
+					for (const block of blocks) {
+						if (block.type !== "tool_use") continue;
+						const msg = formatToolUse(block, cwd);
+						if (msg) {
+							try { onEvent({ type: "log", message: msg }); } catch { /* swallow */ }
+						}
+					}
+				} else if (evt.type === "result") {
+					streamedResult = evt;
+				}
+			}
+		});
+		proc.stderr.on("data", (d) => { stderr += d; });
+
+		proc.on("close", (code) => {
+			clearTimeout(timer);
+			if (code !== 0) {
+				try {
+					const wrapper = streamedResult ?? JSON.parse(stdout.trim());
+					const msg = wrapper.result || wrapper.error || stderr.trim() || stdout.trim();
+					reject(new Error(`claude CLI error: ${msg}`));
+				} catch {
+					reject(new Error(`claude CLI error: ${stderr.trim() || stdout.trim()}`));
+				}
+				return;
+			}
+			let wrapper;
+			if (streaming) {
+				if (!streamedResult) {
+					reject(new Error(`claude CLI stream ended without a result event (${stdout.length} bytes). First 200 chars: ${stdout.slice(0, 200)}`));
+					return;
+				}
+				wrapper = streamedResult;
+			} else {
+				try {
+					wrapper = JSON.parse(stdout.trim());
+				} catch {
+					reject(new Error(`claude CLI returned non-JSON output (${stdout.length} bytes). First 200 chars: ${stdout.slice(0, 200)}`));
+					return;
+				}
+			}
+
+			const result = wrapper.result ?? "";
+			if (!result.trim()) {
+				// Claude succeeded but emitted no content. Usually means the model
+				// got stuck in a tool-use loop or was blocked by --disallowed-tools.
+				// Surface a clean, actionable message instead of dumping the wrapper.
+				const stopReason = wrapper.stop_reason ?? "unknown";
+				const turns = wrapper.num_turns ?? 0;
+				const hint = stopReason === "tool_use"
+					? "model tried to use a blocked tool — retry or allow the tool."
+					: "model produced empty output — retry or switch model.";
+				reject(new Error(`Claude returned no content (stop_reason: ${stopReason}, turns: ${turns}). ${hint}`));
+				return;
+			}
+
+			let data;
+			try {
+				data = extractJSON(result);
+			} catch (err) {
+				reject(new Error(`Claude response was not valid JSON — ${err.message}. First 200 chars of result: ${result.slice(0, 200)}`));
+				return;
+			}
+
+			// The CLI echoes the session id it actually used. If it doesn't match
+			// the one we passed (CLI version drift, resume silently forked to a
+			// new session, etc.), warn — the caller should persist the CLI's id
+			// going forward or we'll resume the wrong conversation next turn.
+			const wrapperSessionId = wrapper.session_id ?? null;
+			if (sessionId && wrapperSessionId && wrapperSessionId !== sessionId) {
+				console.warn(
+					`[claudeClient] session_id mismatch: passed ${sessionId}, CLI returned ${wrapperSessionId}. Using CLI value.`,
+				);
+			}
+
+			resolve({
+				data,
+				cost: wrapper.total_cost_usd ?? 0,
+				serviceTier: wrapper.usage?.service_tier ?? "unknown",
+				inputTokens: wrapper.usage?.input_tokens ?? 0,
+				outputTokens: wrapper.usage?.output_tokens ?? 0,
+				cacheCreationTokens: wrapper.usage?.cache_creation_input_tokens ?? 0,
+				cacheReadTokens: wrapper.usage?.cache_read_input_tokens ?? 0,
+				sessionId: wrapperSessionId ?? sessionId ?? null,
+			});
+		});
+
+		proc.stdin.write(prompt, "utf8");
+		proc.stdin.end();
+	});
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+export async function checkResolution(issue, diffs, model, opts = {}) {
+	const { data, cost, serviceTier, inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens } = await runClaude(
+		buildCheckResolutionPrompt(issue, diffs),
+		RESOLUTION_CHECK_SCHEMA,
+		"You are Forge, a code review assistant. Assess whether code changes actually fix the reported issue. Be concise and direct.",
+		model,
+		{ signal: opts.signal },
+	);
+	return { ...data, cost, serviceTier, inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens };
+}
+
+export async function identifyRelevantFiles(issue, fileTree, model, opts = {}) {
+	const { data, cost, serviceTier, inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens } = await runClaude(
+		buildIdentifyFilesPrompt(issue, fileTree),
+		SELECT_FILES_SCHEMA,
+		"You are Forge, a code review assistant. You only output raw JSON — never markdown or prose.",
+		model,
+		{ signal: opts.signal },
+	);
+	return { ...data, cost, serviceTier, inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens };
+}
+
+export async function refineOrAsk(issue, fileContents, options = {}, model, onEvent, opts = {}) {
+	const { repoCwd, sessionId, resumeSession } = options;
+	const hasRepoAccess = Boolean(repoCwd);
+	const accessLine = hasRepoAccess
+		? `You ARE running inside a checkout of the repo at the current working directory, with the user's proposed changes already overlaid on the working tree. You can use Read, Glob, and Grep to inspect any file in the repo. Use them when you need context beyond the files listed in the prompt.`
+		: `The prompt lists the file paths in the repo and the full content of the files currently in scope. Treat those as authoritative — do NOT claim you lack repo access. If you need a file that isn't attached, name the path and ask the user to share it.`;
+
+	// When resuming, the system prompt + issue/files/previousChanges are already
+	// in Claude's context from the initial turn — send only what's new.
+	const prompt = resumeSession
+		? buildRefineResumePrompt(options)
+		: buildRefineOrAskPrompt(issue, fileContents, options);
+
+	const runOptions = hasRepoAccess
+		? { cwd: repoCwd, allowedTools: ["Read", "Glob", "Grep"], onEvent }
+		: { onEvent };
+	if (sessionId) runOptions.sessionId = sessionId;
+	if (resumeSession) runOptions.resumeSession = true;
+	if (opts.signal) runOptions.signal = opts.signal;
+
+	const { data, cost, serviceTier, inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens, sessionId: returnedSessionId } = await runClaude(
+		prompt,
+		REFINE_OR_ASK_SCHEMA,
+		`You are Forge, an AI code assistant in a production React/TypeScript/Express codebase.
+${accessLine}
+You auto-classify the user's message: answer questions about state, or produce a refined code change when given a directive.
+Rules when producing changes:
+- Changes must be minimal and surgical.
+- Match the existing code style exactly (TypeScript strict, no barrel imports, Tailwind for UI).
+- For "proposed", always return the COMPLETE file content.
+- Maximum 5 files changed.
+- Never add console.* — use the existing log utility.
+- Never add comments unless the logic is non-obvious.
+Rules when answering:
+- Ground statements in the validation state, the proposed changes, and (when available) files you read from the working tree.
+- If validation hasn't been run yet, say so plainly.
+- Be concise — one to four short paragraphs at most.
+Your final message MUST be a single raw JSON object matching the schema — no prose, no code fences, no preamble.`,
+		model,
+		runOptions,
+	);
+	return { ...data, cost, serviceTier, inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens, sessionId: returnedSessionId };
+}
+
+export async function proposeFix(issue, fileContents, options = {}, model, opts = {}) {
+	const { data, cost, serviceTier, inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens } = await runClaude(
+		buildProposeFixPrompt(issue, fileContents, options),
+		PROPOSE_FIX_SCHEMA,
+		`You are Forge, an AI code assistant in a production React/TypeScript/Express codebase.
+Rules:
+- Changes must be minimal and surgical.
+- Match the existing code style exactly (TypeScript strict, no barrel imports, Tailwind for UI).
+- For "proposed", always return the COMPLETE file content, not a diff or snippet.
+- Maximum 5 files changed.
+- Never add console.* — use the existing log utility.
+- Never add comments unless the logic is non-obvious.
+- Before returning, verify TypeScript correctness: no implicit any, no missing imports, no type mismatches, all imported symbols must actually be exported from their source.
+- If fixing a CI failure, address only what the logs report — do not change unrelated code.
+Root-cause discipline:
+- A fix that only improves an error message or adds a guard at the point of failure is a symptom suppressor, not a fix. Reject it and find the upstream origin of the bad input.
+- When a value is undefined/null at a check, trace one or two frames up (the caller of the function, the prop passed into the component, the handler bound to an onClick). Default function parameters are defeated when the caller passes an unexpected argument (e.g. React forwarding a MouseEvent) — look for that class of bug before patching the consumer.
+- In "explanation", name the origin of the bad value and state why the reported symptom can no longer occur after your change.`,
+		model,
+		{ signal: opts.signal },
+	);
+	return { ...data, cost, serviceTier, inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens };
+}

package/server/forge/core/configStore.js

@@ -0,0 +1,214 @@
+/**
+ * Forge persistent config.
+ *
+ * Storage contract
+ * ────────────────
+ * A single JSON blob on disk (default: ~/.forge/config.json). Loaded once at
+ * process start into an in-memory cache so route handlers read synchronously.
+ * Writes are atomic (tmp-file + rename) and serialized to avoid interleaving.
+ *
+ * Swap to Redis or another backend by re-exporting a different instance from
+ * this module — callers import `get()` / `patch()` and don't know the source.
+ */
+
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+/** @typedef {{ id: string, label: string, projectType?: "auto" | "node" | "go" }} ForgeRepo */
+
+/**
+ * @typedef {{ baseUrl: string, token: string }} GitLabConnection
+ * @typedef {{ token: string }} GitHubConnection
+ * @typedef {{ token: string }} AzureDevOpsConnection
+ *
+ * @typedef {{
+ *   repos: ForgeRepo[],
+ *   defaults: {
+ *     model: string | null,
+ *     agent: string | null,
+ *     autoPushOnValidatePass: boolean,
+ *     refineRepoAccess: boolean,
+ *   },
+ *   connections: {
+ *     gitlab: GitLabConnection,
+ *     github: GitHubConnection,
+ *     azuredevops: AzureDevOpsConnection,
+ *   }
+ * }} ForgeConfig
+ */
+
+const BUILTIN_BASE_URLS = {
+	gitlab: "https://gitlab.com/api/v4",
+	github: "https://api.github.com",
+};
+
+/** @type {ForgeConfig} */
+const DEFAULT_CONFIG = {
+	repos: [],
+	defaults: {
+		model: null,
+		agent: null,
+		autoPushOnValidatePass: false,
+		// When true (default), Refine gets Read/Glob/Grep access to a local
+		// clone of the primary repo. Off → lighter "file tree in prompt" flow.
+		// The FORGE_REFINE_REPO_ACCESS env var, when set, overrides this.
+		refineRepoAccess: true,
+		// Test-deploy URL surfaced next to "Approve & Create MR" when the
+		// branch pipeline is green. Plain URL (e.g. "https://test.example.com")
+		// for a shared env; supports "{branch}" / "{slug}" placeholders when
+		// moving to ephemeral per-branch deploys.
+		testDeployUrlTemplate: "",
+	},
+	connections: {
+		gitlab: { baseUrl: BUILTIN_BASE_URLS.gitlab, token: "" },
+		github: { token: "" },
+		azuredevops: { token: "" },
+	},
+};
+
+function configPath() {
+	return process.env.FORGE_CONFIG_PATH ?? path.join(os.homedir(), ".forge", "config.json");
+}
+
+/**
+ * Synchronous load — called once at startup so the rest of the routes can
+ * read config without awaiting. If the file is missing we return defaults;
+ * if it's malformed we warn and return defaults (don't crash the server over
+ * a bad config).
+ */
+function loadSync() {
+	const p = configPath();
+	try {
+		const raw = fsSync.readFileSync(p, "utf8");
+		const parsed = JSON.parse(raw);
+		return mergeDeep(DEFAULT_CONFIG, parsed);
+	} catch (err) {
+		if (err.code === "ENOENT") return structuredClone(DEFAULT_CONFIG);
+		console.warn(`[forge] config file at ${p} is unreadable (${err.message}); using defaults`);
+		return structuredClone(DEFAULT_CONFIG);
+	}
+}
+
+/** @type {ForgeConfig} */
+let cache = loadSync();
+
+/** Serializes writes so two concurrent PUTs can't interleave. */
+let inFlight = Promise.resolve();
+
+async function writeToDisk(cfg) {
+	const p = configPath();
+	await fs.mkdir(path.dirname(p), { recursive: true });
+	const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+	await fs.writeFile(tmp, JSON.stringify(cfg, null, 2), "utf8");
+	// 0600 — owner read/write only. Belt-and-suspenders for when tokens land here.
+	await fs.chmod(tmp, 0o600);
+	await fs.rename(tmp, p);
+}
+
+function mergeDeep(base, patch) {
+	const out = Array.isArray(base) ? [...base] : { ...base };
+	for (const [k, v] of Object.entries(patch)) {
+		const bv = base?.[k];
+		if (
+			v !== null &&
+			typeof v === "object" &&
+			!Array.isArray(v) &&
+			bv !== null &&
+			typeof bv === "object" &&
+			!Array.isArray(bv)
+		) {
+			out[k] = mergeDeep(bv, v);
+		} else {
+			out[k] = v;
+		}
+	}
+	return out;
+}
+
+/** Returns the current cached config. Synchronous. */
+export function get() {
+	return cache;
+}
+
+/**
+ * Deep-merges `patch` into the current config, persists, and updates the
+ * cache. Arrays are replaced (not merged) so callers send the whole repos
+ * list when editing it.
+ */
+export function patch(delta) {
+	inFlight = inFlight.then(async () => {
+		const next = mergeDeep(cache, delta);
+		await writeToDisk(next);
+		cache = next;
+		return next;
+	});
+	return inFlight;
+}
+
+/** Escape hatch for tests / explicit reload from disk. */
+export function reload() {
+	cache = loadSync();
+	return cache;
+}
+
+const ENV_TOKEN_KEYS = {
+	gitlab: "GITLAB_TOKEN",
+	github: "GITHUB_TOKEN",
+	azuredevops: "AZURE_DEVOPS_TOKEN",
+};
+
+/**
+ * Resolved provider connection: config value wins, env var fills gaps, builtin
+ * URL is the last fallback. Providers call this instead of reading process.env.
+ *
+ * @param {"gitlab"|"github"|"azuredevops"} provider
+ * @returns {{ baseUrl?: string, token: string }}
+ */
+export function getConnection(provider) {
+	const fromCfg = cache.connections?.[provider] ?? {};
+	const envToken = process.env[ENV_TOKEN_KEYS[provider]] ?? "";
+	const baseUrl = fromCfg.baseUrl || BUILTIN_BASE_URLS[provider];
+	return {
+		...(baseUrl ? { baseUrl } : {}),
+		token: fromCfg.token || envToken,
+	};
+}
+
+function maskToken(t) {
+	if (!t) return "";
+	if (t.length <= 4) return "••••";
+	return `••••${t.slice(-4)}`;
+}
+
+/**
+ * Safe view for the API — raw tokens are replaced with a short hint and a
+ * boolean so the UI can render state without ever seeing a secret.
+ */
+export function getPublic() {
+	const cfg = cache;
+	const conn = cfg.connections ?? {};
+	return {
+		repos: cfg.repos,
+		defaults: cfg.defaults,
+		connections: {
+			gitlab: {
+				baseUrl: conn.gitlab?.baseUrl ?? BUILTIN_BASE_URLS.gitlab,
+				hasToken: Boolean(conn.gitlab?.token || process.env.GITLAB_TOKEN),
+				tokenHint: maskToken(conn.gitlab?.token || process.env.GITLAB_TOKEN || ""),
+				tokenSource: conn.gitlab?.token ? "config" : process.env.GITLAB_TOKEN ? "env" : "none",
+			},
+			github: {
+				hasToken: Boolean(conn.github?.token || process.env.GITHUB_TOKEN),
+				tokenHint: maskToken(conn.github?.token || process.env.GITHUB_TOKEN || ""),
+				tokenSource: conn.github?.token ? "config" : process.env.GITHUB_TOKEN ? "env" : "none",
+			},
+			azuredevops: {
+				hasToken: Boolean(conn.azuredevops?.token || process.env.AZURE_DEVOPS_TOKEN),
+				tokenHint: maskToken(conn.azuredevops?.token || process.env.AZURE_DEVOPS_TOKEN || ""),
+				tokenSource: conn.azuredevops?.token ? "config" : process.env.AZURE_DEVOPS_TOKEN ? "env" : "none",
+			},
+		},
+	};
+}