0.7.0: exported API with repository handles, change events and remote providers; Open on Remote commands f6bda77ecb9f

Author: Andy McCall @andymccall <[email protected]>
When: 1 month ago · 2026-09-27 19:32 UTC
Signature: ✔ signed by Andy McCall
Hash: f6bda77ecb9f3551f579d5594834d44936fbf0211fec60331da6f8449547c399
Depends on: 25103dddd993 3006b700c514 35d56b5803d9 810a1c538e78 9020cf612749 ab81294a9ba9 bed495a96408 c8f955891224 d2c9a5843004
Depended on by: dac6876e4d08 013fefef11e3 0c26846a9a81 cdcffe39dd9f 1f7fc1e3ae4a 44bfd5adfc9a b4626290e660 9627171e23e2
In bookmarks: main
In tags: v0.16.0 v0.16.1 v0.17.0 v0.17.1 v0.18.0
Edits: 26 atoms, 3 tree operations, 7 files

Browse the tree at this change

hide whitespace changes

added docs/plan.md +2 −0

added src/api.ts +83 −0

added test/api.test.mjs +23 −0

modified CHANGELOG.md +5 −0

modified docs/spec.md +4 −0

modified package.json +567 −109

modified src/extension.ts +95 −1

1	+	// The API this extension exports to others (spec §9, "extension API"): the
2	+	// same idea as the built-in Git extension's `getAPI()`. A forge extension
3	+	// such as oxygenhub-vscode consumes it instead of running oxy itself, and
4	+	// registers a remote provider so this extension can offer "Open on …"
5	+	// links without knowing any hub.
6	+	//
7	+	// Pure functions live here so they can be tested with plain Node; the
8	+	// vscode-facing object is assembled in extension.ts.
9	+
10	+	/** What a remote-aware extension registers. */
11	+	export interface RemoteProvider {
12	+	/** A stable id, e.g. `oxygenhub`. */
13	+	readonly id: string;
14	+	/** Shown in menus: "Open on Oxygenhub". */
15	+	readonly label: string;
16	+	/** Whether this provider understands a remote URL. */
17	+	matches(remoteUrl: string): boolean;
18	+	/** A web URL for a thing in that remote, or undefined when the provider has none. */
19	+	urlFor(remoteUrl: string, target: RemoteTarget): string \| undefined;
20	+	}
21	+
22	+	export type RemoteTarget =
23	+	\| { kind: "repository" }
24	+	\| { kind: "bookmark"; name: string }
25	+	\| { kind: "change"; hash: string }
26	+	\| { kind: "file"; reference: string; path: string; line?: number }
27	+	\| { kind: "proposals" }
28	+	\| { kind: "issues" };
29	+
30	+	/** A minimal view of one repository, stable across versions. */
31	+	export interface RepositoryHandle {
32	+	readonly root: string;
33	+	/** `oxy status --json` as last refreshed, or undefined before the first refresh. */
34	+	readonly status: unknown;
35	+	readonly bookmarks: { name: string; heads: string[]; current?: boolean }[];
36	+	readonly currentBookmark: string \| undefined;
37	+	remotes(): Promise<{ name: string; url: string }[]>;
38	+	/** Run an oxy command in this repository and parse its JSON output. */
39	+	json<T>(args: string[]): Promise<T>;
40	+	refresh(): Promise<void>;
41	+	}
42	+
43	+	export interface OxygenAPI {
44	+	readonly version: 1;
45	+	readonly repositories: readonly RepositoryHandle[];
46	+	/** Fires with the repository whose status changed. */
47	+	readonly onDidChangeStatus: (listener: (repo: RepositoryHandle) => void) => { dispose(): void };
48	+	/** Fires when repositories are discovered or removed. */
49	+	readonly onDidChangeRepositories: (listener: () => void) => { dispose(): void };
50	+	getRepository(fsPath: string): RepositoryHandle \| undefined;
51	+	registerRemoteProvider(provider: RemoteProvider): { dispose(): void };
52	+	/** The providers registered so far, for callers that build their own menus. */
53	+	remoteProviders(): readonly RemoteProvider[];
54	+	}
55	+
56	+	/** The provider (and remote) to use for a repository's remotes, if any. */
57	+	export function pickProvider(providers: readonly RemoteProvider[], remotes: { name: string; url: string }[]): { provider: RemoteProvider; remote: { name: string; url: string } } \| undefined {
58	+	// Prefer a remote called origin or earth, then any.
59	+	const ordered = [...remotes].sort((a, b) => rank(a.name) - rank(b.name));
60	+	for (const remote of ordered) {
61	+	for (const provider of providers) {
62	+	if (provider.matches(remote.url)) {
63	+	return { provider, remote };
64	+	}
65	+	}
66	+	}
67	+	return undefined;
68	+	}
69	+
70	+	function rank(name: string): number {
71	+	return name === "origin" ? 0 : name === "hub" ? 1 : 2;
72	+	}
73	+
74	+	/** The repository handle a folder path belongs to: the longest root that prefixes it. */
75	+	export function repositoryFor(roots: string[], fsPath: string): string \| undefined {
76	+	let best: string \| undefined;
77	+	for (const r of roots) {
78	+	if ((fsPath === r \|\| fsPath.startsWith(r.endsWith("/") ? r : r + "/")) && (!best \|\| r.length > best.length)) {
79	+	best = r;
80	+	}
81	+	}
82	+	return best;
83	+	}

