@kana-ai/edgar-ext-linear 0.0.0-stage → 0.1.0
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/LICENSE +202 -0
- package/README.md +198 -2
- package/dist/src/api/client.d.ts +21 -0
- package/dist/src/api/client.js +53 -0
- package/dist/src/api/failures.d.ts +11 -0
- package/dist/src/api/failures.js +37 -0
- package/dist/src/index.d.ts +3 -0
- package/dist/src/index.js +19 -0
- package/dist/src/schemas/config.d.ts +25 -0
- package/dist/src/schemas/config.js +37 -0
- package/dist/src/schemas/linear.d.ts +116 -0
- package/dist/src/schemas/linear.js +57 -0
- package/dist/src/schemas/tools.d.ts +169 -0
- package/dist/src/schemas/tools.js +147 -0
- package/dist/src/tracker/assignee.d.ts +15 -0
- package/dist/src/tracker/assignee.js +58 -0
- package/dist/src/tracker/cards.d.ts +33 -0
- package/dist/src/tracker/cards.js +372 -0
- package/dist/src/tracker/comments.d.ts +11 -0
- package/dist/src/tracker/comments.js +62 -0
- package/dist/src/tracker/description.d.ts +19 -0
- package/dist/src/tracker/description.js +55 -0
- package/dist/src/tracker/hand-back.d.ts +8 -0
- package/dist/src/tracker/hand-back.js +94 -0
- package/dist/src/tracker/port.d.ts +2 -0
- package/dist/src/tracker/port.js +46 -0
- package/dist/src/tracker/states.d.ts +21 -0
- package/dist/src/tracker/states.js +82 -0
- package/dist/src/tracker/tools.d.ts +142 -0
- package/dist/src/tracker/tools.js +130 -0
- package/dist/src/tracker/transitions.d.ts +13 -0
- package/dist/src/tracker/transitions.js +94 -0
- package/edgar-extension.json +208 -0
- package/package.json +41 -3
- package/schemas/assign.in.json +15 -0
- package/schemas/assign.out.json +14 -0
- package/schemas/batch_cards.in.json +27 -0
- package/schemas/batch_cards.out.json +37 -0
- package/schemas/close.in.json +14 -0
- package/schemas/close.out.json +10 -0
- package/schemas/comment.in.json +19 -0
- package/schemas/comment.out.json +10 -0
- package/schemas/config.json +94 -0
- package/schemas/count_sighting.in.json +17 -0
- package/schemas/count_sighting.out.json +10 -0
- package/schemas/create_card.in.json +108 -0
- package/schemas/create_card.out.json +13 -0
- package/schemas/find_assignee.in.json +15 -0
- package/schemas/find_assignee.out.json +10 -0
- package/schemas/find_cards.in.json +18 -0
- package/schemas/find_cards.out.json +33 -0
- package/schemas/find_description.in.json +15 -0
- package/schemas/find_description.out.json +10 -0
- package/schemas/hand_back.in.json +11 -0
- package/schemas/hand_back.out.json +18 -0
- package/schemas/move.in.json +15 -0
- package/schemas/move.out.json +10 -0
- package/schemas/release_follow_ups.in.json +15 -0
- package/schemas/release_follow_ups.out.json +13 -0
- package/schemas/restore_assignee.in.json +20 -0
- package/schemas/restore_assignee.out.json +10 -0
- package/schemas/restore_description.in.json +20 -0
- package/schemas/restore_description.out.json +10 -0
- package/schemas/update_description.in.json +15 -0
- package/schemas/update_description.out.json +14 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
179
|
+
|
|
180
|
+
To apply the Apache License to your work, attach the following
|
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
182
|
+
replaced with your own identifying information. (Don't include
|
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
184
|
+
comment syntax for the file format. We also recommend that a
|
|
185
|
+
file or class name and description of purpose be included on the
|
|
186
|
+
same "printed page" as the copyright notice for easier
|
|
187
|
+
identification within third-party archives.
|
|
188
|
+
|
|
189
|
+
Copyright 2026 Kana.ai
|
|
190
|
+
|
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
|
+
you may not use this file except in compliance with the License.
|
|
193
|
+
You may obtain a copy of the License at
|
|
194
|
+
|
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
196
|
+
|
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
200
|
+
See the License for the specific language governing permissions and
|
|
201
|
+
limitations under the License.
|
|
202
|
+
|
package/README.md
CHANGED
|
@@ -1,3 +1,199 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @kana-ai/edgar-ext-linear
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The Linear extension of EDGAR. It implements the engine's tracker port over Linear's GraphQL API, and the tools the default workflows call as `tracker__<tool>`, a name the engine gives the tracker of each card, so they run here as `linear__<tool>` for a card from Linear.
|
|
4
|
+
|
|
5
|
+
## Tracker port
|
|
6
|
+
|
|
7
|
+
All 11 methods: `list_cards`, `card`, `comments`, `attachments`, `comment`, `move`, `set_labels`, `create_card`, `close`, `whoami` and `person`. 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`. 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.
|
|
8
|
+
|
|
9
|
+
## Tools
|
|
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, or from or to a column the mapping does not name 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. |
|
|
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
|
+
| `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. |
|
|
19
|
+
| `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. |
|
|
20
|
+
| `release_follow_ups` | `card`, `pull_request` | `released` | Moves each card in the `intake` column whose block has `waits_for = "<card>"` to `ready`. Follow-up cards wait in `intake`. |
|
|
21
|
+
| `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`. |
|
|
22
|
+
| `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. |
|
|
23
|
+
| `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. |
|
|
24
|
+
| `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`. |
|
|
25
|
+
| `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. |
|
|
26
|
+
| `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. |
|
|
27
|
+
| `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
|
+
|
|
29
|
+
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
|
+
|
|
31
|
+
### Replace a description
|
|
32
|
+
|
|
33
|
+
A stage replaces the text of card `ENG-12`, whose description is `Users wait 30 s.` and its block:
|
|
34
|
+
|
|
35
|
+
```toml
|
|
36
|
+
[stages.describe]
|
|
37
|
+
tool = "linear__update_description"
|
|
38
|
+
input = { card = "trigger.card.id", description = "stages.analyze.output.summary" }
|
|
39
|
+
compensate = "linear__restore_description"
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
The tool reads the card, writes the new text with the old block at its end, and answers:
|
|
43
|
+
|
|
44
|
+
````json
|
|
45
|
+
{
|
|
46
|
+
"outcome": "done",
|
|
47
|
+
"output": { "id": "ENG-12", "previous": "Users wait 30 s.\n\n```toml edgar:v0\n..." }
|
|
48
|
+
}
|
|
49
|
+
````
|
|
50
|
+
|
|
51
|
+
A retry after a lost answer reads the card again, finds the same text, writes nothing and answers `done` with no `previous`, because the retry cannot know what the lost call replaced. A card with no block gets the text as it is. A card that does not exist is `not_found`. If boot settles a call through `find_description`, its output has no `previous` either. An undo of a call with no `previous` writes nothing and answers `done`, so a workflow that writes the same description on each pass does not stop the undos behind it; it never empties a description and never writes the new text over itself. Known limit: after a retry whose first answer was lost, the undo leaves the new text on the card.
|
|
52
|
+
|
|
53
|
+
### Assign a card
|
|
54
|
+
|
|
55
|
+
A stage gives card `ENG-12`, which is assigned to the user `u-ana`, to the person who reviews the change:
|
|
56
|
+
|
|
57
|
+
```toml
|
|
58
|
+
[stages.hand_over]
|
|
59
|
+
tool = "linear__assign"
|
|
60
|
+
input = { card = "trigger.card.id", user = "stages.review.output.reviewer_email" }
|
|
61
|
+
compensate = "linear__restore_assignee"
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
The tool reads the card, finds the user and writes the new assignee. It answers:
|
|
65
|
+
|
|
66
|
+
```json
|
|
67
|
+
{ "outcome": "done", "output": { "id": "ENG-12", "previous": "u-ana" } }
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
`user` is an email, a Linear user id, `me` for the user of `LINEAR_TOKEN`, or an empty text, which takes the assignee off. A user is found one time for the life of the runtime: an email by `users`, an id by `user`, `me` by `viewer`. An email or an id that the workspace does not have is `permanent_failure(not_found)` with the message `linear: no user <user>`, and nothing is written. A card that does not exist is `not_found`. A retry after a lost answer reads the card again, finds that assignee, writes nothing and answers `done` with no `previous`. An undo of a call with no `previous` writes nothing. An undo with an empty `previous` takes the assignee off, because the card had none before the call. Known limit: after a retry whose first answer was lost, the undo leaves the new assignee on the card.
|
|
71
|
+
|
|
72
|
+
With `assignee_only = true`, a card that this tool assigns to another user leaves EDGAR's scope at the next sweep, and the engine stops the run that works on it, with its work kept. Use that to hand a card over to a person. Do not use it in the middle of a workflow that must go on.
|
|
73
|
+
|
|
74
|
+
## The card block
|
|
75
|
+
|
|
76
|
+
A card carries one fenced block in its description:
|
|
77
|
+
|
|
78
|
+
````md
|
|
79
|
+
```toml edgar:v0
|
|
80
|
+
kind = "defect"
|
|
81
|
+
service = "api"
|
|
82
|
+
fingerprint = "0123456789abcdef"
|
|
83
|
+
first_seen = 2026-11-01T08:00:00Z
|
|
84
|
+
waits_for = "ENG-7"
|
|
85
|
+
```
|
|
86
|
+
````
|
|
87
|
+
|
|
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 = null`.
|
|
89
|
+
|
|
90
|
+
## Configuration
|
|
91
|
+
|
|
92
|
+
```toml
|
|
93
|
+
[extensions.linear]
|
|
94
|
+
team = "ENG" # the team key
|
|
95
|
+
project = "Platform" # optional
|
|
96
|
+
title_prefix = "[edgar]" # optional
|
|
97
|
+
labels = ["edgar"] # optional
|
|
98
|
+
assigned = ["Backlog"] # optional: columns where a card assigned to `assignee` counts as intake
|
|
99
|
+
assignee = "edgar@shop.example" # optional: a Linear user id, an email, or "me"; the default is "me", the user of LINEAR_TOKEN
|
|
100
|
+
assignee_only = true # optional, default false: only the cards assigned to `assignee` are in scope
|
|
101
|
+
|
|
102
|
+
[extensions.linear.columns] # every engine state, required
|
|
103
|
+
intake = "Triage"
|
|
104
|
+
ready = "Todo"
|
|
105
|
+
working = "In Progress"
|
|
106
|
+
in_review = "In Review"
|
|
107
|
+
waiting_on_person = "Waiting"
|
|
108
|
+
in_testing = "Testing"
|
|
109
|
+
done = "Done"
|
|
110
|
+
cancelled = "Canceled"
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
- `project`: EDGAR picks only the cards in this project, by name or URL key, and files its own cards there.
|
|
114
|
+
- `title_prefix`: EDGAR picks only the cards whose title starts with this text, and adds it to the cards it files.
|
|
115
|
+
- `labels`: EDGAR picks only the cards that carry every label in the list, and adds them to the cards it files.
|
|
116
|
+
|
|
117
|
+
With none of the three set and `assignee_only` off, EDGAR picks every card of the team in the mapped columns.
|
|
118
|
+
|
|
119
|
+
- `assignee_only`: with `true`, a card is in scope only while it is assigned to `assignee`, in every mapped column. Set it when the team in `team` also holds cards that people work on, so that EDGAR takes only the cards that someone gave to its user. The default is `false`. The value is a boolean, and `edgar check` refuses any other value. The user is `assignee`, so the smallest setting is `assignee_only = true` with no `assignee`, which takes the cards assigned to the user of `LINEAR_TOKEN`.
|
|
120
|
+
- The listing filters in Linear: `list_cards` adds `assignee: { id: { eq: <user> } }` to the filter of every column, so a card of another user, or of nobody, is never read.
|
|
121
|
+
- A card that carries the label `edgar:waiting` is in scope too, whoever holds it. `hand_back` adds the label when it gives a card to a person, so the person's reply on the card is still read and starts the work again. `move` out of `waiting_on_person` and `close` take it off. A card that a person moves or closes in Linear keeps it. The listing asks for `or: [{ assignee }, { labels: edgar:waiting }]` inside its `and` list.
|
|
122
|
+
- A card that a person assigns to another user, or to nobody, leaves the scope the same way a card that leaves the board does. The next listing does not have it, the engine then asks `card` for it, and `card` answers `not_found` with the message `linear: card <id> is not assigned to the user of [extensions.linear] assignee`. The engine stores the card as closed and stops each run that was open on it, with the work kept. A card that is assigned back is a card again at the next sweep.
|
|
123
|
+
- A card that EDGAR files (`create_card`, as a tool and as the tracker method that the feeders of EDGAR's own service use) is assigned to `assignee` when it is made. Without that, a feeder's card would be assigned to nobody and would never be in scope. With `assignee_only` off, EDGAR assigns a new card to nobody, as before.
|
|
124
|
+
- `create_card` still returns the open card that holds the fingerprint, whoever it is assigned to. If a person took that card, EDGAR files no second card and does not take the card back.
|
|
125
|
+
- When the user cannot be read (the token is refused, or Linear limits the rate), `list_cards` and `card` answer that failure. They never answer `not_found` for it, so no card closes because of a failed read.
|
|
126
|
+
|
|
127
|
+
- `assigned` and `assignee`: a card assigned to `assignee` in a column of `assigned` is a card in `intake`. The sweep's `list_cards` for `intake` asks for it in the same query, it reads as `intake`, and `move` takes it forward from there, so a person hands a card to EDGAR by assigning it, in any of these columns. A column of `assigned` cannot be a column of `columns`. `assignee` is found once for the life of the runtime: an email by `users`, an id by `user`, and `me` or no value by `viewer`. An email or an id that no user of the workspace has is a permanent `invalid` that names it. With `assigned` empty and `assignee_only` off, the defaults, nothing is asked.
|
|
128
|
+
|
|
129
|
+
## Secret
|
|
130
|
+
|
|
131
|
+
`LINEAR_TOKEN`: a personal API key (`lin_api_...`, sent bare) or an OAuth token (sent as `Bearer`). It reaches only `api.linear.app`.
|
|
132
|
+
|
|
133
|
+
### What the key must be able to do
|
|
134
|
+
|
|
135
|
+
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
|
+
|
|
137
|
+
| Write | Linear operation | Scope it needs |
|
|
138
|
+
| ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ---------------------------- |
|
|
139
|
+
| `comment`, the tracker's `comment` | `CommentCreate` | `comments:create` or `write` |
|
|
140
|
+
| `create_card`, the tracker's `create_card` | `IssueCreate` | `issues:create` or `write` |
|
|
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` | `IssueLabelCreate` | `write` |
|
|
143
|
+
|
|
144
|
+
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
|
+
|
|
146
|
+
```json
|
|
147
|
+
{
|
|
148
|
+
"outcome": "permanent_failure",
|
|
149
|
+
"kind": "forbidden",
|
|
150
|
+
"message": "linear CommentCreate: forbidden: the LINEAR_TOKEN key needs the comments:create or write scope",
|
|
151
|
+
"cause": "400 FORBIDDEN Invalid scope: write or comments:create required"
|
|
152
|
+
}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
## Errors
|
|
156
|
+
|
|
157
|
+
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.
|
|
158
|
+
|
|
159
|
+
## Limits
|
|
160
|
+
|
|
161
|
+
Each answer's `X-RateLimit-Requests-Limit`, `-Remaining` and `-Reset`, and `X-RateLimit-Complexity-Limit`, `-Remaining` and `-Reset` (Unix milliseconds), are read with the SDK's `linear` scheme. The window with the smallest share left is reported for the source `api.linear.app`, with the window `requests` or `complexity`, on a success and on a failure. A `Retry-After` makes the limit used up until the time it names. The operator sees the source on the console's Limits page and on `GET /api/limits`. While `api.linear.app` has none left, EDGAR does not start a stage whose tool has `network:api.linear.app`, and records `waited_for_limit` until the reset.
|
|
162
|
+
|
|
163
|
+
## Build and test
|
|
164
|
+
|
|
165
|
+
```sh
|
|
166
|
+
pnpm build # writes edgar-extension.json and schemas/
|
|
167
|
+
pnpm test # unit tests with a mock Linear, no network
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
`edgar-extension.json` and `schemas/` are committed: a change to them in a diff is a change to what a person approves.
|
|
171
|
+
|
|
172
|
+
## Validation
|
|
173
|
+
|
|
174
|
+
Run on 2026-11-11 from the repository root, after `assignee_only` and `assign`:
|
|
175
|
+
|
|
176
|
+
| Command | Exit code |
|
|
177
|
+
| ---------------------------------------------------------- | ----------------- |
|
|
178
|
+
| `pnpm --filter @kana-ai/edgar-ext-linear run check-types` | 0 |
|
|
179
|
+
| `pnpm --filter @kana-ai/edgar-ext-linear run lint` | 0 |
|
|
180
|
+
| `pnpm --filter @kana-ai/edgar-ext-linear run format:check` | 0 |
|
|
181
|
+
| `pnpm --filter @kana-ai/edgar-ext-linear run test` | 0, 67 tests pass |
|
|
182
|
+
| `pnpm --filter @kana-ai/edgar-ext-linear run build`, twice | 0, the same bytes |
|
|
183
|
+
|
|
184
|
+
## Shortcuts
|
|
185
|
+
|
|
186
|
+
- 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.
|
|
189
|
+
- shortcut: `close` does not post `reason`.
|
|
190
|
+
- 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
|
+
- shortcut: `comment`, `move`, `close`, `set_labels`, `update_description`, `assign` and `release_follow_ups` 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
|
+
- 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
|
+
- 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
|
+
- 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
|
+
- 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
|
+
- shortcut: `budget_remaining` is 0 when Linear sends no rate-limit header, so the sweep slows down rather than speeds up.
|
|
198
|
+
- shortcut: a mention is read as `@<display name>` in the body; no recorded Linear mention sample exists yet. Upgrade when one is recorded.
|
|
199
|
+
- shortcut: error codes other than `RATELIMITED` follow the mapping table; Linear's pages document no others. Check them against recorded answers before release.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import { type Ctx, type Err, type Failure, type Ok } from "@kana-ai/edgar-sdk";
|
|
2
|
+
import type { z } from "zod";
|
|
3
|
+
/** The secret every Linear call sends. */
|
|
4
|
+
export declare const TOKEN = "LINEAR_TOKEN";
|
|
5
|
+
/** The host every Linear call goes to. */
|
|
6
|
+
export declare const HOST: "api.linear.app";
|
|
7
|
+
/** The secret and the capability of the tracker and of each tool, which all call the API. */
|
|
8
|
+
export declare const apiAccess: {
|
|
9
|
+
readonly secrets: readonly ["LINEAR_TOKEN"];
|
|
10
|
+
readonly capabilities: readonly ["network:api.linear.app"];
|
|
11
|
+
};
|
|
12
|
+
/** A tool context that holds the Linear token. */
|
|
13
|
+
export type LinearCtx = Ctx<typeof TOKEN>;
|
|
14
|
+
/** The answer of one Linear call: the parsed `data` and the requests left in the window, or the failure it maps to. */
|
|
15
|
+
export type Reply<T> = (Ok<T> & {
|
|
16
|
+
readonly remaining: number;
|
|
17
|
+
}) | Err<Failure>;
|
|
18
|
+
/** A UUID derived from the operation id, sent as the id of what a write creates so a repeat cannot create twice. */
|
|
19
|
+
export declare function keyOf(operationId: string): string;
|
|
20
|
+
/** Sends one named GraphQL operation to Linear with the call's `LINEAR_TOKEN` and parses `data` with `schema`; each answer's rate limit goes on the call's outcome. A secret read outside the call is a bug and throws before the request. */
|
|
21
|
+
export declare function linear<T>(ctx: LinearCtx, query: string, variables: Readonly<Record<string, unknown>>, schema: z.ZodType<T>): Promise<Reply<T>>;
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import { attemptAsync, err, failure, fetchFailure, limitFromHeaders, ok, reportLimit, unwrapOr, } from "@kana-ai/edgar-sdk";
|
|
3
|
+
import { limits, mapFailure } from "#api/failures";
|
|
4
|
+
import { envelope } from "#schemas/linear";
|
|
5
|
+
/** The secret every Linear call sends. */
|
|
6
|
+
export const TOKEN = "LINEAR_TOKEN";
|
|
7
|
+
/** The host every Linear call goes to. */
|
|
8
|
+
export const HOST = limits.source;
|
|
9
|
+
/** The secret and the capability of the tracker and of each tool, which all call the API. */
|
|
10
|
+
export const apiAccess = { secrets: [TOKEN], capabilities: [`network:${HOST}`] };
|
|
11
|
+
/** A UUID derived from the operation id, sent as the id of what a write creates so a repeat cannot create twice. */
|
|
12
|
+
export function keyOf(operationId) {
|
|
13
|
+
const h = createHash("sha256").update(operationId).digest("hex");
|
|
14
|
+
const variant = ((Number.parseInt(h.charAt(16), 16) & 3) | 8).toString(16);
|
|
15
|
+
return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-${variant}${h.slice(17, 20)}-${h.slice(20, 32)}`;
|
|
16
|
+
}
|
|
17
|
+
function authorization(token) {
|
|
18
|
+
return token.startsWith("lin_api_") ? token : `Bearer ${token}`;
|
|
19
|
+
}
|
|
20
|
+
/** Sends one named GraphQL operation to Linear with the call's `LINEAR_TOKEN` and parses `data` with `schema`; each answer's rate limit goes on the call's outcome. A secret read outside the call is a bug and throws before the request. */
|
|
21
|
+
export async function linear(ctx, query, variables, schema) {
|
|
22
|
+
const context = `linear ${/^\s*(?:query|mutation)\s+(\w+)/.exec(query)?.[1] ?? "operation"}`;
|
|
23
|
+
const headers = {
|
|
24
|
+
authorization: authorization(ctx.secrets.get(TOKEN)),
|
|
25
|
+
"content-type": "application/json",
|
|
26
|
+
};
|
|
27
|
+
const sent = await attemptAsync(async () => await fetch(`https://${HOST}/graphql`, {
|
|
28
|
+
method: "POST",
|
|
29
|
+
signal: ctx.signal,
|
|
30
|
+
headers,
|
|
31
|
+
body: JSON.stringify({ query, variables }),
|
|
32
|
+
}), (caught) => fetchFailure(caught, ctx.signal, context));
|
|
33
|
+
if (!sent.ok)
|
|
34
|
+
return sent;
|
|
35
|
+
const response = sent.value;
|
|
36
|
+
reportLimit(ctx, limitFromHeaders(response.headers, limits.scheme, HOST));
|
|
37
|
+
const json = unwrapOr(await attemptAsync(async () => await response.json(), () => null), null);
|
|
38
|
+
const body = envelope.safeParse(json);
|
|
39
|
+
const errors = body.success ? (body.data.errors ?? []) : [];
|
|
40
|
+
if (!response.ok || errors.length > 0) {
|
|
41
|
+
return err(mapFailure(response.status, response.headers, errors, context));
|
|
42
|
+
}
|
|
43
|
+
const parsed = schema.safeParse(body.success ? body.data.data : undefined);
|
|
44
|
+
if (parsed.success) {
|
|
45
|
+
const remaining = Number(response.headers.get("x-ratelimit-requests-remaining"));
|
|
46
|
+
return {
|
|
47
|
+
...ok(parsed.data),
|
|
48
|
+
remaining: Number.isFinite(remaining) ? Math.max(0, Math.floor(remaining)) : 0,
|
|
49
|
+
};
|
|
50
|
+
}
|
|
51
|
+
const fields = parsed.error.issues.map((issue) => issue.path.join(".")).join(", ");
|
|
52
|
+
return err(failure("tool_error", `${context}: unexpected answer`, { cause: `fields: ${fields}` }));
|
|
53
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { type Failure } from "@kana-ai/edgar-sdk";
|
|
2
|
+
import type { GraphqlError } from "#schemas/linear";
|
|
3
|
+
/** Linear reports its request and complexity limits in `x-ratelimit-{requests,complexity}-*` on every answer of its API host. */
|
|
4
|
+
export declare const limits: {
|
|
5
|
+
readonly scheme: "linear";
|
|
6
|
+
readonly source: "api.linear.app";
|
|
7
|
+
};
|
|
8
|
+
/** The scope a Linear key needs for each write the extension sends. Linear has no read of a key's scopes, so a `forbidden` write names its scope in the message, and the README names them all. */
|
|
9
|
+
export declare const writeScopes: Map<string, string>;
|
|
10
|
+
/** Maps a Linear error answer to a failure: the first error's code wins over the HTTP status, and `cause` keeps both raw with Linear's message. A `forbidden` write says the scope the key needs. */
|
|
11
|
+
export declare function mapFailure(status: number, headers: Headers, errors: readonly GraphqlError[], context: string, now?: number): Failure;
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import { vendorFailure } from "@kana-ai/edgar-sdk";
|
|
2
|
+
/** Linear reports its request and complexity limits in `x-ratelimit-{requests,complexity}-*` on every answer of its API host. */
|
|
3
|
+
export const limits = { scheme: "linear", source: "api.linear.app" };
|
|
4
|
+
const statusKinds = new Map([
|
|
5
|
+
[400, "invalid"],
|
|
6
|
+
[401, "unauthenticated"],
|
|
7
|
+
[403, "forbidden"],
|
|
8
|
+
[429, "rate_limited"],
|
|
9
|
+
]);
|
|
10
|
+
const codeKinds = new Map([
|
|
11
|
+
["RATELIMITED", "rate_limited"],
|
|
12
|
+
["AUTHENTICATION_ERROR", "unauthenticated"],
|
|
13
|
+
["FORBIDDEN", "forbidden"],
|
|
14
|
+
["NOT_FOUND", "not_found"],
|
|
15
|
+
["INVALID_INPUT", "invalid"],
|
|
16
|
+
["GRAPHQL_VALIDATION_FAILED", "invalid"],
|
|
17
|
+
]);
|
|
18
|
+
/** The scope a Linear key needs for each write the extension sends. Linear has no read of a key's scopes, so a `forbidden` write names its scope in the message, and the README names them all. */
|
|
19
|
+
export const writeScopes = new Map([
|
|
20
|
+
["CommentCreate", "comments:create or write"],
|
|
21
|
+
["IssueCreate", "issues:create or write"],
|
|
22
|
+
["IssueUpdate", "write"],
|
|
23
|
+
]);
|
|
24
|
+
/** Maps a Linear error answer to a failure: the first error's code wins over the HTTP status, and `cause` keeps both raw with Linear's message. A `forbidden` write says the scope the key needs. */
|
|
25
|
+
export function mapFailure(status, headers, errors, context, now = Date.now()) {
|
|
26
|
+
const code = errors[0]?.extensions?.code;
|
|
27
|
+
const kind = (code === undefined ? undefined : codeKinds.get(code)) ??
|
|
28
|
+
(status >= 500 ? "provider_unavailable" : statusKinds.get(status)) ??
|
|
29
|
+
"tool_error";
|
|
30
|
+
const said = errors[0]?.message?.slice(0, 200) ?? "";
|
|
31
|
+
const cause = `${String(status)} ${code ?? ""} ${said}`.replace(/\s+/g, " ").trim();
|
|
32
|
+
const failed = vendorFailure(kind, context, cause, headers, limits, now);
|
|
33
|
+
const scope = writeScopes.get(context.replace(/^linear /, ""));
|
|
34
|
+
return kind === "forbidden" && scope !== undefined
|
|
35
|
+
? { ...failed, message: `${failed.message}: the LINEAR_TOKEN key needs the ${scope} scope` }
|
|
36
|
+
: failed;
|
|
37
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import { defineExtension } from "@kana-ai/edgar-sdk";
|
|
2
|
+
import { HOST, TOKEN, apiAccess } from "#api/client";
|
|
3
|
+
import { config } from "#schemas/config";
|
|
4
|
+
import { tracker } from "#tracker/port";
|
|
5
|
+
import { tools } from "#tracker/tools";
|
|
6
|
+
/** The Linear extension: the tracker port and the tools the default workflows call. */
|
|
7
|
+
export default defineExtension({
|
|
8
|
+
name: "linear",
|
|
9
|
+
config,
|
|
10
|
+
secrets: {
|
|
11
|
+
[TOKEN]: {
|
|
12
|
+
hosts: [HOST],
|
|
13
|
+
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
|
+
capabilities: [...apiAccess.capabilities],
|
|
17
|
+
tools,
|
|
18
|
+
tracker,
|
|
19
|
+
});
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
/** 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. */
|
|
3
|
+
export declare const config: z.ZodObject<{
|
|
4
|
+
team: z.ZodString;
|
|
5
|
+
project: z.ZodOptional<z.ZodString>;
|
|
6
|
+
title_prefix: z.ZodOptional<z.ZodString>;
|
|
7
|
+
labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
8
|
+
columns: z.ZodObject<{
|
|
9
|
+
intake: z.ZodString;
|
|
10
|
+
ready: z.ZodString;
|
|
11
|
+
working: z.ZodString;
|
|
12
|
+
in_review: z.ZodString;
|
|
13
|
+
waiting_on_person: z.ZodString;
|
|
14
|
+
in_testing: z.ZodString;
|
|
15
|
+
done: z.ZodString;
|
|
16
|
+
cancelled: z.ZodString;
|
|
17
|
+
}, z.core.$strict>;
|
|
18
|
+
assignee: z.ZodOptional<z.ZodString>;
|
|
19
|
+
assignee_only: z.ZodDefault<z.ZodBoolean>;
|
|
20
|
+
assigned: z.ZodDefault<z.ZodArray<z.ZodString>>;
|
|
21
|
+
}, z.core.$strict>;
|
|
22
|
+
/** The parsed `[extensions.linear]` table. */
|
|
23
|
+
export type Config = z.infer<typeof config>;
|
|
24
|
+
/** An engine state the table maps to a column. */
|
|
25
|
+
export type State = keyof Config["columns"];
|