@kana-ai/edgar-ext-github 0.0.0-stage → 0.1.1

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 (136) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +469 -2
  3. package/agents/dismiss/agent.toml +4 -0
  4. package/agents/dismiss/instructions.md +25 -0
  5. package/dist/src/api/app.d.ts +16 -0
  6. package/dist/src/api/app.js +32 -0
  7. package/dist/src/api/client.d.ts +26 -0
  8. package/dist/src/api/client.js +103 -0
  9. package/dist/src/api/failures.d.ts +8 -0
  10. package/dist/src/api/failures.js +31 -0
  11. package/dist/src/feed/alerts.d.ts +26 -0
  12. package/dist/src/feed/alerts.js +117 -0
  13. package/dist/src/feed/cards.d.ts +32 -0
  14. package/dist/src/feed/cards.js +164 -0
  15. package/dist/src/feed/service.d.ts +28 -0
  16. package/dist/src/feed/service.js +163 -0
  17. package/dist/src/index.d.ts +490 -0
  18. package/dist/src/index.js +62 -0
  19. package/dist/src/schemas/config.d.ts +57 -0
  20. package/dist/src/schemas/config.js +89 -0
  21. package/dist/src/schemas/github.d.ts +417 -0
  22. package/dist/src/schemas/github.js +216 -0
  23. package/dist/src/schemas/tools.d.ts +620 -0
  24. package/dist/src/schemas/tools.js +501 -0
  25. package/dist/src/tools/alerts.d.ts +45 -0
  26. package/dist/src/tools/alerts.js +100 -0
  27. package/dist/src/tools/branch.d.ts +9 -0
  28. package/dist/src/tools/branch.js +48 -0
  29. package/dist/src/tools/checks.d.ts +118 -0
  30. package/dist/src/tools/checks.js +223 -0
  31. package/dist/src/tools/discussion.d.ts +41 -0
  32. package/dist/src/tools/discussion.js +66 -0
  33. package/dist/src/tools/pull-request.d.ts +195 -0
  34. package/dist/src/tools/pull-request.js +537 -0
  35. package/dist/src/tools/repository.d.ts +53 -0
  36. package/dist/src/tools/repository.js +134 -0
  37. package/dist/src/tools/screenshot.d.ts +21 -0
  38. package/dist/src/tools/screenshot.js +99 -0
  39. package/dist/src/tracker/assignee.d.ts +15 -0
  40. package/dist/src/tracker/assignee.js +65 -0
  41. package/dist/src/tracker/cards.d.ts +41 -0
  42. package/dist/src/tracker/cards.js +361 -0
  43. package/dist/src/tracker/comments.d.ts +9 -0
  44. package/dist/src/tracker/comments.js +68 -0
  45. package/dist/src/tracker/description.d.ts +19 -0
  46. package/dist/src/tracker/description.js +55 -0
  47. package/dist/src/tracker/hand-back.d.ts +8 -0
  48. package/dist/src/tracker/hand-back.js +60 -0
  49. package/dist/src/tracker/port.d.ts +2 -0
  50. package/dist/src/tracker/port.js +42 -0
  51. package/dist/src/tracker/states.d.ts +77 -0
  52. package/dist/src/tracker/states.js +189 -0
  53. package/dist/src/tracker/tools.d.ts +143 -0
  54. package/dist/src/tracker/tools.js +131 -0
  55. package/dist/src/tracker/transitions.d.ts +12 -0
  56. package/dist/src/tracker/transitions.js +101 -0
  57. package/edgar-extension.json +507 -0
  58. package/package.json +43 -3
  59. package/schemas/assign.in.json +15 -0
  60. package/schemas/assign.out.json +14 -0
  61. package/schemas/attach_screenshot.in.json +44 -0
  62. package/schemas/attach_screenshot.out.json +31 -0
  63. package/schemas/batch_cards.in.json +27 -0
  64. package/schemas/batch_cards.out.json +37 -0
  65. package/schemas/branch_protection.in.json +15 -0
  66. package/schemas/branch_protection.out.json +67 -0
  67. package/schemas/ci_run.in.json +12 -0
  68. package/schemas/ci_run.out.json +109 -0
  69. package/schemas/close.in.json +14 -0
  70. package/schemas/close.out.json +10 -0
  71. package/schemas/close_pull_request.in.json +21 -0
  72. package/schemas/close_pull_request.out.json +14 -0
  73. package/schemas/comment.in.json +19 -0
  74. package/schemas/comment.out.json +10 -0
  75. package/schemas/config.json +202 -0
  76. package/schemas/count_sighting.in.json +17 -0
  77. package/schemas/count_sighting.out.json +10 -0
  78. package/schemas/create_card.in.json +108 -0
  79. package/schemas/create_card.out.json +13 -0
  80. package/schemas/dependabot_alerts.in.json +49 -0
  81. package/schemas/dependabot_alerts.out.json +75 -0
  82. package/schemas/dismiss_dependabot_alert.in.json +26 -0
  83. package/schemas/dismiss_dependabot_alert.out.json +27 -0
  84. package/schemas/find_assignee.in.json +15 -0
  85. package/schemas/find_assignee.out.json +10 -0
  86. package/schemas/find_cards.in.json +18 -0
  87. package/schemas/find_cards.out.json +33 -0
  88. package/schemas/find_dependabot_dismissal.in.json +12 -0
  89. package/schemas/find_dependabot_dismissal.out.json +27 -0
  90. package/schemas/find_description.in.json +15 -0
  91. package/schemas/find_description.out.json +10 -0
  92. package/schemas/find_pull_request.in.json +25 -0
  93. package/schemas/find_pull_request.out.json +14 -0
  94. package/schemas/hand_back.in.json +11 -0
  95. package/schemas/hand_back.out.json +18 -0
  96. package/schemas/linked_pull_requests.in.json +15 -0
  97. package/schemas/linked_pull_requests.out.json +44 -0
  98. package/schemas/list_pull_requests.in.json +26 -0
  99. package/schemas/list_pull_requests.out.json +42 -0
  100. package/schemas/merge_pull_request.in.json +22 -0
  101. package/schemas/merge_pull_request.out.json +16 -0
  102. package/schemas/move.in.json +15 -0
  103. package/schemas/move.out.json +10 -0
  104. package/schemas/note_pull_request.in.json +15 -0
  105. package/schemas/note_pull_request.out.json +10 -0
  106. package/schemas/open_pull_request.in.json +113 -0
  107. package/schemas/open_pull_request.out.json +15 -0
  108. package/schemas/pull_request_checks.in.json +11 -0
  109. package/schemas/pull_request_checks.out.json +72 -0
  110. package/schemas/pull_request_discussion.in.json +11 -0
  111. package/schemas/pull_request_discussion.out.json +107 -0
  112. package/schemas/pull_request_state.in.json +11 -0
  113. package/schemas/pull_request_state.out.json +52 -0
  114. package/schemas/push_branch.in.json +21 -0
  115. package/schemas/push_branch.out.json +13 -0
  116. package/schemas/release_follow_ups.in.json +15 -0
  117. package/schemas/release_follow_ups.out.json +13 -0
  118. package/schemas/reopen_dependabot_alert.in.json +33 -0
  119. package/schemas/reopen_dependabot_alert.out.json +22 -0
  120. package/schemas/restore_assignee.in.json +20 -0
  121. package/schemas/restore_assignee.out.json +10 -0
  122. package/schemas/restore_description.in.json +20 -0
  123. package/schemas/restore_description.out.json +10 -0
  124. package/schemas/update_description.in.json +15 -0
  125. package/schemas/update_description.out.json +14 -0
  126. package/schemas/update_pull_request.in.json +81 -0
  127. package/schemas/update_pull_request.out.json +10 -0
  128. package/schemas/wait_for_checks.in.json +11 -0
  129. package/schemas/wait_for_checks.out.json +72 -0
  130. package/schemas/wait_for_merge.in.json +11 -0
  131. package/schemas/wait_for_merge.out.json +17 -0
  132. package/schemas/wait_for_passed_checks.in.json +11 -0
  133. package/schemas/wait_for_passed_checks.out.json +72 -0
  134. package/schemas/wait_for_review.in.json +11 -0
  135. package/schemas/wait_for_review.out.json +52 -0
  136. package/workflows/resume.toml +17 -0
