@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,134 @@
1
+ import { defineTool, done, ok, permanentFailure } from "@kana-ai/edgar-sdk";
2
+ import { z } from "zod";
3
+ import { apiAccess, github } from "#api/client";
4
+ import { alert, branch, classicProtection, rule } from "#schemas/github";
5
+ import { alertStates, branchProtection, dependabotAlerts } from "#schemas/tools";
6
+ import { repoOf } from "#tools/pull-request";
7
+ /** The facts a stage decides on, lifted out of GitHub's alert. */
8
+ export function factsOf(a) {
9
+ const v = a.security_vulnerability;
10
+ const adv = a.security_advisory;
11
+ return {
12
+ number: a.number,
13
+ url: a.html_url,
14
+ state: a.state,
15
+ package: a.dependency.package?.name ?? null,
16
+ ecosystem: a.dependency.package?.ecosystem ?? null,
17
+ severity: v.severity,
18
+ vulnerable_range: v.vulnerable_version_range,
19
+ first_patched: v.first_patched_version?.identifier ?? null,
20
+ manifest: a.dependency.manifest_path ?? null,
21
+ scope: a.dependency.scope ?? null,
22
+ ghsa: adv.ghsa_id,
23
+ cve: adv.cve_id,
24
+ summary: adv.summary,
25
+ };
26
+ }
27
+ /** The classic rule of a branch: `none` on 404 for an unprotected branch, `unreadable` when GitHub hides it from a token that is not an admin's (403, or 404 on a protected branch). */
28
+ async function classicOf(ctx, path, protectedBranch) {
29
+ const read = await github(ctx, "GET", `${path}/protection`, classicProtection);
30
+ if (read.ok)
31
+ return read;
32
+ if (read.error.kind === "forbidden")
33
+ return ok("unreadable");
34
+ if (read.error.kind === "not_found")
35
+ return ok(protectedBranch ? "unreadable" : "none");
36
+ return read;
37
+ }
38
+ /** The repository tools of the GitHub extension, by the name the manifest gives them. */
39
+ export const repositoryTools = {
40
+ /** shortcut: one page of up to 100 alerts, newest first; `ghsa` and `cve` match within that page, said by `complete`. */
41
+ dependabot_alerts: defineTool({
42
+ description: "Read the Dependabot alerts of a repository, or one alert by number: package, severity, vulnerable range, first patched version, manifest and advisory ids",
43
+ input: dependabotAlerts.input,
44
+ output: dependabotAlerts.output,
45
+ ...apiAccess,
46
+ execute: async (input, ctx) => {
47
+ const repo = repoOf(input.repo);
48
+ if (!repo.ok)
49
+ return repo.error;
50
+ const base = `/repos/${repo.value}/dependabot/alerts`;
51
+ const states = input.state ?? [];
52
+ const limit = input.limit ?? 30;
53
+ const ids = [...(input.ghsa ?? []), ...(input.cve ?? [])].map((id) => id.toLowerCase());
54
+ if (input.number !== undefined) {
55
+ if (states.length > 0 || input.package !== undefined || ids.length > 0) {
56
+ return permanentFailure("invalid_input", "number reads one alert, so the filters stay empty");
57
+ }
58
+ const one = await github(ctx, "GET", `${base}/${String(input.number)}`, alert);
59
+ if (!one.ok)
60
+ return one.error;
61
+ return done({ alerts: [factsOf(one.value)], complete: true });
62
+ }
63
+ const perPage = ids.length > 0 ? 100 : limit;
64
+ const query = new URLSearchParams({
65
+ state: (states.length > 0 ? states : alertStates.options).join(","),
66
+ sort: "created",
67
+ direction: "desc",
68
+ per_page: String(perPage),
69
+ ...(input.package === undefined ? {} : { package: input.package }),
70
+ });
71
+ const listed = await github(ctx, "GET", `${base}?${query.toString()}`, z.array(alert));
72
+ if (!listed.ok)
73
+ return listed.error;
74
+ const about = (a) => ids.length === 0 ||
75
+ ids.includes(a.security_advisory.ghsa_id.toLowerCase()) ||
76
+ ids.includes((a.security_advisory.cve_id ?? "").toLowerCase());
77
+ const matched = listed.value.filter(about);
78
+ return done({
79
+ alerts: matched.slice(0, limit).map(factsOf),
80
+ complete: listed.value.length < perPage && matched.length <= limit,
81
+ });
82
+ },
83
+ }),
84
+ branch_protection: defineTool({
85
+ description: "Read what GitHub enforces on a branch: whether a merge needs a pull request and how many approvals, the required checks, and each rule and ruleset that applies",
86
+ input: branchProtection.input,
87
+ output: branchProtection.output,
88
+ ...apiAccess,
89
+ execute: async (input, ctx) => {
90
+ const repo = repoOf(input.repo);
91
+ if (!repo.ok)
92
+ return repo.error;
93
+ const name = encodeURIComponent(input.branch);
94
+ const path = `/repos/${repo.value}/branches/${name}`;
95
+ const read = await github(ctx, "GET", path, branch);
96
+ if (!read.ok)
97
+ return read.error;
98
+ const rules = await github(ctx, "GET", `/repos/${repo.value}/rules/branches/${name}?per_page=100`, z.array(rule));
99
+ if (!rules.ok)
100
+ return rules.error;
101
+ const classic = await classicOf(ctx, path, read.value.protected);
102
+ if (!classic.ok)
103
+ return classic.error;
104
+ const c = typeof classic.value === "string" ? undefined : classic.value;
105
+ const prRules = rules.value.filter((r) => r.type === "pull_request");
106
+ const approvals = [
107
+ ...prRules.map((r) => r.parameters?.required_approving_review_count ?? 0),
108
+ ...(c?.required_pull_request_reviews === undefined
109
+ ? []
110
+ : [c.required_pull_request_reviews.required_approving_review_count]),
111
+ ];
112
+ const known = classic.value !== "unreadable";
113
+ const required = prRules.length > 0 || c?.required_pull_request_reviews !== undefined;
114
+ const checks = new Set([
115
+ ...(read.value.protection?.required_status_checks?.contexts ?? []),
116
+ ...(c?.required_status_checks?.contexts ?? []),
117
+ ...rules.value.flatMap((r) => r.parameters?.required_status_checks?.map((s) => s.context) ?? []),
118
+ ]);
119
+ return done({
120
+ branch: read.value.name,
121
+ protected: read.value.protected,
122
+ pull_request_required: required || known ? required : null,
123
+ required_approvals: approvals.length > 0 ? Math.max(...approvals) : known ? 0 : null,
124
+ required_checks: [...checks].sort(),
125
+ rules: rules.value.map((r) => ({
126
+ type: r.type,
127
+ ruleset_id: r.ruleset_id,
128
+ source: r.ruleset_source,
129
+ })),
130
+ classic: typeof classic.value === "string" ? classic.value : "read",
131
+ });
132
+ },
133
+ }),
134
+ };
@@ -0,0 +1,21 @@
1
+ import { type Ctx, type Failure, type Result } from "@kana-ai/edgar-sdk";
2
+ import { z } from "zod";
3
+ import { type TOKEN } from "#api/client";
4
+ import type { attachScreenshot } from "#schemas/tools";
5
+ /** The branch of a repository that holds EDGAR's screenshots. It has a history of its own, so the diff of a change never holds a picture. */
6
+ export declare const SCREENSHOTS = "edgar/screenshots";
7
+ /** The largest picture that goes into a body, as the contents API takes a file of about 1 MB. */
8
+ export declare const MAX_SCREENSHOT_BYTES = 1048576;
9
+ type Shot = z.infer<typeof attachScreenshot.input>["shot"];
10
+ /** The screenshot part of `body`, with its markers, when the body has one. */
11
+ export declare function screenshotOf(body: string): string | undefined;
12
+ /** `body` with `text` as its screenshot part: in the place of the part it has, or at its end. */
13
+ export declare function withScreenshot(body: string, text: string): string;
14
+ /** A failure in one line that a person reads in a body. */
15
+ export declare function said(failure: Failure): string;
16
+ /** The Markdown of `shot` stored on the screenshots branch of `repo`, as an image pinned to the commit that holds it, or why there is none. */
17
+ export declare function picture(ctx: Ctx<typeof TOKEN>, repo: string, shot: Shot): Promise<Result<{
18
+ readonly image: string;
19
+ readonly text: string;
20
+ }, string>>;
21
+ export {};
@@ -0,0 +1,99 @@
1
+ import { createHash } from "node:crypto";
2
+ import { err, ok } from "@kana-ai/edgar-sdk";
3
+ import { z } from "zod";
4
+ import { github } from "#api/client";
5
+ import { gitObject, gitRef, storedFile } from "#schemas/github";
6
+ /** The branch of a repository that holds EDGAR's screenshots. It has a history of its own, so the diff of a change never holds a picture. */
7
+ export const SCREENSHOTS = "edgar/screenshots";
8
+ /** The largest picture that goes into a body, as the contents API takes a file of about 1 MB. */
9
+ export const MAX_SCREENSHOT_BYTES = 1_048_576;
10
+ const OPEN = "<!-- edgar:screenshot -->";
11
+ const CLOSE = "<!-- /edgar:screenshot -->";
12
+ /** The screenshot part of `body`, with its markers, when the body has one. */
13
+ export function screenshotOf(body) {
14
+ const start = body.indexOf(OPEN);
15
+ const end = start < 0 ? -1 : body.indexOf(CLOSE, start);
16
+ return end < 0 ? undefined : body.slice(start, end + CLOSE.length);
17
+ }
18
+ /** `body` with `text` as its screenshot part: in the place of the part it has, or at its end. */
19
+ export function withScreenshot(body, text) {
20
+ const part = `${OPEN}\n${text}\n${CLOSE}`;
21
+ const old = screenshotOf(body);
22
+ if (old !== undefined)
23
+ return body.replace(old, () => part);
24
+ return body === "" ? part : `${body}\n\n${part}`;
25
+ }
26
+ /** A failure in one line that a person reads in a body. */
27
+ export function said(failure) {
28
+ const text = failure.cause === undefined ? failure.message : `${failure.message}: ${failure.cause}`;
29
+ return text.replaceAll(/\s+/g, " ").trim().slice(0, 300);
30
+ }
31
+ const message = (run) => `Add a screenshot of run ${run}`;
32
+ /** A branch that starts from an empty tree, with `content` at `file` and no parent commit, so it shares no history with the code; the commit that holds the file. */
33
+ async function orphan(ctx, repo, file, content) {
34
+ const at = `/repos/${repo}/git`;
35
+ const blob = await github(ctx, "POST", `${at}/blobs`, gitObject, { content, encoding: "base64" });
36
+ if (!blob.ok)
37
+ return blob;
38
+ const entry = { path: file, mode: "100644", type: "blob", sha: blob.value.sha };
39
+ const tree = await github(ctx, "POST", `${at}/trees`, gitObject, { tree: [entry] });
40
+ if (!tree.ok)
41
+ return tree;
42
+ const commit = await github(ctx, "POST", `${at}/commits`, gitObject, {
43
+ message: message(ctx.run_id),
44
+ tree: tree.value.sha,
45
+ parents: [],
46
+ });
47
+ if (!commit.ok)
48
+ return commit;
49
+ const ref = await github(ctx, "POST", `${at}/refs`, gitRef, {
50
+ ref: `refs/heads/${SCREENSHOTS}`,
51
+ sha: commit.value.sha,
52
+ });
53
+ return ref.ok ? ok(commit.value.sha) : ref;
54
+ }
55
+ /** Writes `content`, in base64, at `file` of the screenshots branch of `repo`; the commit that holds it. A 422 on the branch's creation is a branch that another run made first. A 409 on the write is another run that moved the branch at the same moment, so the write goes once more. A 422 on the write is the file there already: its name holds the hash of its bytes, so its newest commit holds the same picture. */
56
+ async function stored(ctx, repo, file, content) {
57
+ const branch = await github(ctx, "GET", `/repos/${repo}/git/ref/heads/${SCREENSHOTS}`, gitRef);
58
+ if (!branch.ok && branch.error.kind !== "not_found")
59
+ return branch;
60
+ if (!branch.ok) {
61
+ const made = await orphan(ctx, repo, file, content);
62
+ if (made.ok || made.error.kind !== "invalid")
63
+ return made;
64
+ }
65
+ const write = () => github(ctx, "PUT", `/repos/${repo}/contents/${file}`, storedFile, {
66
+ message: message(ctx.run_id),
67
+ content,
68
+ branch: SCREENSHOTS,
69
+ });
70
+ const first = await write();
71
+ const put = !first.ok && first.error.kind === "tool_error" ? await write() : first;
72
+ if (put.ok)
73
+ return ok(put.value.commit.sha);
74
+ if (put.error.kind !== "invalid")
75
+ return put;
76
+ const query = `sha=${encodeURIComponent(SCREENSHOTS)}&path=${encodeURIComponent(file)}&per_page=1`;
77
+ const newest = await github(ctx, "GET", `/repos/${repo}/commits?${query}`, z.array(gitObject));
78
+ const sha = newest.ok ? newest.value[0]?.sha : undefined;
79
+ return sha === undefined ? put : ok(sha);
80
+ }
81
+ /** The Markdown of `shot` stored on the screenshots branch of `repo`, as an image pinned to the commit that holds it, or why there is none. */
82
+ export async function picture(ctx, repo, shot) {
83
+ if ("missing" in shot)
84
+ return err(shot.missing);
85
+ const kb = (bytes) => String(Math.ceil(bytes / 1024));
86
+ if (shot.bytes > MAX_SCREENSHOT_BYTES) {
87
+ return err(`it is ${kb(shot.bytes)} KB, over the ${kb(MAX_SCREENSHOT_BYTES)} KB a body shows`);
88
+ }
89
+ const read = await ctx.sandbox.read(shot.path, "base64");
90
+ if (!read.ok)
91
+ return err(`it could not be read from the sandbox: ${read.error.message}`);
92
+ const hash = createHash("sha256").update(Buffer.from(read.value, "base64")).digest("hex");
93
+ const file = `${ctx.run_id}/preview-${hash.slice(0, 16)}.png`;
94
+ const commit = await stored(ctx, repo, file, read.value);
95
+ if (!commit.ok)
96
+ return err(`the upload to GitHub failed: ${said(commit.error)}`);
97
+ const image = `https://github.com/${repo}/blob/${commit.value}/${file}?raw=true`;
98
+ return ok({ image, text: `![${shot.caption.replaceAll(/[[\]\n]/g, " ")}](${image})` });
99
+ }
@@ -0,0 +1,15 @@
1
+ import { type Outcome } from "@kana-ai/edgar-sdk";
2
+ import { type GithubCtx } from "#tracker/states";
3
+ /** Assigns a card to `login` alone, or to nobody for an empty `login`, and answers the login it replaced, `""` for nobody. A card that already has that assignee is not written again and gets no `previous`: this call cannot know what a lost earlier call replaced, so its undo writes nothing. */
4
+ export declare function assign(ctx: GithubCtx, card: string, login: string): Promise<Outcome<{
5
+ id: string;
6
+ previous?: string;
7
+ }>>;
8
+ /** Sets the card's assignee back to `previous`, the login that `assign` answered, or to nobody for `""`. With no `previous` the undone call wrote nothing, so this writes nothing. */
9
+ export declare function restoreAssignee(ctx: GithubCtx, card: string, previous: string | undefined): Promise<Outcome<{
10
+ id: string;
11
+ }>>;
12
+ /** `done` when the card already has the assignee that `assign` sets for `login`, else `skipped`: the lookup of a call that did not end. */
13
+ export declare function findAssignee(ctx: GithubCtx, card: string, login: string): Promise<Outcome<{
14
+ id: string;
15
+ }>>;
@@ -0,0 +1,65 @@
1
+ import { done, err, ok, permanentFailure, skipped, } from "@kana-ai/edgar-sdk";
2
+ import { github } from "#api/client";
3
+ import { issue, user } from "#schemas/github";
4
+ import { issueOf, ownLogin, settingsOf } from "#tracker/states";
5
+ /** The issue behind a card with its assignee's login, and the login that an assign to `login` writes; `null` is nobody. `me` is EDGAR's own login. A card or a login that GitHub does not have is `not_found`. */
6
+ async function planned(ctx, card, login) {
7
+ const settings = settingsOf(ctx);
8
+ if (!settings.ok)
9
+ return err(settings.error);
10
+ const target = issueOf(settings.value, card);
11
+ if (!target.ok)
12
+ return err(target.error);
13
+ const read = await github(ctx, "GET", target.value.path, issue);
14
+ if (!read.ok)
15
+ return err(read.error);
16
+ const path = target.value.path;
17
+ const current = read.value.assignees?.[0]?.login ?? null;
18
+ if (login === "")
19
+ return ok({ path, current, next: null });
20
+ if (login === "me") {
21
+ const me = await ownLogin(ctx, settings.value);
22
+ return me.ok ? ok({ path, current, next: me.value }) : err(me.error);
23
+ }
24
+ const found = await github(ctx, "GET", `/users/${encodeURIComponent(login)}`, user);
25
+ if (found.ok)
26
+ return ok({ path, current, next: found.value.login });
27
+ return err(found.error.outcome === "permanent_failure" && found.error.kind === "not_found"
28
+ ? permanentFailure("not_found", `github: no user ${login}`)
29
+ : found.error);
30
+ }
31
+ /** Assigns a card to `login` alone, or to nobody for an empty `login`, and answers the login it replaced, `""` for nobody. A card that already has that assignee is not written again and gets no `previous`: this call cannot know what a lost earlier call replaced, so its undo writes nothing. */
32
+ export async function assign(ctx, card, login) {
33
+ const plan = await planned(ctx, card, login);
34
+ if (!plan.ok)
35
+ return plan.error;
36
+ const { path, current, next } = plan.value;
37
+ if (current === next)
38
+ return done({ id: card });
39
+ const written = await github(ctx, "PATCH", path, issue, {
40
+ assignees: next === null ? [] : [next],
41
+ });
42
+ return written.ok ? done({ id: card, previous: current ?? "" }) : written.error;
43
+ }
44
+ /** Sets the card's assignee back to `previous`, the login that `assign` answered, or to nobody for `""`. With no `previous` the undone call wrote nothing, so this writes nothing. */
45
+ export async function restoreAssignee(ctx, card, previous) {
46
+ if (previous === undefined)
47
+ return done({ id: card });
48
+ const settings = settingsOf(ctx);
49
+ if (!settings.ok)
50
+ return settings.error;
51
+ const target = issueOf(settings.value, card);
52
+ if (!target.ok)
53
+ return target.error;
54
+ const written = await github(ctx, "PATCH", target.value.path, issue, {
55
+ assignees: previous === "" ? [] : [previous],
56
+ });
57
+ return written.ok ? done({ id: card }) : written.error;
58
+ }
59
+ /** `done` when the card already has the assignee that `assign` sets for `login`, else `skipped`: the lookup of a call that did not end. */
60
+ export async function findAssignee(ctx, card, login) {
61
+ const plan = await planned(ctx, card, login);
62
+ if (!plan.ok)
63
+ return plan.error;
64
+ return plan.value.current === plan.value.next ? done({ id: card }) : skipped();
65
+ }
@@ -0,0 +1,41 @@
1
+ import type { CardSpec } from "@kana-ai/edgar-contracts/rpc";
2
+ import { type Failure, type Outcome, type Result } from "@kana-ai/edgar-sdk";
3
+ import { z } from "zod";
4
+ import { foundIssues } from "#schemas/github";
5
+ import type { batchCardsTool, findCardsTool } from "#schemas/tools";
6
+ import { type GithubCtx, type Repo, type Settings, type TrackedCard } from "#tracker/states";
7
+ /** One page of the open issues of the table's repositories that are in scope and in the engine states `columns`, a repository after the other, with the cursor of the next page and the requests left. Pull requests are left out. A name that is not an engine state is `invalid`. A closed issue is never listed: the engine reads a card that a listing no longer has, and `card` answers `done` or `cancelled`. */
8
+ export declare function listCards(ctx: GithubCtx, input: {
9
+ readonly columns: readonly string[];
10
+ readonly cursor: string | null;
11
+ }): Promise<Outcome<{
12
+ cards: TrackedCard[];
13
+ next: string | null;
14
+ budget_remaining: number;
15
+ }>>;
16
+ /** The card `id`; a missing or deleted issue, a pull request and a key the table does not name are `not_found`, and a bad block `invalid`. An open issue out of the table's scope is `not_found` too, so the engine reads it as a card that left; a closed issue reads as `done` or `cancelled`. */
17
+ export declare function readCard(ctx: GithubCtx, id: string): Promise<Outcome<TrackedCard>>;
18
+ /** Forgets every remembered filing, for a test that starts cold. */
19
+ export declare function forgetFilings(): void;
20
+ /** An open issue the search API found, with its repository of the table. */
21
+ export interface Found {
22
+ readonly repo: Repo;
23
+ readonly item: z.infer<typeof foundIssues>["items"][number];
24
+ }
25
+ /** At most `max` open issues of the table's repositories that GitHub's search matches with `words`, the best match first; issues of other repositories are left out. */
26
+ export declare function searchOpen(ctx: GithubCtx, settings: Settings, words: string, max: number): Promise<Result<Found[], Failure>>;
27
+ /** Files an issue inside the table's scope, or returns the open issue that already holds the block's fingerprint, counting one more sighting on it. The issue goes to the repository of the block's service, else the first; it gets `title_prefix`, `labels` and the label of `spec.column`, and with `assignee_only`, `assignee`. A retry finds the issue its first call filed by the hidden marker of the operation among the newest 10 issues of the repository. Those 10 issues are also read for an open holder of the fingerprint that the search does not index yet, and calls with one fingerprint run one at a time in this process, so the second finds the issue the first filed. */
28
+ export declare function createCard(ctx: GithubCtx, spec: CardSpec): Promise<Outcome<{
29
+ id: string;
30
+ url: string;
31
+ }>>;
32
+ /** Counts one more sighting, at `seen` or now, of the fault that the card `card` holds, for a fault that a run found again without filing a card. */
33
+ export declare function countSightingOn(ctx: GithubCtx, card: string, seen: string | undefined): Promise<Outcome<{
34
+ id: string;
35
+ }>>;
36
+ /** At most 10 open issues of the table's repositories and scope that GitHub's search matches with the first 200 characters of `text`, without quotes or colons, the best match first. With `except`, that card and each issue made after it are left out, so two cards never point at each other; a missing `except` is `not_found`. */
37
+ export declare function findCards(ctx: GithubCtx, text: string, except?: string): Promise<Outcome<z.infer<typeof findCardsTool.output>>>;
38
+ /** At most 20 open issues of the table's repositories and scope whose block names `batch` in `decided.batch`, with `except` left out. With `ids`, only those, and the ids not found as `skipped`. An issue whose block does not read is left out. */
39
+ export declare function batchCards(ctx: GithubCtx, batch: string, except: string, ids?: readonly string[]): Promise<Outcome<z.infer<typeof batchCardsTool.output>>>;
40
+ /** The open issues in `intake` whose block waits for `card`, from the search API, read to be sure. */
41
+ export declare function waitingOn(ctx: GithubCtx, settings: Settings, card: string): Promise<Result<string[], Failure>>;