@kana-ai/edgar-ext-github 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/README.md +141 -74
  2. package/dist/src/api/app.d.ts +30 -6
  3. package/dist/src/api/app.js +75 -10
  4. package/dist/src/api/client.d.ts +11 -4
  5. package/dist/src/api/client.js +71 -20
  6. package/dist/src/api/commits.d.ts +4 -0
  7. package/dist/src/api/commits.js +69 -0
  8. package/dist/src/api/failures.d.ts +4 -0
  9. package/dist/src/api/failures.js +14 -1
  10. package/dist/src/feed/alerts.d.ts +9 -3
  11. package/dist/src/feed/alerts.js +66 -6
  12. package/dist/src/feed/service.d.ts +10 -1
  13. package/dist/src/feed/service.js +79 -16
  14. package/dist/src/index.d.ts +97 -1
  15. package/dist/src/index.js +19 -5
  16. package/dist/src/schemas/config.d.ts +1 -0
  17. package/dist/src/schemas/config.js +73 -29
  18. package/dist/src/schemas/github.d.ts +121 -1
  19. package/dist/src/schemas/github.js +37 -2
  20. package/dist/src/schemas/tools.d.ts +159 -2
  21. package/dist/src/schemas/tools.js +129 -6
  22. package/dist/src/tools/alerts.js +1 -0
  23. package/dist/src/tools/branch.d.ts +12 -0
  24. package/dist/src/tools/branch.js +69 -1
  25. package/dist/src/tools/pull-request.d.ts +55 -7
  26. package/dist/src/tools/pull-request.js +131 -42
  27. package/dist/src/tools/revert.d.ts +27 -0
  28. package/dist/src/tools/revert.js +98 -0
  29. package/dist/src/tools/screenshot.d.ts +1 -1
  30. package/dist/src/tools/screenshot.js +25 -11
  31. package/dist/src/tracker/cards.d.ts +1 -1
  32. package/dist/src/tracker/cards.js +84 -8
  33. package/dist/src/tracker/comments.d.ts +14 -2
  34. package/dist/src/tracker/comments.js +100 -4
  35. package/dist/src/tracker/port.d.ts +1 -1
  36. package/dist/src/tracker/port.js +4 -6
  37. package/dist/src/tracker/read-link.d.ts +2 -0
  38. package/dist/src/tracker/read-link.js +23 -0
  39. package/dist/src/tracker/states.d.ts +14 -3
  40. package/dist/src/tracker/states.js +37 -6
  41. package/dist/src/tracker/tools.d.ts +27 -0
  42. package/dist/src/tracker/tools.js +63 -7
  43. package/dist/src/tracker/transitions.d.ts +14 -3
  44. package/dist/src/tracker/transitions.js +57 -10
  45. package/edgar-extension.json +124 -6
  46. package/package.json +3 -3
  47. package/schemas/attach_screenshot.in.json +19 -0
  48. package/schemas/config.json +49 -23
  49. package/schemas/create_card.in.json +4 -0
  50. package/schemas/delete_closed_branches.in.json +26 -0
  51. package/schemas/delete_closed_branches.out.json +22 -0
  52. package/schemas/find_revert_pull_request.in.json +21 -0
  53. package/schemas/find_revert_pull_request.out.json +14 -0
  54. package/schemas/list_pull_requests.out.json +5 -1
  55. package/schemas/mark_seen.in.json +11 -0
  56. package/schemas/mark_seen.out.json +10 -0
  57. package/schemas/merged_pull_request.in.json +17 -0
  58. package/schemas/merged_pull_request.out.json +18 -0
  59. package/schemas/open_pull_request.in.json +73 -1
  60. package/schemas/park.in.json +15 -0
  61. package/schemas/park.out.json +10 -0
  62. package/schemas/pull_request_state.out.json +10 -1
  63. package/schemas/release_follow_ups.in.json +5 -0
  64. package/schemas/retitle.in.json +16 -0
  65. package/schemas/retitle.out.json +13 -0
  66. package/schemas/revert_pull_request.in.json +11 -0
  67. package/schemas/revert_pull_request.out.json +14 -0
  68. package/schemas/set_priority.in.json +16 -0
  69. package/schemas/set_priority.out.json +10 -0
  70. package/schemas/update_pull_request.in.json +28 -1
  71. package/schemas/wait_for_review.out.json +10 -1
@@ -5,8 +5,10 @@ import { github } from "#api/client";
5
5
  import { forget, sweepAlerts } from "#feed/alerts";
6
6
  import { redBranchCards, redPullCard, reviewCard } from "#feed/cards";
7
7
  import { config } from "#schemas/config";