1	+	import { test } from "node:test";
2	+	import assert from "node:assert/strict";
3	+	import { pickProvider, repositoryFor } from "../out/api.mjs";
4	+
5	+	test("picks the first provider that matches, preferring origin", () => {
6	+	const hub = { id: "hub", label: "Hub", matches: (u) => u.includes("hub.example"), urlFor: () => undefined };
7	+	const other = { id: "other", label: "Other", matches: (u) => u.includes("other.example"), urlFor: () => undefined };
8	+	const remotes = [
9	+	{ name: "mirror", url: "https://other.example/a/b" },
10	+	{ name: "origin", url: "https://hub.example/a/b" },
11	+	];
12	+	const pick = pickProvider([hub, other], remotes);
13	+	assert.equal(pick.provider.id, "hub");
14	+	assert.equal(pick.remote.name, "origin");
15	+	assert.equal(pickProvider([hub], [{ name: "x", url: "https://nowhere" }]), undefined);
16	+	});
17	+
18	+	test("repositoryFor picks the longest matching root", () => {
19	+	const roots = ["/w/a", "/w/a/sub", "/w/b"];
20	+	assert.equal(repositoryFor(roots, "/w/a/sub/file.rs"), "/w/a/sub");
21	+	assert.equal(repositoryFor(roots, "/w/a/x.rs"), "/w/a");
22	+	assert.equal(repositoryFor(roots, "/w/ab/x"), undefined);
23	+	});

1	1		# Changelog
2	2
	3	+	## 0.7.0
	4	+
	5	+	- An exported API for other extensions (`vscode.extensions.getExtension("...").exports`): repositories with status, bookmarks, remotes and `json(args)`, change events, and `registerRemoteProvider` so a forge extension such as Oxygenhub can say which remotes it understands and where things live on the web.
	6	+	- "Open on Remote" and "Open Change on Remote" commands, shown once a provider is registered.
	7	+
3	8		## 0.6.0 (2026-09-27)
4	9
5	10		Milestone 0.6: a Subrepos group with update and open, Oxygen Bisect and Oxygen Trust views, Verify Signatures, tag picker and Create Tag, Add Workspace, and Clone Repository.
		…	32 unchanged lines

		…	205 unchanged lines
206	206		- `oxy` gained `tag list --json` and `workspace list --json` for §4, and two bugs the extension's tests found were fixed in `oxy`: a chosen addition hunk now carries its content, and an unsigned repository keeps a tag's message.
207	207		- Extensions are per VS Code profile; the install command must name the profile a workspace uses.
208	208
	209	+	## 9a. Exported API (0.7.0)
	210	+
	211	+	`activate` returns an `OxygenAPI` (`src/api.ts`): the repositories as handles (root, status, bookmarks, current bookmark, `remotes()`, `json(args)`, `refresh()`), `onDidChangeStatus`, `onDidChangeRepositories`, `getRepository(path)`, and `registerRemoteProvider`. A remote provider gives an id and label, `matches(remoteUrl)` and `urlFor(remoteUrl, target)` for repository, bookmark, change, file (with line), proposals and issues targets. This extension uses the providers for its Open on Remote commands and sets the `oxygen.hasRemoteProvider` context; oxygenhub-vscode registers one for hubs and consumes the handles instead of running `oxy` itself, mirroring how the GitHub Pull Requests extension builds on the built-in Git extension.
	212	+
