@kana-ai/edgar-ext-github 0.1.4 → 0.1.5

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.
package/README.md CHANGED
@@ -4,35 +4,35 @@ The GitHub extension of EDGAR. It pushes `edgar/` branches from the run's sandbo
4
4
 
5
5
  ## Tools
6
6
 
7
- | Tool | Input | Output | Notes |
8
- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9
- | `push_branch` | `repo`, and `branch` or `to` | `branch`, `commit` | Runs `git rev-parse` and `git push origin <branch>` in the sandbox, never forced. Refuses a branch outside `edgar/` or with `:`, `+` or `..`. Needs `git:push` and `sandbox:read`. |
10
- | `open_pull_request` | `repo`, `branch`, `title`, `body`, `review`; optional `base`, `card`, `labels`, `large_diff_lines`, `path_notices`, `checks`, `not_verified`, `proof`, `proof_passes`, `related` | `url`, `number` | Opens onto `base`, the service's default branch, or onto `default_base` when the call names none. The body ends with `edgar-operation: <operation id>`. Side effect, undone by `close_pull_request`, found by `find_pull_request`. See [Body notices and labels](#body-notices-and-labels). |
11
- | `close_pull_request` | `stage_output`: the output of `open_pull_request`; optional `text` | `url`, `state` | Closes without merging. A pull request that is merged or closed answers `skipped`, with no write. With `text`, the tool first adds it as one line of EDGAR's note, as `note_pull_request` does: the sweep gives the reason when a person closed the card of the pull request. |
12
- | `find_pull_request` | `operation_id`, `input`: the input of an `open_pull_request` call | `url`, `state` | `skipped` when the branch has no pull request. |
13
- | `linked_pull_requests` | `text`, `repo` | `pull_requests`: `url`, `state`, `title`, `body`, `files` (`path`, `patch`) | Reads each pull request of `repo` that `text` links, in any spelling of the repository: the first 5 links, 100 files each, and 4,000 characters of each patch. A link to another repository is left out with no call, so a card cannot bring code from elsewhere into the project's tracker. A link that answers 404 or 403 is left out. With no link to `repo`, the tool answers `skipped`, with no call. |
14
- | `note_pull_request` | `url`, `text`: one new item | `url`: the note | Adds an item to EDGAR's one note on the pull request, a comment that EDGAR finds by its hidden first line. The note's first sentence, "EDGAR's notes on this pull request, oldest first:", leads the list of items. The item keeps the lines of `text` under its bullet, so its paragraphs and lists stay. The first call makes the note. |
15
- | `update_pull_request` | `url`, `title`, `body`; optional `card`, `large_diff_lines`, `path_notices`, `checks`, `not_verified` | `url` | Gives an open pull request a new title and body, when a later change made them untrue. The body gets its notices and proof again, as `open_pull_request` writes them, and the operation line of this call. The review line of the first body is left out, because that review read the change before. A pull request that is merged or closed answers `skipped`, with no write. |
16
- | `attach_screenshot` | `url`; `shot`: `path`, `bytes` and `caption` of a PNG in the sandbox, with the `url` EDGAR serves it at when it is in `[storage]` and a flow's `video`, or `missing` | `attached`; `image` or `missing` | With a `url`, puts that address in the body and writes nothing to the repository. Otherwise stores the PNG on the branch `edgar/screenshots` of the pull request's repository, at `<run id>/preview-<hash>.png`, and puts it in the body pinned to the commit that holds it. The first picture of a repository starts that branch from an empty tree, so it shares no history with the code. A picture over 1 MB, one that cannot be read, or an upload that GitHub refuses gives the body one line, "The screenshot is missing:", with the reason, and the output says it too. A flow's `video` (`path`, `bytes`) goes to the same branch, at `<run id>/flow-<hash>.mp4`, as a link under the picture; a video over 1 MB or not stored gives the line "The video is missing:" with the reason, and the picture still shows. Only an input that is not a pull request fails. `update_pull_request` keeps the picture when it rewrites the body. |
17
- | `list_pull_requests` | `services`: a list of `repo`; optional `merged_within_hours` (1 to 720) | `pull_requests`: `url`, `branch`, `card`, `unmerged`; `complete` | One page of open pull requests per repository, read once however the services spell it (`git@github.com:o/r.git`, `https://github.com/o/r`, any letter case), on `edgar/<card>-<slug>` branches whose head is in that repository, so a fork's branch of that name is left out. With `merged_within_hours`, the pull requests merged within that many hours in place of the open ones, from one page of the 100 closed pull requests updated last. The engine passes the project's services. A service whose `repo` is not on github.com has none here, so `merge_watch` goes on for the others. With `merged_within_hours`, `unmerged` lists each pull request of the `Goes with:` line of the body that is not merged, as `url` and `state` (`open` or `closed`); one that answers 404 or 403 is `closed`. It is empty for the open ones and for a pull request that goes with none. `complete` is false when the page of a repository came back full, 100 pull requests, so one past them is not listed; the runtime log names that repository. |
18
- | `delete_closed_branches` | `services`: a list of `repo`; `closed_within_hours` (1 to 720) | `deleted`: `pull_request`, `branch` | Deletes the head branch of each pull request closed within that many hours, merged or not, from one page of the 100 closed pull requests updated last per repository. It deletes only an `edgar/<card>-<slug>` branch whose head is in that repository and that is not the base of its pull request, and only while the branch exists and no open pull request uses it, so `edgar/screenshots`, a fork's branch and a person's branch are never touched. A repository that deletes head branches on merge leaves those to GitHub, and a branch that a delete finds gone already (404 or 422) counts as done, with a log line. The built-in `merge_watch` calls it last, every 10 minutes, with `closed_within_hours = 24`. |
19
- | `pull_request_state` | `url` | `url`, `state`, `merged`, `review_state`, `approved_by`, `card`, `commit`, `branch`, `head_repo`, `mergeable`, `base_commit` | `review_state` comes from each reviewer's latest approval or change request. A change request made on a commit before the head is `pending` until its reviewer reviews again, whatever the others did, because a push answered it. `approved_by` lists the login of each reviewer whose latest one approves. `commit` is the merge commit once merged. `card` is `null` for a branch with no card. `branch` is the head branch and `head_repo` its repository as `owner/name`, a fork's for a fork, `null` when that repository was deleted. `mergeable` is `false` when the open pull request conflicts with its base branch, and `null` while GitHub computes it or once it is merged or closed. On a conflict, a third read gives `base_commit`, the newest commit of the base branch, to merge into the head. |
20
- | `wait_for_review` | `url` | as `pull_request_state` | The recheck of a `wait` stage for a review. This tool answers `skipped` while the pull request is open, no review has decided and it does not conflict with its base branch, and the output of `pull_request_state` once it is approved, has a change request, conflicts (`mergeable` is `false`), or is merged or closed. |
21
- | `wait_for_merge` | `url` | `url`, `merged`, `sha` | The recheck of a `wait` stage that ends on a merge or a close only. This tool answers `skipped` while the pull request is open, whatever its reviews say, `merged: true` with the merge commit as `sha` once it is merged, and `merged: false` with no `sha` once it is closed without a merge. |
22
- | `merge_pull_request` | `url`, `commit`, `changed_files` | `url`, `merged`, `commit` | Shipped turned off, approval `always`, no undo. Merges `commit` only, the head that `pull_request_state` gave and that the person approved; when the head has moved, GitHub merges nothing and the tool answers `invalid`. With `changed_files`, the call is EDGAR's own merge from a workflow stage: the engine runs it with no person when the count is under `[limits] self_merge_files`, and skips the stage at or past it. |
23
- | `merged_pull_request` | `repo`, `card` | `url`, `merged_at`, `commit` | The newest merged pull request of the card's `edgar/<card>-` branch, from the 100 closed pull requests updated last; a fork's is left out. `skipped` when there is none. |
24
- | `revert_pull_request` | `url` | `url`, `state` | Opens GitHub's revert of a merged pull request with GraphQL `revertPullRequest`, as a new pull request whose body says that a person merges it; no tool merges it. The revert already there, found by GitHub's branch name `revert-<number>-<branch>`, is answered instead of a second one. `skipped` when the pull request is not merged. Its undo is `close_pull_request`, its lookup `find_revert_pull_request`. A GraphQL error maps by its `type`: `NOT_FOUND` is `not_found`, `FORBIDDEN` `forbidden`, `UNPROCESSABLE` `invalid`, `RATE_LIMITED` a temporary `rate_limited`, and any other, or none, `tool_error`, with the type and message in `cause`. |
25
- | `find_revert_pull_request` | `operation_id`, `input`: the input of a `revert_pull_request` call | `url`, `state` | The lookup of `revert_pull_request`. `skipped` when there is no revert. |
26
- | `pull_request_checks` | `url` | `url`, `commit`, `state`, `merged`, `checks`, `failed`, `retry_after_seconds`, `summary`, `changed_files` | Reads the check runs and the commit statuses of the head commit, and `changed_files`, the files that the pull request changes. `state` is `failed` when one failed, else `pending` while one runs, else `passed`. A closed pull request, merged or not, is `closed` with no check read, `checks` 0 and `merged` from GitHub; `merged` is `false` while it is open. `failed` lists each failed check's `name` and details `url`. `retry_after_seconds` is 60 while pending, else `null`. `summary` is one sentence that a later stage posts as it is, such as `All 3 checks passed on 6dcb09b.`, `1 of 3 checks failed: test (<details url>).` or `2 checks still run.` See [Wait for CI](#wait-for-ci). |
27
- | `wait_for_checks` | `url` | as `pull_request_checks` | The recheck of a `wait` stage. A recheck that answers `done` ends the wait, so this tool answers `skipped` while a check runs, or while a pull request updated in the last 2 minutes has no check yet, and the output of `pull_request_checks` once every check has ended or the pull request is closed. |
28
- | `wait_for_passed_checks` | `url` | as `pull_request_checks` | The recheck of a `wait` stage that only passed checks end. It answers `skipped` while a check runs and also while a check has failed, so a later push or a rerun that passes ends the wait. A closed pull request ends it as `closed`. The built-in `remediate` uses it after its last repair: no review is asked for while a check is red. |
29
- | `ci_run` | `url` of a run, or of a job | `url`, `workflow`, `status`, `conclusion`, `commit`, `branch`, `attempt`, `jobs`, `logs`, `unread` | Reads a GitHub Actions run and each job of its latest attempt with its failed steps. For each failed job (`failure`, `timed_out`), at most 3, or for the job in a `/job/<id>` URL, it reads the log: the `##[error]` lines (at most 20) and an `excerpt` of the 120 lines up to the first error, at most 16,000 characters, with timestamps and colour codes removed. `gone` is `true` when GitHub no longer keeps the log. `unread` lists the failed jobs past the limit. |
30
- | `pull_request_discussion` | `url` | `url`, `reviews`, `threads`, `conversation`, `complete` | `reviews` holds each verdict, and each review with words; a wordless `COMMENTED` review is left out. `threads` holds each line comment with its `path`, `line`, the last 8 lines of its `hunk` and its `replies`. `conversation` holds the issue comments. EDGAR's own remarks stay, with `by`. A failed read is the failure, never an empty discussion. |
31
- | `dependabot_alerts` | `repo`; optional `number`, `state`, `package`, `ghsa`, `cve`, `limit` | `alerts`, `complete` | With `number`, that alert; the filters then must be empty, or `invalid_input`. Without it, newest first, every state unless `state` names some, at most `limit` (30, at most 100). Each alert has its `package`, `ecosystem`, `severity`, `vulnerable_range`, `first_patched`, `manifest`, `scope`, `ghsa`, `cve` and `summary`. `ghsa` and `cve` match within a page of 100. |
32
- | `branch_protection` | `repo`, `branch` | `branch`, `protected`, `pull_request_required`, `required_approvals`, `required_checks`, `rules`, `classic` | Joins the branch's own protection, each rule and ruleset that applies (`/rules/branches`), and the classic rule. GitHub shows the classic rule to admins only: `classic` is then `unreadable`, and `pull_request_required` and `required_approvals` are `null` unless a rule settles them. |
33
- | `dismiss_dependabot_alert` | `repo`, `number`, `reason`, `comment` | `repo`, `number`, `url`, `reason`, `reopen` | Approval `always`. Side effect, undone by `reopen_dependabot_alert`, found by `find_dependabot_dismissal`. `reason` is one of GitHub's reasons: `fix_started`, `inaccurate`, `no_bandwidth`, `not_used`, `tolerable_risk`. `comment` has 1 to 280 characters. See [Dismiss a Dependabot alert](#dismiss-a-dependabot-alert). |
34
- | `reopen_dependabot_alert` | `stage_output`: the output of `dismiss_dependabot_alert` | `repo`, `number`, `url`, `reopened` | The undo of `dismiss_dependabot_alert`. It opens the alert again when `reopen` is `true` and the alert is still dismissed. Otherwise it writes nothing and answers `reopened: false`. |
35
- | `find_dependabot_dismissal` | `operation_id`, `input`: the input of a `dismiss_dependabot_alert` call | as `dismiss_dependabot_alert` | The lookup of `dismiss_dependabot_alert`. `done` when the alert is dismissed with the `reason` and the `comment` of the call. `skipped` otherwise. |
7
+ | Tool | Input | Output | Notes |
8
+ | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9
+ | `push_branch` | `repo`, and `branch` or `to`; optional `suffix` | `branch`, `commit` | Runs `git rev-parse` and `git push origin <branch>` in the sandbox, never forced. With `to`, or with `branch` and `suffix`, it pushes the head of the sandbox to `to` or to `<branch>-<suffix>`, so one sandbox can open a second pull request, such as a companion. Refuses a branch outside `edgar/` or with `:`, `+` or `..`. Needs `git:push` and `sandbox:read`. |
10
+ | `open_pull_request` | `repo`, `branch`, `title`, `body`, `review`; optional `base`, `card`, `labels`, `large_diff_lines`, `path_notices`, `checks`, `not_verified`, `proof`, `proof_passes`, `related`, `after`, `first` | `url`, `number`, `commit` | Opens onto `base`, the service's default branch, or onto `default_base` when the call names none. The body ends with `edgar-operation: <operation id>`. With `after`, the URL of a companion pull request, the body names it on the `Goes with:` line and says to merge it first, because this one is built on it. With `first`, why the fix needs this companion, the body says to merge this one first. `commit` is the head commit of the pull request. Side effect, undone by `close_pull_request`, found by `find_pull_request`. See [Body notices and labels](#body-notices-and-labels). |
11
+ | `close_pull_request` | `stage_output`: the output of `open_pull_request`; optional `text` | `url`, `state` | Closes without merging. A pull request that is merged or closed answers `skipped`, with no write. With `text`, the tool first adds it as one line of EDGAR's note, as `note_pull_request` does: the sweep gives the reason when a person closed the card of the pull request. |
12
+ | `find_pull_request` | `operation_id`, `input`: the input of an `open_pull_request` call | `url`, `state` | `skipped` when the branch has no pull request. |
13
+ | `linked_pull_requests` | `text`, `repo` | `pull_requests`: `url`, `state`, `title`, `body`, `files` (`path`, `patch`) | Reads each pull request of `repo` that `text` links, in any spelling of the repository: the first 5 links, 100 files each, and 4,000 characters of each patch. A link to another repository is left out with no call, so a card cannot bring code from elsewhere into the project's tracker. A link that answers 404 or 403 is left out. With no link to `repo`, the tool answers `skipped`, with no call. |
14
+ | `note_pull_request` | `url`, `text`: one new item | `url`: the note | Adds an item to EDGAR's one note on the pull request, a comment that EDGAR finds by its hidden first line. The note's first sentence, "EDGAR's notes on this pull request, oldest first:", leads the list of items. The item keeps the lines of `text` under its bullet, so its paragraphs and lists stay. The first call makes the note. |
15
+ | `update_pull_request` | `url`, `title`, `body`; optional `card`, `large_diff_lines`, `path_notices`, `checks`, `not_verified` | `url` | Gives an open pull request a new title and body, when a later change made them untrue. The body gets its notices and proof again, as `open_pull_request` writes them, and the operation line of this call. The review line of the first body is left out, because that review read the change before. A pull request that is merged or closed answers `skipped`, with no write. |
16
+ | `attach_screenshot` | `url`; `shot`: `path`, `bytes` and `caption` of a PNG in the sandbox, with the `url` EDGAR serves it at when it is in `[storage]` and a flow's `video`, or `missing` | `attached`; `image` or `missing` | With a `url`, puts that address in the body and writes nothing to the repository. Otherwise stores the PNG on the branch `edgar/screenshots` of the pull request's repository, at `<run id>/preview-<hash>.png`, and puts it in the body pinned to the commit that holds it. The first picture of a repository starts that branch from an empty tree, so it shares no history with the code. A picture over 1 MB, one that cannot be read, or an upload that GitHub refuses gives the body one line, "The screenshot is missing:", with the reason, and the output says it too. A flow's `video` (`path`, `bytes`) goes to the same branch, at `<run id>/flow-<hash>.mp4`, as a link under the picture; a video over 1 MB or not stored gives the line "The video is missing:" with the reason, and the picture still shows. Only an input that is not a pull request fails. `update_pull_request` keeps the picture when it rewrites the body. |
17
+ | `list_pull_requests` | `services`: a list of `repo`; optional `merged_within_hours` (1 to 720), and with it `unless_noted` | `pull_requests`: `url`, `branch`, `card`, `unmerged`; `complete` | One page of open pull requests per repository, read once however the services spell it (`git@github.com:o/r.git`, `https://github.com/o/r`, any letter case), on `edgar/<card>-<slug>` branches whose head is in that repository, so a fork's branch of that name is left out. With `merged_within_hours`, the pull requests merged within that many hours in place of the open ones, from one page of the 100 closed pull requests updated last. With `unless_noted` too, each merged pull request whose EDGAR note already holds that text as one of its lines is left out, after one read of its comments, so `merge_watch` handles a merge once. The engine passes the project's services. A service whose `repo` is not on github.com has none here, so `merge_watch` goes on for the others. With `merged_within_hours`, `unmerged` lists each pull request of the `Goes with:` line of the body that is not merged, as `url` and `state` (`open` or `closed`); one that answers 404 or 403 is `closed`. It is empty for the open ones and for a pull request that goes with none. With `merged_within_hours`, a pull request whose body opens the companion line of `first` has `companion: true`, so `merge_watch` leaves its card for the fix built on it. `complete` is false when the page of a repository came back full, 100 pull requests, so one past them is not listed; the runtime log names that repository. |
18
+ | `delete_closed_branches` | `services`: a list of `repo`; `closed_within_hours` (1 to 720) | `deleted`: `pull_request`, `branch` | Deletes the head branch of each pull request closed within that many hours, merged or not, from one page of the 100 closed pull requests updated last per repository. It deletes only an `edgar/<card>-<slug>` branch whose head is in that repository and that is not the base of its pull request, and only while the branch exists and no open pull request uses it, so `edgar/screenshots`, a fork's branch and a person's branch are never touched. A repository that deletes head branches on merge leaves those to GitHub, and a branch that a delete finds gone already (404 or 422) counts as done, with a log line. The built-in `merge_watch` calls it last, every 10 minutes, with `closed_within_hours = 24`. |
19
+ | `pull_request_state` | `url` | `url`, `state`, `merged`, `review_state`, `approved_by`, `card`, `commit`, `branch`, `head_repo`, `mergeable`, `base_commit` | `review_state` comes from each reviewer's latest approval or change request. A change request made on a commit before the head is `pending` until its reviewer reviews again, whatever the others did, because a push answered it. `approved_by` lists the login of each reviewer whose latest one approves. `commit` is the merge commit once merged. `card` is `null` for a branch with no card. `branch` is the head branch and `head_repo` its repository as `owner/name`, a fork's for a fork, `null` when that repository was deleted. `mergeable` is `false` when the open pull request conflicts with its base branch, and `null` while GitHub computes it or once it is merged or closed. On a conflict, a third read gives `base_commit`, the newest commit of the base branch, to merge into the head. |
20
+ | `wait_for_review` | `url` | as `pull_request_state` | The recheck of a `wait` stage for a review. This tool answers `skipped` while the pull request is open, no review has decided and it does not conflict with its base branch, and the output of `pull_request_state` once it is approved, has a change request, conflicts (`mergeable` is `false`), or is merged or closed. |
21
+ | `wait_for_merge` | `url` | `url`, `merged`, `sha` | The recheck of a `wait` stage that ends on a merge or a close only. This tool answers `skipped` while the pull request is open, whatever its reviews say, `merged: true` with the merge commit as `sha` once it is merged, and `merged: false` with no `sha` once it is closed without a merge. |
22
+ | `merge_pull_request` | `url`, `commit`, `changed_files` | `url`, `merged`, `commit` | Shipped turned off, approval `always`, no undo. Merges `commit` only, the head that `pull_request_state` gave and that the person approved; when the head has moved, GitHub merges nothing and the tool answers `invalid`. With `changed_files`, the call is EDGAR's own merge from a workflow stage: the engine runs it with no person when the count is under `[limits] self_merge_files`, and skips the stage at or past it. |
23
+ | `merged_pull_request` | `repo`, `card` | `url`, `merged_at`, `commit` | The newest merged pull request of the card's `edgar/<card>-` branch, from the 100 closed pull requests updated last; a fork's is left out. `skipped` when there is none. |
24
+ | `revert_pull_request` | `url` | `url`, `state` | Opens GitHub's revert of a merged pull request with GraphQL `revertPullRequest`, as a new pull request whose body says that a person merges it; no tool merges it. The revert already there, found by GitHub's branch name `revert-<number>-<branch>`, is answered instead of a second one. `skipped` when the pull request is not merged. Its undo is `close_pull_request`, its lookup `find_revert_pull_request`. A GraphQL error maps by its `type`: `NOT_FOUND` is `not_found`, `FORBIDDEN` `forbidden`, `UNPROCESSABLE` `invalid`, `RATE_LIMITED` a temporary `rate_limited`, and any other, or none, `tool_error`, with the type and message in `cause`. |
25
+ | `find_revert_pull_request` | `operation_id`, `input`: the input of a `revert_pull_request` call | `url`, `state` | The lookup of `revert_pull_request`. `skipped` when there is no revert. |
26
+ | `pull_request_checks` | `url` | `url`, `commit`, `state`, `merged`, `checks`, `failed`, `retry_after_seconds`, `summary`, `changed_files` | Reads the check runs and the commit statuses of the head commit, and `changed_files`, the files that the pull request changes. `state` is `failed` when one failed, else `pending` while one runs, else `passed`. A closed pull request, merged or not, is `closed` with no check read, `checks` 0 and `merged` from GitHub; `merged` is `false` while it is open. `failed` lists each failed check's `name` and details `url`. `retry_after_seconds` is 60 while pending, else `null`. `summary` is one sentence that a later stage posts as it is, such as `All 3 checks passed on 6dcb09b.`, `1 of 3 checks failed: test (<details url>).` or `2 checks still run.` See [Wait for CI](#wait-for-ci). |
27
+ | `wait_for_checks` | `url` | as `pull_request_checks` | The recheck of a `wait` stage. A recheck that answers `done` ends the wait, so this tool answers `skipped` while a check runs, or while a pull request updated in the last 2 minutes has no check yet, and the output of `pull_request_checks` once every check has ended or the pull request is closed. |
28
+ | `wait_for_passed_checks` | `url` | as `pull_request_checks` | The recheck of a `wait` stage that only passed checks end. It answers `skipped` while a check runs and also while a check has failed, so a later push or a rerun that passes ends the wait. A closed pull request ends it as `closed`. The built-in `remediate` uses it after its last repair: no review is asked for while a check is red. |
29
+ | `ci_run` | `url` of a run, or of a job | `url`, `workflow`, `status`, `conclusion`, `commit`, `branch`, `attempt`, `jobs`, `logs`, `unread` | Reads a GitHub Actions run and each job of its latest attempt with its failed steps. For each failed job (`failure`, `timed_out`), at most 3, or for the job in a `/job/<id>` URL, it reads the log: the `##[error]` lines (at most 20) and an `excerpt` of the 120 lines up to the first error, at most 16,000 characters, with timestamps and colour codes removed. `gone` is `true` when GitHub no longer keeps the log. `unread` lists the failed jobs past the limit. |
30
+ | `pull_request_discussion` | `url` | `url`, `reviews`, `threads`, `conversation`, `complete` | `reviews` holds each verdict, and each review with words; a wordless `COMMENTED` review is left out. `threads` holds each line comment with its `path`, `line`, the last 8 lines of its `hunk` and its `replies`. `conversation` holds the issue comments. EDGAR's own remarks stay, with `by`. A failed read is the failure, never an empty discussion. |
31
+ | `dependabot_alerts` | `repo`; optional `number`, `state`, `package`, `ghsa`, `cve`, `limit` | `alerts`, `complete` | With `number`, that alert; the filters then must be empty, or `invalid_input`. Without it, newest first, every state unless `state` names some, at most `limit` (30, at most 100). Each alert has its `package`, `ecosystem`, `severity`, `vulnerable_range`, `first_patched`, `manifest`, `scope`, `ghsa`, `cve` and `summary`. `ghsa` and `cve` match within a page of 100. |
32
+ | `branch_protection` | `repo`, `branch` | `branch`, `protected`, `pull_request_required`, `required_approvals`, `required_checks`, `rules`, `classic` | Joins the branch's own protection, each rule and ruleset that applies (`/rules/branches`), and the classic rule. GitHub shows the classic rule to admins only: `classic` is then `unreadable`, and `pull_request_required` and `required_approvals` are `null` unless a rule settles them. |
33
+ | `dismiss_dependabot_alert` | `repo`, `number`, `reason`, `comment` | `repo`, `number`, `url`, `reason`, `reopen` | Approval `always`. Side effect, undone by `reopen_dependabot_alert`, found by `find_dependabot_dismissal`. `reason` is one of GitHub's reasons: `fix_started`, `inaccurate`, `no_bandwidth`, `not_used`, `tolerable_risk`. `comment` has 1 to 280 characters. See [Dismiss a Dependabot alert](#dismiss-a-dependabot-alert). |
34
+ | `reopen_dependabot_alert` | `stage_output`: the output of `dismiss_dependabot_alert` | `repo`, `number`, `url`, `reopened` | The undo of `dismiss_dependabot_alert`. It opens the alert again when `reopen` is `true` and the alert is still dismissed. Otherwise it writes nothing and answers `reopened: false`. |
35
+ | `find_dependabot_dismissal` | `operation_id`, `input`: the input of a `dismiss_dependabot_alert` call | as `dismiss_dependabot_alert` | The lookup of `dismiss_dependabot_alert`. `done` when the alert is dismissed with the `reason` and the `comment` of the call. `skipped` otherwise. |
36
36
 
