The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 04:45 UTC
| 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 | } |