209	213		## 9. Open questions
210	214
211	215		1. Whether the extension should ship `oxy` binaries for the three platforms or only locate one; shipping simplifies onboarding but ties releases together.
		…	2 unchanged lines

		…	1 unchanged lines
2	2		// decorations, the content provider, and the commands (spec §3).
3	3
4	4		import * as vscode from "vscode";
	5	+	import { OxygenAPI, RemoteProvider, RemoteTarget, RepositoryHandle, pickProvider, repositoryFor as rootFor } from "./api";
5	6		import { basename } from "node:path";
6	7		import { Oxy, OxyError, findBinary } from "./oxy";
7	8		import { Repository, OxyResourceState, SubrepoState } from "./repository";
		…	18 unchanged lines
26	27		let trustView: TrustProvider;
27	28		const repositories = new Map<string, Repository>();
28	29
29		-	export async function activate(context: vscode.ExtensionContext): Promise<void> {
	30	+	export async function activate(context: vscode.ExtensionContext): Promise<OxygenAPI \| undefined> {
30	31		output = vscode.window.createOutputChannel("Oxygen");
31	32		context.subscriptions.push(output);
32	33		output.appendLine(`Oxygen extension ${context.extension.packageJSON.version} activating; folders: ${(vscode.workspace.workspaceFolders ?? []).map((f) => f.uri.fsPath).join(", ") \|\| "(none)"}`);
		…	32 unchanged lines
65	66		await Promise.all([...repositories.values()].map((r) => r.refresh()));
66	67		}),
67	68		vscode.commands.registerCommand("oxygen.showOutput", () => output.show()),
	69	+	vscode.commands.registerCommand("oxygen.openOnRemote", (arg?: Repository \| vscode.SourceControl) => openOnRemote(undefined, arg instanceof Repository ? arg : undefined)),
	70	+	vscode.commands.registerCommand("oxygen.openChangeOnRemote", (root: string, hash: string) => openOnRemote({ kind: "change", hash }, repositories.get(root))),
68	71		vscode.commands.registerCommand("oxygen.openFile", (state?: OxyResourceState) => state && vscode.commands.executeCommand("vscode.open", state.resourceUri)),
69	72		vscode.commands.registerCommand("oxygen.openChanges", (state?: OxyResourceState) => state && openChanges(state)),
70	73		vscode.commands.registerCommand("oxygen.openBaseVersion", (state?: OxyResourceState) => state && vscode.commands.executeCommand("vscode.open", baseUri(state.repository.root, state.path))),
		…	67 unchanged lines