37
37
  `repo` is `owner/name`, `git@github.com:owner/name.git` or `https://github.com/owner/name`.
38
38
 
@@ -38,9 +38,12 @@ export declare const tools: {
38
38
  } | undefined;
39
39
  proof_passes?: string | undefined;
40
40
  related?: string | string[] | undefined;
41
+ after?: string | undefined;
42
+ first?: string | undefined;
41
43
  }, {
42
44
  url: string;
43
45
  number: number;
46
+ commit?: string | undefined;
44
47
  }, "GITHUB_TOKEN">;
45
48
  update_pull_request: import("@kana-ai/edgar-sdk").Tool<{
46
49
  url: string;
@@ -135,6 +138,7 @@ export declare const tools: {
135
138
  repo: string;
136
139
  }[];
137
140
  merged_within_hours?: number | undefined;
141
+ unless_noted?: string | undefined;
138
142
  }, {
139
143
  pull_requests: {
140
144
  url: string;
@@ -144,6 +148,7 @@ export declare const tools: {
144
148
  url: string;
145
149
  state: "closed" | "open";
146
150
  }[];
151
+ companion?: true | undefined;
147
152
  }[];
148
153
  complete: boolean;
149
154
  }, "GITHUB_TOKEN">;
@@ -441,6 +446,8 @@ export declare const tools: {
441
446
  thread: string;
442
447
  };
