Skip to content

Commit ee62d56

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 6c6a5b2 commit ee62d56

18 files changed

Lines changed: 480 additions & 0 deletions

File tree

‎packages/client-runtime/package.json‎

Lines changed: 11 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,13 @@
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-gitcafe": "workspace:*",
411+
"@t3tools/source-control-github": "workspace:*",
412+
"@t3tools/source-control-gitlab": "workspace:*",
402413
"effect": "catalog:",
403414
"three": "0.180.0"
404415
},
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
import { describe, expect, it } from "vite-plus/test";
2+
3+
import { sourceControlClients } from "./sourceControlClients.ts";
4+
5+
describe("sourceControlClients", () => {
6+
it("reads a missing kind as the first host and an unshipped kind as the generic one", () => {
7+
expect(sourceControlClients.get(undefined).kind).toBe("github");
8+
expect(sourceControlClients.get("forkhost").kind).toBe("unknown");
9+
});
10+
11+
it("gives a change request URL to the first host whose shape it has", () => {
12+
// GitCafe and Forgejo share `/pulls/`; GitCafe only claims its own hostnames.
13+
const kindOf = (url: string) => sourceControlClients.findByChangeRequestUrl(url)?.kind;
14+
expect(kindOf("https://git.cafe/acme/web/pulls/7")).toBe("gitcafe");
15+
expect(kindOf("https://codeberg.org/acme/web/pulls/7")).toBe("forgejo");
16+
});
17+
});
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
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+
type ChangeRequestTerminology,
16+
type SourceControlClientDefinition,
17+
} from "@t3tools/source-control-core/client/definition";
18+
import * as Forgejo from "@t3tools/source-control-forgejo/client/definition";
19+
import * as GitCafe from "@t3tools/source-control-gitcafe/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+
* GitHub comes first because a repository that has not reported its host yet reads as GitHub,
25+
* which is what clients have always shown there. A change request URL goes to the first host
26+
* whose shape it has, so GitCafe, which claims `/pulls/` only on its own hostnames, comes before
27+
* Forgejo, which claims it everywhere. Pickers sort by readiness and label, not by this order.
28+
*/
29+
const BUILT_IN_SOURCE_CONTROL_CLIENTS = [
30+
GitHub.definition,
31+
GitLab.definition,
32+
GitCafe.definition,
33+
Forgejo.definition,
34+
Bitbucket.definition,
35+
AzureDevOps.definition,
36+
];
37+
38+
/** `definitions` lists the built-in hosts in that order, for pickers that offer every host. */
39+
export const sourceControlClients = makeSourceControlClientRegistry(
40+
BUILT_IN_SOURCE_CONTROL_CLIENTS,
41+
);