138	141		context.subscriptions.push({ dispose: () => repositories.forEach((r) => r.dispose()) });
139	142
140	143		await discover();
	144	+	return buildApi();
	145	+	}
	146	+
	147	+
	148	+	// ---------------------------------------------------------------- exported API
	149	+
	150	+	const remoteProviders: RemoteProvider[] = [];
	151	+	const onDidChangeRepositoriesEmitter = new vscode.EventEmitter<void>();
	152	+	const onDidChangeStatusEmitter = new vscode.EventEmitter<RepositoryHandle>();
	153	+
	154	+	function handleOf(repo: Repository): RepositoryHandle {
	155	+	return {
	156	+	root: repo.root,
	157	+	get status() {
	158	+	return repo.status;
	159	+	},
	160	+	get bookmarks() {
	161	+	return repo.bookmarks.map((b) => ({ name: b.name, heads: b.heads, current: b.current }));
	162	+	},
	163	+	get currentBookmark() {
	164	+	return repo.currentBookmark?.name;
	165	+	},
	166	+	remotes: async () => (await repo.oxy.remotes(repo.root)).map((r) => ({ name: r.name, url: r.url })),
	167	+	json: <T>(args: string[]) => repo.oxy.json<T>(repo.root, args),
	168	+	refresh: () => repo.refresh(),
	169	+	};
	170	+	}
	171	+
	172	+	function buildApi(): OxygenAPI {
	173	+	return {
	174	+	version: 1,
	175	+	get repositories() {
	176	+	return [...repositories.values()].map(handleOf);
	177	+	},
	178	+	onDidChangeStatus: (listener) => onDidChangeStatusEmitter.event(listener),
	179	+	onDidChangeRepositories: (listener) => onDidChangeRepositoriesEmitter.event(listener),
	180	+	getRepository: (fsPath) => {
	181	+	const root = rootFor([...repositories.keys()], fsPath);
	182	+	const repo = root ? repositories.get(root) : undefined;
	183	+	return repo ? handleOf(repo) : undefined;
	184	+	},
	185	+	registerRemoteProvider: (provider) => {
	186	+	remoteProviders.push(provider);
	187	+	void vscode.commands.executeCommand("setContext", "oxygen.hasRemoteProvider", true);
	188	+	return {
	189	+	dispose: () => {
	190	+	const i = remoteProviders.indexOf(provider);
	191	+	if (i >= 0) {
	192	+	remoteProviders.splice(i, 1);
	193	+	}
	194	+	void vscode.commands.executeCommand("setContext", "oxygen.hasRemoteProvider", remoteProviders.length > 0);
	195	+	},
	196	+	};
	197	+	},
	198	+	remoteProviders: () => [...remoteProviders],
	199	+	};
	200	+	}
	201	+
	202	+	/** Open the current repository, file or change on whichever provider knows its remote. */
	203	+	async function openOnRemote(target?: RemoteTarget, repoArg?: Repository): Promise<void> {
	204	+	const editor = vscode.window.activeTextEditor;
	205	+	const repo = repoArg ?? (editor ? repositoryFor2(editor.document.uri) : undefined) ?? [...repositories.values()][0];
	206	+	if (!repo) {
	207	+	void vscode.window.showInformationMessage("Oxygen: no repository is open.");
	208	+	return;
	209	+	}
	210	+	const remotes = (await repo.oxy.remotes(repo.root)).map((r) => ({ name: r.name, url: r.url }));
	211	+	const pick = pickProvider(remoteProviders, remotes);
	212	+	if (!pick) {
	213	+	void vscode.window.showInformationMessage("Oxygen: no extension knows this repository's remotes. Install a forge extension such as Oxygenhub.");
	214	+	return;
	215	+	}
	216	+	let t: RemoteTarget = target ?? { kind: "repository" };
	217	+	if (!target && editor) {
	218	+	const rel = repo.relativePath(editor.document.uri);
	219	+	if (rel) {
	220	+	t = { kind: "file", reference: repo.currentBookmark?.name ?? "main", path: rel, line: editor.selection.active.line + 1 };
	221	+	}
	222	+	}
	223	+	const url = pick.provider.urlFor(pick.remote.url, t);
	224	+	if (url) {
	225	+	await vscode.env.openExternal(vscode.Uri.parse(url));
	226	+	}
	227	+	}
	228	+
	229	+	function repositoryFor2(uri: vscode.Uri): Repository \| undefined {
	230	+	const root = rootFor([...repositories.keys()], uri.fsPath);
	231	+	return root ? repositories.get(root) : undefined;
141	232		}
142	233
143	234		export function deactivate(): void {
		…	16 unchanged lines
160	251		if (!wanted.has(root)) {
161	252		repo.dispose();
162	253		repositories.delete(root);
	254	+	onDidChangeRepositoriesEmitter.fire();
163	255		}
164	256		}
165	257		if (wanted.size === 0 && (vscode.workspace.workspaceFolders ?? []).length > 0) {
		…	17 unchanged lines
183	275		repo.sourceControl.inputBox.placeholder = resolved ? "Describe the resolution (Ctrl+Enter to commit)" : "Message (Ctrl+Enter to commit)";
184	276		});
185	277		repositories.set(root, repo);
	278	+	repo.onDidChangeStatus(() => onDidChangeStatusEmitter.fire(handleOf(repo)));
	279	+	onDidChangeRepositoriesEmitter.fire();
186	280		output.appendLine(`repository ${root}`);
187	281		await repo.refresh();
188	282		}
		…	842 unchanged lines

	1	+
	2	+	The cross-product order of work is in `oxygen/docs/roadmap.md`.