443
448
  trust?: "outside" | "team";
449
+ requested_by?: string;
450
+ requested_by_id?: string;
444
451
  };
445
452
  };
446
453
  parent?: string;
@@ -563,6 +570,7 @@ export declare const tools: {
563
570
  repo: string;
564
571
  branch?: string | undefined;
565
572
  to?: string | undefined;
573
+ suffix?: string | undefined;
566
574
  }, {
567
575
  branch: string;
568
576
  commit: string;
@@ -17,6 +17,7 @@ export declare const pushBranch: {
17
17
  repo: z.ZodString;
18
18
  branch: z.ZodOptional<z.ZodString>;
19
19
  to: z.ZodOptional<z.ZodString>;
20
+ suffix: z.ZodOptional<z.ZodString>;
20
21
  }, z.core.$strip>;
21
22
  output: z.ZodObject<{
22
23
  branch: z.ZodString;
@@ -70,10 +71,13 @@ export declare const openPullRequest: {
70
71
  }, z.core.$strip>>;
71
72
  proof_passes: z.ZodOptional<z.ZodString>;
72
73
  related: z.ZodOptional<z.ZodUnion<readonly [z.ZodURL, z.ZodArray<z.ZodURL>]>>;
74
+ after: z.ZodOptional<z.ZodURL>;
75
+ first: z.ZodOptional<z.ZodString>;
73
76
  }, z.core.$strip>;
74
77
  output: z.ZodObject<{
75
78
  url: z.ZodString;
76
79
  number: z.ZodNumber;
80
+ commit: z.ZodOptional<z.ZodString>;
77
81
  }, z.core.$strip>;
78
82
  };
