@ipul-labs/forge 1.13.0

package/server/forge/core/providers/azuredevops.js

@@ -0,0 +1,408 @@
+/**
+ * server/forge/core/providers/azuredevops.js
+ *
+ * Azure DevOps REST API implementation of ScmProvider.
+ * Maps Work Items → issues, Pull Requests → MRs, Pipelines → CI.
+ *
+ * Required env vars:
+ *   AZURE_DEVOPS_TOKEN   — Personal Access Token (Base64 or raw PAT)
+ *   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 (often same as project)
+ *
+ * Optional:
+ *   AZURE_DEVOPS_BASE_BRANCH  — default target branch (default: "main")
+ */
+
+import { getConnection } from "../configStore.js";
+import { ScmProvider } from "./base.js";
+
+export class AzureDevOpsProvider extends ScmProvider {
+	/**
+	 * @param {string} [repo]  "org/project/repo" — overrides env vars
+	 */
+	constructor(repo) {
+		super();
+		if (repo && repo.includes("/")) {
+			const parts = repo.split("/");
+			this._org = parts[0];
+			this._project = parts[1];
+			this._repo = parts[2] ?? parts[1];
+		} else {
+			this._org = process.env.AZURE_DEVOPS_ORG ?? "";
+			this._project = process.env.AZURE_DEVOPS_PROJECT ?? "";
+			this._repo = process.env.AZURE_DEVOPS_REPO ?? this._project;
+		}
+		this._defaultBranch = process.env.AZURE_DEVOPS_BASE_BRANCH ?? "main";
+		this._vsBase = `https://dev.azure.com/${this._org}`;
+		this._vssmBase = `https://vsrm.dev.azure.com/${this._org}`;
+	}
+
+	get name() { return "azuredevops"; }
+	get supportsRebase() { return false; }
+
+	// ─── Internal helpers ──────────────────────────────────────────────────────
+
+	_headers() {
+		const token = getConnection("azuredevops").token;
+		// ADO accepts Basic auth with a PAT as the password (username can be anything)
+		const encoded = Buffer.from(`:${token}`).toString("base64");
+		return {
+			Authorization: `Basic ${encoded}`,
+			"Content-Type": "application/json",
+		};
+	}
+
+	_gitBase() {
+		return `${this._vsBase}/${encodeURIComponent(this._project)}/_apis/git/repositories/${encodeURIComponent(this._repo)}`;
+	}
+
+	_witBase() {
+		return `${this._vsBase}/${encodeURIComponent(this._project)}/_apis/wit`;
+	}
+
+	_pipelineBase() {
+		return `${this._vsBase}/${encodeURIComponent(this._project)}/_apis/pipelines`;
+	}
+
+	_buildBase() {
+		return `${this._vsBase}/${encodeURIComponent(this._project)}/_apis/build`;
+	}
+
+	async _req(url, options = {}) {
+		const sep = url.includes("?") ? "&" : "?";
+		const versioned = url.includes("api-version") ? url : `${url}${sep}api-version=7.1`;
+		const res = await fetch(versioned, {
+			...options,
+			headers: { ...this._headers(), ...options.headers },
+		});
+		if (res.status === 204) return null;
+		if (!res.ok) {
+			const text = await res.text().catch(() => "");
+			throw new Error(`AzureDevOps ${res.status} on ${url}: ${text}`);
+		}
+		return res.json();
+	}
+
+	// ─── Normalizers ──────────────────────────────────────────────────────────
+
+	_issue(raw) {
+		const fields = raw.fields ?? {};
+		return {
+			iid: raw.id,
+			title: fields["System.Title"] ?? "",
+			description: fields["System.Description"] ?? null,
+			labels: (fields["System.Tags"] ?? "").split(";").map((t) => t.trim()).filter(Boolean),
+			author: { name: fields["System.CreatedBy"]?.displayName ?? "" },
+			created_at: fields["System.CreatedDate"] ?? "",
+			web_url: raw._links?.html?.href ?? "",
+		};
+	}
+
+	_mr(raw) {
+		const status = raw.status ?? "";
+		return {
+			iid: raw.pullRequestId,
+			title: raw.title,
+			web_url: `${this._vsBase}/${encodeURIComponent(this._project)}/_git/${encodeURIComponent(this._repo)}/pullrequest/${raw.pullRequestId}`,
+			source_branch: (raw.sourceRefName ?? "").replace("refs/heads/", ""),
+			target_branch: (raw.targetRefName ?? "").replace("refs/heads/", ""),
+			state: status === "completed" ? "merged" : status === "abandoned" ? "closed" : "opened",
+			has_conflicts: raw.mergeStatus === "conflicts",
+			rebase_in_progress: false,
+			merge_status: raw.mergeStatus ?? "",
+			detailed_merge_status: null,
+			draft: raw.isDraft ?? false,
+			head_pipeline: null,
+			author: { name: raw.createdBy?.displayName ?? "" },
+			created_at: raw.creationDate ?? "",
+			merged_at: status === "completed" ? (raw.closedDate ?? null) : null,
+		};
+	}
+
+	_pipeline(raw) {
+		return {
+			id: raw.id,
+			status: this._buildStatus(raw),
+			web_url: raw._links?.web?.href ?? "",
+			created_at: raw.queueTime ?? raw.startTime ?? "",
+		};
+	}
+
+	_buildStatus(raw) {
+		const result = raw.result;
+		if (result === "succeeded") return "success";
+		if (result === "failed" || result === "partiallySucceeded") return "failed";
+		if (result === "canceled") return "cancelled";
+		const status = raw.status;
+		if (status === "inProgress") return "running";
+		if (status === "notStarted") return "pending";
+		return status ?? "unknown";
+	}
+
+	_job(raw) {
+		return {
+			id: raw.id,
+			name: raw.name,
+			stage: raw.stageName ?? "",
+			status: this._taskStatus(raw),
+			web_url: raw._links?.web?.href ?? "",
+			duration: raw.finishTime && raw.startTime
+				? Math.round((new Date(raw.finishTime) - new Date(raw.startTime)) / 1000)
+				: null,
+		};
+	}
+
+	_taskStatus(raw) {
+		const result = raw.result;
+		if (result === "succeeded") return "success";
+		if (result === "failed") return "failed";
+		if (result === "skipped") return "skipped";
+		const state = raw.state;
+		if (state === "inProgress") return "running";
+		if (state === "pending") return "pending";
+		return state ?? "unknown";
+	}
+
+	_diff(raw) {
+		const changeType = raw.changeType ?? "";
+		return {
+			old_path: raw.item?.path ?? "",
+			new_path: raw.item?.path ?? "",
+			diff: "",  // ADO diff content requires a separate API call
+			new_file: changeType === "add",
+			renamed_file: changeType === "rename",
+			deleted_file: changeType === "delete",
+		};
+	}
+
+	// ─── Issues (Work Items) ──────────────────────────────────────────────────
+
+	async listOpenIssues() {
+		// WIQL query for open issues in the project
+		const wiql = {
+			query: `SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = '${this._project}' AND [System.State] <> 'Done' AND [System.State] <> 'Closed' AND [System.WorkItemType] IN ('Bug','Issue','Task','User Story') ORDER BY [System.ChangedDate] DESC`,
+		};
+		const result = await this._req(
+			`${this._witBase()}/wiql?$top=25`,
+			{ method: "POST", body: JSON.stringify(wiql) },
+		);
+		const ids = (result?.workItems ?? []).map((w) => w.id);
+		if (ids.length === 0) return [];
+
+		const batch = await this._req(
+			`${this._witBase()}/workitems?ids=${ids.join(",")}&$expand=fields`,
+		);
+		return (batch?.value ?? []).map((wi) => this._issue(wi));
+	}
+
+	async getIssue(iid) {
+		const raw = await this._req(`${this._witBase()}/workitems/${iid}?$expand=fields`);
+		return this._issue(raw);
+	}
+
+	async createIssue(title, description = "") {
+		const patch = [
+			{ op: "add", path: "/fields/System.Title", value: title },
+			{ op: "add", path: "/fields/System.Description", value: description },
+		];
+		const raw = await this._req(
+			`${this._witBase()}/workitems/$Issue`,
+			{
+				method: "POST",
+				headers: { "Content-Type": "application/json-patch+json" },
+				body: JSON.stringify(patch),
+			},
+		);
+		return this._issue(raw);
+	}
+
+	async updateIssue(iid, { title, description }) {
+		const patch = [];
+		if (title !== undefined) patch.push({ op: "replace", path: "/fields/System.Title", value: title });
+		if (description !== undefined) patch.push({ op: "replace", path: "/fields/System.Description", value: description });
+		const raw = await this._req(
+			`${this._witBase()}/workitems/${iid}`,
+			{
+				method: "PATCH",
+				headers: { "Content-Type": "application/json-patch+json" },
+				body: JSON.stringify(patch),
+			},
+		);
+		return this._issue(raw);
+	}
+
+	async closeIssue(iid) {
+		const patch = [{ op: "replace", path: "/fields/System.State", value: "Closed" }];
+		const raw = await this._req(
+			`${this._witBase()}/workitems/${iid}`,
+			{
+				method: "PATCH",
+				headers: { "Content-Type": "application/json-patch+json" },
+				body: JSON.stringify(patch),
+			},
+		);
+		return this._issue(raw);
+	}
+
+	// ─── Repository ───────────────────────────────────────────────────────────
+
+	async getFileTree(srcPath = "src", ref = this._defaultBranch) {
+		const data = await this._req(
+			`${this._gitBase()}/trees/${ref}?recursive=true&$scopePath=/${srcPath}`,
+		);
+		return (data?.treeEntries ?? [])
+			.filter((item) => item.gitObjectType === "blob")
+			.filter((item) => /\.(ts|tsx|js|jsx|json|css|yaml|yml|md)$/.test(item.relativePath))
+			.map((item) => item.relativePath);
+	}
+
+	async getFileContent(filePath, ref = this._defaultBranch) {
+		const encoded = encodeURIComponent(filePath);
+		const url = `${this._gitBase()}/items?path=${encoded}&versionDescriptor.version=${ref}&versionDescriptor.versionType=branch&$format=text&api-version=7.1`;
+		const res = await fetch(url, { headers: this._headers() });
+		if (!res.ok) {
+			const text = await res.text().catch(() => "");
+			throw new Error(`AzureDevOps ${res.status} on items/${filePath}: ${text}`);
+		}
+		return res.text();
+	}
+
+	// ─── Mutations ────────────────────────────────────────────────────────────
+
+	async createBranch(branchName, ref = this._defaultBranch) {
+		// Get current SHA for ref
+		const refs = await this._req(`${this._gitBase()}/refs?filter=heads/${ref}`);
+		const sha = refs?.value?.[0]?.objectId;
+		if (!sha) throw new Error(`AzureDevOps: could not resolve ref ${ref}`);
+
+		return this._req(`${this._gitBase()}/refs`, {
+			method: "POST",
+			body: JSON.stringify([
+				{
+					name: `refs/heads/${branchName}`,
+					newObjectId: sha,
+					oldObjectId: "0000000000000000000000000000000000000000",
+				},
+			]),
+		});
+	}
+
+	async commitFiles(branch, message, actions) {
+		const changes = actions.map((action) => ({
+			changeType: action.action === "create" ? "add" : action.action === "delete" ? "delete" : "edit",
+			item: { path: `/${action.file_path}` },
+			newContent: action.action !== "delete"
+				? { content: action.content, contentType: "rawtext" }
+				: undefined,
+		}));
+
+		// Get current commit SHA
+		const refs = await this._req(`${this._gitBase()}/refs?filter=heads/${branch}`);
+		const oldSha = refs?.value?.[0]?.objectId ?? "0000000000000000000000000000000000000000";
+
+		return this._req(`${this._gitBase()}/pushes`, {
+			method: "POST",
+			body: JSON.stringify({
+				refUpdates: [{ name: `refs/heads/${branch}`, oldObjectId: oldSha }],
+				commits: [{ comment: message, changes }],
+			}),
+		});
+	}
+
+	async createMR({ sourceBranch, targetBranch = this._defaultBranch, title, description = "" }) {
+		const raw = await this._req(`${this._gitBase()}/pullrequests`, {
+			method: "POST",
+			body: JSON.stringify({
+				sourceRefName: `refs/heads/${sourceBranch}`,
+				targetRefName: `refs/heads/${targetBranch}`,
+				title,
+				description,
+			}),
+		});
+		return this._mr(raw);
+	}
+
+	// ─── PR queries ───────────────────────────────────────────────────────────
+
+	async listAllForgeMRs(state = "open") {
+		const adoStatus =
+			state === "merged" ? "completed"
+				: state === "closed" ? "abandoned"
+					: "active";
+		const data = await this._req(
+			`${this._gitBase()}/pullrequests?searchCriteria.status=${adoStatus}&$top=50`,
+		);
+		return (data?.value ?? [])
+			.filter((pr) => pr.sourceRefName?.includes("refs/heads/forge/"))
+			.map((pr) => this._mr(pr));
+	}
+
+	async listForgeMRsForIssue(issueIid) {
+		const data = await this._req(
+			`${this._gitBase()}/pullrequests?searchCriteria.status=active&$top=50`,
+		);
+		return (data?.value ?? [])
+			.filter((pr) => pr.sourceRefName?.includes(`refs/heads/forge/issue-${issueIid}-`))
+			.map((pr) => this._mr(pr));
+	}
+
+	async listMergedForgeMRsForIssue(issueIid) {
+		const data = await this._req(
+			`${this._gitBase()}/pullrequests?searchCriteria.status=completed&$top=50`,
+		);
+		return (data?.value ?? [])
+			.filter((pr) => pr.sourceRefName?.includes(`refs/heads/forge/issue-${issueIid}-`))
+			.map((pr) => this._mr(pr));
+	}
+
+	async getMR(mrIid) {
+		const raw = await this._req(`${this._gitBase()}/pullrequests/${mrIid}`);
+		return this._mr(raw);
+	}
+
+	async getMRDiffs(mrIid) {
+		const data = await this._req(
+			`${this._gitBase()}/pullrequests/${mrIid}/iterations/1/changes`,
+		);
+		return (data?.changeEntries ?? []).map((c) => this._diff(c));
+	}
+
+	// ─── CI / Pipelines ───────────────────────────────────────────────────────
+
+	async getMRPipelines(mrIid) {
+		// Get PR statuses which link to builds
+		const data = await this._req(
+			`${this._gitBase()}/pullrequests/${mrIid}/statuses`,
+		);
+		const buildIds = (data?.value ?? [])
+			.map((s) => s.targetUrl?.match(/buildId=(\d+)/)?.[1])
+			.filter(Boolean)
+			.map(Number);
+
+		if (buildIds.length === 0) return [];
+		return Promise.all(buildIds.map((id) => this.getPipeline(id)));
+	}
+
+	async getPipeline(pipelineId) {
+		const raw = await this._req(`${this._buildBase()}/builds/${pipelineId}`);
+		return this._pipeline(raw);
+	}
+
+	async getPipelineJobs(pipelineId) {
+		const data = await this._req(`${this._buildBase()}/builds/${pipelineId}/timeline`);
+		return (data?.records ?? [])
+			.filter((r) => r.type === "Task")
+			.map((r) => this._job(r));
+	}
+
+	async getJobTrace(jobId) {
+		const url = `${this._buildBase()}/builds/${jobId}/logs/1?api-version=7.1`;
+		const res = await fetch(url, { headers: this._headers() });
+		if (!res.ok) {
+			const text = await res.text().catch(() => "");
+			throw new Error(`AzureDevOps ${res.status} on builds/${jobId}/logs: ${text}`);
+		}
+		return res.text();
+	}
+}

