@kana-ai/edgar-ext-linear 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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
|
@@ -0,0 +1,372 @@
|
|
|
1
|
+
import { blockLine, done, err, ok, oneAtATime, permanentFailure, readBlock, sighted, withBlock, } from "@kana-ai/edgar-sdk";
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
import { keyOf, linear } from "#api/client";
|
|
4
|
+
import { created, heldIssue, idNames, issue, issueFields, oneIssue, oneIssueFields, } from "#schemas/linear";
|
|
5
|
+
import { WAITING, assigneeOf, columnOf, isState, settingsOf } from "#tracker/states";
|
|
6
|
+
import { update } from "#tracker/transitions";
|
|
7
|
+
function toCard(settings, value, strict, assignee) {
|
|
8
|
+
const description = value.description ?? "";
|
|
9
|
+
const block = readBlock(description);
|
|
10
|
+
if (!block.ok && strict)
|
|
11
|
+
return block.error;
|
|
12
|
+
const assigned = value.assignee?.displayName;
|
|
13
|
+
return done({
|
|
14
|
+
id: value.identifier,
|
|
15
|
+
title: value.title,
|
|
16
|
+
description,
|
|
17
|
+
column: columnOf(settings, value.state.name, assignee, value.assignee?.id) ?? value.state.name,
|
|
18
|
+
labels: value.labels.nodes.map((label) => label.name),
|
|
19
|
+
url: value.url,
|
|
20
|
+
block: block.ok ? block.value : null,
|
|
21
|
+
...(assigned === undefined ? {} : { assignee: assigned }),
|
|
22
|
+
});
|
|
23
|
+
}
|
|
24
|
+
/** The Linear id of the card `card`, or `not_found`. */
|
|
25
|
+
export async function issueId(ctx, card) {
|
|
26
|
+
const found = await linear(ctx, "query IssueId($id: String!) { issue(id: $id) { id } }", { id: card }, z.object({ issue: z.object({ id: z.string() }).nullable() }));
|
|
27
|
+
if (!found.ok)
|
|
28
|
+
return found;
|
|
29
|
+
return found.value.issue === null
|
|
30
|
+
? err(permanentFailure("not_found", `linear: no card ${card}`))
|
|
31
|
+
: ok(found.value.issue.id);
|
|
32
|
+
}
|
|
33
|
+
/** The ids of the labels named `names`, the first match per name; a missing name is `invalid`. */
|
|
34
|
+
export async function labelIds(ctx, names) {
|
|
35
|
+
if (names.length === 0)
|
|
36
|
+
return ok([]);
|
|
37
|
+
const found = await linear(ctx, "query Labels($names: [String!]!) { issueLabels(filter: { name: { in: $names } }) { nodes { id name } } }", { names }, z.object({ issueLabels: idNames }));
|
|
38
|
+
if (!found.ok)
|
|
39
|
+
return found;
|
|
40
|
+
const byName = new Map();
|
|
41
|
+
for (const label of found.value.issueLabels.nodes)
|
|
42
|
+
if (!byName.has(label.name))
|
|
43
|
+
byName.set(label.name, label.id);
|
|
44
|
+
const missing = names.filter((name) => !byName.has(name));
|
|
45
|
+
if (missing.length > 0) {
|
|
46
|
+
return err(permanentFailure("invalid", "linear: labels missing", { cause: missing.join(", ") }));
|
|
47
|
+
}
|
|
48
|
+
return ok(names.flatMap((name) => byName.get(name) ?? []));
|
|
49
|
+
}
|
|
50
|
+
/** With `assignee_only`, the cards in EDGAR's scope: assigned to `$assignee`, or handed back with `edgar:waiting`. */
|
|
51
|
+
const mineOrWaiting = `{ or: [{ assignee: { id: { eq: $assignee } } }, { labels: { some: { name: { eq: ${JSON.stringify(WAITING)} } } } }] }`;
|
|
52
|
+
const projectMatch = "{ or: [{ name: { eq: $project } }, { slugId: { eq: $project } }] }";
|
|
53
|
+
/** The query parameters, filter clauses and variables of the table's `project`, `title_prefix` and `labels`, with `also` added to the `and` list; empty when none is set. */
|
|
54
|
+
function scope(settings, also = []) {
|
|
55
|
+
const params = [];
|
|
56
|
+
const clauses = [];
|
|
57
|
+
const variables = {};
|
|
58
|
+
if (settings.project !== undefined) {
|
|
59
|
+
params.push("$project: String!");
|
|
60
|
+
clauses.push(`project: ${projectMatch}`);
|
|
61
|
+
variables["project"] = settings.project;
|
|
62
|
+
}
|
|
63
|
+
if (settings.title_prefix !== undefined) {
|
|
64
|
+
params.push("$prefix: String!");
|
|
65
|
+
clauses.push("title: { startsWith: $prefix }");
|
|
66
|
+
variables["prefix"] = settings.title_prefix;
|
|
67
|
+
}
|
|
68
|
+
const labels = settings.labels ?? [];
|
|
69
|
+
labels.forEach((label, index) => {
|
|
70
|
+
params.push(`$label${String(index)}: String!`);
|
|
71
|
+
variables[`label${String(index)}`] = label;
|
|
72
|
+
});
|
|
73
|
+
const every = [
|
|
74
|
+
...labels.map((_, index) => `{ labels: { some: { name: { eq: $label${String(index)} } } } }`),
|
|
75
|
+
...also,
|
|
76
|
+
];
|
|
77
|
+
if (every.length > 0)
|
|
78
|
+
clauses.push(`and: [${every.join(", ")}]`);
|
|
79
|
+
return {
|
|
80
|
+
params: params.map((param) => `, ${param}`).join(""),
|
|
81
|
+
clauses: clauses.map((clause) => `, ${clause}`).join(""),
|
|
82
|
+
variables,
|
|
83
|
+
};
|
|
84
|
+
}
|
|
85
|
+
/** The Linear id of the project named, or with the URL key, `project`; a missing project is `invalid`. */
|
|
86
|
+
async function projectId(ctx, project) {
|
|
87
|
+
const found = await linear(ctx, `query Project($project: String!) { projects(first: 1, filter: ${projectMatch}) { nodes { id } } }`, { project }, z.object({ projects: z.object({ nodes: z.array(z.object({ id: z.string() })) }) }));
|
|
88
|
+
if (!found.ok)
|
|
89
|
+
return found;
|
|
90
|
+
const [match] = found.value.projects.nodes;
|
|
91
|
+
return match === undefined
|
|
92
|
+
? err(permanentFailure("invalid", `linear: no project ${project}`, { cause: project }))
|
|
93
|
+
: ok(match.id);
|
|
94
|
+
}
|
|
95
|
+
/** One page of the cards in the engine states `columns` and in the table's scope, with the cursor of the next and the requests left; a name that is not an engine state is `invalid`. `intake` also takes each card assigned to `assignee` in a column of `assigned`. With `assignee_only`, Linear answers only the cards assigned to `assignee` or labelled `edgar:waiting`. */
|
|
96
|
+
export async function listCards(ctx, input) {
|
|
97
|
+
const settings = settingsOf(ctx);
|
|
98
|
+
if (!settings.ok)
|
|
99
|
+
return settings.error;
|
|
100
|
+
const unknown = input.columns.filter((column) => !isState(column));
|
|
101
|
+
if (unknown.length > 0) {
|
|
102
|
+
return permanentFailure("invalid", "linear: list_cards takes engine states, not column names", {
|
|
103
|
+
cause: unknown.join(", "),
|
|
104
|
+
});
|
|
105
|
+
}
|
|
106
|
+
const names = input.columns.filter(isState).map((state) => settings.value.columns[state]);
|
|
107
|
+
const assignee = await assigneeOf(ctx, settings.value);
|
|
108
|
+
if (!assignee.ok)
|
|
109
|
+
return assignee.error;
|
|
110
|
+
const assigned = settings.value.assigned;
|
|
111
|
+
const taken = assigned.length > 0 && input.columns.includes("intake") ? assignee.value : undefined;
|
|
112
|
+
const only = settings.value.assignee_only ? assignee.value : undefined;
|
|
113
|
+
const user = taken ?? only;
|
|
114
|
+
const byState = "state: { name: { in: $states } }";
|
|
115
|
+
const byUser = "assignee: { id: { eq: $assignee } }";
|
|
116
|
+
const state = taken === undefined
|
|
117
|
+
? byState
|
|
118
|
+
: `or: [{ ${byState} }, { state: { name: { in: $assigned } }, ${byUser} }]`;
|
|
119
|
+
const narrow = scope(settings.value, only === undefined ? [] : [mineOrWaiting]);
|
|
120
|
+
const params = `${taken === undefined ? "" : ", $assigned: [String!]!"}${user === undefined ? "" : ", $assignee: ID!"}${narrow.params}`;
|
|
121
|
+
const extra = {
|
|
122
|
+
...(taken === undefined ? {} : { assigned }),
|
|
123
|
+
...(user === undefined ? {} : { assignee: user }),
|
|
124
|
+
};
|
|
125
|
+
const listed = await linear(ctx, `query Cards($team: String!, $states: [String!]!, $after: String${params}) { issues(first: 50, after: $after, filter: { team: { key: { eq: $team } }, ${state}${narrow.clauses} }) { nodes { ${issueFields} } pageInfo { hasNextPage endCursor } } }`, {
|
|
126
|
+
team: settings.value.team,
|
|
127
|
+
states: names,
|
|
128
|
+
after: input.cursor,
|
|
129
|
+
...extra,
|
|
130
|
+
...narrow.variables,
|
|
131
|
+
}, z.object({
|
|
132
|
+
issues: z.object({
|
|
133
|
+
nodes: z.array(issue),
|
|
134
|
+
pageInfo: z.object({ hasNextPage: z.boolean(), endCursor: z.string().nullable() }),
|
|
135
|
+
}),
|
|
136
|
+
}));
|
|
137
|
+
if (!listed.ok)
|
|
138
|
+
return listed.error;
|
|
139
|
+
const cards = listed.value.issues.nodes.flatMap((node) => {
|
|
140
|
+
const read = toCard(settings.value, node, false, taken);
|
|
141
|
+
return read.outcome === "done" ? [read.output] : [];
|
|
142
|
+
});
|
|
143
|
+
const page = listed.value.issues.pageInfo;
|
|
144
|
+
return done({
|
|
145
|
+
cards,
|
|
146
|
+
next: page.hasNextPage ? page.endCursor : null,
|
|
147
|
+
budget_remaining: listed.remaining,
|
|
148
|
+
});
|
|
149
|
+
}
|
|
150
|
+
/** The card `id`; a missing, archived or trashed card is `not_found` and a bad block `invalid`. With `assignee_only`, a card that is not assigned to `assignee` and not labelled `edgar:waiting` is `not_found` too, so the engine reads it as a card that left the board. */
|
|
151
|
+
export async function readCard(ctx, id) {
|
|
152
|
+
const settings = settingsOf(ctx);
|
|
153
|
+
if (!settings.ok)
|
|
154
|
+
return settings.error;
|
|
155
|
+
const read = await linear(ctx, `query Card($id: String!) { issue(id: $id) { ${oneIssueFields} } }`, { id }, z.object({ issue: oneIssue.nullable() }));
|
|
156
|
+
if (!read.ok)
|
|
157
|
+
return read.error;
|
|
158
|
+
const found = read.value.issue;
|
|
159
|
+
if (found === null || found.trashed === true || (found.archivedAt ?? null) !== null) {
|
|
160
|
+
return permanentFailure("not_found", `linear: no card ${id}`);
|
|
161
|
+
}
|
|
162
|
+
const assignee = await assigneeOf(ctx, settings.value);
|
|
163
|
+
if (!assignee.ok)
|
|
164
|
+
return assignee.error;
|
|
165
|
+
const handedBack = found.labels.nodes.some((label) => label.name === WAITING);
|
|
166
|
+
if (settings.value.assignee_only && found.assignee?.id !== assignee.value && !handedBack) {
|
|
167
|
+
return permanentFailure("not_found", `linear: card ${id} is not assigned to the user of [extensions.linear] assignee`);
|
|
168
|
+
}
|
|
169
|
+
return toCard(settings.value, found, true, assignee.value);
|
|
170
|
+
}
|
|
171
|
+
const found = z.object({
|
|
172
|
+
identifier: z.string(),
|
|
173
|
+
title: z.string(),
|
|
174
|
+
url: z.string(),
|
|
175
|
+
createdAt: z.string(),
|
|
176
|
+
state: z.object({ name: z.string() }),
|
|
177
|
+
});
|
|
178
|
+
/** At most 10 open cards of the table's team and scope that Linear's search matches with `text`, the best match first; with `assignee_only`, only EDGAR's cards and those handed back. With `except`, that card and each card made after it are left out, so two cards never point at each other; a missing `except` is `not_found`. */
|
|
179
|
+
export async function findCards(ctx, text, except) {
|
|
180
|
+
const settings = settingsOf(ctx);
|
|
181
|
+
if (!settings.ok)
|
|
182
|
+
return settings.error;
|
|
183
|
+
let before;
|
|
184
|
+
if (except !== undefined) {
|
|
185
|
+
const read = await linear(ctx, "query Except($id: String!) { issue(id: $id) { createdAt } }", { id: except }, z.object({ issue: z.object({ createdAt: z.string() }).nullable() }));
|
|
186
|
+
if (!read.ok)
|
|
187
|
+
return read.error;
|
|
188
|
+
if (read.value.issue === null)
|
|
189
|
+
return permanentFailure("not_found", `linear: no card ${except}`);
|
|
190
|
+
before = read.value.issue.createdAt;
|
|
191
|
+
}
|
|
192
|
+
const assignee = await assigneeOf(ctx, settings.value);
|
|
193
|
+
if (!assignee.ok)
|
|
194
|
+
return assignee.error;
|
|
195
|
+
const only = settings.value.assignee_only ? assignee.value : undefined;
|
|
196
|
+
const narrow = scope(settings.value, [
|
|
197
|
+
...(before === undefined ? [] : ["{ createdAt: { lt: $before } }"]),
|
|
198
|
+
...(only === undefined ? [] : [mineOrWaiting]),
|
|
199
|
+
]);
|
|
200
|
+
const params = `${before === undefined ? "" : ", $before: DateTimeOrDuration!"}${only === undefined ? "" : ", $assignee: ID!"}${narrow.params}`;
|
|
201
|
+
const searched = await linear(ctx, `query FindCards($text: String!, $team: String!${params}) { searchIssues(term: $text, first: 10, filter: { team: { key: { eq: $team } }, state: { type: { nin: ["completed", "canceled"] } }${narrow.clauses} }) { nodes { identifier title url createdAt state { name } } } }`, {
|
|
202
|
+
text,
|
|
203
|
+
team: settings.value.team,
|
|
204
|
+
...(before === undefined ? {} : { before }),
|
|
205
|
+
...(only === undefined ? {} : { assignee: only }),
|
|
206
|
+
...narrow.variables,
|
|
207
|
+
}, z.object({ searchIssues: z.object({ nodes: z.array(found) }) }));
|
|
208
|
+
if (!searched.ok)
|
|
209
|
+
return searched.error;
|
|
210
|
+
return done({
|
|
211
|
+
cards: searched.value.searchIssues.nodes.map((node) => ({
|
|
212
|
+
id: node.identifier,
|
|
213
|
+
title: node.title,
|
|
214
|
+
url: node.url,
|
|
215
|
+
state: columnOf(settings.value, node.state.name, undefined, undefined) ?? node.state.name,
|
|
216
|
+
created_at: node.createdAt,
|
|
217
|
+
})),
|
|
218
|
+
});
|
|
219
|
+
}
|
|
220
|
+
const batched = z.object({
|
|
221
|
+
identifier: z.string(),
|
|
222
|
+
title: z.string(),
|
|
223
|
+
url: z.string(),
|
|
224
|
+
description: z.string().nullable(),
|
|
225
|
+
});
|
|
226
|
+
/** At most 20 open cards of the table's team and scope whose block names `batch` in `decided.batch`, with `except` left out; with `assignee_only`, only EDGAR's cards and those handed back. A card whose block does not read is left out. */
|
|
227
|
+
export async function batchCards(ctx, batch, except, ids) {
|
|
228
|
+
const settings = settingsOf(ctx);
|
|
229
|
+
if (!settings.ok)
|
|
230
|
+
return settings.error;
|
|
231
|
+
const assignee = await assigneeOf(ctx, settings.value);
|
|
232
|
+
if (!assignee.ok)
|
|
233
|
+
return assignee.error;
|
|
234
|
+
const only = settings.value.assignee_only ? assignee.value : undefined;
|
|
235
|
+
const narrow = scope(settings.value, only === undefined ? [] : [mineOrWaiting]);
|
|
236
|
+
const params = `${only === undefined ? "" : ", $assignee: ID!"}${narrow.params}`;
|
|
237
|
+
const listed = await linear(ctx, `query BatchCards($text: String!, $team: String!${params}) { issues(first: 21, filter: { team: { key: { eq: $team } }, description: { contains: $text }, state: { type: { nin: ["completed", "canceled"] } }${narrow.clauses} }) { nodes { identifier title url description } } }`, {
|
|
238
|
+
text: blockLine("batch", batch),
|
|
239
|
+
team: settings.value.team,
|
|
240
|
+
...(only === undefined ? {} : { assignee: only }),
|
|
241
|
+
...narrow.variables,
|
|
242
|
+
}, z.object({ issues: z.object({ nodes: z.array(batched) }) }));
|
|
243
|
+
if (!listed.ok)
|
|
244
|
+
return listed.error;
|
|
245
|
+
const cards = listed.value.issues.nodes.flatMap((node) => {
|
|
246
|
+
const description = node.description ?? "";
|
|
247
|
+
const block = readBlock(description);
|
|
248
|
+
const same = block.ok && block.value?.decided?.["batch"] === batch;
|
|
249
|
+
return same && node.identifier !== except
|
|
250
|
+
? [{ id: node.identifier, title: node.title, url: node.url, description }]
|
|
251
|
+
: [];
|
|
252
|
+
});
|
|
253
|
+
return done(kept(cards, ids));
|
|
254
|
+
}
|
|
255
|
+
/** The first 20 `cards`, or with `only`, those of its ids and the ids of `only` not found. */
|
|
256
|
+
function kept(cards, only) {
|
|
257
|
+
if (only === undefined)
|
|
258
|
+
return { cards: cards.slice(0, 20) };
|
|
259
|
+
const wanted = new Set(only);
|
|
260
|
+
const found = cards.filter((card) => wanted.has(card.id)).slice(0, 20);
|
|
261
|
+
const ids = new Set(found.map((card) => card.id));
|
|
262
|
+
const skipped = [...wanted].filter((id) => !ids.has(id));
|
|
263
|
+
return skipped.length === 0 ? { cards: found } : { cards: found, skipped };
|
|
264
|
+
}
|
|
265
|
+
/**
|
|
266
|
+
* Raises `occurrences` and `last_seen` in the holder's block for one more sighting at `at`; a holder with no readable block, or a retried sighting, is not written.
|
|
267
|
+
* A count refused for good is logged and dropped, because the card was found and a count never costs the stage its card.
|
|
268
|
+
*/
|
|
269
|
+
async function countSighting(ctx, holder, at) {
|
|
270
|
+
const description = holder.description ?? "";
|
|
271
|
+
const block = readBlock(description);
|
|
272
|
+
if (!block.ok || block.value === null)
|
|
273
|
+
return ok(null);
|
|
274
|
+
const next = sighted(block.value, at);
|
|
275
|
+
if (next === null)
|
|
276
|
+
return ok(null);
|
|
277
|
+
const written = await update(ctx, holder.id, { description: withBlock(description, next) });
|
|
278
|
+
if (written.ok || written.error.outcome === "temporary_failure")
|
|
279
|
+
return written;
|
|
280
|
+
ctx.log(`sighting not counted on ${holder.identifier}: ${written.error.message}`);
|
|
281
|
+
return ok(null);
|
|
282
|
+
}
|
|
283
|
+
/** Counts one more sighting, at `seen` or now, of the fault that the card `card` holds, for a fault that a run found again without filing a card. */
|
|
284
|
+
export async function countSightingOn(ctx, card, seen) {
|
|
285
|
+
const read = await linear(ctx, "query Held($id: String!) { issue(id: $id) { id identifier url description } }", { id: card }, z.object({ issue: heldIssue.nullable() }));
|
|
286
|
+
if (!read.ok)
|
|
287
|
+
return read.error;
|
|
288
|
+
const holder = read.value.issue;
|
|
289
|
+
if (holder === null)
|
|
290
|
+
return permanentFailure("not_found", `linear: no card ${card}`);
|
|
291
|
+
const counted = await countSighting(ctx, holder, seen ?? new Date().toISOString());
|
|
292
|
+
return counted.ok ? done({ id: holder.identifier }) : counted.error;
|
|
293
|
+
}
|
|
294
|
+
/** Files a card inside the table's scope, or returns the open card that already holds the block's fingerprint. With `assignee_only`, the new card is assigned to `assignee`, so it is in scope from its first sweep. Calls with one fingerprint run one at a time in this process, so the second finds the card the first filed. */
|
|
295
|
+
export async function createCard(ctx, spec, parent) {
|
|
296
|
+
const fingerprint = spec.block.fingerprint;
|
|
297
|
+
if (fingerprint === undefined)
|
|
298
|
+
return await fileCard(ctx, spec, parent);
|
|
299
|
+
return await oneAtATime(`linear:${fingerprint}`, () => fileCard(ctx, spec, parent));
|
|
300
|
+
}
|
|
301
|
+
/** One `create_card` call: the holder search, then the new card. */
|
|
302
|
+
async function fileCard(ctx, spec, parent) {
|
|
303
|
+
const settings = settingsOf(ctx);
|
|
304
|
+
if (!settings.ok)
|
|
305
|
+
return settings.error;
|
|
306
|
+
const team = settings.value.team;
|
|
307
|
+
const fingerprint = spec.block.fingerprint;
|
|
308
|
+
if (fingerprint !== undefined) {
|
|
309
|
+
const held = await linear(ctx, `query Holder($team: String!, $text: String!) { issues(first: 1, filter: { team: { key: { eq: $team } }, description: { contains: $text }, state: { type: { nin: ["completed", "canceled"] } } }) { nodes { id identifier url description } } }`, { team, text: blockLine("fingerprint", fingerprint) }, z.object({ issues: z.object({ nodes: z.array(heldIssue) }) }));
|
|
310
|
+
if (!held.ok)
|
|
311
|
+
return held.error;
|
|
312
|
+
const [holder] = held.value.issues.nodes;
|
|
313
|
+
if (holder !== undefined) {
|
|
314
|
+
const at = spec.block.last_seen ?? new Date().toISOString();
|
|
315
|
+
const counted = await countSighting(ctx, holder, at);
|
|
316
|
+
return counted.ok ? done({ id: holder.identifier, url: holder.url }) : counted.error;
|
|
317
|
+
}
|
|
318
|
+
}
|
|
319
|
+
const found = await linear(ctx, "query Team($team: String!) { teams(filter: { key: { eq: $team } }) { nodes { id states { nodes { id name } } } } }", { team }, z.object({
|
|
320
|
+
teams: z.object({ nodes: z.array(z.object({ id: z.string(), states: idNames })) }),
|
|
321
|
+
}));
|
|
322
|
+
if (!found.ok)
|
|
323
|
+
return found.error;
|
|
324
|
+
const [owner] = found.value.teams.nodes;
|
|
325
|
+
if (owner === undefined)
|
|
326
|
+
return permanentFailure("invalid", `linear: no team ${team}`, { cause: team });
|
|
327
|
+
const columnName = spec.column !== undefined && isState(spec.column)
|
|
328
|
+
? settings.value.columns[spec.column]
|
|
329
|
+
: undefined;
|
|
330
|
+
const stateId = owner.states.nodes.find((state) => state.name === columnName)?.id;
|
|
331
|
+
const labels = await labelIds(ctx, [
|
|
332
|
+
...new Set([...(spec.labels ?? []), ...(settings.value.labels ?? [])]),
|
|
333
|
+
]);
|
|
334
|
+
if (!labels.ok)
|
|
335
|
+
return labels.error;
|
|
336
|
+
const project = settings.value.project;
|
|
337
|
+
const inProject = project === undefined ? undefined : await projectId(ctx, project);
|
|
338
|
+
if (inProject !== undefined && !inProject.ok)
|
|
339
|
+
return inProject.error;
|
|
340
|
+
const parentId = parent === undefined ? undefined : await issueId(ctx, parent);
|
|
341
|
+
if (parentId !== undefined && !parentId.ok)
|
|
342
|
+
return parentId.error;
|
|
343
|
+
const assignee = settings.value.assignee_only
|
|
344
|
+
? await assigneeOf(ctx, settings.value)
|
|
345
|
+
: ok(undefined);
|
|
346
|
+
if (!assignee.ok)
|
|
347
|
+
return assignee.error;
|
|
348
|
+
const prefix = settings.value.title_prefix ?? "";
|
|
349
|
+
const id = keyOf(ctx.operation_id);
|
|
350
|
+
const made = await linear(ctx, "mutation IssueCreate($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { identifier url } } }", {
|
|
351
|
+
input: {
|
|
352
|
+
id,
|
|
353
|
+
teamId: owner.id,
|
|
354
|
+
title: spec.title.startsWith(prefix) ? spec.title : `${prefix} ${spec.title}`,
|
|
355
|
+
description: withBlock(spec.description, spec.block),
|
|
356
|
+
...(stateId === undefined ? {} : { stateId }),
|
|
357
|
+
...(labels.value.length === 0 ? {} : { labelIds: labels.value }),
|
|
358
|
+
...(inProject === undefined ? {} : { projectId: inProject.value }),
|
|
359
|
+
...(parentId === undefined ? {} : { parentId: parentId.value }),
|
|
360
|
+
...(assignee.value === undefined ? {} : { assigneeId: assignee.value }),
|
|
361
|
+
},
|
|
362
|
+
}, z.object({ issueCreate: z.object({ success: z.boolean(), issue: created }) }));
|
|
363
|
+
if (made.ok)
|
|
364
|
+
return done({
|
|
365
|
+
id: made.value.issueCreate.issue.identifier,
|
|
366
|
+
url: made.value.issueCreate.issue.url,
|
|
367
|
+
});
|
|
368
|
+
const earlier = await linear(ctx, "query Created($id: String!) { issue(id: $id) { identifier url } }", { id }, z.object({ issue: created.nullable() }));
|
|
369
|
+
return earlier.ok && earlier.value.issue !== null
|
|
370
|
+
? done({ id: earlier.value.issue.identifier, url: earlier.value.issue.url })
|
|
371
|
+
: made.error;
|
|
372
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { Attachment, Comment } from "@kana-ai/edgar-contracts/rpc";
|
|
2
|
+
import { type Outcome } from "@kana-ai/edgar-sdk";
|
|
3
|
+
import { type LinearCtx } from "#api/client";
|
|
4
|
+
/** Posts a comment keyed by the operation id; a repeat finds the first comment instead of posting twice. */
|
|
5
|
+
export declare function postComment(ctx: LinearCtx, card: string, body: string): Promise<Outcome<{
|
|
6
|
+
id: string;
|
|
7
|
+
}>>;
|
|
8
|
+
/** The comments of card `id` since `since`, oldest first, each flagged when it mentions the token's user. */
|
|
9
|
+
export declare function listComments(ctx: LinearCtx, id: string, since: string | null): Promise<Outcome<Comment[]>>;
|
|
10
|
+
/** The attachments of card `id`. */
|
|
11
|
+
export declare function listAttachments(ctx: LinearCtx, id: string): Promise<Outcome<Attachment[]>>;
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
import { done, permanentFailure } from "@kana-ai/edgar-sdk";
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
import { keyOf, linear } from "#api/client";
|
|
4
|
+
import { attachment, comment } from "#schemas/linear";
|
|
5
|
+
import { issueId } from "#tracker/cards";
|
|
6
|
+
/** Posts a comment keyed by the operation id; a repeat finds the first comment instead of posting twice. */
|
|
7
|
+
export async function postComment(ctx, card, body) {
|
|
8
|
+
const target = await issueId(ctx, card);
|
|
9
|
+
if (!target.ok)
|
|
10
|
+
return target.error;
|
|
11
|
+
const id = keyOf(ctx.operation_id);
|
|
12
|
+
const made = await linear(ctx, "mutation CommentCreate($input: CommentCreateInput!) { commentCreate(input: $input) { success comment { id } } }", { input: { id, issueId: target.value, body } }, z.object({
|
|
13
|
+
commentCreate: z.object({ success: z.boolean(), comment: z.object({ id: z.string() }) }),
|
|
14
|
+
}));
|
|
15
|
+
if (made.ok)
|
|
16
|
+
return done({ id: made.value.commentCreate.comment.id });
|
|
17
|
+
const earlier = await linear(ctx, "query Comment($id: String!) { comment(id: $id) { id } }", { id }, z.object({ comment: z.object({ id: z.string() }).nullable() }));
|
|
18
|
+
return earlier.ok && earlier.value.comment !== null ? done({ id }) : made.error;
|
|
19
|
+
}
|
|
20
|
+
/** The comments of card `id` since `since`, oldest first, each flagged when it mentions the token's user. */
|
|
21
|
+
export async function listComments(ctx, id, since) {
|
|
22
|
+
const read = await linear(ctx, "query Comments($id: String!, $filter: CommentFilter) { viewer { displayName } issue(id: $id) { comments(first: 100, filter: $filter) { nodes { id body createdAt user { id } botActor { id } } } } }", { id, filter: since === null ? {} : { createdAt: { gt: since } } }, z.object({
|
|
23
|
+
viewer: z.object({ displayName: z.string() }),
|
|
24
|
+
issue: z.object({ comments: z.object({ nodes: z.array(comment) }) }).nullable(),
|
|
25
|
+
}));
|
|
26
|
+
if (!read.ok)
|
|
27
|
+
return read.error;
|
|
28
|
+
if (read.value.issue === null)
|
|
29
|
+
return permanentFailure("not_found", `linear: no card ${id}`);
|
|
30
|
+
const mention = `@${read.value.viewer.displayName}`;
|
|
31
|
+
const comments = read.value.issue.comments.nodes
|
|
32
|
+
.map((node) => ({
|
|
33
|
+
id: node.id,
|
|
34
|
+
author: node.user?.id ?? node.botActor?.id ?? "",
|
|
35
|
+
text: node.body,
|
|
36
|
+
at: node.createdAt,
|
|
37
|
+
mentioned: node.body.includes(mention),
|
|
38
|
+
}))
|
|
39
|
+
.sort((a, b) => a.at.localeCompare(b.at));
|
|
40
|
+
return done(comments);
|
|
41
|
+
}
|
|
42
|
+
/** The attachments of card `id`. */
|
|
43
|
+
export async function listAttachments(ctx, id) {
|
|
44
|
+
const read = await linear(ctx, "query Attachments($id: String!) { issue(id: $id) { attachments(first: 50) { nodes { id title url } } } }", { id }, z.object({
|
|
45
|
+
issue: z
|
|
46
|
+
.object({
|
|
47
|
+
attachments: z.object({
|
|
48
|
+
nodes: z.array(attachment),
|
|
49
|
+
}),
|
|
50
|
+
})
|
|
51
|
+
.nullable(),
|
|
52
|
+
}));
|
|
53
|
+
if (!read.ok)
|
|
54
|
+
return read.error;
|
|
55
|
+
if (read.value.issue === null)
|
|
56
|
+
return permanentFailure("not_found", `linear: no card ${id}`);
|
|
57
|
+
return done(read.value.issue.attachments.nodes.map((node) => ({
|
|
58
|
+
id: node.id,
|
|
59
|
+
name: node.title,
|
|
60
|
+
url: node.url,
|
|
61
|
+
})));
|
|
62
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import { type Outcome } from "@kana-ai/edgar-sdk";
|
|
2
|
+
import { type LinearCtx } from "#api/client";
|
|
3
|
+
/** Replaces a card's description, keeping its block, and answers the description it replaced. A description that already reads so is not written again and gets no `previous`: this call cannot know what a lost earlier call replaced, so its undo writes nothing. */
|
|
4
|
+
export declare function updateDescription(ctx: LinearCtx, card: string, text: string): Promise<Outcome<{
|
|
5
|
+
id: string;
|
|
6
|
+
previous?: string;
|
|
7
|
+
}>>;
|
|
8
|
+
/**
|
|
9
|
+
* Writes `previous` back as the card's description, as it was before `update_description`, with the card's current block, so a count made since stays. With no `previous` the undone call wrote nothing, so this writes nothing.
|
|
10
|
+
*
|
|
11
|
+
* shortcut: a retried `update_description` whose first answer was lost has no `previous` either, so its undo leaves the new text; keep the replaced text in the first call's own record when a card must get it back.
|
|
12
|
+
*/
|
|
13
|
+
export declare function restoreDescription(ctx: LinearCtx, card: string, previous: string | undefined): Promise<Outcome<{
|
|
14
|
+
id: string;
|
|
15
|
+
}>>;
|
|
16
|
+
/** `done` when the card's description already is what `update_description` writes for `text`, else `skipped`: the lookup of a call that did not end. Its answer has no `previous`, so a later undo of a call it settled writes nothing, never a wipe. */
|
|
17
|
+
export declare function findDescription(ctx: LinearCtx, card: string, text: string): Promise<Outcome<{
|
|
18
|
+
id: string;
|
|
19
|
+
}>>;
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
import { done, err, ok, permanentFailure, readBlock, skipped, withBlock, } from "@kana-ai/edgar-sdk";
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
import { linear } from "#api/client";
|
|
4
|
+
import { update } from "#tracker/transitions";
|
|
5
|
+
/** The issue behind a card, and the description a replace with `text` writes: `text`, with the card's `edgar:v0` block kept, so the fingerprint and `waits_for` survive. */
|
|
6
|
+
async function planned(ctx, card, text) {
|
|
7
|
+
const read = await linear(ctx, "query Description($id: String!) { issue(id: $id) { id description } }", { id: card }, z.object({
|
|
8
|
+
issue: z.object({ id: z.string(), description: z.string().nullable() }).nullable(),
|
|
9
|
+
}));
|
|
10
|
+
if (!read.ok)
|
|
11
|
+
return err(read.error);
|
|
12
|
+
const issue = read.value.issue;
|
|
13
|
+
if (issue === null)
|
|
14
|
+
return err(permanentFailure("not_found", `linear: no card ${card}`));
|
|
15
|
+
const current = issue.description ?? "";
|
|
16
|
+
const block = readBlock(current);
|
|
17
|
+
const next = block.ok && block.value !== null ? withBlock(text, block.value) : text;
|
|
18
|
+
return ok({ id: issue.id, current, next });
|
|
19
|
+
}
|
|
20
|
+
/** Replaces a card's description, keeping its block, and answers the description it replaced. A description that already reads so is not written again and gets no `previous`: this call cannot know what a lost earlier call replaced, so its undo writes nothing. */
|
|
21
|
+
export async function updateDescription(ctx, card, text) {
|
|
22
|
+
const plan = await planned(ctx, card, text);
|
|
23
|
+
if (!plan.ok)
|
|
24
|
+
return plan.error;
|
|
25
|
+
const { id, current, next } = plan.value;
|
|
26
|
+
if (current === next)
|
|
27
|
+
return done({ id: card });
|
|
28
|
+
const written = await update(ctx, id, { description: next });
|
|
29
|
+
return written.ok ? done({ id: card, previous: current }) : written.error;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Writes `previous` back as the card's description, as it was before `update_description`, with the card's current block, so a count made since stays. With no `previous` the undone call wrote nothing, so this writes nothing.
|
|
33
|
+
*
|
|
34
|
+
* shortcut: a retried `update_description` whose first answer was lost has no `previous` either, so its undo leaves the new text; keep the replaced text in the first call's own record when a card must get it back.
|
|
35
|
+
*/
|
|
36
|
+
export async function restoreDescription(ctx, card, previous) {
|
|
37
|
+
if (previous === undefined)
|
|
38
|
+
return done({ id: card });
|
|
39
|
+
const plan = await planned(ctx, card, previous);
|
|
40
|
+
if (!plan.ok)
|
|
41
|
+
return plan.error;
|
|
42
|
+
const { id, current, next } = plan.value;
|
|
43
|
+
if (current === next)
|
|
44
|
+
return done({ id: card });
|
|
45
|
+
const written = await update(ctx, id, { description: next });
|
|
46
|
+
return written.ok ? done({ id: card }) : written.error;
|
|
47
|
+
}
|
|
48
|
+
/** `done` when the card's description already is what `update_description` writes for `text`, else `skipped`: the lookup of a call that did not end. Its answer has no `previous`, so a later undo of a call it settled writes nothing, never a wipe. */
|
|
49
|
+
export async function findDescription(ctx, card, text) {
|
|
50
|
+
const plan = await planned(ctx, card, text);
|
|
51
|
+
if (!plan.ok)
|
|
52
|
+
return plan.error;
|
|
53
|
+
const { current, next } = plan.value;
|
|
54
|
+
return current === next ? done({ id: card }) : skipped();
|
|
55
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import { type Outcome } from "@kana-ai/edgar-sdk";
|
|
2
|
+
import { type LinearCtx } from "#api/client";
|
|
3
|
+
/** Gives the card to the person who asked for the work: the newest person who assigned it to EDGAR, else its writer, never EDGAR's user, an app or a bot. Adds `edgar:waiting`, so with `assignee_only` the card and the person's reply stay in scope. A card that nobody can be given, such as a feeder's card, is `skipped`. */
|
|
4
|
+
export declare function handBack(ctx: LinearCtx, card: string): Promise<Outcome<{
|
|
5
|
+
id: string;
|
|
6
|
+
to: string;
|
|
7
|
+
previous: string;
|
|
8
|
+
}>>;
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import { done, err, ok, permanentFailure, skipped, } from "@kana-ai/edgar-sdk";
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
import { linear } from "#api/client";
|
|
4
|
+
import { idNames } from "#schemas/linear";
|
|
5
|
+
import { WAITING, assigneeOf, settingsOf, userId } from "#tracker/states";
|
|
6
|
+
import { update } from "#tracker/transitions";
|
|
7
|
+
const person = z.object({ id: z.string(), displayName: z.string(), app: z.boolean() });
|
|
8
|
+
const handed = z.object({
|
|
9
|
+
issue: z
|
|
10
|
+
.object({
|
|
11
|
+
id: z.string(),
|
|
12
|
+
team: z.object({ id: z.string() }),
|
|
13
|
+
assignee: z.object({ id: z.string() }).nullish(),
|
|
14
|
+
labels: idNames,
|
|
15
|
+
creator: person.nullish(),
|
|
16
|
+
history: z.object({
|
|
17
|
+
nodes: z.array(z.object({
|
|
18
|
+
createdAt: z.string(),
|
|
19
|
+
actor: person.nullish(),
|
|
20
|
+
toAssignee: z.object({ id: z.string() }).nullish(),
|
|
21
|
+
})),
|
|
22
|
+
}),
|
|
23
|
+
})
|
|
24
|
+
.nullable(),
|
|
25
|
+
});
|
|
26
|
+
/** The ids of EDGAR's own users: the user of `LINEAR_TOKEN`, and `[extensions.linear] assignee` when the table needs one. */
|
|
27
|
+
async function ownUsers(ctx) {
|
|
28
|
+
const settings = settingsOf(ctx);
|
|
29
|
+
if (!settings.ok)
|
|
30
|
+
return settings;
|
|
31
|
+
const me = await userId(ctx, "me");
|
|
32
|
+
if (!me.ok)
|
|
33
|
+
return me;
|
|
34
|
+
const assignee = await assigneeOf(ctx, settings.value);
|
|
35
|
+
if (!assignee.ok)
|
|
36
|
+
return assignee;
|
|
37
|
+
return ok(new Set([me.value, assignee.value].flatMap((id) => id ?? [])));
|
|
38
|
+
}
|
|
39
|
+
/** The id of the label `edgar:waiting` of the workspace or the card's team, made in the team when neither has one; another team's label is refused on the card. */
|
|
40
|
+
async function waitingLabel(ctx, team) {
|
|
41
|
+
const found = await linear(ctx, "query WaitingLabel($name: String!, $team: ID!) { issueLabels(first: 1, filter: { name: { eq: $name }, or: [{ team: { null: true } }, { team: { id: { eq: $team } } }] }) { nodes { id name } } }", { name: WAITING, team }, z.object({ issueLabels: idNames }));
|
|
42
|
+
if (!found.ok)
|
|
43
|
+
return found;
|
|
44
|
+
const [label] = found.value.issueLabels.nodes;
|
|
45
|
+
if (label !== undefined)
|
|
46
|
+
return ok(label.id);
|
|
47
|
+
const made = await linear(ctx, "mutation IssueLabelCreate($input: IssueLabelCreateInput!) { issueLabelCreate(input: $input) { success issueLabel { id } } }", { input: { name: WAITING, teamId: team } }, z.object({
|
|
48
|
+
issueLabelCreate: z.object({
|
|
49
|
+
success: z.boolean(),
|
|
50
|
+
issueLabel: z.object({ id: z.string() }),
|
|
51
|
+
}),
|
|
52
|
+
}));
|
|
53
|
+
if (!made.ok)
|
|
54
|
+
return made;
|
|
55
|
+
return made.value.issueLabelCreate.success
|
|
56
|
+
? ok(made.value.issueLabelCreate.issueLabel.id)
|
|
57
|
+
: err(permanentFailure("tool_error", "linear IssueLabelCreate: not applied", {
|
|
58
|
+
cause: "success: false",
|
|
59
|
+
}));
|
|
60
|
+
}
|
|
61
|
+
/** Gives the card to the person who asked for the work: the newest person who assigned it to EDGAR, else its writer, never EDGAR's user, an app or a bot. Adds `edgar:waiting`, so with `assignee_only` the card and the person's reply stay in scope. A card that nobody can be given, such as a feeder's card, is `skipped`. */
|
|
62
|
+
export async function handBack(ctx, card) {
|
|
63
|
+
const read = await linear(ctx, "query HandBack($id: String!) { issue(id: $id) { id team { id } assignee { id } labels { nodes { id name } } creator { id displayName app } history(first: 50) { nodes { createdAt actor { id displayName app } toAssignee { id } } } } }", { id: card }, handed);
|
|
64
|
+
if (!read.ok)
|
|
65
|
+
return read.error;
|
|
66
|
+
const issue = read.value.issue;
|
|
67
|
+
if (issue === null)
|
|
68
|
+
return permanentFailure("not_found", `linear: no card ${card}`);
|
|
69
|
+
const own = await ownUsers(ctx);
|
|
70
|
+
if (!own.ok)
|
|
71
|
+
return own.error;
|
|
72
|
+
const human = (who) => who !== null && who !== undefined && !who.app && !own.value.has(who.id);
|
|
73
|
+
const handOver = issue.history.nodes
|
|
74
|
+
.filter((entry) => own.value.has(entry.toAssignee?.id ?? ""))
|
|
75
|
+
.toSorted((a, b) => b.createdAt.localeCompare(a.createdAt))
|
|
76
|
+
.map((entry) => entry.actor)
|
|
77
|
+
.find(human);
|
|
78
|
+
const to = handOver ?? (human(issue.creator) ? issue.creator : undefined);
|
|
79
|
+
if (to === undefined)
|
|
80
|
+
return skipped();
|
|
81
|
+
const previous = issue.assignee?.id ?? "";
|
|
82
|
+
const labelled = issue.labels.nodes.some((label) => label.name === WAITING);
|
|
83
|
+
if (previous === to.id && labelled)
|
|
84
|
+
return done({ id: card, to: to.displayName, previous });
|
|
85
|
+
const label = labelled ? ok(undefined) : await waitingLabel(ctx, issue.team.id);
|
|
86
|
+
if (!label.ok)
|
|
87
|
+
return label.error;
|
|
88
|
+
const labelIds = [
|
|
89
|
+
...issue.labels.nodes.map((node) => node.id),
|
|
90
|
+
...(label.value === undefined ? [] : [label.value]),
|
|
91
|
+
];
|
|
92
|
+
const written = await update(ctx, issue.id, { assigneeId: to.id, labelIds });
|
|
93
|
+
return written.ok ? done({ id: card, to: to.displayName, previous }) : written.error;
|
|
94
|
+
}
|