79
83
  /** The input and output of `close_pull_request`, which the engine calls with the output of the `open_pull_request` call that it undoes. The sweep adds `text`, the line that says why, when a person closed the card of the pull request. */
@@ -206,6 +210,7 @@ export declare const listPullRequests: {
206
210
  repo: z.ZodString;
207
211
  }, z.core.$strip>>;
208
212
  merged_within_hours: z.ZodOptional<z.ZodNumber>;
213
+ unless_noted: z.ZodOptional<z.ZodString>;
209
214
  }, z.core.$strip>;
210
215
  output: z.ZodObject<{
211
216
  pull_requests: z.ZodArray<z.ZodObject<{
@@ -219,6 +224,7 @@ export declare const listPullRequests: {
219
224
  open: "open";
220
225
  }>;
221
226
  }, z.core.$strip>>;
227
+ companion: z.ZodOptional<z.ZodLiteral<true>>;
222
228
  }, z.core.$strip>>;
223
229
  complete: z.ZodBoolean;
224
230
  }, z.core.$strip>;
@@ -570,6 +576,8 @@ export declare const createCardTool: {
570
576
  outside: "outside";
571
577
  team: "team";
572
578
  }>>;
579
+ requested_by: z.ZodExactOptional<z.ZodString>;
580
+ requested_by_id: z.ZodExactOptional<z.ZodString>;
573
581
  }, z.core.$strict>;