`/`	Search
`g` `c`	Code
`g` `h`	History
`g` `b`	Bookmarks
`g` `t`	Trust
`y`	Permalink to this state (files and trees)
`?`	This sheet

		…	1 unchanged lines
2	2		"name": "oxygen-vscode",
3	3		"displayName": "Oxygen",
4	4		"description": "Oxygen version control: source control view, diffs, decorations, bookmarks and history for oxy repositories",
5		-	"version": "0.6.0",
	5	+	"version": "0.7.0",
6	6		"publisher": "oxygen",
7	7		"license": "MIT OR Apache-2.0",
8	8		"icon": "assets/images/oxygen.png",
		…	17 unchanged lines
26	26		"main": "./dist/extension.js",
27	27		"contributes": {
28	28		"commands": [
29		-	{ "command": "oxygen.refresh", "title": "Refresh", "category": "Oxygen", "icon": "$(refresh)" },
30		-	{ "command": "oxygen.commit", "title": "Commit", "category": "Oxygen", "icon": "$(check)" },
31		-	{ "command": "oxygen.openFile", "title": "Open File", "category": "Oxygen", "icon": "$(go-to-file)" },
32		-	{ "command": "oxygen.openChanges", "title": "Open Changes", "category": "Oxygen" },
33		-	{ "command": "oxygen.openBaseVersion", "title": "Open Base Version", "category": "Oxygen" },
34		-	{ "command": "oxygen.showOutput", "title": "Show Output", "category": "Oxygen" },
35		-	{ "command": "oxygen.showLog", "title": "Show Log", "category": "Oxygen" },
36		-	{ "command": "oxygen.init", "title": "Initialize Repository", "category": "Oxygen" },
37		-	{ "command": "oxygen.discard", "title": "Discard Changes", "category": "Oxygen", "icon": "$(discard)" },
38		-	{ "command": "oxygen.commitSelected", "title": "Commit Selected Paths", "category": "Oxygen" },
39		-	{ "command": "oxygen.commitHunks", "title": "Commit Hunks…", "category": "Oxygen" },
40		-	{ "command": "oxygen.amend", "title": "Amend", "category": "Oxygen" },
41		-	{ "command": "oxygen.undo", "title": "Undo Last Operation", "category": "Oxygen", "icon": "$(discard)" },
42		-	{ "command": "oxygen.undoTo", "title": "Undo to Here", "category": "Oxygen", "icon": "$(discard)" },
43		-	{ "command": "oxygen.refreshOperations", "title": "Refresh Operations", "category": "Oxygen", "icon": "$(refresh)" },
44		-	{ "command": "oxygen.switchBookmark", "title": "Switch Bookmark…", "category": "Oxygen", "icon": "$(bookmark)" },
45		-	{ "command": "oxygen.createBookmark", "title": "Create Bookmark…", "category": "Oxygen" },
46		-	{ "command": "oxygen.mergeBookmark", "title": "Merge Bookmark…", "category": "Oxygen" },
47		-	{ "command": "oxygen.deleteBookmark", "title": "Delete Bookmark…", "category": "Oxygen" },
48		-	{ "command": "oxygen.fetch", "title": "Fetch", "category": "Oxygen" },
49		-	{ "command": "oxygen.pull", "title": "Pull", "category": "Oxygen" },
50		-	{ "command": "oxygen.push", "title": "Push", "category": "Oxygen" },
51		-	{ "command": "oxygen.pushBookmark", "title": "Push Bookmark…", "category": "Oxygen" },
52		-	{ "command": "oxygen.sync", "title": "Sync", "category": "Oxygen", "icon": "$(sync)" },
53		-	{ "command": "oxygen.showHistory", "title": "Show History", "category": "Oxygen", "icon": "$(git-commit)" },
54		-	{ "command": "oxygen.fileHistory", "title": "File History…", "category": "Oxygen", "icon": "$(history)" },
55		-	{ "command": "oxygen.toggleBlame", "title": "Toggle Inline Blame", "category": "Oxygen" },

0.7.0: exported API with repository handles, change events and remote providers; Open on Remote commands f6bda77ecb9f

Keyboard