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

main
ts 649 lines 25.3 KB
Raw
1 import * as Schema from "effect/Schema";
2 import * as HttpServerRespondable from "effect/http/HttpServerRespondable";
3 import * as HttpServerResponse from "effect/http/HttpServerResponse";
4
5 import {
6 IsoDateTime,
7 NonNegativeInt,
8 PositiveInt,
9 ProjectId,
10 ThreadId,
11 TrimmedNonEmptyString,
12 } from "./baseSchemas.ts";
13 import {
14 PullRequestActor,
15 PullRequestLabel,
16 PullRequestReaction,
17 PullRequestReactionContent,
18 PullRequestState,
19 } from "./pullRequest.ts";
20
21 /**
22 * Which tracker an issue lives in. Git hosts reuse their `SourceControlProviderKind` spelling
23 * (`github`, `gitlab`); standalone trackers get their own (`linear`, `jira`). Branded apart from
24 * the source control kind because the two sets are not the same: Bitbucket is a git host with no
25 * tracker, and Linear is a tracker with no git host.
26 */
27 export const IssueTrackerKind = TrimmedNonEmptyString.check(
28 Schema.isMaxLength(64),
29 Schema.isPattern(/^[a-z][a-z0-9-]*$/),
30 ).pipe(Schema.brand("IssueTrackerKind"));
31 export type IssueTrackerKind = typeof IssueTrackerKind.Type;
32
33 export const IssueActor = PullRequestActor;
34 export type IssueActor = typeof IssueActor.Type;
35
36 export const IssueLabel = PullRequestLabel;
37 export type IssueLabel = typeof IssueLabel.Type;
38
39 /**
40 * Where an issue stands: the tracker's own name for the state ("In Review", "Closed as not
41 * planned"), which is what people read and what a move is asked for by, and the category every
42 * tracker has, which only filters and colours key off. Nothing moves an issue to "open" or
43 * "closed": it moves to one of the states its `IssueDetail.states` lists.
44 */
45 export const IssueStateCategory = Schema.Literals(["open", "closed"]);
46 export type IssueStateCategory = typeof IssueStateCategory.Type;
47
48 export const IssueState = Schema.Struct({
49 category: IssueStateCategory,
50 name: TrimmedNonEmptyString,
51 /** How a closed state ended, where the tracker says: `completed`, or its word for not done. */
52 closeReason: Schema.optional(TrimmedNonEmptyString),
53 });
54 export type IssueState = typeof IssueState.Type;
55
56 /** What a listing asks for: either category, or both. */
57 export const IssueListState = Schema.Literals(["all", "open", "closed"]);
58 export type IssueListState = typeof IssueListState.Type;
59
60 export const IssueInvolvement = Schema.Literals(["all", "assigned", "authored", "mentioned"]);
61 export type IssueInvolvement = typeof IssueInvolvement.Type;
62
63 /** Newest first by the named date. */
64 export const IssueListSort = Schema.Literals(["updated", "created"]);
65 export type IssueListSort = typeof IssueListSort.Type;
66
67 export const IssueReactionContent = PullRequestReactionContent;
68 export type IssueReactionContent = typeof IssueReactionContent.Type;
69
70 export const IssueReaction = PullRequestReaction;
71 export type IssueReaction = typeof IssueReaction.Type;
72
73 /**
74 * Addresses one issue: `scope` is the tracker's own container (`owner/repo`, a team key) and
75 * `key` the issue's native id in it. `host` is absent for the kind's public host. `projectId`
76 * names the project whose credentials serve the read, which need not own the issue.
77 */
78 export const IssueRef = Schema.Struct({
79 projectId: ProjectId,
80 tracker: IssueTrackerKind,
81 host: Schema.optional(TrimmedNonEmptyString),
82 scope: TrimmedNonEmptyString,
83 key: TrimmedNonEmptyString,
84 });
85 export type IssueRef = typeof IssueRef.Type;
86
87 /** A scope with no issue in it, for reads about the container itself: templates, candidates. */
88 export const IssueScopeRef = Schema.Struct({
89 projectId: ProjectId,
90 tracker: IssueTrackerKind,
91 host: Schema.optional(TrimmedNonEmptyString),
92 scope: TrimmedNonEmptyString,
93 });
94 export type IssueScopeRef = typeof IssueScopeRef.Type;
95
96 /** One row of a listing. Carries everything a list needs and nothing a detail needs. */
97 export const IssueSummary = Schema.Struct({
98 tracker: IssueTrackerKind,
99 host: TrimmedNonEmptyString,
100 scope: TrimmedNonEmptyString,
101 key: TrimmedNonEmptyString,
102 /** How the tracker writes the key for people: `#123` on a git host, `ENG-123` on Linear. */
103 displayKey: TrimmedNonEmptyString,
104 title: TrimmedNonEmptyString,
105 url: TrimmedNonEmptyString,
106 author: Schema.NullOr(IssueActor),
107 state: IssueState,
108 createdAt: IsoDateTime,
109 updatedAt: IsoDateTime,
110 closedAt: Schema.NullOr(IsoDateTime),
111 assignees: Schema.Array(IssueActor),
112 labels: Schema.Array(IssueLabel),
113 commentCount: NonNegativeInt,
114 });
115 export type IssueSummary = typeof IssueSummary.Type;
116
117 export const IssueListEntry = Schema.Struct({
118 ...IssueSummary.fields,
119 projectId: ProjectId,
120 projectTitle: TrimmedNonEmptyString,
121 });
122 export type IssueListEntry = typeof IssueListEntry.Type;
123
124 export const IssueComment = Schema.Struct({
125 id: TrimmedNonEmptyString,
126 author: Schema.NullOr(IssueActor),
127 body: Schema.String,
128 createdAt: IsoDateTime,
129 url: Schema.NullOr(Schema.String),
130 /** Absent from a tracker with no reactions, which differs from none on this comment. */
131 reactions: Schema.optional(Schema.Array(IssueReaction)),
132 });
133 export type IssueComment = typeof IssueComment.Type;
134
135 /**
136 * Something that happened to an issue that nobody wrote words for: it was closed, labelled,
137 * assigned, renamed. Kinds are the common vocabulary; a tracker drops what it cannot map rather
138 * than guessing.
139 */
140 export const IssueEventKind = Schema.Literals([
141 "closed",
142 "reopened",
143 "labeled",
144 "unlabeled",
145 "assigned",
146 "unassigned",
147 "renamed",
148 "referenced",
149 "state-changed",
150 ]);
151 export type IssueEventKind = typeof IssueEventKind.Type;
152
153 export const IssueEvent = Schema.Struct({
154 id: TrimmedNonEmptyString,
155 kind: IssueEventKind,
156 actor: Schema.NullOr(IssueActor),
157 createdAt: IsoDateTime,
158 /** What the event was about, where it has a subject: a label name, a login, a new title. */
159 detail: Schema.NullOr(TrimmedNonEmptyString),
160 });
161 export type IssueEvent = typeof IssueEvent.Type;
162
163 /** A change request the tracker says closes or mentions this issue. */
164 export const IssueLinkedPullRequest = Schema.Struct({
165 repository: TrimmedNonEmptyString,
166 number: PositiveInt,
167 title: TrimmedNonEmptyString,
168 url: TrimmedNonEmptyString,
169 state: PullRequestState,
170 isDraft: Schema.Boolean,
171 /** Merging it closes this issue, rather than only citing it. */
172 closesIssue: Schema.Boolean,
173 });
174 export type IssueLinkedPullRequest = typeof IssueLinkedPullRequest.Type;
175
176 /**
177 * What a tracker can do at all, so a surface never offers an action that would fail. The
178 * service refuses a call outside these before it reaches the driver.
179 */
180 export const IssueCapabilities = Schema.Struct({
181 create: Schema.Boolean,
182 /** Title and body can be rewritten after filing. */
183 edit: Schema.Boolean,
184 comment: Schema.Boolean,
185 labels: Schema.Boolean,
186 assignees: Schema.Boolean,
187 /** Reactions can be read and written on the issue and its comments. */
188 reactions: Schema.Boolean,
189 /** The scope offers starting points for a new issue. */
190 templates: Schema.Boolean,
191 /** The tracker reports linked change requests of its own accord. */
192 linkedPullRequests: Schema.Boolean,
193 /** State changes arrive as events beside the comments, not only as comments. */
194 events: Schema.Boolean,
195 /** The tracker narrows a listing by free text itself. */
196 search: Schema.Boolean,
197 });
198 export type IssueCapabilities = typeof IssueCapabilities.Type;
199
200 /**
201 * What the signed-in account may do with this issue, which `capabilities` says nothing about.
202 * A permission the tracker reports nothing about is granted, so a refusal comes from the
203 * tracker, which says why, rather than from a missing control.
204 */
205 export const IssueViewerPermissions = Schema.Struct({
206 setState: Schema.Boolean,
207 comment: Schema.Boolean,
208 edit: Schema.Boolean,
209 labels: Schema.Boolean,
210 assignees: Schema.Boolean,
211 });
212 export type IssueViewerPermissions = typeof IssueViewerPermissions.Type;
213
214 export const IssueDetail = Schema.Struct({
215 ...IssueSummary.fields,
216 projectId: ProjectId,
217 projectTitle: TrimmedNonEmptyString,
218 /** False for an issue outside every project's scope, which is read-only through this server. */
219 writable: Schema.Boolean,
220 capabilities: IssueCapabilities,
221 viewerPermissions: IssueViewerPermissions,
222 /**
223 * Every state this issue can be in, in the tracker's workflow order, its current one included.
224 * Empty means its state cannot be changed from here.
225 */
226 states: Schema.Array(IssueState),
227 /** The signed-in account, so a comment edit is offered only on the viewer's own remarks. */
228 viewer: Schema.NullOr(TrimmedNonEmptyString),
229 body: Schema.String,
230 reactions: Schema.optional(Schema.Array(IssueReaction)),
231 comments: Schema.Array(IssueComment),
232 /** Where older comments carry on; null once the conversation is whole. */
233 commentsCursor: Schema.NullOr(TrimmedNonEmptyString),
234 events: Schema.Array(IssueEvent),
235 linkedPullRequests: Schema.Array(IssueLinkedPullRequest),
236 });
237 export type IssueDetail = typeof IssueDetail.Type;
238
239 /** Older comments, one page past a cursor the detail or a previous page handed over. */
240 export const IssueCommentsPageInput = Schema.Struct({
241 ...IssueRef.fields,
242 cursor: TrimmedNonEmptyString.check(Schema.isMaxLength(4_096)),
243 });
244 export type IssueCommentsPageInput = typeof IssueCommentsPageInput.Type;
245
246 export const IssueCommentsPage = Schema.Struct({
247 comments: Schema.Array(IssueComment),
248 nextCursor: Schema.NullOr(TrimmedNonEmptyString),
249 });
250 export type IssueCommentsPage = typeof IssueCommentsPage.Type;
251
252 /** Where each scope a listing already reached carries on, keyed `"<host> <scope>"`. */
253 export const IssueListCursors = Schema.Record(
254 TrimmedNonEmptyString,
255 TrimmedNonEmptyString.check(Schema.isMaxLength(4_096)),
256 );
257 export type IssueListCursors = typeof IssueListCursors.Type;
258
259 export const ISSUE_LIST_MAX_EXCLUDED_PROJECTS = 1_000;
260
261 export const IssueListInput = Schema.Struct({
262 state: IssueListState,
263 involvement: Schema.optional(IssueInvolvement),
264 projectId: Schema.optional(ProjectId),
265 /** Projects left out of the listing, as the issues page hides them. */
266 excludeProjectIds: Schema.optional(
267 Schema.Array(ProjectId).check(Schema.isMaxLength(ISSUE_LIST_MAX_EXCLUDED_PROJECTS)),
268 ),
269 /** Narrows to one host, named as the host itself. Absent means every host the workspace has. */
270 host: Schema.optional(TrimmedNonEmptyString),
271 /** Rows per scope, which with a continuation is rows per slice. */
272 limit: Schema.optional(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 200 }))),
273 /** Carry on from an earlier answer: only the scopes named here are read, one slice each. */
274 cursors: Schema.optional(IssueListCursors),
275 /** An explicit refresh of the first page may also refresh tracker metadata. */
276 refresh: Schema.optional(Schema.Boolean),
277 /** Free text the trackers themselves are asked to match. */
278 query: Schema.optional(TrimmedNonEmptyString.check(Schema.isMaxLength(200))),
279 /** Label names an issue must carry, every one of them. */
280 labels: Schema.optional(
281 Schema.Array(TrimmedNonEmptyString.check(Schema.isMaxLength(200))).check(
282 Schema.isMaxLength(20),
283 ),
284 ),
285 /** An assignee's `login`, as an issue of that tracker names them. */
286 assignee: Schema.optional(TrimmedNonEmptyString.check(Schema.isMaxLength(320))),
287 /** Absent means `updated`. */
288 sort: Schema.optional(IssueListSort),
289 });
290 export type IssueListInput = typeof IssueListInput.Type;
291
292 /** One tracker account the workspace has projects on, and whether it can be read right now. */
293 export const IssueTrackerSummary = Schema.Struct({
294 tracker: IssueTrackerKind,
295 host: TrimmedNonEmptyString,
296 projectCount: PositiveInt,
297 capabilities: Schema.NullOr(IssueCapabilities),
298 /** False when the tracker's tool or credentials are missing, with `detail` saying which. */
299 configured: Schema.Boolean,
300 detail: Schema.NullOr(TrimmedNonEmptyString),
301 });
302 export type IssueTrackerSummary = typeof IssueTrackerSummary.Type;
303
304 export const IssueListProjectError = Schema.Struct({
305 projectId: ProjectId,
306 projectTitle: TrimmedNonEmptyString,
307 message: TrimmedNonEmptyString,
308 });
309 export type IssueListProjectError = typeof IssueListProjectError.Type;
310
311 export const IssueListResult = Schema.Struct({
312 /** The signed-in account per host that involvement compared against. Empty for `all`. */
313 viewers: Schema.Record(TrimmedNonEmptyString, TrimmedNonEmptyString),
314 trackers: Schema.Array(IssueTrackerSummary),
315 /** By update, newest first, across every scope this answer covers. */
316 entries: Schema.Array(IssueListEntry),
317 errors: Schema.Array(IssueListProjectError),
318 /** Where each scope carries on, sent straight back as `cursors`. Absent once a scope is done. */
319 nextCursors: IssueListCursors,
320 /**
321 * Every scope the listing covers, matched or not, with one project that reads it. A Linear team
322 * bound in settings is named nowhere else. Absent from servers that predate it.
323 */
324 scopes: Schema.optional(Schema.Array(IssueScopeRef)),
325 });
326 export type IssueListResult = typeof IssueListResult.Type;
327
328 const IssueTitle = TrimmedNonEmptyString.check(Schema.isMaxLength(1024));
329 // Not trimmed: a body is markdown, where leading spaces open a code block. The bound keeps
330 // oversized payloads off the wire; the service rejects a comment that is only whitespace.
331 const IssueBody = Schema.String.check(Schema.isMaxLength(65_536));
332 const CommentBody = Schema.String.check(Schema.isNonEmpty()).check(Schema.isMaxLength(65_536));
333
334 export const IssueCreateInput = Schema.Struct({
335 ...IssueScopeRef.fields,
336 title: IssueTitle,
337 /** May be empty: an issue with a title and nothing else is a legitimate one. */
338 body: IssueBody,
339 labels: Schema.Array(TrimmedNonEmptyString).check(Schema.isMaxLength(50)),
340 assignees: Schema.Array(TrimmedNonEmptyString).check(Schema.isMaxLength(25)),
341 });
342 export type IssueCreateInput = typeof IssueCreateInput.Type;
343
344 export const IssueCreateResult = Schema.Struct({
345 key: TrimmedNonEmptyString,
346 displayKey: TrimmedNonEmptyString,
347 url: TrimmedNonEmptyString,
348 });
349 export type IssueCreateResult = typeof IssueCreateResult.Type;
350
351 export const IssueCommentInput = Schema.Struct({
352 ...IssueRef.fields,
353 body: CommentBody,
354 });
355 export type IssueCommentInput = typeof IssueCommentInput.Type;
356
357 /**
358 * Rewrites the issue's own fields. Every field is optional and only the present ones are
359 * written; `labels` and `assignees` are the whole set, which is how every tracker writes them.
360 * The service refuses a request with nothing present.
361 */
362 export const IssueUpdateInput = Schema.Struct({
363 ...IssueRef.fields,
364 title: Schema.optional(IssueTitle),
365 body: Schema.optional(IssueBody),
366 labels: Schema.optional(Schema.Array(TrimmedNonEmptyString).check(Schema.isMaxLength(50))),
367 assignees: Schema.optional(Schema.Array(TrimmedNonEmptyString).check(Schema.isMaxLength(25))),
368 });
369 export type IssueUpdateInput = typeof IssueUpdateInput.Type;
370
371 /** Moves the issue to one of the states the tracker declared in `capabilities.states`. */
372 export const IssueSetStateInput = Schema.Struct({
373 ...IssueRef.fields,
374 /** The name of one of the issue's `states`. */
375 state: TrimmedNonEmptyString,
376 });
377 export type IssueSetStateInput = typeof IssueSetStateInput.Type;
378
379 export const IssueReactionInput = Schema.Struct({
380 ...IssueRef.fields,
381 /** Absent reacts to the issue itself; present names a comment id as the detail carried it. */
382 subjectId: Schema.optional(TrimmedNonEmptyString),
383 content: IssueReactionContent,
384 reacted: Schema.Boolean,
385 });
386 export type IssueReactionInput = typeof IssueReactionInput.Type;
387
388 /**
389 * One starting point a scope offers for a new issue. Only the body-shaped kind travels here:
390 * GitHub's typed issue forms are flattened to a body by the driver, so a composer on any
391 * tracker is one text box with a draft in it.
392 */
393 export const IssueTemplate = Schema.Struct({
394 key: TrimmedNonEmptyString,
395 name: TrimmedNonEmptyString,
396 about: Schema.String,
397 title: Schema.String,
398 body: Schema.String,
399 labels: Schema.Array(TrimmedNonEmptyString),
400 assignees: Schema.Array(TrimmedNonEmptyString),
401 });
402 export type IssueTemplate = typeof IssueTemplate.Type;
403
404 /** A starting point only the tracker's own site can render: Linear's form and rich templates. */
405 export const IssueExternalTemplate = Schema.Struct({
406 name: TrimmedNonEmptyString,
407 about: Schema.String,
408 /** Opens the exact template on the tracker, ready to fill in. */
409 url: TrimmedNonEmptyString,
410 });
411 export type IssueExternalTemplate = typeof IssueExternalTemplate.Type;
412
413 export const IssueTemplateList = Schema.Struct({
414 templates: Schema.Array(IssueTemplate),
415 /** Absent from a tracker whose every template is body-shaped. */
416 externalTemplates: Schema.optional(Schema.Array(IssueExternalTemplate)),
417 /** False where the scope's config forbids an issue filed from nothing. */
418 blankIssuesEnabled: Schema.Boolean,
419 });
420 export type IssueTemplateList = typeof IssueTemplateList.Type;
421
422 export const IssueLabelCandidate = Schema.Struct({
423 ...IssueLabel.fields,
424 description: Schema.NullOr(Schema.String),
425 });
426 export type IssueLabelCandidate = typeof IssueLabelCandidate.Type;
427
428 export const IssueAssigneeCandidate = Schema.Struct({
429 ...IssueActor.fields,
430 /** How the tracker addresses this person on a write, which is not always the login. */
431 id: TrimmedNonEmptyString,
432 });
433 export type IssueAssigneeCandidate = typeof IssueAssigneeCandidate.Type;
434
435 /** The labels and people a scope offers, read when a picker opens rather than with every issue. */
436 export const IssueCandidates = Schema.Struct({
437 labels: Schema.Array(IssueLabelCandidate),
438 assignees: Schema.Array(IssueAssigneeCandidate),
439 /** The tracker has more than were read, so somebody missing is not necessarily ineligible. */
440 truncated: Schema.Boolean,
441 });
442 export type IssueCandidates = typeof IssueCandidates.Type;
443
444 export const IssueUnavailableReason = Schema.Literals([
445 "tool-missing",
446 "unauthenticated",
447 "tracker-unsupported",
448 ]);
449 export type IssueUnavailableReason = typeof IssueUnavailableReason.Type;
450
451 /** The tracker cannot be read at all for this project, as opposed to one request failing. */
452 export class IssueUnavailableError extends Schema.TaggedError<IssueUnavailableError>()(
453 "IssueUnavailableError",
454 {
455 reason: IssueUnavailableReason,
456 tracker: Schema.optional(IssueTrackerKind),
457 cause: Schema.optional(Schema.Defect()),
458 },
459 { httpApiStatus: 503 },
460 ) {
461 [HttpServerRespondable.symbol]() {
462 return HttpServerResponse.schemaJson(IssueUnavailableError)(this, { status: 503 });
463 }
464
465 override get message(): string {
466 switch (this.reason) {
467 case "tool-missing":
468 return "The tool this tracker is read through is not installed or set up.";
469 case "unauthenticated":
470 return "This tracker has no working credentials.";
471 case "tracker-unsupported":
472 return "Issues cannot be browsed for this project yet.";
473 }
474 }
475 }
476
477 export class IssueOperationError extends Schema.TaggedError<IssueOperationError>()(
478 "IssueOperationError",
479 {
480 operation: Schema.String,
481 detail: TrimmedNonEmptyString,
482 reason: Schema.optional(Schema.Literals(["not-found", "read-only", "rate-limited"])),
483 retryAt: Schema.optional(Schema.Number),
484 cause: Schema.optional(Schema.Defect()),
485 },
486 { httpApiStatus: 502 },
487 ) {
488 [HttpServerRespondable.symbol]() {
489 return HttpServerResponse.schemaJson(IssueOperationError)(this, { status: 502 });
490 }
491
492 override get message(): string {
493 return `Issue operation ${this.operation} failed: ${this.detail}`;
494 }
495 }
496
497 export type IssueError = IssueUnavailableError | IssueOperationError;
498
499 /** Who created a thread ↔ issue link. */
500 export const ThreadIssueLinkSource = Schema.Literals(["manual", "agent"]);
501 export type ThreadIssueLinkSource = typeof ThreadIssueLinkSource.Type;
502
503 /**
504 * Identity of an issue as a thread link sees it: tracker-level, so the same issue linked through
505 * two projects compares equal. `host` is always written here, unlike `IssueRef`, because a link
506 * outlives the project whose binding supplied the default.
507 */
508 export const ThreadIssueKey = Schema.Struct({
509 tracker: IssueTrackerKind,
510 host: TrimmedNonEmptyString,
511 scope: TrimmedNonEmptyString,
512 key: TrimmedNonEmptyString,
513 });
514 export type ThreadIssueKey = typeof ThreadIssueKey.Type;
515
516 /**
517 * An issue linked to a thread. `projectId` is the project the issue is read through, which the
518 * detail panel needs; `url` is what the agent or user handed over.
519 */
520 export const ThreadIssueLink = Schema.Struct({
521 ...ThreadIssueKey.fields,
522 projectId: ProjectId,
523 url: TrimmedNonEmptyString,
524 source: ThreadIssueLinkSource,
525 linkedAt: IsoDateTime,
526 /** As the tracker named the issue when it was linked; opening it reads the live state. */
527 displayKey: TrimmedNonEmptyString,
528 title: TrimmedNonEmptyString,
529 });
530 export type ThreadIssueLink = typeof ThreadIssueLink.Type;
531
532 export function threadIssueKeyOf(key: ThreadIssueKey): string {
533 return `${key.tracker}\u0000${key.host.trim().toLowerCase()}\u0000${key.scope.trim().toLowerCase()}\u0000${key.key.trim()}`;
534 }
535
536 export function threadIssueKeysEqual(left: ThreadIssueKey, right: ThreadIssueKey): boolean {
537 return threadIssueKeyOf(left) === threadIssueKeyOf(right);
538 }
539
540 /** The threads an issue is linked to, most recently active first. */
541 export const IssueLinkedThreadsResult = Schema.Struct({
542 threads: Schema.Array(
543 Schema.Struct({
544 id: ThreadId,
545 projectId: ProjectId,
546 title: Schema.String,
547 archivedAt: Schema.NullOr(IsoDateTime),
548 settled: Schema.Boolean,
549 }),
550 ),
551 });
552 export type IssueLinkedThreadsResult = typeof IssueLinkedThreadsResult.Type;
553
554 /**
555 * A tracker that is not a git host: it is reached with its own credential rather than a
556 * checkout's, and a project opts into it by binding one of the tracker's scopes. Everything a
557 * client needs to draw the connect flow for any such tracker without knowing which one it is.
558 */
559 export const StandaloneIssueTrackerDescriptor = Schema.Struct({
560 tracker: IssueTrackerKind,
561 displayName: TrimmedNonEmptyString,
562 /** Where the tracker is served from; what `IssueRef.host` carries for its issues. */
563 host: TrimmedNonEmptyString,
564 /** What the tracker calls its container, in the singular: "team" on Linear, "project" on Jira. */
565 scopeNoun: TrimmedNonEmptyString,
566 credential: Schema.Struct({
567 /** What the tracker calls the credential: "Personal API key", "API token". */
568 label: TrimmedNonEmptyString,
569 /** Where to mint one, or null when the tracker has no stable page for it. */
570 helpUrl: Schema.NullOr(TrimmedNonEmptyString),
571 }),
572 });
573 export type StandaloneIssueTrackerDescriptor = typeof StandaloneIssueTrackerDescriptor.Type;
574
575 /** Which standalone tracker scope a project's issues come from, beside its git host's own. */
576 export const IssueTrackerProjectBinding = Schema.Struct({
577 tracker: IssueTrackerKind,
578 scope: TrimmedNonEmptyString,
579 });
580 export type IssueTrackerProjectBinding = typeof IssueTrackerProjectBinding.Type;
581
582 /** One container the connected account can read, offered when a project is bound. */
583 export const IssueTrackerScope = Schema.Struct({
584 key: TrimmedNonEmptyString,
585 name: TrimmedNonEmptyString,
586 });
587 export type IssueTrackerScope = typeof IssueTrackerScope.Type;
588
589 /**
590 * A standalone tracker as the settings page sees it: the descriptor, whether a credential is
591 * stored and still works, and the scopes it can reach. `scopes` is empty until connected.
592 */
593 export const IssueTrackerConnection = Schema.Struct({
594 ...StandaloneIssueTrackerDescriptor.fields,
595 /** A credential is stored. It may still be rejected, which `account` being null reports. */
596 connected: Schema.Boolean,
597 /** Who the credential signs in as, or null when there is none or it was refused. */
598 account: Schema.NullOr(TrimmedNonEmptyString),
599 /** Why a stored credential did not work, when it did not. */
600 detail: Schema.NullOr(TrimmedNonEmptyString),
601 /** The workspace the credential reaches, as its issue URLs name it; links elsewhere are foreign. */
602 workspace: Schema.optional(TrimmedNonEmptyString),
603 scopes: Schema.Array(IssueTrackerScope),
604 });
605 export type IssueTrackerConnection = typeof IssueTrackerConnection.Type;
606
607 export const IssueTrackerConnectionList = Schema.Struct({
608 trackers: Schema.Array(IssueTrackerConnection),
609 /** Which standalone tracker scope each bound project reads; a project absent here reads none. */
610 bindings: Schema.Record(ProjectId, IssueTrackerProjectBinding),
611 });
612 export type IssueTrackerConnectionList = typeof IssueTrackerConnectionList.Type;
613
614 /** A credential for one standalone tracker; `null` disconnects it and unbinds its projects. */
615 export const IssueTrackerConnectInput = Schema.Struct({
616 tracker: IssueTrackerKind,
617 token: Schema.NullOr(TrimmedNonEmptyString.check(Schema.isMaxLength(4_096))),
618 });
619 export type IssueTrackerConnectInput = typeof IssueTrackerConnectInput.Type;
620
621 export const IssueTrackerBindProjectInput = Schema.Struct({
622 projectId: ProjectId,
623 /** Null unbinds. */
624 binding: Schema.NullOr(IssueTrackerProjectBinding),
625 });
626 export type IssueTrackerBindProjectInput = typeof IssueTrackerBindProjectInput.Type;
627
628 /**
629 * A standalone tracker the connect flow could not reach or that refused the credential, or a
630 * binding that could not be saved.
631 */
632 export class IssueTrackerConnectionError extends Schema.TaggedError<IssueTrackerConnectionError>()(
633 "IssueTrackerConnectionError",
634 {
635 tracker: IssueTrackerKind,
636 reason: Schema.Literals(["unknown-tracker", "rejected", "failed"]),
637 detail: TrimmedNonEmptyString,
638 cause: Schema.optional(Schema.Defect()),
639 },
640 { httpApiStatus: 502 },
641 ) {
642 [HttpServerRespondable.symbol]() {
643 return HttpServerResponse.schemaJson(IssueTrackerConnectionError)(this, { status: 502 });
644 }
645
646 override get message(): string {
647 return `${this.tracker} connection failed: ${this.detail}`;
648 }
649 }