574
582
  }, z.core.$strict>;
575
583
  parent: z.ZodExactOptional<z.ZodString>;
@@ -21,6 +21,11 @@ export const pushBranch = {
21
21
  .min(1)
22
22
  .optional()
23
23
  .describe("the edgar/ branch on origin that gets the head of the sandbox: the branch of an open pull request"),
24
+ suffix: z
25
+ .string()
26
+ .regex(/^[a-z]+$/)
27
+ .optional()
28
+ .describe("with `branch`: the head of the sandbox goes to `<branch>-<suffix>` instead, so one sandbox opens a second pull request, such as a companion"),
24
29
  }),
25
30
  output: z.object({ branch: z.string(), commit: z.string() }),
26
31
  };
@@ -86,8 +91,20 @@ export const openPullRequest = {
86
91
  .union([httpsUrl, z.array(httpsUrl).max(5)])
87
92
  .optional()
88
93
  .describe("one URL, or at most 5, of the pull requests this one goes with, named after the body; each must be https, which the tool checks when it runs"),
94
+ after: httpsUrl
95
+ .optional()
96
+ .describe("the companion pull request that this one is built on: the body says to merge it first"),
97
+ first: z
98
+ .string()
99
+ .min(1)
100
+ .optional()
101
+ .describe("for a companion pull request: why the fix of the card needs it; the body says to merge this one first"),
102
+ }),
103
+ output: z.object({
104
+ url: z.string(),
105
+ number: z.number().int(),
106
+ commit: z.string().optional().describe("the head commit of the pull request"),
89
107
  }),
90
- output: z.object({ url: z.string(), number: z.number().int() }),
91
108
  };
92
109
  /** The input and output of `close_pull_request`, which the engine calls with the output of the `open_pull_request` call that it undoes. The sweep adds `text`, the line that says why, when a person closed the card of the pull request. */
93
110
  export const closePullRequest = {
@@ -166,6 +183,11 @@ export const listPullRequests = {
166
183
  .max(720)
167
184
  .optional()
168
185
  .describe("with it, the pull requests merged within this many hours, in place of the open ones"),
186
+ unless_noted: z
187
+ .string()
188
+ .min(1)
189
+ .optional()
190
+ .describe("with merged_within_hours, leaves out each merged pull request whose EDGAR note already holds this text as one of its lines, so a merge that was handled is not listed again"),
169
191
  }),