‎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"
Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
/**
2+
* The client half of a source control host package.
3+
*
4+
* Every host package exports a `SourceControlClientDefinition` from its `./client/definition`
5+
* entry point, the way `./server/driver` is its server entry. Web, mobile, and client-runtime
6+
* read labels, change request nouns, picker copy, and checkout commands from these definitions,
7+
* so a new host needs no per-kind branches in client code.
8+
*
9+
* Definitions are browser- and React Native-safe: plain data and pure functions, no server or
10+
* platform UI imports.
11+
*
12+
* @module source-control-core/client/definition
13+
*/
14+
import { type PullRequestReviewVerdict, SourceControlProviderKind } from "@t3tools/contracts";
15+
16+
/** What a host calls a change request, e.g. `MR` and `merge request` on GitLab. */
17+
export interface ChangeRequestTerminology {
18+
readonly shortLabel: string;
19+
readonly singular: string;
20+
}
21+
22+
/** Where a project's repository lives, for building its change request URLs. */
23+
export interface ChangeRequestUrlInput {
24+
/** The host below which the repository is addressed, as `pullRequestHostOf` reports it. */
25+
readonly host: string;
26+
/** The repository path below the host. */
27+
readonly repository: string;
28+
readonly number: number;
29+
/** The checkout's remote URL, whose origin some hosts serve their web pages from. */
30+
readonly remoteUrl?: string | undefined;
31+
/** The repository's browser URL, when the server resolved one from a hosting account. */
32+
readonly webUrl?: string | undefined;
33+
}
34+
35+
/** The change request a checkout command is built for. */
36+
export interface ChangeRequestCheckoutInput {
37+
readonly number: number;
38+
readonly headBranch: string;
39+
readonly headRepositoryNameWithOwner?: string | null | undefined;
40+
/** The repository's web URL, for hosts whose checkout fetches from it. */
41+
readonly repositoryUrl?: string | null | undefined;
42+
}
43+
44+
export interface SourceControlClientDefinition {
45+
readonly kind: SourceControlProviderKind;
46+
/** The host's name, as in "Open on GitHub". */
47+
readonly label: string;
48+
/** How the clone and publish pickers name the host; Forgejo's covers Gitea too. */
49+
readonly pickerLabel: string;
50+
/** Glyph key each client maps to its own icon; a key a client lacks draws the generic glyph. */
51+
readonly icon: string;
52+
readonly changeRequest: ChangeRequestTerminology;
53+
/** Placeholder for a repository path on this host, such as `owner/repo`. */
54+
readonly repositoryPathHint: string;
55+
/**
56+
* The hostname a change request reference can be attributed to before any repository
57+
* identity is known, or null when a hostname alone does not name this host.
58+
*/
59+
readonly publicHost: string | null;
60+
/** Subtitle beside the host in the publish picker. */
61+
readonly publishDescription: string;
62+
/** Where a publish lands, given the host the server is signed in to, if it reported one. */
63+
readonly publishHost: (signedInHost: string | null) => string;
64+
/** Which of a repository's clone URLs a new clone uses. */
65+
readonly defaultCloneTransport: "https" | "ssh";
66+
/** The web URL of a change request, or null when this client cannot build one for the host. */
67+
readonly changeRequestUrl: (input: ChangeRequestUrlInput) => string | null;
68+
/** A shell command that checks the change request out, or null when it cannot be built. */
69+
readonly checkoutCommand: (changeRequest: ChangeRequestCheckoutInput) => string | null;
70+
/** A comment author's profile page, or null where the host has none clients can link. */
71+
readonly authorProfileUrl: (login: string, repositoryUrl: string) => string | null;
72+
/**
73+
* The repository URL that `#123` and commit SHAs in change request text link under, using
74+
* GitHub's `/issues/` and `/commit/` routes, or null where the host does not route them so.
75+
*/
76+
readonly referenceAutolinkRepositoryUrl: (repositoryUrl: string) => string | null;
77+
/** Whether a review with this verdict must carry a summary, beyond what every host asks. */
78+
readonly reviewSummaryRequired: (verdict: PullRequestReviewVerdict) => boolean;
79+
/** Whether a change request URL has this host's path shape, e.g. GitLab's `/-/merge_requests/`. */
80+
readonly isChangeRequestUrl: (url: string) => boolean;
81+
}
82+
83+
export function defineSourceControlClient<const Definition extends SourceControlClientDefinition>(
84+
definition: Definition,
85+
): Definition {
86+
return definition;
87+
}
88+
89+
/** What clients show for a host they ship no definition for, including `unknown`. */
90+
const UNKNOWN_SOURCE_CONTROL_CLIENT: SourceControlClientDefinition = {
91+
kind: SourceControlProviderKind.make("unknown"),
92+
label: "source control",
93+
pickerLabel: "source control",
94+
icon: "change-request",
95+
changeRequest: { shortLabel: "change request", singular: "change request" },
96+
repositoryPathHint: "URL",
97+
publicHost: null,
98+
publishDescription: "Your signed-in server",
99+
publishHost: (signedInHost) => signedInHost ?? "your server",
100+
defaultCloneTransport: "ssh",
101+
changeRequestUrl: () => null,
102+
checkoutCommand: () => null,
103+
authorProfileUrl: () => null,
104+
referenceAutolinkRepositoryUrl: () => null,
105+
reviewSummaryRequired: () => false,
106+
isChangeRequestUrl: () => false,
107+
};
108+
109+
/** The host definitions a client loaded. */
110+
export interface SourceControlClientRegistry {
111+
readonly definitions: ReadonlyArray<SourceControlClientDefinition>;
112+
/**
113+
* The definition for a kind. No kind at all, before a repository reports its host, reads as
114+
* the first definition; a kind this client lacks, `unknown` included, reads as
115+
* `UNKNOWN_SOURCE_CONTROL_CLIENT`.
116+
*/
117+
readonly get: (kind: string | null | undefined) => SourceControlClientDefinition;
118+
/** The definition for a kind, or `undefined` for one this client lacks. */
119+
readonly find: (kind: string) => SourceControlClientDefinition | undefined;
120+
/** The definition whose public instance is `hostname`, if any. */
121+
readonly findByPublicHost: (hostname: string) => SourceControlClientDefinition | undefined;
122+
/** The definition whose change request path shape `url` has, if any. */
123+
readonly findByChangeRequestUrl: (url: string) => SourceControlClientDefinition | undefined;
124+
/** The name of the host a change request URL is on, for copy about that change request. */
125+
readonly hostLabelForChangeRequestUrl: (url: string) => string;
126+
}
127+
128+
export function makeSourceControlClientRegistry(
129+
definitions: ReadonlyArray<SourceControlClientDefinition>,
130+
): SourceControlClientRegistry {
131+
const byKind = new Map<string, SourceControlClientDefinition>();
132+
for (const definition of definitions) {
133+
if (byKind.has(definition.kind)) {
134+
throw new Error(`Source control host '${definition.kind}' is defined more than once.`);
135+
}
136+
byKind.set(definition.kind, definition);
137+
}
138+
return {
139+
definitions,
140+
get: (kind) => (kind ? byKind.get(kind) : definitions[0]) ?? UNKNOWN_SOURCE_CONTROL_CLIENT,
141+
find: (kind) => byKind.get(kind),
142+
findByPublicHost: (hostname) => {
143+
const host = hostname.toLowerCase();
144+
return definitions.find((definition) => definition.publicHost === host);
145+
},
146+
findByChangeRequestUrl: (url) =>
147+
definitions.find((definition) => definition.isChangeRequestUrl(url)),
148+
hostLabelForChangeRequestUrl: (url) =>
149+
definitions.find((definition) => definition.isChangeRequestUrl(url))?.label ?? "the host",
150+
};
151+
}

‎packages/source-control-forgejo/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/driver": {
711
"types": "./src/server/driver.ts",
812
"import": "./src/server/driver.ts"

0 commit comments

Comments
 (0)