Skip to content

Commit c554ca2

Browse files
feat(source-control): each host package ships a client definition
Clients branched on the host kind for labels, change request nouns, picker copy, URL shapes and checkout commands. Each host package now exports a `SourceControlClientDefinition` from `./client/definition`, next to its `./server/driver`, and client-runtime lists the built-in ones in `sourceControlClients`, with an unknown-host fallback. Every field is a value or a resolver every host answers. Nothing reads them yet; the next layer moves the web switches onto them. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 2f6a68c commit c554ca2

16 files changed

Lines changed: 553 additions & 0 deletions

File tree

‎packages/client-runtime/package.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -390,6 +390,10 @@
390390
"./state/mcp-apps": {
391391
"types": "./src/state/mcpApps.ts",
392392
"default": "./src/state/mcpApps.ts"
393+
},
394+
"./source-control-clients": {
395+
"types": "./src/sourceControlClients.ts",
396+
"default": "./src/sourceControlClients.ts"
393397
}
394398
},
395399
"scripts": {
@@ -399,6 +403,12 @@
399403
"dependencies": {
400404
"@t3tools/contracts": "workspace:*",
401405
"@t3tools/shared": "workspace:*",
406+
"@t3tools/source-control-azure-devops": "workspace:*",
407+
"@t3tools/source-control-bitbucket": "workspace:*",
408+
"@t3tools/source-control-core": "workspace:*",
409+
"@t3tools/source-control-forgejo": "workspace:*",
410+
"@t3tools/source-control-github": "workspace:*",
411+
"@t3tools/source-control-gitlab": "workspace:*",
402412
"effect": "catalog:",
403413
"three": "0.180.0"
404414
},
Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
import {
2+
type ChangeRequestCheckoutInput,
3+
UNKNOWN_SOURCE_CONTROL_CLIENT,
4+
} from "@t3tools/source-control-core/client/definition";
5+
import { describe, expect, it } from "vite-plus/test";
6+
7+
import { sourceControlClients } from "./sourceControlClients.ts";
8+
9+
describe("sourceControlClients", () => {
10+
it("reads a missing kind as GitHub and an unshipped kind as the generic host", () => {
11+
expect(sourceControlClients.get(undefined).kind).toBe("github");
12+
expect(sourceControlClients.get(null).kind).toBe("github");
13+
expect(sourceControlClients.get("unknown")).toBe(UNKNOWN_SOURCE_CONTROL_CLIENT);
14+
expect(sourceControlClients.get("gitcafe")).toBe(UNKNOWN_SOURCE_CONTROL_CLIENT);
15+
expect(sourceControlClients.find("gitcafe")).toBeUndefined();
16+
expect(UNKNOWN_SOURCE_CONTROL_CLIENT.changeRequest).toEqual({
17+
shortLabel: "change request",
18+
singular: "change request",
19+
});
20+
});
21+
22+
it("attributes change request URLs by their path shape", () => {
23+
const kindOf = (url: string) => sourceControlClients.findByChangeRequestUrl(url)?.kind;
24+
expect(kindOf("https://github.com/acme/web/pull/7")).toBe("github");
25+
expect(kindOf("https://gitlab.example/group/sub/web/-/merge_requests/7")).toBe("gitlab");
26+
expect(kindOf("https://codeberg.org/acme/web/pulls/7")).toBe("forgejo");
27+
expect(kindOf("https://bitbucket.org/acme/web/pull-requests/7")).toBe("bitbucket");
28+
expect(kindOf("https://dev.azure.com/org/project/_git/web/pullrequest/7")).toBe("azure-devops");
29+
expect(kindOf("https://example.com/acme/web/issues/7")).toBeUndefined();
30+
});
31+
32+
it("attributes only public hostnames that name exactly one host", () => {
33+
expect(sourceControlClients.findByPublicHost("GitHub.com")?.kind).toBe("github");
34+
expect(sourceControlClients.findByPublicHost("gitlab.com")?.kind).toBe("gitlab");
35+
expect(sourceControlClients.findByPublicHost("codeberg.org")).toBeUndefined();
36+
expect(sourceControlClients.findByPublicHost("dev.azure.com")).toBeUndefined();
37+
});
38+
39+
it("builds each host's checkout command", () => {
40+
const checkout = (kind: string, input: ChangeRequestCheckoutInput) =>
41+
sourceControlClients.get(kind).checkoutCommand(input);
42+
expect(checkout("github", { number: 42, headBranch: "" })).toBe("gh pr checkout 42");
43+
expect(checkout("gitlab", { number: 42, headBranch: "" })).toBe("glab mr checkout 42");
44+
expect(checkout("azure-devops", { number: 42, headBranch: "" })).toBe(
45+
"az repos pr checkout --id 42",
46+
);
47+
expect(checkout("unknown", { number: 42, headBranch: "feature" })).toBeNull();
48+
expect(checkout("forgejo", { number: 42, headBranch: "feature" })).toBeNull();
49+
expect(
50+
checkout("forgejo", {
51+
number: 42,
52+
headBranch: "feature",
53+
repositoryUrl: "https://forgejo.local/maria/repo'$(echo nope)",
54+
}),
55+
).toBe(
56+
"git fetch 'https://forgejo.local/maria/repo'\\''$(echo nope)' refs/pull/42/head && git checkout -B pulls/42 FETCH_HEAD",
57+
);
58+
expect(
59+
checkout("bitbucket", {
60+
number: 42,
61+
headBranch: "feature/checkout",
62+
headRepositoryNameWithOwner: "maria/t3code",
63+
}),
64+
).toBe(
65+
"git clone --single-branch --branch feature/checkout https://bitbucket.org/maria/t3code.git t3code-pr-42",
66+
);
67+
expect(
68+
checkout("bitbucket", {
69+
number: 42,
70+
headBranch: "feature;rm -rf /",
71+
headRepositoryNameWithOwner: "maria/t3code",
72+
}),
73+
).toBeNull();
74+
});
75+
76+
it("links GitHub author profiles but not bots, and no other host's", () => {
77+
const github = sourceControlClients.get("github");
78+
expect(github.authorProfileUrl("octo cat", "https://ghe.example/acme/web")).toBe(
79+
"https://ghe.example/octo%20cat",
80+
);
81+
expect(github.authorProfileUrl("renovate[bot]", "https://github.com/acme/web")).toBeNull();
82+
expect(
83+
sourceControlClients.get("gitlab").authorProfileUrl("octocat", "https://gitlab.com/a/b"),
84+
).toBeNull();
85+
});
86+
87+
it("asks only Forgejo for a summary when requesting changes", () => {
88+
expect(sourceControlClients.get("forgejo").reviewSummaryRequired("request-changes")).toBe(true);
89+
expect(sourceControlClients.get("forgejo").reviewSummaryRequired("approve")).toBe(false);
90+
expect(sourceControlClients.get("github").reviewSummaryRequired("request-changes")).toBe(false);
91+
});
92+
});
93+
94+
describe("reference autolinks", () => {
95+
it("link only under GitHub's repository URL", () => {
96+
expect(
97+
sourceControlClients.get("github").referenceAutolinkRepositoryUrl("https://github.com/a/b"),
98+
).toBe("https://github.com/a/b");
99+
expect(
100+
sourceControlClients.get("gitlab").referenceAutolinkRepositoryUrl("https://gitlab.com/a/b"),
101+
).toBeNull();
102+
});
103+
});
104+
105+
describe("change request URLs", () => {
106+
const url = (
107+
kind: string,
108+
input: Parameters<typeof UNKNOWN_SOURCE_CONTROL_CLIENT.changeRequestUrl>[0],
109+
) => sourceControlClients.get(kind).changeRequestUrl(input);
110+
const at = { host: "code.example", repository: "acme/web", number: 7 };
111+
112+
it("builds each host's path", () => {
113+
expect(url("github", at)).toBe("https://code.example/acme/web/pull/7");
114+
expect(url("gitlab", at)).toBe("https://code.example/acme/web/-/merge_requests/7");
115+
expect(url("bitbucket", at)).toBe("https://code.example/acme/web/pull-requests/7");
116+
expect(
117+
url("azure-devops", {
118+
host: "ssh.dev.azure.com",
119+
repository: "v3/org/project/web",
120+
number: 7,
121+
}),
122+
).toBe("https://dev.azure.com/org/project/_git/web/pullrequest/7");
123+
expect(url("unknown", at)).toBeNull();
124+
});
125+
126+
it("puts Forgejo pages on the server's web origin", () => {
127+
expect(url("forgejo", { ...at, webUrl: "https://code.example:3000/git/acme/web/" })).toBe(
128+
"https://code.example:3000/git/acme/web/pulls/7",
129+
);
130+
expect(url("forgejo", { ...at, remoteUrl: "http://code.example:3000/acme/web.git" })).toBe(
131+
"http://code.example:3000/acme/web/pulls/7",
132+
);
133+
expect(url("forgejo", { ...at, remoteUrl: "[email protected]:acme/web.git" })).toBe(
134+
"https://code.example/acme/web/pulls/7",
135+
);
136+
expect(url("forgejo", { ...at, remoteUrl: "https://elsewhere.example/acme/web.git" })).toBe(
137+
"https://code.example/acme/web/pulls/7",
138+
);
139+
});
140+
});
Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
/**
2+
* The source control host definitions web and mobile ship, and the one lookup they use.
3+
*
4+
* Adding a host means writing its `@t3tools/source-control-<host>` package with a
5+
* `./client/definition` entry and adding it here; clients then label, list, and check out its
6+
* change requests without further branches.
7+
*
8+
* @module client-runtime/sourceControlClients
9+
*/
10+
import * as AzureDevOps from "@t3tools/source-control-azure-devops/client/definition";
11+
import * as Bitbucket from "@t3tools/source-control-bitbucket/client/definition";
12+
import { makeSourceControlClientRegistry } from "@t3tools/source-control-core/client/definition";
13+
14+
export {
15+
UNKNOWN_SOURCE_CONTROL_CLIENT,
16+
type ChangeRequestTerminology,
17+
type SourceControlClientDefinition,
18+
} from "@t3tools/source-control-core/client/definition";
19+
import * as Forgejo from "@t3tools/source-control-forgejo/client/definition";
20+
import * as GitHub from "@t3tools/source-control-github/client/definition";
21+
import * as GitLab from "@t3tools/source-control-gitlab/client/definition";
22+
23+
/**
24+
* Ordered as the clone picker lists hosts. GitHub comes first because a repository that has not
25+
* reported its host yet reads as GitHub, which is what clients have always shown there.
26+
*/
27+
const BUILT_IN_SOURCE_CONTROL_CLIENTS = [
28+
GitHub.definition,
29+
GitLab.definition,
30+
Forgejo.definition,
31+
Bitbucket.definition,
32+
AzureDevOps.definition,
33+
];
34+
35+
/** `definitions` lists the built-in hosts in that order, for pickers that offer every host. */
36+
export const sourceControlClients = makeSourceControlClientRegistry(
37+
BUILT_IN_SOURCE_CONTROL_CLIENTS,
38+
);

‎packages/source-control-azure-devops/package.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@
33
"private": true,
44
"type": "module",
55
"exports": {
6+
"./client/definition": {
7+
"types": "./src/client/definition.ts",
8+
"import": "./src/client/definition.ts"
9+
},
610
"./server/AzureDevOpsCli": {
711
"types": "./src/server/AzureDevOpsCli.ts",
812
"import": "./src/server/AzureDevOpsCli.ts"
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
/**
2+
* Azure DevOps's client definition. Browser- and React Native-safe.
3+
*
4+
* @module source-control-azure-devops/client/definition
5+
*/
6+
import { SourceControlProviderKind } from "@t3tools/contracts";
7+
import { canonicalRepositoryKey } from "@t3tools/shared/sourceControl";
8+
import { defineSourceControlClient } from "@t3tools/source-control-core/client/definition";
9+
10+
export const definition = defineSourceControlClient({
11+
kind: SourceControlProviderKind.make("azure-devops"),
12+
label: "Azure DevOps",
13+
pickerLabel: "Azure DevOps",
14+
icon: "azure-devops",
15+
changeRequest: { shortLabel: "PR", singular: "pull request" },
16+
repositoryPathHint: "project/repository",
17+
// `az repos` reads need the checkout's organization and project, so a bare hostname names no
18+
// repository this client can act on.
19+
publicHost: null,
20+
publishDescription: "dev.azure.com",
21+
publishHost: () => "dev.azure.com",
22+
defaultCloneTransport: "ssh",
23+
changeRequestUrl: ({ host, repository, number }) =>
24+
`https://${canonicalRepositoryKey(`${host}/${repository}`.toLowerCase())}/pullrequest/${number}`,
25+
checkoutCommand: ({ number }) => `az repos pr checkout --id ${number}`,
26+
authorProfileUrl: () => null,
27+
referenceAutolinkRepositoryUrl: () => null,
28+
reviewSummaryRequired: () => false,
29+
isChangeRequestUrl: (url) => url.includes("/pullrequest/"),
30+
});

‎packages/source-control-bitbucket/package.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@
33
"private": true,
44
"type": "module",
55
"exports": {
6+
"./client/definition": {
7+
"types": "./src/client/definition.ts",
8+
"import": "./src/client/definition.ts"
9+
},
610
"./server/BitbucketApi": {
711
"types": "./src/server/BitbucketApi.ts",
812
"import": "./src/server/BitbucketApi.ts"
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
/**
2+
* Bitbucket's client definition. Browser- and React Native-safe.
3+
*
4+
* @module source-control-bitbucket/client/definition
5+
*/
6+
import { SourceControlProviderKind } from "@t3tools/contracts";
7+
import { defineSourceControlClient } from "@t3tools/source-control-core/client/definition";
8+
9+
const safeShellArgument = /^[A-Za-z0-9._/@+=,-]+$/;
10+
const repositoryName = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
11+
12+
export const definition = defineSourceControlClient({
13+
kind: SourceControlProviderKind.make("bitbucket"),
14+
label: "Bitbucket",
15+
pickerLabel: "Bitbucket",
16+
icon: "bitbucket",
17+
changeRequest: { shortLabel: "PR", singular: "pull request" },
18+
repositoryPathHint: "workspace/repository",
19+
publicHost: "bitbucket.org",
20+
publishDescription: "bitbucket.org",
21+
publishHost: () => "bitbucket.org",
22+
defaultCloneTransport: "ssh",
23+
changeRequestUrl: ({ host, repository, number }) =>
24+
`https://${host}/${repository}/pull-requests/${number}`,
25+
// Bitbucket has no checkout CLI, so clone the head branch from its own repository.
26+
checkoutCommand: ({ number, headBranch, headRepositoryNameWithOwner }) =>
27+
headRepositoryNameWithOwner &&
28+
repositoryName.test(headRepositoryNameWithOwner) &&
29+
safeShellArgument.test(headBranch)
30+
? `git clone --single-branch --branch ${headBranch} https://bitbucket.org/${headRepositoryNameWithOwner}.git t3code-pr-${number}`
31+
: null,
32+
authorProfileUrl: () => null,
33+
referenceAutolinkRepositoryUrl: () => null,
34+
reviewSummaryRequired: () => false,
35+
isChangeRequestUrl: (url) => url.includes("/pull-requests/"),
36+
});

‎packages/source-control-core/package.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@
33
"private": true,
44
"type": "module",
55
"exports": {
6+
"./client/definition": {
7+
"types": "./src/client/definition.ts",
8+
"import": "./src/client/definition.ts"
9+
},
610
"./server/diffFileRevisions": {
711
"types": "./src/server/diffFileRevisions.ts",
812
"import": "./src/server/diffFileRevisions.ts"

0 commit comments

Comments
 (0)