170
192
  output: z.object({
171
193
  pull_requests: z.array(z.object({
@@ -175,6 +197,10 @@ export const listPullRequests = {
175
197
  unmerged: z
176
198
  .array(z.object({ url: z.string(), state: z.enum(["open", "closed"]) }))
177
199
  .describe("with merged_within_hours, the pull requests of its `Goes with:` line that are not merged; empty otherwise"),
200
+ companion: z
201
+ .literal(true)
202
+ .optional()
203
+ .describe("with merged_within_hours, a companion pull request: the fix of its card is built on it and moves the card when it merges"),
178
204
  })),
179
205
  complete: z
180
206
  .boolean()
@@ -1,8 +1,9 @@
1
- /** Pushes through the sandbox's git, never forced. With `to`, the head of the sandbox goes to that `edgar/` branch of origin, the branch of an open pull request: what the checks ran on is what is pushed, whatever a role named its own branch. With `branch` alone, that `edgar/` branch goes to origin under its own name. */
1
+ /** Pushes through the sandbox's git, never forced. With `to`, the head of the sandbox goes to that `edgar/` branch of origin, the branch of an open pull request: what the checks ran on is what is pushed, whatever a role named its own branch. With `branch` and `suffix`, the head goes to `<branch>-<suffix>`, a second pull request of the same sandbox. With `branch` alone, that `edgar/` branch goes to origin under its own name. */
2
2
  export declare const pushBranch: import("@kana-ai/edgar-sdk").Tool<{
3
3
  repo: string;
4
4
  branch?: string | undefined;
5
5
  to?: string | undefined;
6
+ suffix?: string | undefined;
6
7
  }, {
7
8
  branch: string;
8
9
  commit: string;
@@ -18,14 +18,15 @@ async function git(ctx, args) {
18
18
  }
19
19
  return ok(ran.value.stdout.trim());
20
20
  }
21
- /** Pushes through the sandbox's git, never forced. With `to`, the head of the sandbox goes to that `edgar/` branch of origin, the branch of an open pull request: what the checks ran on is what is pushed, whatever a role named its own branch. With `branch` alone, that `edgar/` branch goes to origin under its own name. */
21
+ /** Pushes through the sandbox's git, never forced. With `to`, the head of the sandbox goes to that `edgar/` branch of origin, the branch of an open pull request: what the checks ran on is what is pushed, whatever a role named its own branch. With `branch` and `suffix`, the head goes to `<branch>-<suffix>`, a second pull request of the same sandbox. With `branch` alone, that `edgar/` branch goes to origin under its own name. */
22
22
  export const pushBranch = defineTool({
23
23
  description: "Push to origin through the sandbox, never forced: with `to`, the head of the sandbox to that edgar/ branch; with `branch` alone, that edgar/ branch under its own name",
24
24
  input: schema.input,
25
25
  output: schema.output,
26
26
  capabilities: ["git:push", "sandbox:read"],
27
- execute: async ({ branch, to }, ctx) => {
28
- const target = to ?? branch;
27
+ execute: async ({ branch, to, suffix }, ctx) => {
28
+ const target = to ?? (branch !== undefined && suffix !== undefined ? `${branch}-${suffix}` : branch);
29
+ const head = to !== undefined || suffix !== undefined;
29
30
  if (target === undefined) {
30
31
  return permanentFailure("invalid_input", "push_branch needs `branch` or `to`");
31
32
  }
@@ -36,15 +37,11 @@ export const pushBranch = defineTool({
36
37
  const commit = await git(ctx, [
37
38
  "rev-parse",
38
39
  "--verify",
39
- to === undefined ? `refs/heads/${target}` : "HEAD",
40
+ head ? "HEAD" : `refs/heads/${target}`,
40
41
  ]);
41
42
  if (!commit.ok)
42
43
  return commit.error;
43
- const pushed = await git(ctx, [
44
- "push",
45
- "origin",
46
- to === undefined ? target : `HEAD:refs/heads/${to}`,
47
- ]);
44
+ const pushed = await git(ctx, ["push", "origin", head ? `HEAD:refs/heads/${target}` : target]);
48
45
  if (!pushed.ok)
49
46
  return pushed.error;
50
47
  return done({ branch: target, commit: commit.value });
@@ -80,7 +80,7 @@ export function summaryOf(checks, commit) {
80
80
  ? `The 1 check passed on ${short}.`
81
81
  : `All ${String(total)} checks passed on ${short}.`;
82
82
  }
83
- /** Reads the head commit of the pull request at `url` and the files it changes, then its check runs and statuses, and judges them. A closed or merged pull request is `closed` with no check read, so no wait goes on for it. With `now`, a pull request with no check that was updated less than `FIRST_CHECK_GRACE_SECONDS` before it is `skipped`. */
83
+ /** Reads the head commit of the pull request at `url` and the files it changes, then its check runs and statuses, and judges them; when the token may not read statuses, it judges the check runs alone and says so. A closed or merged pull request is `closed` with no check read, so no wait goes on for it. With `now`, a pull request with no check that was updated less than `FIRST_CHECK_GRACE_SECONDS` before it is `skipped`. */
84
84
  async function checksOfPull(ctx, url, now) {
85
85
  const path = pullOf(url);
86
86
  if (!path.ok)
@@ -110,9 +110,11 @@ async function checksOfPull(ctx, url, now) {
110
110
  if (!runs.ok)
111
111
  return runs.error;
112
112
  const status = await github(ctx, "GET", `${repo}/commits/${commit}/status?per_page=100`, combinedStatus);
113
- if (!status.ok)
113
+ // A GitHub App installation without commit statuses still reports Actions as check runs: judge on those.
114
+ const unread = !status.ok && status.error.kind === "forbidden";
115
+ if (!status.ok && !unread)
114
116
  return status.error;
115
- const checks = checksOf(runs.value, status.value);
117
+ const checks = checksOf(runs.value, status.ok ? status.value : { statuses: [] });
116
118
  const sinceUpdate = (now ?? Infinity) - Date.parse(read.value.updated_at);
117
119
  if (checks.length === 0 && sinceUpdate < FIRST_CHECK_GRACE_SECONDS * 1000)
118
120
  return skipped();
@@ -125,7 +127,9 @@ async function checksOfPull(ctx, url, now) {
125
127
  checks: checks.length,
126
128
  failed: checks.filter((c) => c.state === "failed").map(({ name, url }) => ({ name, url })),
127
129
  retry_after_seconds: state === "pending" ? RECHECK_SECONDS : null,
128
- summary: summaryOf(checks, commit),
130
+ summary: unread
131
+ ? `${summaryOf(checks, commit)} I may not read the commit statuses of this repository, so only its check runs count.`
132
+ : summaryOf(checks, commit),
129
133
  changed_files: read.value.changed_files,
130
134
  });
131
135
  }
@@ -76,9 +76,12 @@ export declare const pullRequestTools: {
76
76
  } | undefined;
77
77
  proof_passes?: string | undefined;
78
78
  related?: string | string[] | undefined;
79
+ after?: string | undefined;
80
+ first?: string | undefined;
79
81
  }, {
80
82
  url: string;
81
83
  number: number;
84
+ commit?: string | undefined;
82
85
  }, "GITHUB_TOKEN">;
83
86
  /** The review line of the first body is left out: that review read the change before this one. The notices compare the change with the pull request's own base. */
84
87
  update_pull_request: import("@kana-ai/edgar-sdk").Tool<{
@@ -172,12 +175,13 @@ export declare const pullRequestTools: {
172
175
  url: string;
173
176
  state: "closed" | "merged" | "open";
174
177
  }, "GITHUB_TOKEN">;
175
- /** A pull request whose head is in another repository, such as a fork, is left out: its branch name proves nothing. shortcut: one page of 100 per repository, so with `merged_within_hours` a merge past the 100 closed pull requests updated last is not read; a full page sets `complete` to false and logs the repository; upgrade to `Link` pagination when a repository closes more within the window. */
178
+ /** A pull request whose head is in another repository, such as a fork, is left out: its branch name proves nothing. shortcut: one page of 100 per repository, so with `merged_within_hours` a merge past the 100 closed pull requests updated last is not read; a full page sets `complete` to false and logs the repository; upgrade to `Link` pagination when a repository closes more within the window. With `unless_noted`, each merged pull request costs one read of its comments, so one that EDGAR's note already says was handled costs nothing more, here or in the tracker. */
176
179
  list_pull_requests: import("@kana-ai/edgar-sdk").Tool<{
177
180
  services: {
178
181
  repo: string;
179
182
  }[];
180
183
  merged_within_hours?: number | undefined;
184
+ unless_noted?: string | undefined;
181
185
  }, {
182
186
  pull_requests: {
183
187
  url: string;
@@ -187,6 +191,7 @@ export declare const pullRequestTools: {
187
191
  url: string;
188
192
  state: "closed" | "open";
189
193
  }[];
194
+ companion?: true | undefined;
190
195
  }[];
191
196
  complete: boolean;
192
197
  }, "GITHUB_TOKEN">;
@@ -252,25 +252,52 @@ async function labelled(ctx, repo, made, labels) {
252
252
  if (!added.ok)
253
253
  ctx.log(`labels not added to ${made.html_url}: ${added.error.message}`);
254
254
  }
255
- return done({ url: made.html_url, number: made.number });
255
+ return done({ url: made.html_url, number: made.number, commit: made.head.sha });
256
256
  }
257
+ /** The line that opens the body of a companion pull request, which the fix of its card is built on. */
258
+ const COMPANION_LEAD = "Merge this pull request first:";
257
259
  /** The most pull requests that one read of a list gives. */
258
260
  const PAGE = 100;
259
261
  /** The first line of EDGAR's note on a pull request, which GitHub does not show, and the sentence under it that leads its list. */
260
262
  const NOTE_MARK = "<!-- edgar:note -->";
261
263
  const NOTE_LEAD = "EDGAR's notes on this pull request, oldest first:";
262
- /** Adds `text` as one item of EDGAR's one note on the pull request at the API `path`: the comment that starts with the note's mark, made when there is none. The item keeps the lines of `text`, indented under its bullet, so its paragraphs and lists stay. An item that is already the last one writes nothing. */
263
- async function noted(ctx, path, text) {
264
- const comments = `${path.replace("/pulls/", "/issues/")}/comments`;
264
+ /** The API path of the comments of the pull request at the API `path`. */
265
+ function commentsOf(path) {
266
+ return `${path.replace("/pulls/", "/issues/")}/comments`;
267
+ }
268
+ /** `text` as one item of EDGAR's note: a bullet, with its other lines indented under it. */
269
+ function itemOf(text) {
265
270
  const [first = "", ...rest] = text
266
271
  .trim()
267
272
  .split(/\r?\n/)
268
273
  .map((part) => part.trimEnd());
269
- const line = [`- ${first}`, ...rest.map((part) => (part === "" ? "" : ` ${part}`))].join("\n");
274
+ return [`- ${first}`, ...rest.map((part) => (part === "" ? "" : ` ${part}`))].join("\n");
275
+ }
276
+ /** EDGAR's note among the comments at the API path `comments`, the one that starts with the note's mark; none when there is none. */
277
+ async function noteOf(ctx, comments) {
270
278
  const read = await github(ctx, "GET", `${comments}?per_page=100`, z.array(note));
279
+ if (!read.ok)
280
+ return read;
281
+ return ok(read.value.find((comment) => comment.body?.startsWith(NOTE_MARK) === true));
282
+ }
283
+ /** Whether EDGAR's note on the pull request at `url` holds `text` as one of its items, anywhere in the note. */
284
+ async function hasNoted(ctx, url, text) {
285
+ const path = pullOf(url);
286
+ if (!path.ok)
287
+ return path;
288
+ const read = await noteOf(ctx, commentsOf(path.value));
289
+ if (!read.ok)
290
+ return read;
291
+ return ok(`${read.value?.body ?? ""}\n`.includes(`\n${itemOf(text)}\n`));
292
+ }
293
+ /** Adds `text` as one item of EDGAR's one note on the pull request at the API `path`: the comment that starts with the note's mark, made when there is none. The item keeps the lines of `text`, indented under its bullet, so its paragraphs and lists stay. An item that is already the last one writes nothing. */
294
+ async function noted(ctx, path, text) {
295
+ const comments = commentsOf(path);
296
+ const line = itemOf(text);
297
+ const read = await noteOf(ctx, comments);
271
298
  if (!read.ok)
272
299
  return read.error;
273
- const kept = read.value.find((comment) => comment.body?.startsWith(NOTE_MARK) === true);
300
+ const kept = read.value;
274
301
  if (kept === undefined) {
275
302
  const made = await github(ctx, "POST", comments, note, {
276
303
  body: `${NOTE_MARK}\n${NOTE_LEAD}\n\n${line}`,
@@ -308,8 +335,15 @@ export const pullRequestTools = {
308
335
  return repo.error;
309
336
  const base = input.base ?? settings.data.default_base;
310
337
  const notes = await noticesOf(ctx, repo.value, base, input);
311
- const related = typeof input.related === "string" ? [input.related] : (input.related ?? []);
312
- const body = bodyOf(cardLine(input.card), input.body, related.length === 0 ? "" : `Goes with: ${related.join(", ")}`, ...notes, ...proofOf(input.checks, input.not_verified), ...ownProofOf(input.proof, input.proof_passes), input.review === ""
338
+ const related = [
339
+ ...(typeof input.related === "string" ? [input.related] : (input.related ?? [])),
340
+ ...(input.after === undefined ? [] : [input.after]),
341
+ ];
342
+ const body = bodyOf(cardLine(input.card), input.body, related.length === 0 ? "" : `Goes with: ${related.join(", ")}`, input.after === undefined
343
+ ? ""
344
+ : `Merge ${input.after} first. This pull request is built on it, so its checks ran with that change, and its diff shows that change until it merges.`, input.first === undefined
345
+ ? ""
346
+ : `${COMPANION_LEAD} the fix of the card is built on it, and EDGAR's note below links the fix. Why the fix needs it: ${input.first}`, ...notes, ...proofOf(input.checks, input.not_verified), ...ownProofOf(input.proof, input.proof_passes), input.review === ""
313
347
  ? ""
314
348
  : `Before I opened this, a second model reviewed the change. ${input.review}`, `edgar-operation: ${ctx.operation_id}`);
315
349
  const labels = [...new Set([...settings.data.pr_labels, ...(input.labels ?? [])])];
@@ -500,13 +534,13 @@ export const pullRequestTools = {
500
534
  return first === undefined ? skipped() : done({ url: first.html_url, state: stateOf(first) });
501
535
  },
502
536
  }),
503
- /** A pull request whose head is in another repository, such as a fork, is left out: its branch name proves nothing. shortcut: one page of 100 per repository, so with `merged_within_hours` a merge past the 100 closed pull requests updated last is not read; a full page sets `complete` to false and logs the repository; upgrade to `Link` pagination when a repository closes more within the window. */
537
+ /** A pull request whose head is in another repository, such as a fork, is left out: its branch name proves nothing. shortcut: one page of 100 per repository, so with `merged_within_hours` a merge past the 100 closed pull requests updated last is not read; a full page sets `complete` to false and logs the repository; upgrade to `Link` pagination when a repository closes more within the window. With `unless_noted`, each merged pull request costs one read of its comments, so one that EDGAR's note already says was handled costs nothing more, here or in the tracker. */
504
538
  list_pull_requests: defineTool({
505
539
  description: "List the open pull requests on edgar/ branches of each service's repository on github.com, or with merged_within_hours the ones merged within that many hours; a service elsewhere has none here",
506
540
  input: listPullRequests.input,
507
541
  output: listPullRequests.output,
508
542
  ...apiAccess,
509
- execute: async ({ services, merged_within_hours }, ctx) => {
543
+ execute: async ({ services, merged_within_hours, unless_noted }, ctx) => {
510
544
  const repos = new Set();
511
545
  for (const service of services) {
512
546
  const repo = repoPath(service.repo);
@@ -535,14 +569,23 @@ export const pullRequestTools = {
535
569
  const kept = since === undefined || (p.merged_at !== null && Date.parse(p.merged_at) >= since);
536
570
  if (card === null || !own || !kept)
537
571
  continue;
572
+ if (since !== undefined && unless_noted !== undefined) {
573
+ const already = await hasNoted(ctx, p.html_url, unless_noted);
574
+ if (!already.ok)
575
+ return already.error;
576
+ if (already.value)
577
+ continue;
578
+ }
538
579
  const unmerged = since === undefined ? ok([]) : await unmergedOf(ctx, p.body);
539
580
  if (!unmerged.ok)
540
581
  return unmerged.error;
582
+ const companion = since !== undefined && (p.body ?? "").includes(`\n${COMPANION_LEAD} `);
541
583
  pull_requests.push({
542
584
  url: p.html_url,
543
585
  branch: p.head.ref,
544
586
  card,
545
587
  unmerged: unmerged.value,
588
+ ...(companion ? { companion } : {}),
546
589
  });
547
590
  }
548
591
  }
@@ -67,7 +67,7 @@ export declare function trustOf(written: {
67
67
  }, own: ReadonlySet<string>): Trust;
68
68
  /** True when the issue is a card EDGAR still holds: closed, or open and in the table's scope. */
69
69
  export declare function isHeld(settings: Settings, found: Issue, assignee: string | undefined): boolean;
70
- /** 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 carried as why, for the engine to refuse. `taken_by` is its first assignee that is a person: not a login of `own`, and not a bot; `taken_by_id` is the same login, which names one account at a time. `priority` is the one a `priority:urgent` or `priority:high` label gives, `trust` is its writer's by {@link trustOf}, and `written_by_id` is the writer's login. */
70
+ /** 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 carried as why, for the engine to refuse. `taken_by` is its first assignee that is a person: not a login of `own`, and not a bot; `taken_by_id` is the same login, which names one account at a time. `priority` is the one a `priority:urgent` or `priority:high` label gives, `trust` is its writer's by {@link trustOf}, and `written_by_id` is the writer's login. `requested_by` is the writer too when they are a person, since GitHub names who assigned an issue only in its events, which a page of issues does not carry. */
71
71
  export declare function toCard(settings: Settings, repo: Repo, found: Issue, strict: boolean, own: ReadonlySet<string>): Result<TrackedCard, Failure>;
72
72
  /** EDGAR's own logins: the one it works as, and `[extensions.github.tracker] assignee`. An App with no `assignee` has none, since its `[bot]` login is never a person. */
73
73
  export declare function ownLogins(ctx: GithubCtx, settings: Settings): Promise<Result<ReadonlySet<string>, Failure>>;
@@ -107,7 +107,7 @@ export function trustOf(written, own) {
107
107
  export function isHeld(settings, found, assignee) {
108
108
  return found.state === "closed" || inScope(settings, found, assignee);
109
109
  }
110
- /** 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 carried as why, for the engine to refuse. `taken_by` is its first assignee that is a person: not a login of `own`, and not a bot; `taken_by_id` is the same login, which names one account at a time. `priority` is the one a `priority:urgent` or `priority:high` label gives, `trust` is its writer's by {@link trustOf}, and `written_by_id` is the writer's login. */
110
+ /** 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 carried as why, for the engine to refuse. `taken_by` is its first assignee that is a person: not a login of `own`, and not a bot; `taken_by_id` is the same login, which names one account at a time. `priority` is the one a `priority:urgent` or `priority:high` label gives, `trust` is its writer's by {@link trustOf}, and `written_by_id` is the writer's login. `requested_by` is the writer too when they are a person, since GitHub names who assigned an issue only in its events, which a page of issues does not carry. */
111
111
  export function toCard(settings, repo, found, strict, own) {
112
112
  const description = found.body ?? "";
113
113
  const block = readBlock(description);
@@ -118,6 +118,8 @@ export function toCard(settings, repo, found, strict, own) {
118
118
  const taken = found.assignees?.find((person) => !own.has(person.login) && !person.login.endsWith("[bot]"))?.login;
119
119
  const names = labelNames(found);
120
120
  const priority = priorities.find(([label]) => names.includes(label))?.[1];
121
+ const writer = found.user?.login;
122
+ const asked = writer === undefined || own.has(writer) || writer.endsWith("[bot]") ? undefined : writer;
121
123
  return ok({
122
124
  id: cardId(repo, found.number),
123
125
  title: found.title,
@@ -133,6 +135,7 @@ export function toCard(settings, repo, found, strict, own) {
133
135
  ...(priority === undefined ? {} : { priority }),
134
136
  trust: trustOf(found, own),
135
137
  ...(found.user?.login === undefined ? {} : { written_by_id: found.user.login }),
138
+ ...(asked === undefined ? {} : { requested_by: asked, requested_by_id: asked }),
136
139
  });
137
140
  }
138
141
  /** The logins found so far, by the token that signs in, kept for the life of the process. */
@@ -44,6 +44,8 @@ export declare const trackerTools: {
44
44
  thread: string;
45
45
  };
46
46
  trust?: "outside" | "team";
47
+ requested_by?: string;
48
+ requested_by_id?: string;
47
49
  };
48
50
  };
49
51
  parent?: string;
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "contract": 1,
3
3
  "name": "github",
4
- "version": "0.1.4",
4
+ "version": "0.1.5",
5
5
  "config_schema": "schemas/config.json",
6
6
  "secrets": [
7
7
  {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kana-ai/edgar-ext-github",
3
- "version": "0.1.4",
3
+ "version": "0.1.5",
4
4
  "description": "EDGAR extension for GitHub: push edgar/ branches, open, watch, close and merge pull requests, and track GitHub issues as cards.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -23,8 +23,8 @@
23
23
  ".": "./dist/src/index.js"
24
24
  },
25
25
  "dependencies": {
26
- "@kana-ai/edgar-contracts": "0.1.4",
27
- "@kana-ai/edgar-sdk": "0.1.4",
26
+ "@kana-ai/edgar-contracts": "0.1.5",
27
+ "@kana-ai/edgar-sdk": "0.1.5",
28
28
  "zod": "4.6.7"
29
29
  },
30
30
  "devDependencies": {
@@ -94,6 +94,14 @@
94
94
  "trust": {
95
95
  "type": "string",
96
96
  "enum": ["team", "outside"]
97
+ },
98
+ "requested_by": {
99
+ "type": "string",
100
+ "minLength": 1
101
+ },
102
+ "requested_by_id": {
103
+ "type": "string",
104
+ "minLength": 1
97
105
  }
98
106
  },
99
107
  "required": ["kind"],
@@ -20,6 +20,11 @@
20
20
  "type": "integer",
21
21
  "minimum": 1,
22
22
  "maximum": 720
23
+ },
24
+ "unless_noted": {
25
+ "description": "with merged_within_hours, leaves out each merged pull request whose EDGAR note already holds this text as one of its lines, so a merge that was handled is not listed again",
26
+ "type": "string",
27
+ "minLength": 1
23
28
  }
24
29
  },
25
30
  "required": ["services"]
@@ -32,6 +32,11 @@
32
32
  "required": ["url", "state"]
33
33
  },
34
34
  "description": "with merged_within_hours, the pull requests of its `Goes with:` line that are not merged; empty otherwise"
35
+ },
36
+ "companion": {
37
+ "description": "with merged_within_hours, a companion pull request: the fix of its card is built on it and moves the card when it merges",
38
+ "type": "boolean",
39
+ "const": true
35
40
  }
36
41
  },
37
42
  "required": ["url", "branch", "card", "unmerged"]
@@ -179,6 +179,16 @@
179
179
  }
180
180
  }
181
181
  ]
182
+ },
183
+ "after": {
184
+ "description": "the companion pull request that this one is built on: the body says to merge it first",
185
+ "type": "string",
186
+ "format": "uri"
187
+ },
188
+ "first": {
189
+ "description": "for a companion pull request: why the fix of the card needs it; the body says to merge this one first",
190
+ "type": "string",
191
+ "minLength": 1
182
192
  }
183
193
  },
184
194
  "required": ["repo", "branch", "title", "body", "review"]
@@ -9,6 +9,10 @@
9
9
  "type": "integer",
10
10
  "minimum": -9007199254740991,
11
11
  "maximum": 9007199254740991
12
+ },
13
+ "commit": {
14
+ "description": "the head commit of the pull request",
15
+ "type": "string"
12
16
  }
13
17
  },
14
18
  "required": ["url", "number"]
@@ -15,6 +15,11 @@
15
15
  "description": "the edgar/ branch on origin that gets the head of the sandbox: the branch of an open pull request",
16
16
  "type": "string",
17
17
  "minLength": 1
18
+ },
19
+ "suffix": {
20
+ "description": "with `branch`: the head of the sandbox goes to `<branch>-<suffix>` instead, so one sandbox opens a second pull request, such as a companion",
21
+ "type": "string",
22
+ "pattern": "^[a-z]+$"
18
23
  }
19
24
  },
20
25
  "required": ["repo"]