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

main
ts 228 lines 8.61 KB
Raw
1 /**
2 * The port every issue tracker implements. A tracker hands back the neutral contract types and
3 * declares what it cannot do in `capabilities`; the service refuses a call outside them.
4 */
5 import * as Schema from "effect/Schema";
6 import type * as Effect from "effect/Effect";
7 import type {
8 IssueState,
9 IssueCandidates,
10 IssueCapabilities,
11 IssueComment,
12 IssueCommentsPage,
13 IssueCreateResult,
14 IssueEvent,
15 IssueInvolvement,
16 IssueListSort,
17 IssueLinkedPullRequest,
18 IssueListState,
19 IssueReaction,
20 IssueReactionContent,
21 IssueSummary,
22 IssueTemplateList,
23 IssueTrackerKind,
24 IssueTrackerScope,
25 IssueViewerPermissions,
26 StandaloneIssueTrackerDescriptor,
27 } from "@t3tools/contracts";
28 import { IssueTrackerKind as IssueTrackerKindSchema } from "@t3tools/contracts";
29 import type { IssueLink } from "../shared/definition.ts";
30
31 /**
32 * The one failure shape every tracker reports, so the service can decide what a failure means
33 * without knowing which CLI or API produced it. A missing or unauthenticated tool disables the
34 * tracker for the whole workspace; everything else is specific to the request.
35 */
36 export class IssueTrackerError extends Schema.TaggedError<IssueTrackerError>()(
37 "IssueTrackerError",
38 {
39 tracker: IssueTrackerKindSchema,
40 operation: Schema.String,
41 reason: Schema.Literals([
42 "missing-tool",
43 "unauthenticated",
44 "rate-limited",
45 "not-found",
46 "failed",
47 ]),
48 detail: Schema.String,
49 retryAt: Schema.optional(Schema.Number),
50 cause: Schema.optional(Schema.Defect()),
51 },
52 ) {
53 override get message(): string {
54 return `${this.tracker} failed in ${this.operation}: ${this.detail}`;
55 }
56 }
57
58 /**
59 * Where a tracker's issues are addressed from. `cwd` is a checkout whose credentials serve the
60 * read; `host` is where the tracker is served from (`github.com`, a GHE install, `linear.app`);
61 * `scope` is the tracker's own container — a repository path, a team or project key.
62 */
63 export interface IssueScopeTarget {
64 readonly cwd: string;
65 readonly host: string;
66 readonly scope: string;
67 }
68
69 export interface IssueTarget extends IssueScopeTarget {
70 /** The issue's native id within the scope: `"123"` on GitHub, `"ENG-123"` on Linear. */
71 readonly key: string;
72 }
73
74 /** An issue as the tracker sees it, before the service attaches project context. */
75 export type TrackerIssueSummary = Omit<IssueSummary, "tracker" | "host" | "scope">;
76
77 export interface TrackerIssuePage {
78 readonly items: ReadonlyArray<TrackerIssueSummary>;
79 /** Where the next slice starts, or null once the tracker has nothing more. Opaque. */
80 readonly nextCursor: string | null;
81 }
82
83 export interface TrackerIssueDetail extends TrackerIssueSummary {
84 readonly body: string;
85 readonly viewer: string | null;
86 readonly viewerPermissions: IssueViewerPermissions;
87 /** Every state the issue can be in, in workflow order; `setState` is asked for one by name. */
88 readonly states: ReadonlyArray<IssueState>;
89 readonly reactions?: ReadonlyArray<IssueReaction>;
90 readonly comments: ReadonlyArray<IssueComment>;
91 /** Where older comments carry on; null once the conversation is whole. */
92 readonly commentsCursor: string | null;
93 readonly events: ReadonlyArray<IssueEvent>;
94 readonly linkedPullRequests: ReadonlyArray<IssueLinkedPullRequest>;
95 }
96
97 /**
98 * Whose issues a listing keeps. Only a narrowed listing names the signed-in account it compares
99 * against, so an `all` listing never has to read it.
100 */
101 export type IssueInvolvementFilter =
102 | { readonly involvement: "all" }
103 | { readonly involvement: Exclude<IssueInvolvement, "all">; readonly viewer: string };
104
105 export interface IssueTrackerApi {
106 readonly kind: IssueTrackerKind;
107 readonly capabilities: IssueCapabilities;
108
109 /** The signed-in account, which is what involvement filtering compares against. */
110 readonly getViewer: (input: {
111 readonly cwd: string;
112 readonly host: string;
113 }) => Effect.Effect<string, IssueTrackerError>;
114
115 readonly listIssues: (
116 input: IssueScopeTarget &
117 IssueInvolvementFilter & {
118 readonly state: IssueListState;
119 readonly limit: number;
120 /** Free text as the tracker understands it; ignored by a tracker without `search`. */
121 readonly query?: string | undefined;
122 /** Label names an issue must carry, every one of them. */
123 readonly labels?: ReadonlyArray<string> | undefined;
124 /** The `login` of an assignee, as this tracker's own issues name them. */
125 readonly assignee?: string | undefined;
126 readonly sort: IssueListSort;
127 /** A cursor this tracker handed back from an earlier page. Absent asks for the first. */
128 readonly cursor?: string | undefined;
129 /** Whether to re-read tracker metadata for a first page. */
130 readonly refresh?: boolean | undefined;
131 },
132 ) => Effect.Effect<TrackerIssuePage, IssueTrackerError>;
133
134 /** The issue with its first page of conversation, in one read where the tracker allows. */
135 readonly getIssue: (input: IssueTarget) => Effect.Effect<TrackerIssueDetail, IssueTrackerError>;
136
137 /** One page of older comments past a cursor `getIssue` or a previous page handed over. */
138 readonly getComments: (
139 input: IssueTarget & { readonly cursor: string },
140 ) => Effect.Effect<IssueCommentsPage, IssueTrackerError>;
141
142 /** Only called when `capabilities.create` is true. */
143 readonly create?: (
144 input: IssueScopeTarget & {
145 readonly title: string;
146 readonly body: string;
147 readonly labels: ReadonlyArray<string>;
148 readonly assignees: ReadonlyArray<string>;
149 },
150 ) => Effect.Effect<IssueCreateResult, IssueTrackerError>;
151
152 /** Only called when `capabilities.comment` is true. */
153 readonly comment?: (
154 input: IssueTarget & { readonly body: string },
155 ) => Effect.Effect<void, IssueTrackerError>;
156
157 /**
158 * Rewrites the present fields. Only called with a field the tracker declared it can write
159 * (`edit` for title and body, `labels`, `assignees`), and never with all of them absent.
160 */
161 readonly update?: (
162 input: IssueTarget & {
163 readonly title?: string | undefined;
164 readonly body?: string | undefined;
165 readonly labels?: ReadonlyArray<string> | undefined;
166 readonly assignees?: ReadonlyArray<string> | undefined;
167 },
168 ) => Effect.Effect<void, IssueTrackerError>;
169
170 /**
171 * Moves the issue to the state `getIssue` listed under that name, and refuses any other: the
172 * name comes from a client, so the tracker is what proves it.
173 */
174 readonly setState?: (
175 input: IssueTarget & { readonly state: string },
176 ) => Effect.Effect<void, IssueTrackerError>;
177
178 /**
179 * Adds a reaction or takes it back. `subjectId` is a comment id as the detail carried it;
180 * absent means the issue itself. Only called when `capabilities.reactions` is true.
181 */
182 readonly setReaction?: (
183 input: IssueTarget & {
184 readonly subjectId?: string | undefined;
185 readonly content: IssueReactionContent;
186 readonly reacted: boolean;
187 },
188 ) => Effect.Effect<void, IssueTrackerError>;
189
190 /** Only called when `capabilities.templates` is true. */
191 readonly listTemplates?: (
192 input: IssueScopeTarget,
193 ) => Effect.Effect<IssueTemplateList, IssueTrackerError>;
194
195 /** Only called when `capabilities.labels` or `capabilities.assignees` is true. */
196 readonly listCandidates?: (
197 input: IssueScopeTarget,
198 ) => Effect.Effect<IssueCandidates, IssueTrackerError>;
199 }
200
201 /**
202 * A tracker reached with its own credential rather than a checkout's: Linear, Jira. The server
203 * stores one credential per kind and offers the connect flow from `standalone`; a project reads
204 * the tracker by binding one of the scopes `probeCredential` lists. The `cwd` on every target is
205 * then only the project's root, which such a tracker ignores.
206 */
207 export interface StandaloneIssueTrackerApi extends IssueTrackerApi {
208 readonly standalone: StandaloneIssueTrackerDescriptor;
209 /** Retains the workspace identity so canonical URLs can disambiguate repeated scope keys. */
210 readonly parseIssueUrl: (url: URL) => (IssueLink & { readonly workspace: string }) | null;
211 /**
212 * Who a credential signs in as and which scopes it reaches, asked of the tracker itself. Run on
213 * a credential before it is stored, and on the stored one to report connection status.
214 */
215 readonly probeCredential: (token: string) => Effect.Effect<
216 {
217 readonly account: string;
218 /** What the tracker's issue URLs name the credential's workspace by, where they name one. */
219 readonly workspace?: string | undefined;
220 readonly scopes: ReadonlyArray<IssueTrackerScope>;
221 },
222 IssueTrackerError
223 >;
224 }
225
226 export function isStandaloneIssueTracker(api: IssueTrackerApi): api is StandaloneIssueTrackerApi {
227 return "standalone" in api;
228 }