The best way to control Claude Code, Codex and more from any computer or phone

main
ts 224 lines 8.74 KB
Raw
1 import * as Context from "effect/Context";
2 import * as Effect from "effect/Effect";
3 import type * as Option from "effect/Option";
4 import type {
5 RepositoryIdentity,
6 ChangeRequest,
7 ChangeRequestState,
8 SourceControlProviderError,
9 SourceControlProviderInfo,
10 SourceControlProviderKind,
11 SourceControlRepositoryCloneUrls,
12 SourceControlRepositoryVisibility,
13 } from "@t3tools/contracts";
14
15 export interface SourceControlLinkSubject {
16 readonly title: string;
17 readonly body: string | null;
18 }
19
20 /** Return undefined synchronously for unsupported URLs, without starting a lookup. */
21 export type ResolveSourceControlLink = (input: {
22 readonly cwd: string;
23 readonly url: URL;
24 }) => Effect.Effect<SourceControlLinkSubject, SourceControlProviderError> | undefined;
25
26 export interface SourceControlProviderContext {
27 readonly provider: SourceControlProviderInfo;
28 readonly remoteName: string;
29 readonly remoteUrl: string;
30 readonly requestedHost?: string;
31 }
32
33 export interface SourceControlRefSelector {
34 readonly refName: string;
35 readonly owner?: string;
36 readonly repository?: string;
37 }
38
39 const MAX_ERROR_TRANSPORT_VALUE_LENGTH = 256;
40
41 /**
42 * The fixed product text a provider failure carries for the user, if it has one. Any other
43 * detail may be upstream response text, so callers show a generic message instead.
44 */
45 export function userFacingSourceControlDetail(cause: unknown): string | undefined {
46 return typeof cause === "object" &&
47 cause !== null &&
48 "userFacingDetail" in cause &&
49 typeof cause.userFacingDetail === "string"
50 ? cause.userFacingDetail
51 : undefined;
52 }
53
54 export function transportSafeSourceControlErrorValue(value: string): string {
55 let printable = "";
56 for (const character of value) {
57 const codePoint = character.codePointAt(0);
58 printable += codePoint !== undefined && (codePoint < 32 || codePoint === 127) ? " " : character;
59 }
60 const normalized = printable.trim().replace(/\s+/gu, " ");
61
62 let safe = normalized;
63 try {
64 const url = new URL(normalized);
65 url.username = "";
66 url.password = "";
67 url.search = "";
68 url.hash = "";
69 safe = url.toString();
70 } catch {}
71
72 return safe.slice(0, MAX_ERROR_TRANSPORT_VALUE_LENGTH);
73 }
74
75 export function parseSourceControlOwnerRef(
76 headSelector: string,
77 ): SourceControlRefSelector | undefined {
78 const match = /^([^:/\s]+):(.+)$/u.exec(headSelector.trim());
79 const owner = match?.[1]?.trim();
80 const refName = match?.[2]?.trim();
81 return owner && refName ? { owner, refName } : undefined;
82 }
83
84 function normalizeSourceBranch(headSelector: string): string {
85 return parseSourceControlOwnerRef(headSelector)?.refName ?? headSelector.trim();
86 }
87
88 export function sourceBranch(input: {
89 readonly headSelector: string;
90 readonly source?: SourceControlRefSelector;
91 }): string {
92 return input.source?.refName ?? normalizeSourceBranch(input.headSelector);
93 }
94
95 export function sourceControlRefFromInput(input: {
96 readonly headSelector: string;
97 readonly source?: SourceControlRefSelector;
98 }): SourceControlRefSelector | undefined {
99 return input.source ?? parseSourceControlOwnerRef(input.headSelector);
100 }
101
102 export function repositoryPathFromRemoteUrl(url: string | null): string | null {
103 const remote = url?.trim() ?? "";
104 const trimmed = /^(?:ssh|https?|git):\/\//iu.test(remote) ? remote.split(/[?#]/u, 1)[0]! : remote;
105 if (trimmed.length === 0) {
106 return null;
107 }
108
109 const match =
110 /^(?:[^@/\s]+@[^:/\s]+:|[^@:/\\\s]{2,}:(?!:)|(?:ssh|https?|git):\/\/[^/]+\/)((?:[^/\s]+\/)+[^/\s]+?)(?:\.git)?\/?$/iu.exec(
111 trimmed,
112 );
113 const path = match?.[1]?.trim() ?? "";
114 return path.length > 0 ? path : null;
115 }
116
117 export class SourceControlProvider extends Context.Service<
118 SourceControlProvider,
119 {
120 readonly kind: SourceControlProviderKind;
121 /** The caller verifies owners, so hosts may drop unsupported `owner:branch` selectors. */
122 readonly headBranchProbe?: (input: {
123 readonly headSelectors: ReadonlyArray<string>;
124 readonly state: "open" | "all";
125 /** `owner:branch` to read instead of bare names, when the caller knows the head's owner. */
126 readonly ownerHeadSelector?: string | undefined;
127 }) => { readonly headSelectors: ReadonlyArray<string>; readonly limit: number };
128 readonly readChangeRequestTemplate?: (input: {
129 readonly cwd: string;
130 readonly treeish: string;
131 }) => Effect.Effect<Option.Option<string>>;
132 /** Strip installation mounts from remote paths; absent means use the whole path. */
133 readonly repositoryNameFromRemoteUrl?: (url: string) => string | null;
134 readonly refineRepositoryIdentity?: (input: {
135 readonly identity: RepositoryIdentity;
136 readonly resolveContext: (input: {
137 readonly cwd: string;
138 readonly context: SourceControlProviderContext;
139 }) => Effect.Effect<SourceControlProviderContext | null, SourceControlProviderError>;
140 }) => Effect.Effect<RepositoryIdentity, SourceControlProviderError>;
141 /**
142 * The web host serving a remote, for a host whose remote URL may not name it (an SSH alias
143 * for one of several servers). It answers for the context's `requestedHost` when the caller
144 * narrows to one. Absent, or null, means the remote's own host is the web host.
145 */
146 readonly resolveRemoteWebHost?: (input: {
147 readonly cwd: string;
148 readonly context: SourceControlProviderContext;
149 readonly resolveContext: (input: {
150 readonly cwd: string;
151 readonly context: SourceControlProviderContext;
152 }) => Effect.Effect<SourceControlProviderContext | null, SourceControlProviderError>;
153 }) => Effect.Effect<string | null, SourceControlProviderError>;
154 readonly resolveLink?: ResolveSourceControlLink;
155 /**
156 * Whether `createChangeRequest` from `cwd` targets `repository`, the `owner/name` of the
157 * context's remote, for a host whose tools let configuration outside the remotes name another
158 * repository. Absent means it does.
159 */
160 readonly createsChangeRequestsIn?: (input: {
161 readonly cwd: string;
162 readonly context: SourceControlProviderContext;
163 readonly repository: string | null;
164 }) => Effect.Effect<boolean>;
165 /**
166 * Told when T3 records `baseBranch`, a branch name on the host, as the base `branch` was cut
167 * from, for a host whose own tools keep that in git config of their own.
168 */
169 readonly recordBranchBase?: (input: {
170 readonly cwd: string;
171 readonly branch: string;
172 readonly baseBranch: string;
173 }) => Effect.Effect<void>;
174 /** True when `createChangeRequest` opens the change request as a draft when asked. */
175 readonly createsDraftChangeRequests?: boolean;
176 readonly listChangeRequests: (input: {
177 readonly cwd: string;
178 readonly context?: SourceControlProviderContext;
179 readonly source?: SourceControlRefSelector;
180 readonly headSelector: string;
181 readonly state: ChangeRequestState | "all";
182 readonly limit?: number;
183 }) => Effect.Effect<ReadonlyArray<ChangeRequest>, SourceControlProviderError>;
184 readonly getChangeRequest: (input: {
185 readonly cwd: string;
186 readonly context?: SourceControlProviderContext;
187 readonly reference: string;
188 }) => Effect.Effect<ChangeRequest, SourceControlProviderError>;
189 readonly createChangeRequest: (input: {
190 readonly cwd: string;
191 readonly context?: SourceControlProviderContext;
192 readonly source?: SourceControlRefSelector;
193 readonly target?: SourceControlRefSelector;
194 readonly baseRefName: string;
195 readonly headSelector: string;
196 readonly title: string;
197 readonly bodyFile: string;
198 /** Honored only by a provider with `createsDraftChangeRequests`. */
199 readonly draft?: boolean;
200 }) => Effect.Effect<void, SourceControlProviderError>;
201 readonly getRepositoryCloneUrls: (input: {
202 readonly cwd: string;
203 readonly context?: SourceControlProviderContext;
204 readonly repository: string;
205 /** The host the repository is on. Without it, the checkout's host. */
206 readonly host?: string;
207 }) => Effect.Effect<SourceControlRepositoryCloneUrls, SourceControlProviderError>;
208 readonly createRepository: (input: {
209 readonly cwd: string;
210 readonly repository: string;
211 readonly visibility: SourceControlRepositoryVisibility;
212 }) => Effect.Effect<SourceControlRepositoryCloneUrls, SourceControlProviderError>;
213 readonly getDefaultBranch: (input: {
214 readonly cwd: string;
215 readonly context?: SourceControlProviderContext;
216 }) => Effect.Effect<string | null, SourceControlProviderError>;
217 readonly checkoutChangeRequest: (input: {
218 readonly cwd: string;
219 readonly context?: SourceControlProviderContext;
220 readonly reference: string;
221 readonly force?: boolean;
222 }) => Effect.Effect<void, SourceControlProviderError>;
223 }
224 >()("@t3tools/source-control-core/server/SourceControlProvider") {}