@@ -0,0 +1,77 @@
1
+ import type { Card } from "@kana-ai/edgar-contracts/rpc";
2
+ import { type Ctx, type Failure, type Result } from "@kana-ai/edgar-sdk";
3
+ import type { z } from "zod";
4
+ import { TOKEN } from "#api/client";
5
+ import { type Columns, type Config, type TrackerTable } from "#schemas/config";
6
+ import { type issue } from "#schemas/github";
7
+ /** The label of an issue that EDGAR handed to a person; with `assignee_only`, it keeps the issue in scope while the person holds it. */
8
+ export declare const WAITING = "edgar:waiting";
9
+ /** The engine states in their forward order. */
10
+ export declare const states: readonly ["intake", "ready", "working", "in_review", "waiting_on_person", "in_testing", "done", "cancelled"];
11
+ /** An engine state. */
12
+ export type State = (typeof states)[number];
13
+ /** The open engine states, each marked by a label. */
14
+ export declare const openStates: ("in_review" | "in_testing" | "intake" | "ready" | "waiting_on_person" | "working")[];
15
+ /** An issue as the tracker reads it. */
16
+ export type Issue = z.infer<typeof issue>;
17
+ /** A GitHub call's context. */
18
+ export type GithubCtx = Ctx<typeof TOKEN>;
19
+ /** The tables a tracker call works with: the extension's, and its `columns` and `tracker` tables. */
20
+ export interface Settings {
21
+ readonly table: Config;
22
+ readonly columns: Columns;
23
+ readonly tracker: TrackerTable;
24
+ }
25
+ /** One repository of `[extensions.github.tracker] repos`, with the key of its card ids. */
26
+ export interface Repo {
27
+ readonly key: string;
28
+ readonly repo: string;
29
+ readonly service: string;
30
+ }
31
+ /** True for a name the tracker knows as an engine state. */
32
+ export declare function isState(value: string): value is State;
33
+ /** True when moving from `from` to `to` goes forward. A card that waits on a person goes on to any other state: the person's answer decides which. */
34
+ export declare function forward(from: State, to: State): boolean;
35
+ /** The call's tables; a table that does not match is `invalid` with its fields, and no `columns` and `tracker` tables is `invalid` that says to write them. */
36
+ export declare function settingsOf(ctx: GithubCtx): Result<Settings, Failure>;
37
+ /** Each repository of the table, in the order the table names them. */
38
+ export declare function reposOf(settings: Settings): Repo[];
39
+ /** The repository and issue number of the card id `KEY-123`; a key the table does not name is `not_found`. */
40
+ export declare function issueOf(settings: Settings, card: string): Result<{
41
+ repo: Repo;
42
+ number: number;
43
+ path: string;
44
+ }, Failure>;
45
+ /** The card id of issue `number` of `repo`. */
46
+ export declare function cardId(repo: Repo, number: number): string;
47
+ /** True for a pull request, which the issues API also lists. */
48
+ export declare function isPull(found: Issue): boolean;
49
+ /** The names of an issue's labels. */
50
+ export declare function labelNames(found: Issue): string[];
51
+ /** True when the issue is in the table's scope: its title has `title_prefix`, it has every label of `labels`, and with `assignee_only` it is assigned to `assignee` or labelled edgar:waiting. */
52
+ export declare function inScope(settings: Settings, found: Issue, assignee: string | undefined): boolean;
53
+ /** The engine state of an issue in scope: a closed one is `done`, or `cancelled` when closed as not planned or a duplicate; an open one has the state of its furthest column label, or `intake` with none. */
54
+ export declare function stateOf(settings: Settings, found: Issue): State;
55
+ /** A card whose column is an engine state. */
56
+ export type TrackedCard = Card & {
57
+ readonly column: State;
58
+ };
59
+ /** True when the issue is a card EDGAR still holds: closed, or open and in the table's scope. */
60
+ export declare function isHeld(settings: Settings, found: Issue, assignee: string | undefined): boolean;
61
+ /** The card of an issue that `isHeld` keeps, with the service of its repository in its block. An issue with no block gets a `request` block, because the block is where a card names its service. A block that does not read is `invalid` when `strict`, else read as no block. */
62
+ export declare function toCard(settings: Settings, repo: Repo, found: Issue, strict: boolean): Result<TrackedCard, Failure>;
63
+ /** The login EDGAR works as: the login of `GITHUB_TOKEN`, found once, or with an App, `[extensions.github.tracker] assignee`, since an App's token cannot read `/user`. */
64
+ export declare function ownLogin(ctx: GithubCtx, settings: Settings): Promise<Result<string, Failure>>;
65
+ /** The login of `assignee_only`, or `undefined` when it is off: `assignee`, else EDGAR's own login. */
66
+ export declare function assigneeOf(ctx: GithubCtx, settings: Settings): Promise<Result<string | undefined, Failure>>;
67
+ /** Makes each label of `names` that `repo` lacks, so a write that sets it never fails on a missing label. */
68
+ export declare function ensureLabels(ctx: GithubCtx, repo: Repo, names: readonly string[]): Promise<Result<null, Failure>>;
69
+ /** The person behind a login, as `person` answers it: the name, or the login with none, and the public email, or an empty text. */
70
+ export declare function personOf(ctx: GithubCtx, actor: string): Promise<Result<{
71
+ name: string;
72
+ email: string;
73
+ }, Failure>>;
74
+ /** The marker a write puts in a body, so a retry of the same operation finds what the first call wrote: a hash of the operation id, which says nothing of the run. */
75
+ export declare function marker(operationId: string): string;
76
+ /** Adds `add` to the issue at `path` and takes `remove` off, one label at a time, so a label a person sets meanwhile stays. A label already gone is fine. */
77
+ export declare function relabel(ctx: GithubCtx, path: string, add: readonly string[], remove: readonly string[]): Promise<Result<null, Failure>>;
@@ -0,0 +1,189 @@
1
+ import { createHash } from "node:crypto";
2
+ import { err, ok, permanentFailure, readBlock, } from "@kana-ai/edgar-sdk";
3
+ import { TOKEN, github } from "#api/client";
4
+ import { config, } from "#schemas/config";
5
+ import { namedLabel, user, viewer } from "#schemas/github";
6
+ /** The label of an issue that EDGAR handed to a person; with `assignee_only`, it keeps the issue in scope while the person holds it. */
7
+ export const WAITING = "edgar:waiting";
8
+ /** The engine states in their forward order. */
9
+ export const states = [
10
+ "intake",
11
+ "ready",
12
+ "working",
13
+ "in_review",
14
+ "waiting_on_person",
15
+ "in_testing",
16
+ "done",
17
+ "cancelled",
18
+ ];
19
+ /** The open engine states, each marked by a label. */
20
+ export const openStates = states.filter((state) => state !== "done" && state !== "cancelled");
21
+ /** True for a name the tracker knows as an engine state. */
22
+ export function isState(value) {
23
+ return states.some((state) => state === value);
24
+ }
25
+ /** True when moving from `from` to `to` goes forward. A card that waits on a person goes on to any other state: the person's answer decides which. */
26
+ export function forward(from, to) {
27
+ if (from === "waiting_on_person")
28
+ return to !== from;
29
+ return states.indexOf(to) > states.indexOf(from);
30
+ }
31
+ /** The call's tables; a table that does not match is `invalid` with its fields, and no `columns` and `tracker` tables is `invalid` that says to write them. */
32
+ export function settingsOf(ctx) {
33
+ const parsed = config.safeParse(ctx.config ?? {});
34
+ if (!parsed.success) {
35
+ return err(permanentFailure("invalid", "the [extensions.github] table does not match its schema", {
36
+ cause: parsed.error.issues.map((problem) => problem.path.join(".")).join(", "),
37
+ }));
38
+ }
39
+ const { columns, tracker } = parsed.data;
40
+ return columns === undefined || tracker === undefined
41
+ ? err(permanentFailure("invalid", "github: write [extensions.github.columns] and [extensions.github.tracker] with repos to use GitHub Issues as a tracker"))
42
+ : ok({ table: parsed.data, columns, tracker });
43
+ }
44
+ /** Each repository of the table, in the order the table names them. */
45
+ export function reposOf(settings) {
46
+ return Object.entries(settings.tracker.repos).map(([key, value]) => ({ key, ...value }));
47
+ }
48
+ /** The repository and issue number of the card id `KEY-123`; a key the table does not name is `not_found`. */
49
+ export function issueOf(settings, card) {
50
+ const parts = /^([A-Z][A-Z0-9]{0,9})-([1-9]\d*)$/.exec(card);
51
+ const repo = reposOf(settings).find((known) => known.key === parts?.[1]);
52
+ if (parts?.[2] === undefined || repo === undefined) {
53
+ return err(permanentFailure("not_found", `github: no card ${card}`));
54
+ }
55
+ return ok({ repo, number: Number(parts[2]), path: `/repos/${repo.repo}/issues/${parts[2]}` });
56
+ }
57
+ /** The card id of issue `number` of `repo`. */
58
+ export function cardId(repo, number) {
59
+ return `${repo.key}-${String(number)}`;
60
+ }
61
+ /** True for a pull request, which the issues API also lists. */
62
+ export function isPull(found) {
63
+ return (found.pull_request ?? null) !== null;
64
+ }
65
+ /** The names of an issue's labels. */
66
+ export function labelNames(found) {
67
+ return found.labels.map((label) => (typeof label === "string" ? label : label.name));
68
+ }
69
+ /** True when the issue is in the table's scope: its title has `title_prefix`, it has every label of `labels`, and with `assignee_only` it is assigned to `assignee` or labelled edgar:waiting. */
70
+ export function inScope(settings, found, assignee) {
71
+ const names = labelNames(found);
72
+ const { title_prefix: prefix, labels = [] } = settings.tracker;
73
+ const mine = assignee === undefined ||
74
+ names.includes(WAITING) ||
75
+ (found.assignees ?? []).some((person) => person.login === assignee);
76
+ return ((prefix === undefined || found.title.startsWith(prefix)) &&
77
+ labels.every((label) => names.includes(label)) &&
78
+ mine);
79
+ }
80
+ /** The engine state of an issue in scope: a closed one is `done`, or `cancelled` when closed as not planned or a duplicate; an open one has the state of its furthest column label, or `intake` with none. */
81
+ export function stateOf(settings, found) {
82
+ if (found.state === "closed") {
83
+ return found.state_reason === "not_planned" || found.state_reason === "duplicate"
84
+ ? "cancelled"
85
+ : "done";
86
+ }
87
+ const names = labelNames(found);
88
+ const labelled = openStates.findLast((state) => names.includes(settings.columns[state]));
89
+ return labelled ?? "intake";
90
+ }
91
+ /** True when the issue is a card EDGAR still holds: closed, or open and in the table's scope. */
92
+ export function isHeld(settings, found, assignee) {
93
+ return found.state === "closed" || inScope(settings, found, assignee);
94
+ }
95
+ /** The card of an issue that `isHeld` keeps, with the service of its repository in its block. An issue with no block gets a `request` block, because the block is where a card names its service. A block that does not read is `invalid` when `strict`, else read as no block. */
96
+ export function toCard(settings, repo, found, strict) {
97
+ const description = found.body ?? "";
98
+ const block = readBlock(description);
99
+ if (!block.ok && strict)
100
+ return block;
101
+ const read = block.ok ? block.value : null;
102
+ const columns = new Set(Object.values(settings.columns));
103
+ const assigned = found.assignees?.[0]?.login;
104
+ return ok({
105
+ id: cardId(repo, found.number),
106
+ title: found.title,
107
+ description,
108
+ column: stateOf(settings, found),
109
+ labels: labelNames(found).filter((name) => !columns.has(name)),
110
+ url: found.html_url,
111
+ block: { ...(read ?? { kind: "request" }), service: repo.service },
112
+ ...(assigned === undefined ? {} : { assignee: assigned }),
113
+ });
114
+ }
115
+ /** The logins found so far, by the token that signs in, kept for the life of the process. */
116
+ const logins = new Map();
117
+ /** The login EDGAR works as: the login of `GITHUB_TOKEN`, found once, or with an App, `[extensions.github.tracker] assignee`, since an App's token cannot read `/user`. */
118
+ export async function ownLogin(ctx, settings) {
119
+ if (settings.table.app !== undefined) {
120
+ return settings.tracker.assignee === undefined
121
+ ? err(permanentFailure("invalid", "[extensions.github.tracker] assignee names the login of the App, such as edgar[bot], since an App's token cannot read /user"))
122
+ : ok(settings.tracker.assignee);
123
+ }
124
+ const token = ctx.secrets.get(TOKEN);
125
+ const known = logins.get(token);
126
+ if (known !== undefined)
127
+ return ok(known);
128
+ const me = await github(ctx, "GET", "/user", viewer);
129
+ if (me.ok)
130
+ logins.set(token, me.value.login);
131
+ return me.ok ? ok(me.value.login) : me;
132
+ }
133
+ /** The login of `assignee_only`, or `undefined` when it is off: `assignee`, else EDGAR's own login. */
134
+ export async function assigneeOf(ctx, settings) {
135
+ if (!settings.tracker.assignee_only)
136
+ return ok(undefined);
137
+ return settings.tracker.assignee === undefined
138
+ ? await ownLogin(ctx, settings)
139
+ : ok(settings.tracker.assignee);
140
+ }
141
+ /** The labels known to exist, as `owner/name#label`, kept for the life of the process. */
142
+ const madeLabels = new Set();
143
+ /** Makes each label of `names` that `repo` lacks, so a write that sets it never fails on a missing label. */
144
+ export async function ensureLabels(ctx, repo, names) {
145
+ for (const name of names) {
146
+ const known = `${repo.repo}#${name}`;
147
+ if (madeLabels.has(known))
148
+ continue;
149
+ const path = `/repos/${repo.repo}/labels`;
150
+ const found = await github(ctx, "GET", `${path}/${encodeURIComponent(name)}`, namedLabel);
151
+ if (!found.ok && found.error.kind !== "not_found")
152
+ return found;
153
+ if (!found.ok) {
154
+ const made = await github(ctx, "POST", path, namedLabel, { name });
155
+ if (!made.ok && made.error.kind !== "invalid")
156
+ return made;
157
+ }
158
+ madeLabels.add(known);
159
+ }
160
+ return ok(null);
161
+ }
162
+ /** The person behind a login, as `person` answers it: the name, or the login with none, and the public email, or an empty text. */
163
+ export async function personOf(ctx, actor) {
164
+ const found = await github(ctx, "GET", `/users/${encodeURIComponent(actor)}`, user);
165
+ return found.ok
166
+ ? ok({ name: found.value.name ?? found.value.login, email: found.value.email ?? "" })
167
+ : found;
168
+ }
169
+ /** The marker a write puts in a body, so a retry of the same operation finds what the first call wrote: a hash of the operation id, which says nothing of the run. */
170
+ export function marker(operationId) {
171
+ const hash = createHash("sha256").update(operationId).digest("hex").slice(0, 16);
172
+ return `<!-- edgar:op ${hash} -->`;
173
+ }
174
+ /** Adds `add` to the issue at `path` and takes `remove` off, one label at a time, so a label a person sets meanwhile stays. A label already gone is fine. */
175
+ export async function relabel(ctx, path, add, remove) {
176
+ if (add.length > 0) {
177
+ const added = await github(ctx, "POST", `${path}/labels`, namedLabel.array(), {
178
+ labels: [...add],
179
+ });
180
+ if (!added.ok)
181
+ return added;
182
+ }
183
+ for (const name of remove) {
184
+ const removed = await github(ctx, "DELETE", `${path}/labels/${encodeURIComponent(name)}`, namedLabel.array());
185
+ if (!removed.ok && removed.error.kind !== "not_found")
186
+ return removed;
187
+ }
188
+ return ok(null);
189
+ }
@@ -0,0 +1,143 @@
1
+ /** The tools of the GitHub Issues tracker, by the names the default workflows call on a tracker. */
2
+ export declare const trackerTools: {
3
+ comment: import("@kana-ai/edgar-sdk").Tool<{
4
+ card: string;
5
+ text: string;
6
+ link?: string;
7
+ }, {
8
+ id: string;
9
+ }, "GITHUB_TOKEN">;
10
+ move: import("@kana-ai/edgar-sdk").Tool<{
11
+ card: string;
12
+ column: string;
13
+ }, {
14
+ column: string;
15
+ }, "GITHUB_TOKEN">;
16
+ close: import("@kana-ai/edgar-sdk").Tool<{
17
+ card: string;
18
+ reason: string;
19
+ }, {
20
+ state: string;
21
+ }, "GITHUB_TOKEN">;
22
+ /** `parent` is not used: see the shortcut in the README. */
23
+ create_card: import("@kana-ai/edgar-sdk").Tool<{
24
+ spec: {
25
+ title: string;
26
+ description: string;
27
+ column?: string;
28
+ labels?: string[];
29
+ block: {
30
+ kind: "defect" | "investigation" | "question" | "request";
31
+ service?: string;
32
+ environment?: string;
33
+ fingerprint?: string;
34
+ first_seen?: string;
35
+ last_seen?: string;
36
+ occurrences?: number;
37
+ severity?: string;
38
+ window?: string;
39
+ waits_for?: string;
40
+ decided?: Record<string, string>;
41
+ origin?: {
42
+ extension: string;
43
+ channel: string;
44
+ thread: string;
45
+ };
46
+ };
47
+ };
48
+ parent?: string;
49
+ }, {
50
+ id: string;
51
+ url: string;
52
+ }, "GITHUB_TOKEN">;
53
+ release_follow_ups: import("@kana-ai/edgar-sdk").Tool<{
54
+ card: string;
55
+ pull_request: string;
56
+ }, {
57
+ released: string[];
58
+ }, "GITHUB_TOKEN">;
59
+ /** A retry with the same `seen_at` finds the sighting counted and writes nothing; with no `seen_at`, a retry whose first answer was lost counts it twice. */
60
+ count_sighting: import("@kana-ai/edgar-sdk").Tool<{
61
+ card: string;
62
+ seen_at?: string;
63
+ }, {
64
+ id: string;
65
+ }, "GITHUB_TOKEN">;
66
+ batch_cards: import("@kana-ai/edgar-sdk").Tool<{
67
+ batch: string;
68
+ except: string;
69
+ only?: string[] | undefined;
70
+ }, {
71
+ cards: {
72
+ id: string;
73
+ title: string;
74
+ url: string;
75
+ description: string;
76
+ }[];
77
+ skipped?: string[] | undefined;
78
+ }, "GITHUB_TOKEN">;
79
+ find_cards: import("@kana-ai/edgar-sdk").Tool<{
80
+ text: string;
81
+ except?: string;
82
+ }, {
83
+ cards: {
84
+ id: string;
85
+ title: string;
86
+ url: string;
87
+ state: string;
88
+ created_at: string;
89
+ }[];
90
+ }, "GITHUB_TOKEN">;
91
+ /** A retry reads the card again and writes nothing when the person and the label are already there. */
92
+ hand_back: import("@kana-ai/edgar-sdk").Tool<{
93
+ card: string;
94
+ }, {
95
+ id: string;
96
+ to: string;
97
+ previous: string;
98
+ }, "GITHUB_TOKEN">;
99
+ /** A retry writes the same text again, which changes nothing; the lookup tells boot whether a call that did not end wrote it. */
100
+ update_description: import("@kana-ai/edgar-sdk").Tool<{
101
+ card: string;
102
+ description: string;
103
+ }, {
104
+ id: string;
105
+ previous?: string | undefined;
106
+ }, "GITHUB_TOKEN">;
107
+ restore_description: import("@kana-ai/edgar-sdk").Tool<{
108
+ stage_output: {
109
+ id: string;
110
+ previous?: string | undefined;
111
+ };
112
+ }, {
113
+ id: string;
114
+ }, "GITHUB_TOKEN">;
115
+ find_description: import("@kana-ai/edgar-sdk").Tool<{
116
+ card: string;
117
+ description: string;
118
+ }, {
119
+ id: string;
120
+ }, "GITHUB_TOKEN">;
121
+ /** A retry reads the card again and writes nothing when it already has that assignee; the lookup tells boot whether a call that did not end wrote it. */
122
+ assign: import("@kana-ai/edgar-sdk").Tool<{
123
+ card: string;
124
+ user: string;
125
+ }, {
126
+ id: string;
127
+ previous?: string | undefined;
128
+ }, "GITHUB_TOKEN">;
129
+ restore_assignee: import("@kana-ai/edgar-sdk").Tool<{
130
+ stage_output: {
131
+ id: string;
132
+ previous?: string | undefined;
133
+ };
134
+ }, {
135
+ id: string;
136
+ }, "GITHUB_TOKEN">;
137
+ find_assignee: import("@kana-ai/edgar-sdk").Tool<{
138
+ card: string;
139
+ user: string;
140
+ }, {
141
+ id: string;
142
+ }, "GITHUB_TOKEN">;
143
+ };
@@ -0,0 +1,131 @@
1
+ import { defineTool, done } from "@kana-ai/edgar-sdk";
2
+ import { apiAccess } from "#api/client";
3
+ import { assignTool, batchCardsTool, closeTool, commentTool, countSightingTool, createCardTool, descriptionTool, findCardsTool, handBackTool, moveTool, releaseFollowUpsTool, restoreTool, } from "#schemas/tools";
4
+ import { assign, findAssignee, restoreAssignee } from "#tracker/assignee";
5
+ import { batchCards, countSightingOn, createCard, findCards } from "#tracker/cards";
6
+ import { postComment } from "#tracker/comments";
7
+ import { findDescription, restoreDescription, updateDescription } from "#tracker/description";
8
+ import { handBack } from "#tracker/hand-back";
9
+ import { releaseFollowUps, transition } from "#tracker/transitions";
10
+ /** The tools of the GitHub Issues tracker, by the names the default workflows call on a tracker. */
11
+ export const trackerTools = {
12
+ comment: defineTool({
13
+ description: "Post a comment on a card, with an optional link on its own line",
14
+ input: commentTool.input,
15
+ output: commentTool.output,
16
+ ...apiAccess,
17
+ execute: async ({ card, text, link }, ctx) => await postComment(ctx, card, link === undefined ? text : `${text}\n\n${link}`),
18
+ }),
19
+ move: defineTool({
20
+ description: "Move a card to the column of an engine state, forward only; skipped otherwise",
21
+ input: moveTool.input,
22
+ output: moveTool.output,
23
+ ...apiAccess,
24
+ execute: async ({ card, column }, ctx) => await transition(ctx, card, column),
25
+ }),
26
+ close: defineTool({
27
+ description: "Close a card's issue as completed",
28
+ input: closeTool.input,
29
+ output: closeTool.output,
30
+ ...apiAccess,
31
+ execute: async ({ card }, ctx) => {
32
+ const closed = await transition(ctx, card, "done", true);
33
+ return closed.outcome === "done" ? done({ state: closed.output.column }) : closed;
34
+ },
35
+ }),
36
+ /** `parent` is not used: see the shortcut in the README. */
37
+ create_card: defineTool({
38
+ description: "File a card, or return the open card that holds its fingerprint",
39
+ input: createCardTool.input,
40
+ output: createCardTool.output,
41
+ ...apiAccess,
42
+ execute: async ({ spec }, ctx) => await createCard(ctx, spec),
43
+ }),
44
+ release_follow_ups: defineTool({
45
+ description: "Move the cards that wait for a card's merged pull request to ready",
46
+ input: releaseFollowUpsTool.input,
47
+ output: releaseFollowUpsTool.output,
48
+ ...apiAccess,
49
+ execute: async ({ card }, ctx) => await releaseFollowUps(ctx, card),
50
+ }),
51
+ /** A retry with the same `seen_at` finds the sighting counted and writes nothing; with no `seen_at`, a retry whose first answer was lost counts it twice. */
52
+ count_sighting: defineTool({
53
+ description: "Count one more sighting of the fault that an open card holds: raise occurrences and last_seen in its block; a card with no block is not written",
54
+ input: countSightingTool.input,
55
+ output: countSightingTool.output,
56
+ ...apiAccess,
57
+ execute: async ({ card, seen_at }, ctx) => await countSightingOn(ctx, card, seen_at),
58
+ }),
59
+ batch_cards: defineTool({
60
+ description: "List the other open cards whose decided.batch is the given batch, such as the scanner cards of one repository",
61
+ input: batchCardsTool.input,
62
+ output: batchCardsTool.output,
63
+ ...apiAccess,
64
+ execute: async ({ batch, except, only }, ctx) => await batchCards(ctx, batch, except, only),
65
+ }),
66
+ find_cards: defineTool({
67
+ description: "Search the open cards for words of a fault; with except, only cards made before that card",
68
+ input: findCardsTool.input,
69
+ output: findCardsTool.output,
70
+ ...apiAccess,
71
+ execute: async ({ text, except }, ctx) => await findCards(ctx, text, except),
72
+ }),
73
+ /** A retry reads the card again and writes nothing when the person and the label are already there. */
74
+ hand_back: defineTool({
75
+ description: "Assign a card to the person who handed it to EDGAR, else to its writer, and label it edgar:waiting; skipped when nobody can be given it",
76
+ input: handBackTool.input,
77
+ output: handBackTool.output,
78
+ ...apiAccess,
79
+ execute: async ({ card }, ctx) => await handBack(ctx, card),
80
+ }),
81
+ /** A retry writes the same text again, which changes nothing; the lookup tells boot whether a call that did not end wrote it. */
82
+ update_description: defineTool({
83
+ description: "Replace a card's description, keeping its edgar:v0 block",
84
+ input: descriptionTool.input,
85
+ output: descriptionTool.output,
86
+ ...apiAccess,
87
+ side_effect: true,
88
+ compensate: "restore_description",
89
+ lookup: "find_description",
90
+ execute: async ({ card, description }, ctx) => await updateDescription(ctx, card, description),
91
+ }),
92
+ restore_description: defineTool({
93
+ description: "Put back the description a card had before update_description",
94
+ input: restoreTool.input,
95
+ output: restoreTool.output,
96
+ ...apiAccess,
97
+ execute: async ({ stage_output }, ctx) => await restoreDescription(ctx, stage_output.id, stage_output.previous),
98
+ }),
99
+ find_description: defineTool({
100
+ description: "Done when a card's description already reads as update_description writes it; skipped otherwise",
101
+ input: descriptionTool.input,
102
+ output: restoreTool.output,
103
+ ...apiAccess,
104
+ execute: async ({ card, description }, ctx) => await findDescription(ctx, card, description),
105
+ }),
106
+ /** A retry reads the card again and writes nothing when it already has that assignee; the lookup tells boot whether a call that did not end wrote it. */
107
+ assign: defineTool({
108
+ description: "Assign a card to a GitHub login, to EDGAR's own login with `me`, or to nobody with an empty user",
109
+ input: assignTool.input,
110
+ output: assignTool.output,
111
+ ...apiAccess,
112
+ side_effect: true,
113
+ compensate: "restore_assignee",
114
+ lookup: "find_assignee",
115
+ execute: async ({ card, user }, ctx) => await assign(ctx, card, user),
116
+ }),
117
+ restore_assignee: defineTool({
118
+ description: "Set back the assignee a card had before assign",
119
+ input: restoreTool.input,
120
+ output: restoreTool.output,
121
+ ...apiAccess,
122
+ execute: async ({ stage_output }, ctx) => await restoreAssignee(ctx, stage_output.id, stage_output.previous),
123
+ }),
124
+ find_assignee: defineTool({
125
+ description: "Done when a card already has the assignee that assign sets; skipped otherwise",
126
+ input: assignTool.input,
127
+ output: restoreTool.output,
128
+ ...apiAccess,
129
+ execute: async ({ card, user }, ctx) => await findAssignee(ctx, card, user),
130
+ }),
131
+ };
@@ -0,0 +1,12 @@
1
+ import { type Outcome } from "@kana-ai/edgar-sdk";
2
+ import { type State, type GithubCtx } from "#tracker/states";
3
+ /** Moves a card to `target`: forward only unless `force`, and `skipped` for a name that is not an engine state or an open issue out of scope. An open state adds its column label and takes the others off, and opens a closed issue again; `done` closes it as completed and `cancelled` as not planned, and takes its column labels off. A move to any state but `waiting_on_person` takes edgar:waiting off, so the card no longer waits on a person. Labels change one at a time, so a label a person sets meanwhile stays. */
4
+ export declare function transition(ctx: GithubCtx, card: string, target: string, force?: boolean): Promise<Outcome<{
5
+ column: State;
6
+ }>>;
7
+ /** Sets a card's labels to `labels` whole, keeping the column labels that say its engine state. */
8
+ export declare function setLabels(ctx: GithubCtx, card: string, labels: readonly string[]): Promise<Outcome<null>>;
9
+ /** Moves each card in `intake` whose block waits for `card` to `ready`, and answers the ids it moved. */
10
+ export declare function releaseFollowUps(ctx: GithubCtx, card: string): Promise<Outcome<{
11
+ released: string[];
12
+ }>>;
@@ -0,0 +1,101 @@
1
+ import { done, skipped } from "@kana-ai/edgar-sdk";
2
+ import { github } from "#api/client";
3
+ import { issue } from "#schemas/github";
4
+ import { waitingOn } from "#tracker/cards";
5
+ import { WAITING, assigneeOf, ensureLabels, forward, isHeld, isState, issueOf, labelNames, openStates, relabel, settingsOf, stateOf, } from "#tracker/states";
6
+ /** Moves a card to `target`: forward only unless `force`, and `skipped` for a name that is not an engine state or an open issue out of scope. An open state adds its column label and takes the others off, and opens a closed issue again; `done` closes it as completed and `cancelled` as not planned, and takes its column labels off. A move to any state but `waiting_on_person` takes edgar:waiting off, so the card no longer waits on a person. Labels change one at a time, so a label a person sets meanwhile stays. */
7
+ export async function transition(ctx, card, target, force = false) {
8
+ const settings = settingsOf(ctx);
9
+ if (!settings.ok)
10
+ return settings.error;
11
+ if (!isState(target))
12
+ return skipped();
13
+ const found = issueOf(settings.value, card);
14
+ if (!found.ok)
15
+ return found.error;
16
+ const read = await github(ctx, "GET", found.value.path, issue);
17
+ if (!read.ok)
18
+ return read.error;
19
+ const assignee = await assigneeOf(ctx, settings.value);
20
+ if (!assignee.ok)
21
+ return assignee.error;
22
+ const from = isHeld(settings.value, read.value, assignee.value)
23
+ ? stateOf(settings.value, read.value)
24
+ : undefined;
25
+ const columns = settings.value.columns;
26
+ const names = labelNames(read.value);
27
+ const waiting = target !== "waiting_on_person" && names.includes(WAITING) ? [WAITING] : [];
28
+ if (from === target) {
29
+ if (!force)
30
+ return skipped();
31
+ const unwaited = await relabel(ctx, found.value.path, [], waiting);
32
+ return unwaited.ok ? done({ column: target }) : unwaited.error;
33
+ }
34
+ if (!force && (from === undefined || !forward(from, target)))
35
+ return skipped();
36
+ const state = openStates.find((open) => open === target);
37
+ const label = state === undefined ? undefined : columns[state];
38
+ const stale = openStates
39
+ .map((open) => columns[open])
40
+ .filter((name) => name !== label && names.includes(name));
41
+ if (label === undefined) {
42
+ const closed = await github(ctx, "PATCH", found.value.path, issue, {
43
+ state: "closed",
44
+ state_reason: target === "done" ? "completed" : "not_planned",
45
+ });
46
+ if (!closed.ok)
47
+ return closed.error;
48
+ }
49
+ else {
50
+ const made = await ensureLabels(ctx, found.value.repo, [label]);
51
+ if (!made.ok)
52
+ return made.error;
53
+ if (read.value.state === "closed") {
54
+ const opened = await github(ctx, "PATCH", found.value.path, issue, { state: "open" });
55
+ if (!opened.ok)
56
+ return opened.error;
57
+ }
58
+ }
59
+ const add = label === undefined || names.includes(label) ? [] : [label];
60
+ const moved = await relabel(ctx, found.value.path, add, [...stale, ...waiting]);
61
+ return moved.ok ? done({ column: target }) : moved.error;
62
+ }
63
+ /** Sets a card's labels to `labels` whole, keeping the column labels that say its engine state. */
64
+ export async function setLabels(ctx, card, labels) {
65
+ const settings = settingsOf(ctx);
66
+ if (!settings.ok)
67
+ return settings.error;
68
+ const found = issueOf(settings.value, card);
69
+ if (!found.ok)
70
+ return found.error;
71
+ const read = await github(ctx, "GET", found.value.path, issue);
72
+ if (!read.ok)
73
+ return read.error;
74
+ const columns = settings.value.columns;
75
+ const marks = new Set(openStates.map((state) => columns[state]));
76
+ const kept = labelNames(read.value).filter((name) => marks.has(name));
77
+ const wanted = [...new Set([...kept, ...labels])];
78
+ const made = await ensureLabels(ctx, found.value.repo, labels);
79
+ if (!made.ok)
80
+ return made.error;
81
+ const written = await github(ctx, "PATCH", found.value.path, issue, { labels: wanted });
82
+ return written.ok ? done(null) : written.error;
83
+ }
84
+ /** Moves each card in `intake` whose block waits for `card` to `ready`, and answers the ids it moved. */
85
+ export async function releaseFollowUps(ctx, card) {
86
+ const settings = settingsOf(ctx);
87
+ if (!settings.ok)
88
+ return settings.error;
89
+ const waiting = await waitingOn(ctx, settings.value, card);
90
+ if (!waiting.ok)
91
+ return waiting.error;
92
+ const released = [];
93
+ for (const id of waiting.value) {
94
+ const moved = await transition(ctx, id, "ready");
95
+ if (moved.outcome === "done")
96
+ released.push(id);
97
+ else if (moved.outcome !== "skipped")
98
+ return moved;
99
+ }
100
+ return done({ released });
101
+ }