8
- import { checkRuns, openPull, viewer } from "#schemas/github";
9
- import { repoPath } from "#tools/pull-request";
8
+ import { cardComment, checkRuns, openPull, viewer } from "#schemas/github";
9
+ import { cardOf, repoPath } from "#tools/pull-request";
10
+ import { mentionOf } from "#tracker/comments";
11
+ import { trustOf } from "#tracker/states";
10
12
  const pause = async (signal, seconds) => await attemptAsync(async () => await sleep(seconds * 1000, undefined, { signal }), () => undefined);
11
13
  /** What a part of the service does when the project did not set its table: it waits for the stop. */
12
14
  async function idle(signal) {
@@ -23,19 +25,23 @@ async function loginOf(ctx, settings, watch) {
23
25
  const me = await github(ctx, "GET", "/user", viewer);
24
26
  return me.ok ? ok(me.value.login) : me;
25
27
  }
26
- /** The cards one repository asks for now: a review asked of EDGAR, each failed run on the newest commit of `base`, and red checks on EDGAR's own open pull requests. */
28
+ /** What one repository asks for now: the cards (a review asked of EDGAR, each failed run on the newest commit of `base`, and red checks on EDGAR's own open pull requests), and the card that each open pull request `login` opened names in its branch, by number. */
27
29
  async function cardsOf(ctx, home, base, login) {
28
30
  const repo = `/repos/${home.repo}`;
29
31
  const open = await github(ctx, "GET", `${repo}/pulls?state=open&per_page=100`, z.array(openPull));
30
32
  if (!open.ok)
31
33
  return open;
32
34
  const found = [];
35
+ const own = new Map();
33
36
  for (const pull of open.value) {
34
37
  const review = reviewCard(home, pull, login);
35
38
  if (review !== undefined)
36
39
  found.push(review);
37
40
  if (pull.user?.login !== login)
38
41
  continue;
42
+ const card = cardOf(pull.head.ref);
43
+ if (card !== null)
44
+ own.set(pull.number, card);
39
45
  const path = `${repo}/commits/${pull.head.sha}/check-runs?per_page=100`;
40
46
  const runs = await github(ctx, "GET", path, checkRuns);
41
47
  if (!runs.ok)
@@ -49,15 +55,58 @@ async function cardsOf(ctx, home, base, login) {
49
55
  if (!runs.ok)
50
56
  return runs;
51
57
  found.push(...redBranchCards(home, base, runs.value.check_runs));
52
- return ok(found);
58
+ return ok({ cards: found, own });
59
+ }
60
+ /** Puts each comment made after `since` on the open pull requests that `login` opened in `repo` that mentions `login`, by someone else on the team, on the card that the pull request's branch names, as that person's reply, so the card's run reads it: one request per repository. The card holds the reply as EDGAR's own comment, so a mention from outside the team stays on the pull request, and the log says so. A reply the engine refuses is logged. */
61
+ async function relayMentions(ctx, repo, login, own, since) {
62
+ const query = new URLSearchParams({ per_page: "100", since });
63
+ const path = `/repos/${repo}/issues/comments?${query.toString()}`;
64
+ const read = await github(ctx, "GET", path, z.array(cardComment.extend({ issue_url: z.string() })));
65
+ if (!read.ok)
66
+ return read;
67
+ const mention = mentionOf(login);
68
+ let relayed = 0;
69
+ const after = Date.parse(since);
70
+ for (const said of read.value) {
71
+ const number = Number(said.issue_url.split("/").pop());
72
+ const card = own.get(number);
73
+ const by = said.user?.login;
74
+ const text = said.body ?? "";
75
+ if (card === undefined || by === undefined || by === login)
76
+ continue;
77
+ if (Date.parse(said.created_at) <= after || !mention.test(text))
78
+ continue;
79
+ if (trustOf(said, new Set()) === "outside") {
80
+ ctx.log(`github watch: a mention on ${repo}#${String(number)} by ${by}, who is outside the team, stays on the pull request`);
81
+ continue;
82
+ }
83
+ const put = await ctx.cards.reply({ card }, text, by, "team");
84
+ if (put.ok && put.value.applied)
85
+ relayed += 1;
86
+ else
87
+ ctx.log(`github watch: a mention on ${repo}#${String(number)} did not reach ${card}`);
88
+ }
89
+ return ok(relayed);
53
90
  }
54
91
  /** One sweep over each watched repository; a fingerprint this process opened already is tracked, and EDGAR answers a repeat with the open card that holds it. After a sweep that read every repository on github.com, a fingerprint whose fault is gone is forgotten. A repository that fails is logged and the sweep goes on; a rate limit ends the sweep with its wait, since the limit is the token's; a refused token ends it. */
55
- export async function sweep(ctx, settings, watch, login, opened) {
92
+ export async function sweep(ctx, settings, watch, login, opened, heard) {
93
+ const began = new Date().toISOString();
56
94
  let read = 0;
57
95
  let filed = 0;
58
96
  let tracked = 0;
97
+ let relayed = 0;
59
98
  let whole = true;
60
99
  const open = new Set();
100
+ /** What a failed read of one repository does: a refused token ends the sweep with its failure, a rate limit ends it with its wait, and any other failure is logged and the sweep goes on. */
101
+ const failed = (path, error) => {
102
+ if (error.outcome === "permanent_failure" && error.kind === "unauthenticated")
103
+ return err(error);
104
+ ctx.log(`github watch: ${path}: ${error.message}`);
105
+ whole = false;
106
+ if (error.outcome === "temporary_failure" && error.kind === "rate_limited")
107
+ return ok({ read, filed, tracked, relayed, wait: error.retry_after ?? 0 });
108
+ return undefined;
109
+ };
61
110
  for (const [service, repo] of Object.entries(watch.services)) {
62
111
  const path = repoPath(repo);
63
112
  if (path === undefined) {
@@ -67,16 +116,13 @@ export async function sweep(ctx, settings, watch, login, opened) {
67
116
  const home = { service, repo: path, column: watch.card_column };
68
117
  const found = await cardsOf(ctx, home, settings.default_base, login);
69
118
  if (!found.ok) {
70
- if (found.error.outcome === "permanent_failure" && found.error.kind === "unauthenticated")
71
- return found;
72
- ctx.log(`github watch: ${path}: ${found.error.message}`);
73
- if (found.error.outcome === "temporary_failure" && found.error.kind === "rate_limited")
74
- return ok({ read, filed, tracked, wait: found.error.retry_after ?? 0 });
75
- whole = false;
119
+ const ended = failed(path, found.error);
120
+ if (ended !== undefined)
121
+ return ended;
76
122
  continue;
77
123
  }
78
124
  read += 1;
79
- for (const card of found.value) {
125
+ for (const card of found.value.cards) {
80
126
  const key = card.block.fingerprint ?? card.title;
81
127
  open.add(key);
82
128
  if (opened.has(key)) {
@@ -92,14 +138,29 @@ export async function sweep(ctx, settings, watch, login, opened) {
92
138
  opened.add(key);
93
139
  filed += 1;
94
140
  }
141
+ if (heard === undefined || found.value.own.size === 0)
142
+ continue;
143
+ const said = await relayMentions(ctx, path, login, found.value.own, heard.since);
144
+ if (said.ok)
145
+ relayed += said.value;
146
+ else {
147
+ const ended = failed(path, said.error);
148
+ if (ended !== undefined)
149
+ return ended;
150
+ }
95
151
  }
96
- if (whole)
152
+ if (whole) {
97
153
  forget(opened, open);
98
- return ok({ read, filed, tracked, wait: 0 });
154
+ if (heard !== undefined)
155
+ heard.since = began;
156
+ }
157
+ return ok({ read, filed, tracked, relayed, wait: 0 });
99
158
  }
100
159
  /**
101
160
  * The watch: with `[extensions.github.watch]` set, a sweep every `every_seconds` until the engine stops it; without it, it only waits. A refused token ends it with its permanent failure, which opens its breaker; a repository that fails waits for the next sweep, and after a rate limit the next sweep waits as long as GitHub asks.
102
161
  * shortcut: what was filed lives in memory, so a restart asks for the open cards again, and EDGAR answers each with the card it has; upgrade when a service can keep state.
162
+ * A comment on one of EDGAR's own pull requests that mentions EDGAR is put on the card that the pull request's branch names, as its author's reply, so the run on that card reads it; only comments made after the watch started count.
163
+ * shortcut: the time of the last read lives in memory, so a mention made while EDGAR was stopped is not read; upgrade when a service can keep state.
103
164
  * shortcut: red checks on EDGAR's own pull request open a card that names the pull request's card, since a service cannot comment on a card or start a sub-run; upgrade when the engine takes a comment from a service.
104
165
  */
105
166
  export async function watch(ctx) {
@@ -115,8 +176,9 @@ export async function watch(ctx) {
115
176
  if (!login.ok)
116
177
  return login.error;
117
178
  const opened = new Set();
179
+ const heard = { since: new Date().toISOString() };
118
180
  while (!signal.aborted) {
119
- const swept = await sweep(ctx, settings, table, login.value, opened);
181
+ const swept = await sweep(ctx, settings, table, login.value, opened, heard);
120
182
  if (!swept.ok)
121
183
  return swept.error;
122
184
  ctx.log(`github watch: ${JSON.stringify(swept.value)}`);
@@ -127,6 +189,7 @@ export async function watch(ctx) {
127
189
  /**
128
190
  * The Dependabot feed: with `[extensions.github.dependabot]` set, a sweep every `every_seconds` until the engine stops it; without it, it only waits. A refused token ends it with its permanent failure, which opens its breaker; a repository that fails waits for the next sweep, and after a rate limit the next sweep waits as long as GitHub asks.
129
191
  * shortcut: what was filed lives in memory, so a restart asks for the open cards again, and EDGAR answers each with the card it has; an alert that is still open after its card closed is filed again then. Upgrade when a service can keep state.
192
+ * The card of an alert that GitHub reports fixed or dismissed is closed with a comment, which needs `tracker:write`.
130
193
  */
131
194
  export async function feedAlerts(ctx) {
132
195
  const parsed = config.safeParse(ctx.config ?? {});
@@ -136,7 +199,7 @@ export async function feedAlerts(ctx) {
136
199
  const signal = ctx.signal;
137
200
  if (table === undefined)
138
201
  return await idle(signal);
139
- const memory = { opened: new Set(), said: new Map() };
202
+ const memory = { opened: new Map(), said: new Map() };
140
203
  while (!signal.aborted) {
141
204
  const swept = await sweepAlerts(ctx, table, memory);
142
205
  if (!swept.ok)
@@ -3,10 +3,17 @@ export declare const tools: {
3
3
  open_pull_request: import("@kana-ai/edgar-sdk").Tool<{
4
4
  repo: string;
5
5
  branch: string;
6
+ base?: string | undefined;
6
7
  title: string;
7
8
  body: string;
8
9
  review: string;
9
10
  labels?: string[] | undefined;
11
+ card?: {
12
+ [x: string]: unknown;
13
+ id: string;
14
+ title: string;
15
+ url?: string | undefined;
16
+ } | undefined;
10
17
  large_diff_lines?: number | undefined;
11
18
  path_notices?: {
12
19
  prefix: string;
@@ -16,9 +23,20 @@ export declare const tools: {
16
23
  results: {
17
24
  check: string;
18
25
  exit_code: number | null;
26
+ pre_existing?: boolean | undefined;
27
+ runs?: number | undefined;
19
28
  }[];
20
29
  } | undefined;
21
30
  not_verified?: string[] | undefined;
31
+ proof?: {
32
+ outcome: "failed" | "not_run" | "passed";
33
+ command: string;
34
+ exit_code?: number | null | undefined;
35
+ output_tail?: string | undefined;
36
+ reason?: string | undefined;
37
+ on_base?: "failed" | "passed" | "unknown" | undefined;
38
+ } | undefined;
39
+ proof_passes?: string | undefined;
22
40
  related?: string | string[] | undefined;
23
41
  }, {
24
42
  url: string;
@@ -28,6 +46,12 @@ export declare const tools: {
28
46
  url: string;
29
47
  title: string;
30
48
  body: string;
49
+ card?: {
50
+ [x: string]: unknown;
51
+ id: string;
52
+ title: string;
53
+ url?: string | undefined;
54
+ } | undefined;
31
55
  large_diff_lines?: number | undefined;
32
56
  path_notices?: {
33
57
  prefix: string;
@@ -37,6 +61,8 @@ export declare const tools: {
37
61
  results: {
38
62
  check: string;
39
63
  exit_code: number | null;
64
+ pre_existing?: boolean | undefined;
65
+ runs?: number | undefined;
40
66
  }[];
41
67
  } | undefined;
42
68
  not_verified?: string[] | undefined;
@@ -49,6 +75,11 @@ export declare const tools: {
49
75
  path: string;
50
76
  bytes: number;
51
77
  caption: string;
78
+ url?: string | undefined;
79
+ video?: {
80
+ path: string;
81
+ bytes: number;
82
+ } | undefined;
52
83
  } | {
53
84
  missing: string;
54
85
  };
@@ -114,6 +145,7 @@ export declare const tools: {
114
145
  state: "closed" | "open";
115
146
  }[];
116
147
  }[];
148
+ complete: boolean;
117
149
  }, "GITHUB_TOKEN">;
118
150
  pull_request_state: import("@kana-ai/edgar-sdk").Tool<{
119
151
  url: string;
@@ -127,6 +159,8 @@ export declare const tools: {
127
159
  commit: string;
128
160
  branch: string;
129
161
  head_repo: string | null;
162
+ mergeable: boolean | null;
163
+ base_commit?: string | undefined;
130
164
  }, "GITHUB_TOKEN">;
131
165
  wait_for_review: import("@kana-ai/edgar-sdk").Tool<{
132
166
  url: string;
@@ -140,6 +174,8 @@ export declare const tools: {
140
174
  commit: string;
141
175
  branch: string;
142
176
  head_repo: string | null;
177
+ mergeable: boolean | null;
178
+ base_commit?: string | undefined;
143
179
  }, "GITHUB_TOKEN">;
144
180
  wait_for_merge: import("@kana-ai/edgar-sdk").Tool<{
145
181
  url: string;
@@ -339,6 +375,29 @@ export declare const tools: {
339
375
  }[];
340
376
  complete: boolean;
341
377
  }, "GITHUB_TOKEN">;
378
+ merged_pull_request: import("@kana-ai/edgar-sdk").Tool<{
379
+ repo: string;
380
+ card: string;
381
+ }, {
382
+ url: string;
383
+ merged_at: string;
384
+ commit: string;
385
+ }, "GITHUB_TOKEN">;
386
+ revert_pull_request: import("@kana-ai/edgar-sdk").Tool<{
387
+ url: string;
388
+ }, {
389
+ url: string;
390
+ state: "closed" | "merged" | "open";
391
+ }, "GITHUB_TOKEN">;
392
+ find_revert_pull_request: import("@kana-ai/edgar-sdk").Tool<{
393
+ operation_id: string;
394
+ input: {
395
+ url: string;
396
+ };
397
+ }, {
398
+ url: string;
399
+ state: "closed" | "merged" | "open";
400
+ }, "GITHUB_TOKEN">;
342
401
  comment: import("@kana-ai/edgar-sdk").Tool<{
343
402
  card: string;
344
403
  text: string;
@@ -381,6 +440,7 @@ export declare const tools: {
381
440
  channel: string;
382
441
  thread: string;
383
442
  };
443
+ trust?: "outside" | "team";
384
444
  };
385
445
  };
386
446
  parent?: string;
@@ -388,12 +448,25 @@ export declare const tools: {
388
448
  id: string;
389
449
  url: string;
390
450
  }, "GITHUB_TOKEN">;
451
+ park: import("@kana-ai/edgar-sdk").Tool<{
452
+ card: string;
453
+ waits_for: string;
454
+ }, {
455
+ id: string;
456
+ }, "GITHUB_TOKEN">;
391
457
  release_follow_ups: import("@kana-ai/edgar-sdk").Tool<{
392
458
  card: string;
393
459
  pull_request: string;
460
+ column?: "ready" | "waiting_on_person";
394
461
  }, {
395
462
  released: string[];
396
463
  }, "GITHUB_TOKEN">;
464
+ set_priority: import("@kana-ai/edgar-sdk").Tool<{
465
+ card: string;
466
+ priority: "high" | "low" | "medium" | "urgent";
467
+ }, {
468
+ id: string;
469
+ }, "GITHUB_TOKEN">;
397
470
  count_sighting: import("@kana-ai/edgar-sdk").Tool<{
398
471
  card: string;
399
472
  seen_at?: string;
@@ -432,6 +505,11 @@ export declare const tools: {
432
505
  to: string;
433
506
  previous: string;
434
507
  }, "GITHUB_TOKEN">;
508
+ mark_seen: import("@kana-ai/edgar-sdk").Tool<{
509
+ card: string;
510
+ }, {
511
+ id: string;
512
+ }, "GITHUB_TOKEN">;
435
513
  update_description: import("@kana-ai/edgar-sdk").Tool<{
436
514
  card: string;
437
515
  description: string;
@@ -439,6 +517,13 @@ export declare const tools: {
439
517
  id: string;
440
518
  previous?: string | undefined;
441
519
  }, "GITHUB_TOKEN">;
520
+ retitle: import("@kana-ai/edgar-sdk").Tool<{
521
+ card: string;
522
+ text: string;
523
+ }, {
524
+ id: string;
525
+ title: string;
526
+ }, "GITHUB_TOKEN">;
442
527
  restore_description: import("@kana-ai/edgar-sdk").Tool<{
443
528
  stage_output: {
444
529
  id: string;
@@ -482,9 +567,20 @@ export declare const tools: {
482
567
  branch: string;
483
568
  commit: string;
484
569
  }, never>;
570
+ delete_closed_branches: import("@kana-ai/edgar-sdk").Tool<{
571
+ services: {
572
+ repo: string;
573
+ }[];
574
+ closed_within_hours: number;
575
+ }, {
576
+ deleted: {
577
+ pull_request: string;
578
+ branch: string;
579
+ }[];
580
+ }, "GITHUB_TOKEN">;
485
581
  };
486
582
  /**
487
- * The GitHub extension: branches, pull requests, Dependabot alerts, the `events` webhook, the service that watches each repository of `[extensions.github.watch]` and files the alerts of each repository of `[extensions.github.dependabot]`, and the GitHub Issues tracker of a project that writes `[extensions.github.columns]`.
583
+ * The GitHub extension: branches, pull requests, Dependabot alerts, the `events` webhook, the service that watches each repository of `[extensions.github.watch]` and files the alerts of each repository of `[extensions.github.dependabot]`, the GitHub Issues tracker of a project that writes `[extensions.github.columns]`, the reader of a linked issue, and the publisher of EDGAR's pushes as signed commits.
488
584
  */
489
585
  declare const _default: import("@kana-ai/edgar-sdk").Extension;
490
586
  export default _default;
package/dist/src/index.js CHANGED
@@ -1,27 +1,32 @@
1
- import { defineExtension, defineService } from "@kana-ai/edgar-sdk";
2
- import { HOST, LOG_HOSTS, TOKEN, apiAccess } from "#api/client";
1
+ import { defineCommitPublisher, defineExtension, defineGitCredential, defineService, } from "@kana-ai/edgar-sdk";
2
+ import { HOST, LOG_HOSTS, TOKEN, apiAccess, gitToken } from "#api/client";
3
+ import { publishCommits } from "#api/commits";
3
4
  import { serve } from "#feed/service";
4
5
  import { config } from "#schemas/config";
5
6
  import { alertTools } from "#tools/alerts";
6
- import { pushBranch } from "#tools/branch";
7
+ import { deleteClosedBranches, pushBranch } from "#tools/branch";
7
8
  import { checkTools } from "#tools/checks";
8
9
  import { discussionTools } from "#tools/discussion";
9
10
  import { pullRequestTools } from "#tools/pull-request";
10
11
  import { repositoryTools } from "#tools/repository";
12
+ import { revertTools } from "#tools/revert";
11
13
  import { tracker } from "#tracker/port";
14
+ import { readLink } from "#tracker/read-link";
12
15
  import { trackerTools } from "#tracker/tools";
13
16
  /** Every tool of the GitHub extension, by the name the manifest gives it. */
14
17
  export const tools = {
15
18
  push_branch: pushBranch,
19
+ delete_closed_branches: deleteClosedBranches,
16
20
  ...pullRequestTools,
17
21
  ...checkTools,
18
22
  ...discussionTools,
19
23
  ...repositoryTools,
24
+ ...revertTools,
20
25
  ...alertTools,
21
26
  ...trackerTools,
22
27
  };
23
28
  /**
24
- * The GitHub extension: branches, pull requests, Dependabot alerts, the `events` webhook, the service that watches each repository of `[extensions.github.watch]` and files the alerts of each repository of `[extensions.github.dependabot]`, and the GitHub Issues tracker of a project that writes `[extensions.github.columns]`.
29
+ * The GitHub extension: branches, pull requests, Dependabot alerts, the `events` webhook, the service that watches each repository of `[extensions.github.watch]` and files the alerts of each repository of `[extensions.github.dependabot]`, the GitHub Issues tracker of a project that writes `[extensions.github.columns]`, the reader of a linked issue, and the publisher of EDGAR's pushes as signed commits.
25
30
  */
26
31
  export default defineExtension({
27
32
  name: "github",
@@ -38,12 +43,20 @@ export default defineExtension({
38
43
  ...LOG_HOSTS.map((host) => `network:${host}`),
39
44
  "git:push",
40
45
  "sandbox:read",
46
+ "tracker:write",
41
47
  ],
42
48
  tracker,
43
49
  tools,
44
50
  workflows: ["workflows/resume.toml"],
45
51
  roles: ["agents/dismiss"],
46
- service: defineService({ ...apiAccess, run: serve }),
52
+ service: defineService({
53
+ secrets: apiAccess.secrets,
54
+ capabilities: [...apiAccess.capabilities, "tracker:write"],
55
+ run: serve,
56
+ }),
57
+ gitCredential: defineGitCredential({ ...apiAccess, token: gitToken }),
58
+ commitPublisher: defineCommitPublisher({ ...apiAccess, publish: publishCommits }),
59
+ readLink,
47
60
  executables: {
48
61
  requires: [
49
62
  {
@@ -57,6 +70,7 @@ export default defineExtension({
57
70
  signature: "hmac-sha256",
58
71
  secret: "GITHUB_WEBHOOK_SECRET",
59
72
  delivery_id_header: "X-GitHub-Delivery",
73
+ signature_header: "X-Hub-Signature-256",
60
74
  },
61
75
  },
62
76
  });
@@ -4,6 +4,7 @@ export declare const severities: readonly ["low", "medium", "high", "critical"];
4
4
  /** The extension's `[extensions.github]` table; `columns` and `tracker` come together, and make GitHub Issues a tracker of the project. */
5
5
  export declare const config: z.ZodObject<{
6
6
  default_base: z.ZodDefault<z.ZodString>;
7
+ pr_labels: z.ZodDefault<z.ZodArray<z.ZodString>>;
7
8
  app: z.ZodOptional<z.ZodObject<{
8
9
  id: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
9
10
  installation: z.ZodNumber;
@@ -7,81 +7,125 @@ const label = z.string().min(1);
7
7
  /** The extension's `[extensions.github]` table; `columns` and `tracker` come together, and make GitHub Issues a tracker of the project. */
8
8
  export const config = z
9
9
  .strictObject({
10
- default_base: z.string().min(1).default("main"),
10
+ default_base: z
11
+ .string()
12
+ .min(1)
13
+ .default("main")
14
+ .describe("The branch a new pull request merges into when its call names no base, and the branch whose checks the watch reads. Default main."),
15
+ pr_labels: z
16
+ .array(label)
17
+ .default([])
18
+ .describe("Labels each pull request EDGAR opens gets, beside the ones its workflow names. Default none."),
11
19
  app: z
12
20
  .strictObject({
13
- id: z.union([z.number().int().positive(), z.string().min(1)]),
14
- installation: z.number().int().positive(),
21
+ id: z
22
+ .union([z.number().int().positive(), z.string().min(1)])
23
+ .describe("The GitHub App's id, or its client id."),
24
+ installation: z
25
+ .number()
26
+ .int()
27
+ .positive()
28
+ .describe("The id of the App's installation that EDGAR signs in as."),
15
29
  })
16
30
  .optional()
17
- .describe("sign in as this GitHub App installation; GITHUB_TOKEN then holds the App's private key"),
31
+ .describe("Sign in as this GitHub App installation; GITHUB_TOKEN then holds the App's private key."),
18
32
  watch: z
19
33
  .strictObject({
20
34
  services: z
21
35
  .record(service, z.string().min(1))
22
- .describe("each service of the project to watch, with its repository as owner/name"),
36
+ .describe("Each service of the project to watch, with its repository as owner/name or a git URL; a repository not on github.com is not read."),
23
37
  login: z
24
38
  .string()
25
39
  .min(1)
26
40
  .optional()
27
- .describe("the GitHub login EDGAR works as; the default is the login of GITHUB_TOKEN, and an App needs it, such as edgar[bot]"),
28
- every_seconds: z.number().int().min(30).max(3600).default(60),
29
- card_column: z.string().min(1).default("intake"),
41
+ .describe("The GitHub login EDGAR works as; the default is the login of GITHUB_TOKEN, and an App needs it, such as edgar[bot]."),
42
+ every_seconds: z
43
+ .number()
44
+ .int()
45
+ .min(30)
46
+ .max(3600)
47
+ .default(60)
48
+ .describe("How often the watch reads the repositories, in seconds, from 30 to 3600. Default 60."),
49
+ card_column: z
50
+ .string()
51
+ .min(1)
52
+ .default("intake")
53
+ .describe("The engine state of a card the watch opens. Default intake."),
30
54
  })
31
55
  .optional()
32
- .describe("the service reads each repository every every_seconds and opens a card for a review asked of EDGAR, a red default branch, and red checks on EDGAR's own pull request"),
56
+ .describe("The service reads each repository every every_seconds and opens a card for a review asked of EDGAR, a red default branch, and red checks on EDGAR's own pull request."),
33
57
  dependabot: z
34
58
  .strictObject({
35
59
  services: z
36
60
  .record(repository, service)
37
- .describe("each repository to read, as owner/name, with the service of the project that its cards name"),
38
- every_seconds: z.number().int().min(60).max(86_400).default(300),
61
+ .describe("Each repository to read, as owner/name, with the service of the project that its cards name."),
62
+ every_seconds: z
63
+ .number()
64
+ .int()
65
+ .min(60)
66
+ .max(86_400)
67
+ .default(300)
68
+ .describe("How often the feed reads the open alerts, in seconds, from 60 to 86400. Default 300."),
39
69
  severity_min: z
40
70
  .enum(severities)
41
71
  .default("low")
42
- .describe("an alert under this severity opens no card"),
72
+ .describe("An alert under this severity opens no card: low, medium, high or critical. Default low."),
43
73
  max_per_run: z
44
74
  .number()
45
75
  .int()
46
76
  .min(1)
47
77
  .max(100)
48
78
  .default(10)
49
- .describe("the most cards one sweep opens, the worst first; the rest wait"),
50
- card_column: z.string().min(1).default("intake"),
79
+ .describe("The most cards one sweep opens, the worst first; the rest wait for the next sweep. From 1 to 100, default 10."),
80
+ card_column: z
81
+ .string()
82
+ .min(1)
83
+ .default("intake")
84
+ .describe("The engine state of a card the feed opens. Default intake."),
51
85
  })
52
86
  .optional()
53
- .describe("the service reads the open Dependabot alerts of each repository every every_seconds and opens one card for each advisory of a package"),
87
+ .describe("The service reads the open Dependabot alerts of each repository every every_seconds and opens one card for each advisory of a package."),
54
88
  columns: z
55
89
  .strictObject({
56
- intake: label,
57
- ready: label,
58
- working: label,
59
- in_review: label,
60
- waiting_on_person: label,
61
- in_testing: label,
90
+ intake: label.describe("The issue label of new cards, such as edgar:intake. An open issue in scope with no column label is in intake too."),
91
+ ready: label.describe("The issue label of cards ready to work on, such as edgar:ready."),
92
+ working: label.describe("The issue label of cards EDGAR works on, such as edgar:working."),
93
+ in_review: label.describe("The issue label of cards in review, such as edgar:in_review."),
94
+ waiting_on_person: label.describe("The issue label of cards that wait for a person, such as edgar:waiting_on_person."),
95
+ in_testing: label.describe("The issue label of cards in testing, such as edgar:in_testing."),
62
96
  })
63
97
  .optional()
64
- .describe("the issue label of each open engine state; with tracker, it makes GitHub Issues a tracker of the project; done closes an issue as completed, and cancelled closes it as not planned"),
98
+ .describe("The issue label of each open engine state; with tracker, it makes GitHub Issues a tracker of the project. Done closes an issue as completed, and cancelled closes it as not planned."),
65
99
  tracker: z
66
100
  .strictObject({
67
101
  repos: z
68
- .record(z.string().regex(/^[A-Z][A-Z0-9]{0,9}$/), z.strictObject({ repo: repository, service }))
102
+ .record(z.string().regex(/^[A-Z][A-Z0-9]{0,9}$/), z.strictObject({
103
+ repo: repository.describe("The repository whose issues are the cards of this key, as owner/name."),
104
+ service: service.describe("The service of the project that these cards name."),
105
+ }))
69
106
  .refine((repos) => Object.keys(repos).length > 0, "name at least one repository")
70
- .describe("each repository whose issues are cards, by the key of its card ids (API makes API-123), with its repository as owner/name and the service its cards name"),
71
- title_prefix: z.string().min(1).optional(),
72
- labels: z.array(label).optional(),
107
+ .describe("Each repository whose issues are cards, by the key of its card ids (API makes API-123), with its repository as owner/name and the service its cards name."),
108
+ title_prefix: z
109
+ .string()
110
+ .min(1)
111
+ .optional()
112
+ .describe("Only issues whose title starts with this text are cards, and EDGAR starts the title of each issue it files with it. Not set: any title."),
113
+ labels: z
114
+ .array(label)
115
+ .optional()
116
+ .describe("Only issues that carry every one of these labels are cards, and EDGAR adds them to each issue it files. Not set: any labels."),
73
117
  assignee: z
74
118
  .string()
75
119
  .min(1)
76
120
  .optional()
77
- .describe("the GitHub login of `assignee_only`; the default is the login of GITHUB_TOKEN, and an App needs it, such as edgar[bot]"),
121
+ .describe("The GitHub login of `assignee_only`; the default is the login of GITHUB_TOKEN, and an App needs it, such as edgar[bot]."),
78
122
  assignee_only: z
79
123
  .boolean()
80
124
  .default(false)
81
- .describe("true: an issue is in scope only while it is assigned to `assignee` or labelled edgar:waiting, and EDGAR assigns each issue it files to `assignee`"),
125
+ .describe("True: an issue is in scope only while it is assigned to `assignee` or labelled edgar:waiting, and EDGAR assigns each issue it files to `assignee`. Default false."),
82
126
  })
83
127
  .optional()
84
- .describe("GitHub Issues as a tracker of the project, with columns"),
128
+ .describe("GitHub Issues as a tracker of the project, with columns."),
85
129
  })
86
130
  .refine((table) => (table.columns === undefined) === (table.tracker === undefined), {
87
131
  message: "write [extensions.github.columns] and [extensions.github.tracker] together",