@kana-ai/edgar-ext-linear 0.1.2 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +42 -29
- package/dist/src/index.d.ts +1 -1
- package/dist/src/index.js +15 -1
- package/dist/src/schemas/config.js +33 -17
- package/dist/src/schemas/linear.d.ts +41 -3
- package/dist/src/schemas/linear.js +20 -4
- package/dist/src/schemas/tools.d.ts +60 -1
- package/dist/src/schemas/tools.js +41 -2
- package/dist/src/tracker/cards.d.ts +6 -2
- package/dist/src/tracker/cards.js +90 -15
- package/dist/src/tracker/comments.d.ts +11 -3
- package/dist/src/tracker/comments.js +91 -14
- package/dist/src/tracker/port.js +2 -1
- package/dist/src/tracker/read-link.d.ts +2 -0
- package/dist/src/tracker/read-link.js +22 -0
- package/dist/src/tracker/states.d.ts +23 -0
- package/dist/src/tracker/states.js +14 -0
- package/dist/src/tracker/tools.d.ts +27 -0
- package/dist/src/tracker/tools.js +68 -8
- package/dist/src/tracker/transitions.d.ts +8 -3
- package/dist/src/tracker/transitions.js +34 -7
- package/edgar-extension.json +72 -4
- package/package.json +3 -3
- package/schemas/config.json +26 -13
- package/schemas/create_card.in.json +4 -0
- package/schemas/mark_seen.in.json +11 -0
- package/schemas/mark_seen.out.json +10 -0
- package/schemas/park.in.json +15 -0
- package/schemas/park.out.json +10 -0
- package/schemas/release_follow_ups.in.json +5 -0
- package/schemas/retitle.in.json +16 -0
- package/schemas/retitle.out.json +13 -0
- package/schemas/set_priority.in.json +16 -0
- package/schemas/set_priority.out.json +10 -0
package/README.md
CHANGED
|
@@ -4,27 +4,31 @@ The Linear extension of EDGAR. It implements the engine's tracker port over Line
|
|
|
4
4
|
|
|
5
5
|
## Tracker port
|
|
6
6
|
|
|
7
|
-
All
|
|
7
|
+
All 12 methods: `list_cards`, `card`, `comments`, `mentions`, `attachments`, `comment`, `move`, `set_labels`, `create_card`, `close`, `whoami` and `person`. `mentions` reads at most 50 comments, on any card the token can read, made after `since` whose text holds `@` and the display name of the token's user, oldest first. A card's `id` is its Linear identifier, such as `ENG-12`, and its `column` is the engine state its Linear column maps to. Its `assignee` is the Linear `displayName` of the person the issue is assigned to, and a card with no assignee has no `assignee`. Its `taken_by` is the same name when the assignee is not one of EDGAR's own users (the user of `LINEAR_TOKEN`, which `list_cards` and `card` ask as `viewer` in the same request, and `assignee`), so the engine knows when a person holds the card. Its `taken_by_id` is that person's email, which only their own account can change: `[people.<name>] ids.linear` matches it to find the person's saved keys, while a display name, which any member can set, never does. The email goes into no comment, note or prompt. Its `trust` is `team` when the issue's creator is a member of the workspace (Linear's `guest` is false) or one of EDGAR's own users, and `outside` for a guest or for an issue an integration made for someone with no Linear account. A comment's `trust` follows the same rule for its writer: a comment that an integration brings in, with a `botActor` and no `user`, is `outside`. Its `priority` is `urgent` for Linear's Urgent and `high` for High, absent for Medium, Low and No priority, and the engine starts the queued runs of those cards first. EDGAR writes a Linear priority only with `set_priority`, from the analysis (`urgent` 1, `high` 2, `medium` 3, `low` 4), and only on an issue with No priority: one that a person set stays. The display name is the name Linear shows and a person writes after `@`, so a note or a prompt can name the person; an email would put an address that a person never reads into each agent's input and each Slack note. `list_cards` takes engine states in `columns`, the way the engine's sweep sends them, asks Linear for the columns `[extensions.linear.columns]` maps them to, and answers each card with its engine state. A name that is not an engine state, such as `Todo`, makes `list_cards` answer `invalid` with that name in `cause`, before any request. For example, with `ready = "Todo"`, the request `{"columns": ["intake", "ready"], "cursor": null}` asks Linear for `Triage` and `Todo`, and a card in `Todo` comes back with `"column": "ready"`. `list_cards` reads 50 cards a page and reports `budget_remaining` from `X-RateLimit-Requests-Remaining`. `comments` sets `mentioned` when the body holds `@` and the display name of the `whoami` actor. It asks for the comments updated after `since`, archived ones included, so an edit or a delete is read too: `edited_at` is the comment's `editedAt`, or its `archivedAt` for a deleted comment, which also has `deleted: true`. `attachments` lists the issue's attachments, then each file a person uploaded into a live comment, a Markdown link or image to `uploads.linear.app`, once by url and named by its link text, so the engine fetches it with the attachments, under the same byte caps, once `[tracker] attachment_hosts` holds `uploads.linear.app`.
|
|
8
8
|
|
|
9
9
|
## Tools
|
|
10
10
|
|
|
11
|
-
| Tool | Input | Output | Notes
|
|
12
|
-
| --------------------- | --------------------------------- | ---------------------- |
|
|
13
|
-
| `comment` | `card`, `text`, `link` (optional) | `id` | The link goes on its own line.
|
|
14
|
-
| `move` | `card`, `column` | `column` | `column` is an engine state. Forward only, except that a card in `waiting_on_person` moves to any other column; a move back, to the same column,
|
|
15
|
-
| `close` | `card`, `reason` | `state` | Moves the card to the `done` column from any column, and takes the label `edgar:waiting` off.
|
|
16
|
-
| `create_card` | `spec`, `parent` (optional) | `id`, `url` | Returns the open card that already holds the block's fingerprint, and files nothing then. It raises that card's `occurrences` by one and sets its `last_seen` to the sighting's, or to now; a sighting no newer than the card's `last_seen`, as a retry is, writes nothing. A count that Linear refuses for good goes to the runtime log and the card is still the answer; a count write that can work again is a temporary failure, so the engine runs the call again. Two calls with one fingerprint run one at a time in the extension's process, so the second finds the card the first filed.
|
|
17
|
-
| `count_sighting` | `card`, `seen_at` (optional) | `id` | Counts one more sighting on the card `card`: raises `occurrences` and moves `last_seen` to `seen_at`, else now, in the card's block. A sighting no newer than `last_seen` writes nothing, so a retry counts once. A card with no block is left as it is; a card that Linear does not have is `not_found`. A write that Linear refuses for good goes to the runtime log.
|
|
18
|
-
| `
|
|
19
|
-
| `
|
|
20
|
-
| `
|
|
21
|
-
| `
|
|
22
|
-
| `
|
|
23
|
-
| `
|
|
24
|
-
| `
|
|
25
|
-
| `
|
|
26
|
-
| `
|
|
27
|
-
| `
|
|
11
|
+
| Tool | Input | Output | Notes |
|
|
12
|
+
| --------------------- | --------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
13
|
+
| `comment` | `card`, `text`, `link` (optional) | `id` | The link goes on its own line. |
|
|
14
|
+
| `move` | `card`, `column` | `column` | `column` is an engine state. Forward only, except that a card in `waiting_on_person` moves to any other column; a move back, to the same column, from or to a column the mapping does not name, or of a card out of the table's scope is `skipped`. A move to any column but `waiting_on_person` takes the label `edgar:waiting` off. |
|
|
15
|
+
| `close` | `card`, `reason` | `state` | Moves the card to the `done` column from any column, and takes the label `edgar:waiting` off. A card out of the table's scope is `skipped`. |
|
|
16
|
+
| `create_card` | `spec`, `parent` (optional) | `id`, `url` | Returns the open card that already holds the block's fingerprint, and files nothing then. It raises that card's `occurrences` by one and sets its `last_seen` to the sighting's, or to now; a sighting no newer than the card's `last_seen`, as a retry is, writes nothing. A count that Linear refuses for good goes to the runtime log and the card is still the answer; a count write that can work again is a temporary failure, so the engine runs the call again. Two calls with one fingerprint run one at a time in the extension's process, so the second finds the card the first filed. The same query also reads the newest done or canceled card that holds the fingerprint. With no open card, a card done less than 30 days before the sighting moves to `ready`, gets the line that the fault came back with one more sighting in its description, and is the answer. A canceled card, a card done longer ago, or one out of the table's scope stays closed, and the new card ends with the line "The same fault was on <its URL>, closed as done on <date>." (or "cancelled on"). When a person, not EDGAR's own user or a bot, commented on that card before it closed, the line goes on with `The last note there: "<their last comment>"`, cut to 280 characters, from the card's last 20 comments, so triage reads the decision with its date. |
|
|
17
|
+
| `count_sighting` | `card`, `seen_at` (optional) | `id` | Counts one more sighting on the card `card`: raises `occurrences` and moves `last_seen` to `seen_at`, else now, in the card's block. A sighting no newer than `last_seen` writes nothing, so a retry counts once. A card with no block is left as it is; a card that Linear does not have is `not_found`. A write that Linear refuses for good goes to the runtime log. |
|
|
18
|
+
| `set_priority` | `card`, `priority` | `id` | Sets the card's Linear priority to the one the analysis gave: `urgent` 1, `high` 2, `medium` 3, `low` 4. `skipped` when the card has a priority already, which stays; a card that Linear does not have is `not_found`. |
|
|
19
|
+
| `retitle` | `card`, `text` | `id`, `title` | For a card a feeder filed (its block names `decided.opened_by`): sets the title to the first sentence of `text`, cut at a word to 100 characters, after `title_prefix`, and changes nothing else: the block keeps the feeder's title in `decided.filed_as`, and a new title alone starts no run again. A card a person wrote, or one already titled so, is `skipped`. |
|
|
20
|
+
| `batch_cards` | `batch`, `except`, `only` | `cards`, `skipped` | The other open cards of the table's team and scope (with `assignee_only`, only the cards of `assignee` or labelled `edgar:waiting`) whose block holds `batch` in `decided.batch`, such as the scanner cards of one repository: at most 20, each with `id`, `title`, `url` and `description`. The card `except` is left out, and so is a done or canceled card, and a card whose description holds the text but whose block does not name the batch. Read-only. With `only`, just those ids, and `skipped` lists the ids of `only` that are not open cards of the batch. |
|
|
21
|
+
| `find_cards` | `text`, `except` (optional) | `cards` | Searches the open cards of the table's team and scope (`project`, `title_prefix`, `labels`, and with `assignee_only` only the cards of `assignee` or labelled `edgar:waiting`) with Linear's `searchIssues`, which matches words and meaning, and answers at most 10, the best match first: `id`, `title`, `url`, `state` (the engine state, else the Linear column name) and `created_at`. A done or canceled card is left out. With `except`, that card and each card made after it are left out, so two new cards never name each other; a card `except` that Linear does not have is `not_found`. `text` holds 1 to 1,024 characters. Linear allows 30 searches a minute. Read-only. |
|
|
22
|
+
| `park` | `card`, `waits_for` | `id` | Moves the card to the `intake` column from any column, then writes `waits_for = "<card>"` into its block, a `request` block when it has none, so `release_follow_ups` of that card releases it. A card out of the table's scope is skipped, with nothing written. |
|
|
23
|
+
| `release_follow_ups` | `card`, `pull_request`, `column?` | `released` | Moves each card in the `intake` column whose block has `waits_for = "<card>"` to `ready`, or to `column` (`waiting_on_person` after a close with no merge), and leaves a card out of the table's scope where it is. Follow-up cards wait in `intake`. |
|
|
24
|
+
| `update_description` | `card`, `description` | `id`, `previous` | Replaces the card's description and keeps its `edgar:v0` block, so the fingerprint and `waits_for` stay. `previous` is the description before the write. A description that already reads so is not written again. Side effect, undone by `restore_description`, found by `find_description`. |
|
|
25
|
+
| `restore_description` | `stage_output`: `id`, `previous` | `id` | Writes `previous` back as the description, with the card's current `edgar:v0` block, so a count made since stays. The engine calls it with the output of the `update_description` call that it undoes. |
|
|
26
|
+
| `find_description` | `card`, `description` | `id` | `done` when the description already is what `update_description` writes for that text, else `skipped`. Boot asks it about a call that did not end. |
|
|
27
|
+
| `assign` | `card`, `user` | `id`, `previous` | Assigns the card to the user with that email or id, to the user of `LINEAR_TOKEN` for `me`, or to nobody for an empty `user`. `previous` is the id of the assignee before the write, and an empty text when the card had none. A card that already has that assignee is not written again. A user that Linear does not have is `not_found`. Side effect, undone by `restore_assignee`, found by `find_assignee`. |
|
|
28
|
+
| `restore_assignee` | `stage_output`: `id`, `previous` | `id` | Sets the assignee back to the user `previous`, or to nobody for an empty `previous`. The engine calls it with the output of the `assign` call that it undoes. |
|
|
29
|
+
| `hand_back` | `card` | `id`, `to`, `previous` | Assigns the card to the person who asked for the work, and adds the label `edgar:waiting`. That person is the newest one in the card's history who assigned it to EDGAR's user, else the card's writer. EDGAR's user (the user of `LINEAR_TOKEN`, and `assignee`), an app and a bot are never chosen. `to` is the person's display name, and `previous` the id of the assignee before, or an empty text. A card that nobody can be given, such as a card that EDGAR filed and nobody handed over, is `skipped`. The label is the workspace's `edgar:waiting` or the one of the card's team, never another team's, which Linear refuses on the card; when neither exists, it is made in the card's team. A card that already has that person and the label is not written again. |
|
|
30
|
+
| `mark_seen` | `card` | `id` | Adds an eyes reaction to the card as the user of `LINEAR_TOKEN`. Linear answers a repeat with the first reaction, so a retry adds none. |
|
|
31
|
+
| `find_assignee` | `card`, `user` | `id` | `done` when the card already has the assignee that `assign` sets for that `user`, else `skipped`. Boot asks it about a call that did not end. |
|
|
28
32
|
|
|
29
33
|
A write that creates something sends an id derived from the operation id. A repeat of the same operation that fails looks that id up and returns what the first call made.
|
|
30
34
|
|
|
@@ -85,7 +89,7 @@ waits_for = "ENG-7"
|
|
|
85
89
|
```
|
|
86
90
|
````
|
|
87
91
|
|
|
88
|
-
`kind` is required. The block and card schemas come from `@kana-ai/edgar-contracts/card`, which the demo and GitHub extensions also use. The extension reads and writes the block with the card block helpers of `@kana-ai/edgar-sdk`. `card` answers `not_found` for an issue that Linear has archived or put in the trash, because Linear still reads such an issue by its id. A fingerprint of 16 or more hex characters is lowercased and cut to 16. A block that is not TOML or fails the schema makes `card` answer `invalid` with the line or the fields in `cause`; `list_cards` gives that card `block =
|
|
92
|
+
`kind` is required. The block and card schemas come from `@kana-ai/edgar-contracts/card`, which the demo and GitHub extensions also use. The extension reads and writes the block with the card block helpers of `@kana-ai/edgar-sdk`. `card` answers `not_found` for an issue that Linear has archived or put in the trash, because Linear still reads such an issue by its id. A fingerprint of 16 or more hex characters is lowercased and cut to 16. A block that is not TOML or fails the schema makes `card` answer `invalid` with the line or the fields in `cause`; `list_cards` gives that card `block = { invalid = "<why>" }`, so the engine refuses it with one comment that says why, instead of working it as plain text.
|
|
89
93
|
|
|
90
94
|
## Configuration
|
|
91
95
|
|
|
@@ -134,12 +138,13 @@ With none of the three set and `assignee_only` off, EDGAR picks every card of th
|
|
|
134
138
|
|
|
135
139
|
Make the key in Linear, Settings, Security & access, Personal API keys. A key with only Read lets EDGAR sweep and read cards, and every write fails. Give it the Write permission and access to the team in `[extensions.linear] team`. `edgar check` prints this text with `X004` when the project has no source for the key.
|
|
136
140
|
|
|
137
|
-
| Write
|
|
138
|
-
|
|
|
139
|
-
| `comment`, the tracker's `comment`
|
|
140
|
-
| `create_card`, the tracker's `create_card`
|
|
141
|
-
| `move`, `close`, `set_labels`, `release_follow_ups`, `update_description`, `restore_description`, `assign`, `restore_assignee`, `hand_back` | `IssueUpdate` | `write` |
|
|
142
|
-
| `hand_back`, when the workspace has no label `edgar:waiting`
|
|
141
|
+
| Write | Linear operation | Scope it needs |
|
|
142
|
+
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | ---------------------------- |
|
|
143
|
+
| `comment`, the tracker's `comment` | `CommentCreate` | `comments:create` or `write` |
|
|
144
|
+
| `create_card`, the tracker's `create_card` | `IssueCreate` | `issues:create` or `write` |
|
|
145
|
+
| `move`, `close`, `set_labels`, `park`, `release_follow_ups`, `set_priority`, `retitle`, `count_sighting`, `update_description`, `restore_description`, `assign`, `restore_assignee`, `hand_back` | `IssueUpdate` | `write` |
|
|
146
|
+
| `hand_back`, when the workspace has no label `edgar:waiting` | `IssueLabelCreate` | `write` |
|
|
147
|
+
| `mark_seen` | `ReactionCreate` | `write` |
|
|
143
148
|
|
|
144
149
|
Linear's API has no read of a key's scopes: its GraphQL schema has no scopes field for a personal key, and `integrationHasScopes` is for integrations only. A dry write is not used. So no check can tell a read-only key before its first write. That write fails `permanent_failure(forbidden)`, the engine does not retry it, the outbox records `outbox_failed` and an `alert`, and the message names the scope:
|
|
145
150
|
|
|
@@ -152,6 +157,14 @@ Linear's API has no read of a key's scopes: its GraphQL schema has no scopes fie
|
|
|
152
157
|
}
|
|
153
158
|
```
|
|
154
159
|
|
|
160
|
+
## Linked cards
|
|
161
|
+
|
|
162
|
+
The extension reads a card of `[extensions.linear] team` that a card or its comments link, such as `https://linear.app/<workspace>/issue/ENG-12`, into the run's inbox (`read_link`, for `linear.app`). The text holds the card's column, link, description and comments, with the same `card` and `comments` reads as the tracker port, so a card that the port does not read, such as one of another assignee with `assignee_only`, is a failure that the inbox shows in one line. A card of another team, and any other Linear link, such as a project, are not read.
|
|
163
|
+
|
|
164
|
+
## Webhook
|
|
165
|
+
|
|
166
|
+
The extension declares the `events` webhook, signed `hmac-sha256` with `LINEAR_WEBHOOK_SECRET` in the `Linear-Signature` header. It is optional. Without it, EDGAR finds each change at its next sweep. To wake the sweep sooner, make a webhook in Linear, Settings, API, Webhooks, for the team's issues and comments, with the URL `https://<public name>/hooks/linear/events`, and set its signing secret as `LINEAR_WEBHOOK_SECRET`. The API serves the route on a loopback name only, unless `[webhooks.public]` names the public host; see the config guide. A delivery only brings the next sweep forward, and its body is never read.
|
|
167
|
+
|
|
155
168
|
## Errors
|
|
156
169
|
|
|
157
170
|
One table in `src/api/failures.ts` maps each answer to an outcome, with the HTTP status, the raw code and the first error's message (at most 200 characters) in `cause`. The message is data for people; no code reads it. The first error's `extensions.code` wins: `RATELIMITED` `rate_limited`, `AUTHENTICATION_ERROR` `unauthenticated`, `FORBIDDEN` `forbidden`, `NOT_FOUND` `not_found`, `INVALID_INPUT` and `GRAPHQL_VALIDATION_FAILED` `invalid`. With no known code, HTTP 400 is `invalid`, 401 `unauthenticated`, 403 `forbidden`, 429 `rate_limited`, 5xx and network errors `provider_unavailable`, and anything else `tool_error`. A read of a missing id answers `not_found`. A `forbidden` answer to a write names the scope that the write needs, from the table in "What the key must be able to do". A rate limit waits for `Retry-After`, then `X-RateLimit-Requests-Reset`, then one minute.
|
|
@@ -184,14 +197,14 @@ Run on 2026-11-11 from the repository root, after `assignee_only` and `assign`:
|
|
|
184
197
|
## Shortcuts
|
|
185
198
|
|
|
186
199
|
- shortcut: the fingerprint and `waits_for` searches match the exact TOML line EDGAR writes, such as `waits_for = "ENG-7"`. A block a person reformats is not found. Upgrade to a label or a custom field if people edit blocks by hand.
|
|
187
|
-
- shortcut: the follow-up search reads 50 cards, `comments` 100 and `attachments` 50, with no further pages. Upgrade to cursors when a card exceeds them.
|
|
188
|
-
- shortcut: labels are found by name across the workspace, first match wins, and a missing label is refused, not created.
|
|
200
|
+
- shortcut: the follow-up search reads 50 cards, `comments` 100, and `attachments` 50 with the uploads of 100 comments, with no further pages. Upgrade to cursors when a card exceeds them.
|
|
201
|
+
- shortcut: labels are found by name across the workspace, first match wins, and a missing label is refused, not created; only `hand_back` makes `edgar:waiting` when it is missing.
|
|
189
202
|
- shortcut: `close` does not post `reason`.
|
|
190
203
|
- shortcut: `card` checks `assignee_only` and not `project`, `title_prefix` or `labels`. A card that leaves one of those three is still a card for `card`, and the sweep's alert names it. Upgrade when a project moves cards out of its scope while EDGAR works on them.
|
|
191
|
-
-
|
|
204
|
+
- `move`, `close`, `park` and `release_follow_ups` read the card first and skip it when it is out of the table's scope (`project`, `title_prefix`, `labels`, and with `assignee_only` the cards of `assignee` or labelled `edgar:waiting`). `merge_watch` moves the card of each merged pull request on an `edgar/` branch of the project's repositories, and another EDGAR that shares those repositories names its branches the same way, so without this check a merge of its pull request would move its card.
|
|
205
|
+
- shortcut: `comment`, `set_labels`, `update_description` and `assign` do not check the scope of the card they write to. The engine stops the run of a card that left the scope at the next sweep, so a write can still reach such a card for one sweep.
|
|
192
206
|
- shortcut: `assign` and `[extensions.linear] assignee` take an id as Linear's `user(id:)` reads it, and the Linear names of the assignee writes (`assigneeId` on `IssueCreateInput` and `IssueUpdateInput`, `null` for nobody) are from Linear's GraphQL reference, with no recorded answer. Check them against recorded answers before release.
|
|
193
207
|
- shortcut: `hand_back` reads the first 50 entries of the card's history in the order Linear gives them, so an older hand-over of a card with a longer history is not seen, and the Linear names it reads (`history` with `actor`, `toAssignee` and `createdAt`, `creator`, `User.app`, `issueLabelCreate`) are from Linear's GraphQL reference, with no recorded answer. Check them against recorded answers before release.
|
|
194
|
-
- shortcut: nothing takes `edgar:waiting` off a card. A card that keeps it stays in scope with `assignee_only` after the person's reply. Upgrade when a card must leave the scope again after it was handed back.
|
|
195
208
|
- shortcut: a sighting with no `last_seen` is counted at the time of the call, so a retried `create_card` whose first answer was lost counts it twice. A feed that sets `last_seen` is counted once.
|
|
196
209
|
- shortcut: the count is read and written with no version check, because Linear's `IssueUpdate` takes none. Two sightings at the same moment can both write the same count, and a person's edit of the description between the read and the write is lost. Upgrade when Linear offers a conditional write.
|
|
197
210
|
- shortcut: `budget_remaining` is 0 when Linear sends no rate-limit header, so the sweep slows down rather than speeds up.
|
package/dist/src/index.d.ts
CHANGED
|
@@ -1,3 +1,3 @@
|
|
|
1
|
-
/** The Linear extension: the tracker port
|
|
1
|
+
/** The Linear extension: the tracker port, the tools the default workflows call, the webhook that wakes the sweep, and the reader of a linked card. */
|
|
2
2
|
declare const _default: import("@kana-ai/edgar-sdk").Extension;
|
|
3
3
|
export default _default;
|
package/dist/src/index.js
CHANGED
|
@@ -2,8 +2,9 @@ import { defineExtension } from "@kana-ai/edgar-sdk";
|
|
|
2
2
|
import { HOST, TOKEN, apiAccess } from "#api/client";
|
|
3
3
|
import { config } from "#schemas/config";
|
|
4
4
|
import { tracker } from "#tracker/port";
|
|
5
|
+
import { readLink } from "#tracker/read-link";
|
|
5
6
|
import { tools } from "#tracker/tools";
|
|
6
|
-
/** The Linear extension: the tracker port
|
|
7
|
+
/** The Linear extension: the tracker port, the tools the default workflows call, the webhook that wakes the sweep, and the reader of a linked card. */
|
|
7
8
|
export default defineExtension({
|
|
8
9
|
name: "linear",
|
|
9
10
|
config,
|
|
@@ -12,8 +13,21 @@ export default defineExtension({
|
|
|
12
13
|
hosts: [HOST],
|
|
13
14
|
help: "Make a personal API key in Linear, Settings, Security & access, with the Write permission (comments, moves, closes and descriptions need it) and access to the team in [extensions.linear] team.",
|
|
14
15
|
},
|
|
16
|
+
LINEAR_WEBHOOK_SECRET: {
|
|
17
|
+
hosts: [],
|
|
18
|
+
help: "Optional. The signing secret of a Linear webhook that posts to /hooks/linear/events, so a change on the board wakes the next sweep. Without it, EDGAR finds each change at its next sweep.",
|
|
19
|
+
},
|
|
15
20
|
},
|
|
16
21
|
capabilities: [...apiAccess.capabilities],
|
|
17
22
|
tools,
|
|
18
23
|
tracker,
|
|
24
|
+
webhooks: {
|
|
25
|
+
events: {
|
|
26
|
+
signature: "hmac-sha256",
|
|
27
|
+
secret: "LINEAR_WEBHOOK_SECRET",
|
|
28
|
+
delivery_id_header: "Linear-Delivery",
|
|
29
|
+
signature_header: "Linear-Signature",
|
|
30
|
+
},
|
|
31
|
+
},
|
|
32
|
+
readLink,
|
|
19
33
|
});
|
|
@@ -3,33 +3,49 @@ const column = z.string().min(1);
|
|
|
3
3
|
/** The extension's `[extensions.linear]` table: the team key, the optional card scope, the Linear column of each engine state, the columns where a card assigned to `assignee` counts as intake, and the switch that keeps every card of another assignee out. */
|
|
4
4
|
export const config = z
|
|
5
5
|
.strictObject({
|
|
6
|
-
team: z
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
6
|
+
team: z
|
|
7
|
+
.string()
|
|
8
|
+
.min(1)
|
|
9
|
+
.describe("The key of the Linear team whose cards EDGAR works, such as ENG."),
|
|
10
|
+
project: z
|
|
11
|
+
.string()
|
|
12
|
+
.min(1)
|
|
13
|
+
.optional()
|
|
14
|
+
.describe("Only the cards in this Linear project, by name or URL key, are in scope, and EDGAR files its own cards there. Not set: every project."),
|
|
15
|
+
title_prefix: z
|
|
16
|
+
.string()
|
|
17
|
+
.min(1)
|
|
18
|
+
.optional()
|
|
19
|
+
.describe("Only the cards whose title starts with this text are in scope, and EDGAR adds it to the cards it files. Not set: any title."),
|
|
20
|
+
labels: z
|
|
21
|
+
.array(z.string().min(1))
|
|
22
|
+
.optional()
|
|
23
|
+
.describe("Only the cards that carry every one of these labels are in scope, and EDGAR adds them to the cards it files. Not set: any labels."),
|
|
24
|
+
columns: z
|
|
25
|
+
.strictObject({
|
|
26
|
+
intake: column.describe("The Linear column of new cards, such as Triage."),
|
|
27
|
+
ready: column.describe("The Linear column of cards ready to work on, such as Todo."),
|
|
28
|
+
working: column.describe("The Linear column of cards EDGAR works on, such as In Progress."),
|
|
29
|
+
in_review: column.describe("The Linear column of cards in review, such as In Review."),
|
|
30
|
+
waiting_on_person: column.describe("The Linear column of cards that wait for a person, such as Waiting."),
|
|
31
|
+
in_testing: column.describe("The Linear column of cards in testing, such as Testing."),
|
|
32
|
+
done: column.describe("The Linear column of finished cards, such as Done."),
|
|
33
|
+
cancelled: column.describe("The Linear column of cancelled cards, such as Canceled."),
|
|
34
|
+
})
|
|
35
|
+
.describe("The Linear column of each engine state; write every one."),
|
|
20
36
|
assignee: z
|
|
21
37
|
.string()
|
|
22
38
|
.min(1)
|
|
23
39
|
.optional()
|
|
24
|
-
.describe("
|
|
40
|
+
.describe("The Linear user, by id or email, or `me` for the user of LINEAR_TOKEN, which is the default: the user whose cards in `assigned` count as intake, and the one user of `assignee_only`."),
|
|
25
41
|
assignee_only: z
|
|
26
42
|
.boolean()
|
|
27
43
|
.default(false)
|
|
28
|
-
.describe("
|
|
44
|
+
.describe("True: a card is in scope only while it is assigned to `assignee`, in every column, and EDGAR assigns each card it files to that user. Default false."),
|
|
29
45
|
assigned: z
|
|
30
46
|
.array(column)
|
|
31
47
|
.default([])
|
|
32
|
-
.describe("
|
|
48
|
+
.describe("The Linear columns where a card assigned to `assignee` counts as intake. Default none."),
|
|
33
49
|
})
|
|
34
50
|
.refine((table) => !table.assigned.some((name) => Object.values(table.columns).includes(name)), {
|
|
35
51
|
message: "a column of `assigned` is a column of `columns` already",
|
|
@@ -12,7 +12,7 @@ export declare const envelope: z.ZodObject<{
|
|
|
12
12
|
/** One entry of a GraphQL `errors` list as Linear sends it. */
|
|
13
13
|
export type GraphqlError = NonNullable<z.infer<typeof envelope>["errors"]>[number];
|
|
14
14
|
/** The GraphQL selection of an issue that `issue` parses. */
|
|
15
|
-
export declare const issueFields = "id identifier title description url state { name } labels { nodes { name } } assignee { id displayName }";
|
|
15
|
+
export declare const issueFields = "id identifier title description url state { name } labels { nodes { name } } assignee { id displayName email } priority creator { id guest email }";
|
|
16
16
|
/** An issue with the fields a `Card` needs. */
|
|
17
17
|
export declare const issue: z.ZodObject<{
|
|
18
18
|
id: z.ZodString;
|
|
@@ -31,10 +31,17 @@ export declare const issue: z.ZodObject<{
|
|
|
31
31
|
assignee: z.ZodOptional<z.ZodNullable<z.ZodObject<{
|
|
32
32
|
id: z.ZodString;
|
|
33
33
|
displayName: z.ZodString;
|
|
34
|
+
email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
35
|
+
}, z.core.$strip>>>;
|
|
36
|
+
priority: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
|
|
37
|
+
creator: z.ZodOptional<z.ZodNullable<z.ZodObject<{
|
|
38
|
+
id: z.ZodString;
|
|
39
|
+
guest: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
|
|
40
|
+
email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
34
41
|
}, z.core.$strip>>>;
|
|
35
42
|
}, z.core.$strip>;
|
|
36
43
|
/** The selection of one issue read by its id. Linear answers an archived issue there, and never in a listing. */
|
|
37
|
-
export declare const oneIssueFields = "id identifier title description url state { name } labels { nodes { name } } assignee { id displayName } archivedAt trashed";
|
|
44
|
+
export declare const oneIssueFields = "id identifier title description url state { name } labels { nodes { name } } assignee { id displayName email } priority creator { id guest email } archivedAt trashed";
|
|
38
45
|
/** One issue read by its id, with the two fields that say it left the board. */
|
|
39
46
|
export declare const oneIssue: z.ZodObject<{
|
|
40
47
|
id: z.ZodString;
|
|
@@ -53,6 +60,13 @@ export declare const oneIssue: z.ZodObject<{
|
|
|
53
60
|
assignee: z.ZodOptional<z.ZodNullable<z.ZodObject<{
|
|
54
61
|
id: z.ZodString;
|
|
55
62
|
displayName: z.ZodString;
|
|
63
|
+
email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
64
|
+
}, z.core.$strip>>>;
|
|
65
|
+
priority: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
|
|
66
|
+
creator: z.ZodOptional<z.ZodNullable<z.ZodObject<{
|
|
67
|
+
id: z.ZodString;
|
|
68
|
+
guest: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
|
|
69
|
+
email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
56
70
|
}, z.core.$strip>>>;
|
|
57
71
|
archivedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
58
72
|
trashed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
|
|
@@ -76,18 +90,42 @@ export declare const heldIssue: z.ZodObject<{
|
|
|
76
90
|
id: z.ZodString;
|
|
77
91
|
description: z.ZodNullable<z.ZodString>;
|
|
78
92
|
}, z.core.$strip>;
|
|
79
|
-
/** A comment with its author, a person or a bot. */
|
|
93
|
+
/** A comment with its author, a person or a bot, and when it was edited or deleted. */
|
|
80
94
|
export declare const comment: z.ZodObject<{
|
|
81
95
|
id: z.ZodString;
|
|
82
96
|
body: z.ZodString;
|
|
83
97
|
createdAt: z.ZodString;
|
|
98
|
+
editedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
99
|
+
archivedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
84
100
|
user: z.ZodNullable<z.ZodObject<{
|
|
85
101
|
id: z.ZodString;
|
|
102
|
+
guest: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
|
|
103
|
+
email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
86
104
|
}, z.core.$strip>>;
|
|
87
105
|
botActor: z.ZodNullable<z.ZodObject<{
|
|
88
106
|
id: z.ZodNullable<z.ZodString>;
|
|
89
107
|
}, z.core.$strip>>;
|
|
90
108
|
}, z.core.$strip>;
|
|
109
|
+
/** A closed card that holds a fingerprint, with when it was done or cancelled and its last 20 comments. */
|
|
110
|
+
export declare const closedIssue: z.ZodObject<{
|
|
111
|
+
identifier: z.ZodString;
|
|
112
|
+
url: z.ZodString;
|
|
113
|
+
id: z.ZodString;
|
|
114
|
+
description: z.ZodNullable<z.ZodString>;
|
|
115
|
+
completedAt: z.ZodNullable<z.ZodString>;
|
|
116
|
+
canceledAt: z.ZodNullable<z.ZodString>;
|
|
117
|
+
comments: z.ZodObject<{
|
|
118
|
+
nodes: z.ZodArray<z.ZodObject<{
|
|
119
|
+
body: z.ZodString;
|
|
120
|
+
createdAt: z.ZodString;
|
|
121
|
+
user: z.ZodNullable<z.ZodObject<{
|
|
122
|
+
id: z.ZodString;
|
|
123
|
+
guest: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
|
|
124
|
+
email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
125
|
+
}, z.core.$strip>>;
|
|
126
|
+
}, z.core.$strip>>;
|
|
127
|
+
}, z.core.$strip>;
|
|
128
|
+
}, z.core.$strip>;
|
|
91
129
|
/** An attachment of an issue. */
|
|
92
130
|
export declare const attachment: z.ZodObject<{
|
|
93
131
|
id: z.ZodString;
|
|
@@ -10,7 +10,7 @@ export const envelope = z.object({
|
|
|
10
10
|
.optional(),
|
|
11
11
|
});
|
|
12
12
|
/** The GraphQL selection of an issue that `issue` parses. */
|
|
13
|
-
export const issueFields = "id identifier title description url state { name } labels { nodes { name } } assignee { id displayName }";
|
|
13
|
+
export const issueFields = "id identifier title description url state { name } labels { nodes { name } } assignee { id displayName email } priority creator { id guest email }";
|
|
14
14
|
/** An issue with the fields a `Card` needs. */
|
|
15
15
|
export const issue = z.object({
|
|
16
16
|
id: z.string(),
|
|
@@ -20,7 +20,13 @@ export const issue = z.object({
|
|
|
20
20
|
url: z.string(),
|
|
21
21
|
state: z.object({ name: z.string() }),
|
|
22
22
|
labels: z.object({ nodes: z.array(z.object({ name: z.string() })) }),
|
|
23
|
-
assignee: z
|
|
23
|
+
assignee: z
|
|
24
|
+
.object({ id: z.string(), displayName: z.string(), email: z.string().nullish() })
|
|
25
|
+
.nullish(),
|
|
26
|
+
priority: z.number().nullish(),
|
|
27
|
+
creator: z
|
|
28
|
+
.object({ id: z.string(), guest: z.boolean().nullish(), email: z.string().nullish() })
|
|
29
|
+
.nullish(),
|
|
24
30
|
});
|
|
25
31
|
/** The selection of one issue read by its id. Linear answers an archived issue there, and never in a listing. */
|
|
26
32
|
export const oneIssueFields = `${issueFields} archivedAt trashed`;
|
|
@@ -37,14 +43,24 @@ export const idNames = z.object({
|
|
|
37
43
|
export const created = z.object({ identifier: z.string(), url: z.string() });
|
|
38
44
|
/** An open card that holds a fingerprint, with the description its block is in. */
|
|
39
45
|
export const heldIssue = created.extend({ id: z.string(), description: z.string().nullable() });
|
|
40
|
-
/** A comment with its author, a person or a bot. */
|
|
46
|
+
/** A comment with its author, a person or a bot, and when it was edited or deleted. */
|
|
41
47
|
export const comment = z.object({
|
|
42
48
|
id: z.string(),
|
|
43
49
|
body: z.string(),
|
|
44
50
|
createdAt: z.string(),
|
|
45
|
-
|
|
51
|
+
editedAt: z.string().nullish(),
|
|
52
|
+
archivedAt: z.string().nullish(),
|
|
53
|
+
user: z
|
|
54
|
+
.object({ id: z.string(), guest: z.boolean().nullish(), email: z.string().nullish() })
|
|
55
|
+
.nullable(),
|
|
46
56
|
botActor: z.object({ id: z.string().nullable() }).nullable(),
|
|
47
57
|
});
|
|
58
|
+
/** A closed card that holds a fingerprint, with when it was done or cancelled and its last 20 comments. */
|
|
59
|
+
export const closedIssue = heldIssue.extend({
|
|
60
|
+
completedAt: z.string().nullable(),
|
|
61
|
+
canceledAt: z.string().nullable(),
|
|
62
|
+
comments: z.object({ nodes: z.array(comment.pick({ body: true, createdAt: true, user: true })) }),
|
|
63
|
+
});
|
|
48
64
|
/** An attachment of an issue. */
|
|
49
65
|
export const attachment = z.object({ id: z.string(), title: z.string(), url: z.string() });
|
|
50
66
|
/** The user a token signs in as, from `viewer`. */
|
|
@@ -60,6 +60,10 @@ export declare const createCardTool: {
|
|
|
60
60
|
channel: z.ZodString;
|
|
61
61
|
thread: z.ZodString;
|
|
62
62
|
}, z.core.$strict>>;
|
|
63
|
+
trust: z.ZodExactOptional<z.ZodEnum<{
|
|
64
|
+
outside: "outside";
|
|
65
|
+
team: "team";
|
|
66
|
+
}>>;
|
|
63
67
|
}, z.core.$strict>;
|
|
64
68
|
}, z.core.$strict>;
|
|
65
69
|
parent: z.ZodExactOptional<z.ZodString>;
|
|
@@ -69,11 +73,31 @@ export declare const createCardTool: {
|
|
|
69
73
|
url: z.ZodString;
|
|
70
74
|
}, z.core.$strip>;
|
|
71
75
|
};
|
|
72
|
-
/** The input and output of `
|
|
76
|
+
/** The input and output of `park`. */
|
|
77
|
+
export declare const parkTool: {
|
|
78
|
+
input: z.ZodObject<{
|
|
79
|
+
card: z.ZodString;
|
|
80
|
+
waits_for: z.ZodString;
|
|
81
|
+
}, z.core.$strip>;
|
|
82
|
+
output: z.ZodObject<{
|
|
83
|
+
id: z.ZodString;
|
|
84
|
+
}, z.core.$strip>;
|
|
85
|
+
};
|
|
86
|
+
/** Where `release_follow_ups` moves the cards that wait for a card. */
|
|
87
|
+
export declare const followUpColumn: z.ZodEnum<{
|
|
88
|
+
ready: "ready";
|
|
89
|
+
waiting_on_person: "waiting_on_person";
|
|
90
|
+
}>;
|
|
91
|
+
export type FollowUpColumn = z.infer<typeof followUpColumn>;
|
|
92
|
+
/** The input and output of `release_follow_ups`. A close with no merge holds the waiting cards for a person, as a merge releases them. */
|
|
73
93
|
export declare const releaseFollowUpsTool: {
|
|
74
94
|
input: z.ZodObject<{
|
|
75
95
|
card: z.ZodString;
|
|
76
96
|
pull_request: z.ZodString;
|
|
97
|
+
column: z.ZodExactOptional<z.ZodEnum<{
|
|
98
|
+
ready: "ready";
|
|
99
|
+
waiting_on_person: "waiting_on_person";
|
|
100
|
+
}>>;
|
|
77
101
|
}, z.core.$strip>;
|
|
78
102
|
output: z.ZodObject<{
|
|
79
103
|
released: z.ZodArray<z.ZodString>;
|
|
@@ -146,6 +170,21 @@ export declare const batchCardsTool: {
|
|
|
146
170
|
skipped: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
147
171
|
}, z.core.$strip>;
|
|
148
172
|
};
|
|
173
|
+
/** The input and output of `set_priority`. */
|
|
174
|
+
export declare const setPriorityTool: {
|
|
175
|
+
input: z.ZodObject<{
|
|
176
|
+
card: z.ZodString;
|
|
177
|
+
priority: z.ZodEnum<{
|
|
178
|
+
high: "high";
|
|
179
|
+
low: "low";
|
|
180
|
+
medium: "medium";
|
|
181
|
+
urgent: "urgent";
|
|
182
|
+
}>;
|
|
183
|
+
}, z.core.$strip>;
|
|
184
|
+
output: z.ZodObject<{
|
|
185
|
+
id: z.ZodString;
|
|
186
|
+
}, z.core.$strip>;
|
|
187
|
+
};
|
|
149
188
|
/** The input and output of `count_sighting`. */
|
|
150
189
|
export declare const countSightingTool: {
|
|
151
190
|
input: z.ZodObject<{
|
|
@@ -167,3 +206,23 @@ export declare const handBackTool: {
|
|
|
167
206
|
previous: z.ZodString;
|
|
168
207
|
}, z.core.$strip>;
|
|
169
208
|
};
|
|
209
|
+
/** The input and output of `retitle`. */
|
|
210
|
+
export declare const retitleTool: {
|
|
211
|
+
input: z.ZodObject<{
|
|
212
|
+
card: z.ZodString;
|
|
213
|
+
text: z.ZodString;
|
|
214
|
+
}, z.core.$strip>;
|
|
215
|
+
output: z.ZodObject<{
|
|
216
|
+
id: z.ZodString;
|
|
217
|
+
title: z.ZodString;
|
|
218
|
+
}, z.core.$strip>;
|
|
219
|
+
};
|
|
220
|
+
/** The input and output of `mark_seen`. */
|
|
221
|
+
export declare const markSeenTool: {
|
|
222
|
+
input: z.ZodObject<{
|
|
223
|
+
card: z.ZodString;
|
|
224
|
+
}, z.core.$strip>;
|
|
225
|
+
output: z.ZodObject<{
|
|
226
|
+
id: z.ZodString;
|
|
227
|
+
}, z.core.$strip>;
|
|
228
|
+
};
|