@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

main
ts 639 lines 22.5 KB
Raw
1 /**
2 * Forgejo's issue tracker over `ForgejoCli.api`, which resolves the server and login from the
3 * checkout's remote. Forgejo pages by number and announces a next page in a `Link` header the
4 * CLI surfaces on stderr, so every cursor here is the next page number.
5 */
6 import * as Effect from "effect/Effect";
7 import * as Result from "effect/Result";
8 import * as Schema from "effect/Schema";
9 import {
10 IssueTrackerKind,
11 type IssueCapabilities,
12 type IssueInvolvement,
13 type IssueLinkedPullRequest,
14 type IssueViewerPermissions,
15 } from "@t3tools/contracts";
16 import { decodeJsonResult } from "@t3tools/shared/schemaJson";
17 import {
18 IssueTrackerError,
19 type IssueTrackerApi,
20 } from "@t3tools/source-control-core/server/IssueTracker";
21
22 import * as ForgejoCli from "./ForgejoCli.ts";
23 import {
24 ForgejoIssue,
25 ForgejoIssueConfig,
26 ForgejoIssueRepository,
27 ForgejoIssueTemplate,
28 ForgejoTimelineEntry,
29 ISSUE_STATES,
30 forgejoIssue,
31 forgejoIssueComment,
32 forgejoIssueEvent,
33 forgejoIssueTemplate,
34 } from "./forgejoIssueJson.ts";
35 import {
36 FORGEJO_REACTIONS,
37 ForgejoComment,
38 ForgejoLabel,
39 ForgejoReaction,
40 ForgejoUser,
41 forgejoActor,
42 forgejoReactions,
43 } from "./forgejoPullRequestJson.ts";
44
45 const KIND = IssueTrackerKind.make("forgejo");
46
47 const CAPABILITIES: IssueCapabilities = {
48 create: true,
49 edit: true,
50 comment: true,
51 labels: true,
52 assignees: true,
53 reactions: true,
54 templates: true,
55 linkedPullRequests: true,
56 events: true,
57 search: true,
58 };
59
60 /** Forgejo's own ceiling on a page, which a self-hosted server may lower. */
61 const PAGE_SIZE = 50;
62 /** How many pages of a listing with no cursor of its own are read before giving up on the rest. */
63 const MAX_PAGES = 10;
64
65 const INVOLVEMENT_PARAM: Record<Exclude<IssueInvolvement, "all">, string> = {
66 assigned: "assigned_by",
67 authored: "created_by",
68 mentioned: "mentioned_by",
69 };
70
71 const repoPath = (scope: string) => `repos/${scope.split("/").map(encodeURIComponent).join("/")}`;
72 const issuePath = (scope: string, number: number) => `${repoPath(scope)}/issues/${number}`;
73
74 function parseNumber(key: string): number | null {
75 return /^[1-9]\d*$/.test(key) ? Number(key) : null;
76 }
77
78 function parsePage(cursor: string | undefined): number | null {
79 if (cursor === undefined) return 1;
80 return /^[1-9]\d{0,6}$/.test(cursor) ? Number(cursor) : null;
81 }
82
83 function reasonFor(error: ForgejoCli.ForgejoCliError): IssueTrackerError["reason"] {
84 switch (error.reason) {
85 case "missing-cli":
86 return "missing-tool";
87 case "authentication":
88 return "unauthenticated";
89 case "rate-limit":
90 return "rate-limited";
91 case "not-found":
92 return "not-found";
93 default:
94 return "failed";
95 }
96 }
97
98 /**
99 * What the signed-in account may do. Forgejo reports push access on the repository, and an
100 * issue's author may edit and close their own; an archived repository takes everything away, and
101 * a locked issue takes commenting away from anyone without push.
102 */
103 function permissions(
104 repository: typeof ForgejoIssueRepository.Type,
105 issue: typeof ForgejoIssue.Type,
106 viewer: string,
107 ): IssueViewerPermissions {
108 const active = !repository.archived;
109 const canWrite = repository.permissions?.push ?? false;
110 const canEdit = canWrite || issue.user?.login === viewer;
111 return {
112 setState: active && canEdit,
113 comment: active && (!issue.is_locked || canWrite),
114 edit: active && canEdit,
115 labels: active && canWrite,
116 assignees: active && canWrite,
117 };
118 }
119
120 export const make: Effect.Effect<IssueTrackerApi, never, ForgejoCli.ForgejoCli> = Effect.gen(
121 function* () {
122 const cli = yield* ForgejoCli.ForgejoCli;
123
124 const refused = (operation: string, detail: string, cause?: unknown) =>
125 new IssueTrackerError({
126 tracker: KIND,
127 operation,
128 reason: "failed",
129 detail,
130 ...(cause === undefined ? {} : { cause }),
131 });
132
133 const notFound = (operation: string) =>
134 new IssueTrackerError({
135 tracker: KIND,
136 operation,
137 reason: "not-found",
138 detail: "Forgejo could not find the requested issue.",
139 });
140
141 type Target = { readonly cwd: string; readonly host: string; readonly scope: string };
142
143 const request = (
144 target: Target,
145 operation: string,
146 input: Omit<ForgejoCli.ForgejoApiInput, "cwd" | "repository" | "host">,
147 ) =>
148 cli.api({ cwd: target.cwd, repository: target.scope, host: target.host, ...input }).pipe(
149 Effect.mapError(
150 (error) =>
151 new IssueTrackerError({
152 tracker: KIND,
153 operation,
154 reason: reasonFor(error),
155 detail: error.detail,
156 cause: error,
157 }),
158 ),
159 );
160
161 const read = <A>(
162 target: Target,
163 operation: string,
164 input: Omit<ForgejoCli.ForgejoApiInput, "cwd" | "repository" | "host">,
165 schema: Schema.Codec<A, unknown, never, never>,
166 ): Effect.Effect<A, IssueTrackerError> =>
167 request(target, operation, input).pipe(
168 Effect.flatMap((result) => {
169 if (result.stdoutTruncated) {
170 return Effect.fail(refused(operation, "Forgejo response exceeded the output limit."));
171 }
172 const decoded = decodeJsonResult(schema)(result.stdout);
173 return Result.isSuccess(decoded)
174 ? Effect.succeed(decoded.success)
175 : Effect.fail(
176 refused(operation, "Forgejo returned an invalid response.", decoded.failure),
177 );
178 }),
179 );
180
181 const readArray = <A>(
182 target: Target,
183 operation: string,
184 path: string,
185 schema: Schema.Codec<A, unknown, never, never>,
186 ) =>
187 read(target, operation, { path }, Schema.NullOr(Schema.Array(schema))).pipe(
188 Effect.map((rows) => rows ?? []),
189 );
190
191 /** One page of a listing, and whether Forgejo's `Link` header announced another. */
192 const readPage = <A>(
193 target: Target,
194 operation: string,
195 path: string,
196 page: number,
197 schema: Schema.Codec<A, unknown, never, never>,
198 ): Effect.Effect<
199 { readonly rows: ReadonlyArray<A>; readonly nextCursor: string | null },
200 IssueTrackerError
201 > =>
202 request(target, operation, {
203 path: `${path}${path.includes("?") ? "&" : "?"}limit=${PAGE_SIZE}&page=${page}`,
204 }).pipe(
205 Effect.flatMap((result) => {
206 const decoded = decodeJsonResult(Schema.NullOr(Schema.Array(schema)))(result.stdout);
207 if (Result.isFailure(decoded)) {
208 return Effect.fail(
209 refused(operation, "Forgejo returned an invalid response.", decoded.failure),
210 );
211 }
212 const rows = decoded.success ?? [];
213 const links = /^link:\s*(.*)$/im.exec(result.stderr)?.[1];
214 const more = rows.length > 0 && (links === undefined || /rel="?next"?/i.test(links));
215 return Effect.succeed({ rows, nextCursor: more ? String(page + 1) : null });
216 }),
217 );
218
219 const write = (
220 target: Target,
221 operation: string,
222 input: Omit<ForgejoCli.ForgejoApiInput, "cwd" | "repository" | "host">,
223 ) => request(target, operation, input).pipe(Effect.asVoid);
224
225 const getViewer = (target: Target, operation: string) =>
226 read(target, operation, { path: "user" }, ForgejoUser).pipe(Effect.map((user) => user.login));
227
228 const getRepository = (target: Target, operation: string) =>
229 read(target, operation, { path: repoPath(target.scope) }, ForgejoIssueRepository);
230
231 /** The issue as the API addresses it, or a not-found for a key that names no number. */
232 const issueTarget = (
233 operation: string,
234 input: Target & { readonly key: string },
235 ): Effect.Effect<{ readonly number: number; readonly path: string }, IssueTrackerError> => {
236 const number = parseNumber(input.key);
237 return number === null
238 ? Effect.fail(notFound(operation))
239 : Effect.succeed({ number, path: issuePath(input.scope, number) });
240 };
241
242 const getIssue = (target: Target, operation: string, path: string) =>
243 read(target, operation, { path }, ForgejoIssue).pipe(
244 // The issues API answers for a pull request's number too; that is not an issue here.
245 Effect.filterOrFail(
246 (issue) => !issue.pull_request,
247 () => notFound(operation),
248 ),
249 );
250
251 /** Every page of a listing the caller gets no cursor for, up to `MAX_PAGES`. */
252 const readEveryPage = Effect.fn("ForgejoIssueTracker.readEveryPage")(function* <A>(
253 target: Target,
254 operation: string,
255 path: string,
256 schema: Schema.Codec<A, unknown, never, never>,
257 ) {
258 const rows: A[] = [];
259 for (let page = 1; page <= MAX_PAGES; page++) {
260 const next = yield* readPage(target, operation, path, page, schema);
261 rows.push(...next.rows);
262 if (next.nextCursor === null) break;
263 }
264 return rows;
265 });
266
267 /**
268 * Labels are written by id, so names are resolved against the repository's own, page by page
269 * until each is found. A name the repository lacks refuses the write rather than dropping it.
270 */
271 const labelIds = Effect.fn("ForgejoIssueTracker.labelIds")(function* (
272 target: Target,
273 operation: string,
274 names: ReadonlyArray<string>,
275 ) {
276 const ids = new Map<string, number>();
277 for (let page = 1; ids.size < new Set(names).size && page <= MAX_PAGES; page++) {
278 const next = yield* readPage(
279 target,
280 operation,
281 `${repoPath(target.scope)}/labels`,
282 page,
283 ForgejoLabel,
284 );
285 for (const label of next.rows) {
286 if (names.includes(label.name)) ids.set(label.name, label.id);
287 }
288 if (next.nextCursor === null) break;
289 }
290 if (names.some((name) => !ids.has(name))) {
291 return yield* refused(operation, "Forgejo found no label by one of the names given.");
292 }
293 return [...ids.values()];
294 });
295
296 /** `/comments` takes no page and answers with every comment, so the pages are cut here. */
297 const commentsPage = (
298 target: Target,
299 operation: string,
300 path: string,
301 page: number,
302 viewer: string,
303 ) =>
304 readArray(target, operation, `${path}/comments`, ForgejoComment).pipe(
305 Effect.flatMap((rows) => {
306 const end = page * PAGE_SIZE;
307 return Effect.forEach(
308 rows.slice(end - PAGE_SIZE, end),
309 (comment) =>
310 readArray(
311 target,
312 operation,
313 `${repoPath(target.scope)}/issues/comments/${comment.id}/reactions`,
314 ForgejoReaction,
315 ).pipe(
316 Effect.map((reactions) => ({
317 ...forgejoIssueComment(comment),
318 reactions: forgejoReactions(reactions, viewer),
319 })),
320 ),
321 { concurrency: 4 },
322 ).pipe(
323 Effect.map((comments) => ({
324 comments,
325 nextCursor: rows.length > end ? String(page + 1) : null,
326 })),
327 );
328 }),
329 );
330
331 /** Pull requests the timeline shows citing this issue, each read once for its state. */
332 const linkedPullRequests = (
333 target: Target,
334 timeline: ReadonlyArray<typeof ForgejoTimelineEntry.Type>,
335 ): Effect.Effect<ReadonlyArray<IssueLinkedPullRequest>, IssueTrackerError> => {
336 // A reference may come from another repository, which is where that pull request is read.
337 const cited = new Map<string, { readonly repository: string; readonly number: number }>();
338 for (const entry of timeline) {
339 if (entry.type !== "pull_ref" || !entry.ref_issue?.pull_request) continue;
340 const named = entry.ref_issue.repository?.full_name;
341 // The scope may carry the server's mount path in front of the same repository.
342 const repository =
343 named === undefined || target.scope.endsWith(`/${named}`) ? target.scope : named;
344 cited.set(`${repository}#${entry.ref_issue.number}`, {
345 repository,
346 number: entry.ref_issue.number,
347 });
348 }
349 return Effect.forEach(
350 cited.values(),
351 ({ repository, number }) =>
352 read(
353 target,
354 "getIssue",
355 { path: `${repoPath(repository)}/pulls/${number}` },
356 Schema.Struct({
357 number: Schema.Int,
358 title: Schema.String,
359 html_url: Schema.String,
360 state: Schema.String,
361 merged: Schema.Boolean,
362 draft: Schema.optional(Schema.Boolean),
363 }),
364 ).pipe(
365 Effect.map((pull) => [
366 {
367 repository,
368 number: pull.number,
369 title: pull.title,
370 url: pull.html_url,
371 state: pull.merged
372 ? ("merged" as const)
373 : pull.state === "closed"
374 ? ("closed" as const)
375 : ("open" as const),
376 isDraft: pull.draft ?? false,
377 // Forgejo's timeline cites the pull request without saying whether it closes the issue.
378 closesIssue: false,
379 },
380 ]),
381 Effect.catchIf(
382 (error) => error.reason === "not-found",
383 () => Effect.succeed([]),
384 ),
385 ),
386 { concurrency: 2 },
387 ).pipe(Effect.map((links) => links.flat()));
388 };
389
390 return {
391 kind: KIND,
392 capabilities: CAPABILITIES,
393
394 getViewer: (input) => getViewer({ ...input, scope: "" }, "getViewer"),
395
396 listIssues: Effect.fn("ForgejoIssueTracker.listIssues")(function* (input) {
397 const page = parsePage(input.cursor);
398 if (page === null) {
399 return yield* refused("listIssues", "The cursor was not one Forgejo handed out.");
400 }
401 const params = new URLSearchParams({
402 type: "issues",
403 state: input.state,
404 sort: input.sort === "created" ? "latest" : "recentupdate",
405 });
406 const labels = input.labels ?? [];
407 if (labels.length > 0) params.set("labels", labels.join(","));
408 const text = input.query?.trim() ?? "";
409 if (text.length > 0) params.set("q", text);
410 if (input.involvement !== "all") {
411 params.set(INVOLVEMENT_PARAM[input.involvement], input.viewer);
412 }
413 if (input.assignee !== undefined) params.set("assigned_by", input.assignee);
414 // `assigned_by` names one person, so "assigned to me" is kept here beside a named assignee.
415 const alsoAssignedTo =
416 input.involvement === "assigned" && input.assignee !== undefined
417 ? input.viewer.toLowerCase()
418 : null;
419 const { rows, nextCursor } = yield* readPage(
420 input,
421 "listIssues",
422 `${repoPath(input.scope)}/issues?${params}`,
423 page,
424 ForgejoIssue,
425 );
426 return {
427 items: rows
428 .flatMap((issue) => (issue.pull_request ? [] : [forgejoIssue(issue)]))
429 // Forgejo documents `labels` as matching any of them; every one is what was asked.
430 .filter(
431 (issue) =>
432 labels.every((label) => issue.labels.some((carried) => carried.name === label)) &&
433 (alsoAssignedTo === null ||
434 issue.assignees.some((actor) => actor.login.toLowerCase() === alsoAssignedTo)),
435 ),
436 nextCursor,
437 };
438 }),
439
440 getIssue: (input) =>
441 issueTarget("getIssue", input).pipe(
442 Effect.flatMap(({ path }) =>
443 Effect.all(
444 [
445 getIssue(input, "getIssue", path),
446 getRepository(input, "getIssue"),
447 getViewer(input, "getIssue"),
448 readEveryPage(input, "getIssue", `${path}/timeline`, ForgejoTimelineEntry),
449 readArray(input, "getIssue", `${path}/reactions`, ForgejoReaction),
450 ],
451 { concurrency: 3 },
452 ),
453 ),
454 Effect.flatMap(([issue, repository, viewer, timeline, reactions]) =>
455 Effect.all([
456 commentsPage(input, "getIssue", issuePath(input.scope, issue.number), 1, viewer),
457 linkedPullRequests(input, timeline),
458 ]).pipe(
459 Effect.map(([conversation, links]) => ({
460 ...forgejoIssue(issue),
461 body: issue.body ?? "",
462 viewer,
463 viewerPermissions: permissions(repository, issue, viewer),
464 states: ISSUE_STATES,
465 reactions: forgejoReactions(reactions, viewer),
466 comments: conversation.comments,
467 commentsCursor: conversation.nextCursor,
468 events: timeline.flatMap((entry) => forgejoIssueEvent(entry) ?? []),
469 linkedPullRequests: links,
470 })),
471 ),
472 ),
473 ),
474
475 getComments: (input) => {
476 const page = parsePage(input.cursor);
477 return page === null
478 ? Effect.fail(refused("getComments", "The cursor was not one Forgejo handed out."))
479 : Effect.all([issueTarget("getComments", input), getViewer(input, "getComments")]).pipe(
480 Effect.flatMap(([{ path }, viewer]) =>
481 commentsPage(input, "getComments", path, page, viewer),
482 ),
483 );
484 },
485
486 create: (input) =>
487 labelIds(input, "create", input.labels).pipe(
488 Effect.flatMap((labels) =>
489 read(
490 input,
491 "create",
492 {
493 path: `${repoPath(input.scope)}/issues`,
494 method: "POST",
495 body: {
496 title: input.title,
497 body: input.body,
498 labels,
499 assignees: input.assignees,
500 },
501 },
502 ForgejoIssue,
503 ),
504 ),
505 Effect.map((issue) => ({
506 key: String(issue.number),
507 displayKey: `#${issue.number}`,
508 url: issue.html_url,
509 })),
510 ),
511
512 comment: (input) =>
513 issueTarget("comment", input).pipe(
514 Effect.flatMap(({ path }) =>
515 write(input, "comment", {
516 path: `${path}/comments`,
517 method: "POST",
518 body: { body: input.body },
519 }),
520 ),
521 ),
522
523 update: (input) =>
524 Effect.all([
525 issueTarget("update", input),
526 // Resolved before anything is written, so an unknown label changes nothing.
527 input.labels === undefined ? Effect.void : labelIds(input, "update", input.labels),
528 ]).pipe(
529 Effect.flatMap(([{ path }, labels]) =>
530 Effect.all([
531 input.title === undefined && input.body === undefined && input.assignees === undefined
532 ? Effect.void
533 : write(input, "update", {
534 path,
535 method: "PATCH",
536 body: {
537 ...(input.title === undefined ? {} : { title: input.title }),
538 ...(input.body === undefined ? {} : { body: input.body }),
539 ...(input.assignees === undefined ? {} : { assignees: input.assignees }),
540 },
541 }),
542 labels === undefined
543 ? Effect.void
544 : write(input, "update", {
545 path: `${path}/labels`,
546 method: "PUT",
547 body: { labels },
548 }),
549 ]),
550 ),
551 Effect.asVoid,
552 ),
553
554 setState: (input) => {
555 const wanted = ISSUE_STATES.find((state) => state.name === input.state);
556 if (wanted === undefined) {
557 return Effect.fail(refused("setState", `A Forgejo issue has no "${input.state}" state.`));
558 }
559 return issueTarget("setState", input).pipe(
560 Effect.flatMap(({ path }) =>
561 write(input, "setState", { path, method: "PATCH", body: { state: wanted.category } }),
562 ),
563 );
564 },
565
566 setReaction: (input) =>
567 issueTarget("setReaction", input).pipe(
568 Effect.flatMap(({ path }) => {
569 if (input.subjectId !== undefined && !/^[1-9]\d*$/.test(input.subjectId)) {
570 return Effect.fail(
571 refused("setReaction", "The comment id names no Forgejo comment."),
572 );
573 }
574 return write(input, "setReaction", {
575 path:
576 input.subjectId === undefined
577 ? `${path}/reactions`
578 : `${repoPath(input.scope)}/issues/comments/${input.subjectId}/reactions`,
579 method: input.reacted ? "POST" : "DELETE",
580 body: { content: FORGEJO_REACTIONS[input.content] },
581 });
582 }),
583 ),
584
585 listTemplates: (input) =>
586 Effect.all(
587 [
588 readArray(
589 input,
590 "listTemplates",
591 `${repoPath(input.scope)}/issue_templates`,
592 ForgejoIssueTemplate,
593 ),
594 // A repository with no config leaves the blank issue where Forgejo puts it.
595 read(
596 input,
597 "listTemplates",
598 { path: `${repoPath(input.scope)}/issue_config` },
599 ForgejoIssueConfig,
600 ).pipe(
601 Effect.map((config) => config.blank_issues_enabled !== false),
602 Effect.catchIf(
603 (error) => error.reason === "not-found" || error.reason === "failed",
604 () => Effect.succeed(true),
605 ),
606 ),
607 ],
608 { concurrency: 2 },
609 ).pipe(
610 Effect.map(([templates, blankIssuesEnabled]) => ({
611 templates: templates.flatMap((template) => forgejoIssueTemplate(template) ?? []),
612 blankIssuesEnabled,
613 })),
614 ),
615
616 listCandidates: (input) =>
617 Effect.all(
618 [
619 readPage(input, "listCandidates", `${repoPath(input.scope)}/labels`, 1, ForgejoLabel),
620 readPage(input, "listCandidates", `${repoPath(input.scope)}/assignees`, 1, ForgejoUser),
621 ],
622 { concurrency: 2 },
623 ).pipe(
624 Effect.map(([labels, assignees]) => ({
625 labels: labels.rows.map((label) => ({
626 name: label.name,
627 color: label.color ?? null,
628 description: label.description ?? null,
629 })),
630 assignees: assignees.rows.flatMap((user) => {
631 const actor = forgejoActor(user);
632 return actor === null ? [] : [{ ...actor, id: actor.login }];
633 }),
634 truncated: labels.nextCursor !== null || assignees.nextCursor !== null,
635 })),
636 ),
637 };
638 },
639 );