package/server/forge/core/providers/base.js

@@ -0,0 +1,208 @@
+/**
+ * server/forge/core/providers/base.js
+ *
+ * Abstract base class that defines the interface every SCM provider must
+ * implement.  Methods throw "not implemented" by default so subclasses get
+ * a clear error rather than a silent no-op when something is missing.
+ *
+ * All data shapes returned by provider methods are normalised so that
+ * ForgeAgent and routes.js never need to know which provider is active.
+ *
+ * Normalised shapes (JSDoc):
+ *
+ * @typedef {{ iid: number, title: string, description: string|null,
+ *             labels: string[], author: { name: string },
+ *             created_at: string, web_url: string }} NormalIssue
+ *
+ * @typedef {{ iid: number, title: string, web_url: string,
+ *             source_branch: string, target_branch: string,
+ *             state: string, has_conflicts: boolean,
+ *             rebase_in_progress: boolean, merge_status: string,
+ *             detailed_merge_status: string|null,
+ *             draft: boolean,
+ *             head_pipeline: { status: string, web_url: string }|null,
+ *             author: { name: string }, created_at: string,
+ *             merged_at: string|null,
+ *             merge_commit_sha: string|null }} NormalMR
+ *
+ * @typedef {{ id: number, status: string, web_url: string,
+ *             created_at: string }} NormalPipeline
+ *
+ * @typedef {{ id: number, name: string, stage: string, status: string,
+ *             web_url: string, duration: number|null }} NormalJob
+ *
+ * @typedef {{ old_path: string, new_path: string, diff: string,
+ *             new_file: boolean, renamed_file: boolean,
+ *             deleted_file: boolean }} NormalDiff
+ *
+ * @typedef {{ action: 'create'|'modify'|'delete',
+ *             file_path: string, content: string }} CommitAction
+ *
+ * @typedef {{ id: number, name: string,
+ *             state: 'available'|'stopping'|'stopped'|string,
+ *             external_url: string|null, ref: string|null,
+ *             updated_at: string|null, web_url: string|null }} NormalEnvironment
+ */
+
+export class ScmProvider {
+	/** @returns {string} Provider identifier */
+	get name() { return "base"; }
+
+	/** @returns {boolean} Whether the provider supports server-side rebase */
+	get supportsRebase() { return false; }
+
+	// ─── Issues ────────────────────────────────────────────────────────────────
+
+	/** @returns {Promise<NormalIssue[]>} */
+	async listOpenIssues() { throw new Error(`${this.name}: listOpenIssues not implemented`); }
+
+	/** @param {number|string} iid @returns {Promise<NormalIssue>} */
+	async getIssue(iid) { throw new Error(`${this.name}: getIssue not implemented`); }
+
+	/** @returns {Promise<NormalIssue>} */
+	async createIssue(title, description) { throw new Error(`${this.name}: createIssue not implemented`); }
+
+	/** @returns {Promise<NormalIssue>} */
+	async updateIssue(iid, { title, description }) { throw new Error(`${this.name}: updateIssue not implemented`); }
+
+	/** @returns {Promise<NormalIssue>} */
+	async closeIssue(iid) { throw new Error(`${this.name}: closeIssue not implemented`); }
+
+	// ─── Repository ────────────────────────────────────────────────────────────
+
+	/** @returns {Promise<string[]>} File paths */
+	async getFileTree(srcPath, ref) { throw new Error(`${this.name}: getFileTree not implemented`); }
+
+	/** @returns {Promise<string>} File content */
+	async getFileContent(filePath, ref) { throw new Error(`${this.name}: getFileContent not implemented`); }
+
+	// ─── Mutations ─────────────────────────────────────────────────────────────
+
+	async createBranch(branchName, ref) { throw new Error(`${this.name}: createBranch not implemented`); }
+
+	/** @param {string} branchName @returns {Promise<void>} */
+	async deleteBranch(branchName) { throw new Error(`${this.name}: deleteBranch not implemented`); }
+
+	/** @param {CommitAction[]} actions */
+	async commitFiles(branch, message, actions) { throw new Error(`${this.name}: commitFiles not implemented`); }
+
+	/** @returns {Promise<NormalMR>} */
+	async createMR({ sourceBranch, targetBranch, title, description }) { throw new Error(`${this.name}: createMR not implemented`); }
+
+	// ─── MR / PR queries ───────────────────────────────────────────────────────
+
+	/**
+	 * @param {"open"|"merged"|"closed"} [state="open"] Lifecycle filter
+	 * @returns {Promise<NormalMR[]>} Forge-created MRs in the requested state
+	 */
+	async listAllForgeMRs(_state = "open") { throw new Error(`${this.name}: listAllForgeMRs not implemented`); }
+
+	/** @returns {Promise<NormalMR[]>} Open Forge MRs for a specific issue */
+	async listForgeMRsForIssue(issueIid) { throw new Error(`${this.name}: listForgeMRsForIssue not implemented`); }
+
+	/** @returns {Promise<NormalMR[]>} Merged Forge MRs for a specific issue */
+	async listMergedForgeMRsForIssue(issueIid) { throw new Error(`${this.name}: listMergedForgeMRsForIssue not implemented`); }
+
+	/** @returns {Promise<NormalMR>} */
+	async getMR(mrIid) { throw new Error(`${this.name}: getMR not implemented`); }
+
+	/** @returns {Promise<NormalDiff[]>} */
+	async getMRDiffs(mrIid) { throw new Error(`${this.name}: getMRDiffs not implemented`); }
+
+	/** @returns {Promise<void>} */
+	async rebaseMR(mrIid) { throw new Error(`${this.name}: rebase not supported`); }
+
+	/** Merge the MR immediately. @returns {Promise<void>} */
+	async mergeMR(_mrIid) { throw new Error(`${this.name}: mergeMR not supported`); }
+
+	/** Close the MR without merging. @returns {Promise<void>} */
+	async closeMR(_mrIid) { throw new Error(`${this.name}: closeMR not supported`); }
+
+	/** Reopen a closed MR. @returns {Promise<void>} */
+	async reopenMR(_mrIid) { throw new Error(`${this.name}: reopenMR not supported`); }
+
+	/**
+	 * Toggle draft / work-in-progress state on the MR.
+	 * @param {number} _mrIid
+	 * @param {boolean} _draft true → mark as draft, false → mark as ready
+	 * @returns {Promise<void>}
+	 */
+	async setMRDraft(_mrIid, _draft) { throw new Error(`${this.name}: setMRDraft not supported`); }
+
+	// ─── CI / Pipelines ────────────────────────────────────────────────────────
+
+	/** @returns {Promise<NormalPipeline[]>} */
+	async getMRPipelines(mrIid) { throw new Error(`${this.name}: getMRPipelines not implemented`); }
+
+	/** @returns {Promise<NormalPipeline>} */
+	async getPipeline(pipelineId) { throw new Error(`${this.name}: getPipeline not implemented`); }
+
+	/** @returns {Promise<NormalJob[]>} */
+	async getPipelineJobs(pipelineId) { throw new Error(`${this.name}: getPipelineJobs not implemented`); }
+
+	/** @returns {Promise<string>} Plain-text log */
+	async getJobTrace(jobId) { throw new Error(`${this.name}: getJobTrace not implemented`); }
+
+	/** @returns {Promise<NormalPipeline[]>} Pipelines that ran on a specific commit SHA */
+	async getPipelinesBySha(_sha) { return []; }
+
+	/** @returns {Promise<NormalPipeline[]>} Pipelines that ran on a specific branch ref */
+	async getPipelinesByRef(_ref) { return []; }
+
+	/** @returns {Promise<string[]>} Branch names starting with the given prefix */
+	async listBranchesByPrefix(_prefix) { return []; }
+
+	/**
+	 * Count commits reachable from `toRef` but not from `fromRef`. Used to detect
+	 * stale / empty forge branches (aheadCount === 0 means the branch has no
+	 * pending changes vs. main). Return `null` when the provider can't compute it
+	 * so callers can distinguish "no divergence" from "unknown".
+	 *
+	 * @param {string} _fromRef base ref (typically "main")
+	 * @param {string} _toRef   ref under test (e.g. "forge/issue-10-…")
+	 * @returns {Promise<{aheadCount: number}|null>}
+	 */
+	async compareRefs(_fromRef, _toRef) { return null; }
+
+	/**
+	 * Scan recently merged MRs so callers can badge open issues whose fix
+	 * already shipped. Two attribution paths the consumer can use:
+	 *   1. `closedIssueIids` — issues named by `Closes #N` / `Fixes #N` /
+	 *      `Resolves #N` trailers in the MR description (primary signal).
+	 *   2. `sourceBranch` — the MR's source branch; lets the consumer recover
+	 *      issue IDs from branch names like `forge/issue-42-foo` when the MR
+	 *      description has no closing keyword.
+	 * Returned entries are NOT pre-filtered on `closedIssueIids` — drop noise
+	 * in the caller if you only want one of the two signals. One bulk call per
+	 * issue-list render — do NOT call per-issue.
+	 *
+	 * @param {number} _limit cap on MRs to scan (default 50)
+	 * @returns {Promise<Array<{mrIid: number, webUrl: string, mergedAt: string|null, sourceBranch: string|null, closedIssueIids: number[]}>>}
+	 */
+	async listRecentMergedMRIssueLinks(_limit) { return []; }
+
+	// ─── Environments (ephemeral review apps) ─────────────────────────────────
+
+	/**
+	 * List environments attached to a branch. Used to surface per-issue
+	 * ephemeral URLs + status next to the pipeline on the issue detail view.
+	 *
+	 * Implementations that don't support environments should return `[]` so
+	 * the UI simply doesn't render the section.
+	 *
+	 * @param {string} _branchName
+	 * @returns {Promise<NormalEnvironment[]>}
+	 */
+	async listEnvironmentsForBranch(_branchName) { return []; }
+
+	/**
+	 * Trigger teardown of an environment. GitLab supports this natively via the
+	 * environments/:id/stop action; GitHub has no equivalent and typically
+	 * needs a repository_dispatch event to a cleanup workflow. Implementations
+	 * that can't stop should throw so the caller can surface the limitation.
+	 *
+	 * @param {number|string} _envId
+	 * @returns {Promise<void>}
+	 */
+	async stopEnvironment(_envId) { throw new Error(`${this.name}: stopEnvironment not implemented`); }
+}