@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.
Files changed (65) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +198 -2
  3. package/dist/src/api/client.d.ts +21 -0
  4. package/dist/src/api/client.js +53 -0
  5. package/dist/src/api/failures.d.ts +11 -0
  6. package/dist/src/api/failures.js +37 -0
  7. package/dist/src/index.d.ts +3 -0
  8. package/dist/src/index.js +19 -0
  9. package/dist/src/schemas/config.d.ts +25 -0
  10. package/dist/src/schemas/config.js +37 -0
  11. package/dist/src/schemas/linear.d.ts +116 -0
  12. package/dist/src/schemas/linear.js +57 -0
  13. package/dist/src/schemas/tools.d.ts +169 -0
  14. package/dist/src/schemas/tools.js +147 -0
  15. package/dist/src/tracker/assignee.d.ts +15 -0
  16. package/dist/src/tracker/assignee.js +58 -0
  17. package/dist/src/tracker/cards.d.ts +33 -0
  18. package/dist/src/tracker/cards.js +372 -0
  19. package/dist/src/tracker/comments.d.ts +11 -0
  20. package/dist/src/tracker/comments.js +62 -0
  21. package/dist/src/tracker/description.d.ts +19 -0
  22. package/dist/src/tracker/description.js +55 -0
  23. package/dist/src/tracker/hand-back.d.ts +8 -0
  24. package/dist/src/tracker/hand-back.js +94 -0
  25. package/dist/src/tracker/port.d.ts +2 -0
  26. package/dist/src/tracker/port.js +46 -0
  27. package/dist/src/tracker/states.d.ts +21 -0
  28. package/dist/src/tracker/states.js +82 -0
  29. package/dist/src/tracker/tools.d.ts +142 -0
  30. package/dist/src/tracker/tools.js +130 -0
  31. package/dist/src/tracker/transitions.d.ts +13 -0
  32. package/dist/src/tracker/transitions.js +94 -0
  33. package/edgar-extension.json +208 -0
  34. package/package.json +41 -3
  35. package/schemas/assign.in.json +15 -0
  36. package/schemas/assign.out.json +14 -0
  37. package/schemas/batch_cards.in.json +27 -0
  38. package/schemas/batch_cards.out.json +37 -0
  39. package/schemas/close.in.json +14 -0
  40. package/schemas/close.out.json +10 -0
  41. package/schemas/comment.in.json +19 -0
  42. package/schemas/comment.out.json +10 -0
  43. package/schemas/config.json +94 -0
  44. package/schemas/count_sighting.in.json +17 -0
  45. package/schemas/count_sighting.out.json +10 -0
  46. package/schemas/create_card.in.json +108 -0
  47. package/schemas/create_card.out.json +13 -0
  48. package/schemas/find_assignee.in.json +15 -0
  49. package/schemas/find_assignee.out.json +10 -0
  50. package/schemas/find_cards.in.json +18 -0
  51. package/schemas/find_cards.out.json +33 -0
  52. package/schemas/find_description.in.json +15 -0
  53. package/schemas/find_description.out.json +10 -0
  54. package/schemas/hand_back.in.json +11 -0
  55. package/schemas/hand_back.out.json +18 -0
  56. package/schemas/move.in.json +15 -0
  57. package/schemas/move.out.json +10 -0
  58. package/schemas/release_follow_ups.in.json +15 -0
  59. package/schemas/release_follow_ups.out.json +13 -0
  60. package/schemas/restore_assignee.in.json +20 -0
  61. package/schemas/restore_assignee.out.json +10 -0
  62. package/schemas/restore_description.in.json +20 -0
  63. package/schemas/restore_description.out.json +10 -0
  64. package/schemas/update_description.in.json +15 -0
  65. package/schemas/update_description.out.json +14 -0
@@ -0,0 +1,46 @@
1
+ import { defineTracker, done, permanentFailure } from "@kana-ai/edgar-sdk";
2
+ import { z } from "zod";
3
+ import { apiAccess, linear } from "#api/client";
4
+ import { createCard, issueId, labelIds, listCards, readCard } from "#tracker/cards";
5
+ import { listAttachments, listComments, postComment } from "#tracker/comments";
6
+ import { transition, update } from "#tracker/transitions";
7
+ function asNull(outcome) {
8
+ return outcome.outcome === "done" ? done(null) : outcome;
9
+ }
10
+ function asCreated(outcome) {
11
+ return outcome.outcome === "done" ? done({ id: outcome.output.id }) : outcome;
12
+ }
13
+ /** The tracker port over Linear's GraphQL API. */
14
+ export const tracker = defineTracker({
15
+ ...apiAccess,
16
+ list_cards: async (input, ctx) => await listCards(ctx, input),
17
+ card: async ({ id }, ctx) => await readCard(ctx, id),
18
+ comments: async ({ id, since }, ctx) => await listComments(ctx, id, since),
19
+ attachments: async ({ id }, ctx) => await listAttachments(ctx, id),
20
+ comment: async ({ card, text }, ctx) => asCreated(await postComment(ctx, card, text)),
21
+ move: async ({ card, column }, ctx) => asNull(await transition(ctx, card, column)),
22
+ set_labels: async ({ card, labels }, ctx) => {
23
+ const target = await issueId(ctx, card);
24
+ if (!target.ok)
25
+ return target.error;
26
+ const ids = await labelIds(ctx, labels);
27
+ if (!ids.ok)
28
+ return ids.error;
29
+ const updated = await update(ctx, target.value, { labelIds: ids.value });
30
+ return updated.ok ? done(null) : updated.error;
31
+ },
32
+ create_card: async ({ spec }, ctx) => asCreated(await createCard(ctx, spec)),
33
+ close: async ({ card }, ctx) => asNull(await transition(ctx, card, "done", true)),
34
+ whoami: async (_input, ctx) => {
35
+ const read = await linear(ctx, "query Viewer { viewer { id } }", {}, z.object({ viewer: z.object({ id: z.string() }) }));
36
+ return read.ok ? done({ actor: read.value.viewer.id }) : read.error;
37
+ },
38
+ person: async ({ actor }, ctx) => {
39
+ const read = await linear(ctx, "query Person($id: String!) { user(id: $id) { name email } }", { id: actor }, z.object({ user: z.object({ name: z.string(), email: z.string() }).nullable() }));
40
+ if (!read.ok)
41
+ return read.error;
42
+ return read.value.user === null
43
+ ? permanentFailure("not_found", `linear: no person ${actor}`)
44
+ : done(read.value.user);
45
+ },
46
+ });
@@ -0,0 +1,21 @@
1
+ import { type Failure, type Result } from "@kana-ai/edgar-sdk";
2
+ import { type LinearCtx } from "#api/client";
3
+ import { type Config, type State } from "#schemas/config";
4
+ /** The label of a card that EDGAR handed to a person; with `assignee_only`, it keeps the card in scope while the person holds it. */
5
+ export declare const WAITING = "edgar:waiting";
6
+ /** The engine states in their forward order. */
7
+ export declare const states: readonly ["intake", "ready", "working", "in_review", "waiting_on_person", "in_testing", "done", "cancelled"];
8
+ /** True for a name the column mapping knows as an engine state. */
9
+ export declare function isState(value: string): value is State;
10
+ /** The engine state a Linear column maps to, or `undefined` for a column the mapping does not name. */
11
+ export declare function stateOf(settings: Config, name: string): State | undefined;
12
+ /** True when moving from `from` to `to` goes forward in the mapping. A card that waits on a person goes on to any other column: the person's answer decides which. */
13
+ export declare function forward(from: State, to: State): boolean;
14
+ /** The call's `[extensions.linear]` table, or `invalid` with the fields that do not match. */
15
+ export declare function settingsOf(ctx: LinearCtx): Result<Config, Failure>;
16
+ /** The engine state of a card in column `name`: the mapped state, or `intake` for a card in a column of `assigned` whose assignee is `assignee`. */
17
+ export declare function columnOf(settings: Config, name: string, assignee: string | undefined, cardAssignee: string | undefined): State | undefined;
18
+ /** The Linear id of the user that `user` names: `me` is the user of `LINEAR_TOKEN`, a text with `@` is an email, and any other text is an id that Linear must have. `undefined` when the workspace has no such user. A user is found once for the life of the process. */
19
+ export declare function userId(ctx: LinearCtx, user: string): Promise<Result<string | undefined, Failure>>;
20
+ /** The id of the user of `[extensions.linear] assignee`, who is the user of `LINEAR_TOKEN` when the table names none, or `undefined` when the table needs no user: `assigned` names no column and `assignee_only` is off. A user the workspace does not have is a permanent `invalid` that names it. */
21
+ export declare function assigneeOf(ctx: LinearCtx, settings: Config): Promise<Result<string | undefined, Failure>>;
@@ -0,0 +1,82 @@
1
+ import { err, ok, permanentFailure } from "@kana-ai/edgar-sdk";
2
+ import { linear } from "#api/client";
3
+ import { config } from "#schemas/config";
4
+ import { userById, userIds, viewerId } from "#schemas/linear";
5
+ /** The label of a card that EDGAR handed to a person; with `assignee_only`, it keeps the card in scope while the person holds it. */
6
+ export const WAITING = "edgar:waiting";
7
+ /** The engine states in their forward order. */
8
+ export const states = [
9
+ "intake",
10
+ "ready",
11
+ "working",
12
+ "in_review",
13
+ "waiting_on_person",
14
+ "in_testing",
15
+ "done",
16
+ "cancelled",
17
+ ];
18
+ /** True for a name the column mapping knows as an engine state. */
19
+ export function isState(value) {
20
+ return states.some((state) => state === value);
21
+ }
22
+ /** The engine state a Linear column maps to, or `undefined` for a column the mapping does not name. */
23
+ export function stateOf(settings, name) {
24
+ return states.find((state) => settings.columns[state] === name);
25
+ }
26
+ /** True when moving from `from` to `to` goes forward in the mapping. A card that waits on a person goes on to any other column: the person's answer decides which. */
27
+ export function forward(from, to) {
28
+ if (from === "waiting_on_person")
29
+ return to !== from;
30
+ return states.indexOf(to) > states.indexOf(from);
31
+ }
32
+ /** The call's `[extensions.linear]` table, or `invalid` with the fields that do not match. */
33
+ export function settingsOf(ctx) {
34
+ const parsed = config.safeParse(ctx.config);
35
+ return parsed.success
36
+ ? ok(parsed.data)
37
+ : err(permanentFailure("invalid", "the [extensions.linear] table does not match its schema", {
38
+ cause: parsed.error.issues.map((issue) => issue.path.join(".")).join(", "),
39
+ }));
40
+ }
41
+ /** The engine state of a card in column `name`: the mapped state, or `intake` for a card in a column of `assigned` whose assignee is `assignee`. */
42
+ export function columnOf(settings, name, assignee, cardAssignee) {
43
+ const mapped = stateOf(settings, name);
44
+ if (mapped !== undefined)
45
+ return mapped;
46
+ const taken = assignee !== undefined && cardAssignee === assignee && settings.assigned.includes(name);
47
+ return taken ? "intake" : undefined;
48
+ }
49
+ /** The Linear user ids found so far, by the text that names the user (`me`, an email or an id), kept for the life of the process. */
50
+ const users = new Map();
51
+ async function findUser(ctx, user) {
52
+ if (user === "me") {
53
+ const me = await linear(ctx, "query Viewer { viewer { id } }", {}, viewerId);
54
+ return me.ok ? ok(me.value.viewer.id) : me;
55
+ }
56
+ if (user.includes("@")) {
57
+ const found = await linear(ctx, "query User($email: String!) { users(first: 1, filter: { email: { eq: $email } }) { nodes { id } } }", { email: user }, userIds);
58
+ return found.ok ? ok(found.value.users.nodes[0]?.id) : found;
59
+ }
60
+ const found = await linear(ctx, "query UserId($id: String!) { user(id: $id) { id } }", { id: user }, userById);
61
+ return found.ok ? ok(found.value.user?.id) : found;
62
+ }
63
+ /** The Linear id of the user that `user` names: `me` is the user of `LINEAR_TOKEN`, a text with `@` is an email, and any other text is an id that Linear must have. `undefined` when the workspace has no such user. A user is found once for the life of the process. */
64
+ export async function userId(ctx, user) {
65
+ const known = users.get(user);
66
+ if (known !== undefined)
67
+ return ok(known);
68
+ const found = await findUser(ctx, user);
69
+ if (found.ok && found.value !== undefined)
70
+ users.set(user, found.value);
71
+ return found;
72
+ }
73
+ /** The id of the user of `[extensions.linear] assignee`, who is the user of `LINEAR_TOKEN` when the table names none, or `undefined` when the table needs no user: `assigned` names no column and `assignee_only` is off. A user the workspace does not have is a permanent `invalid` that names it. */
74
+ export async function assigneeOf(ctx, settings) {
75
+ if (settings.assigned.length === 0 && !settings.assignee_only)
76
+ return ok(undefined);
77
+ const wanted = settings.assignee ?? "me";
78
+ const found = await userId(ctx, wanted);
79
+ if (!found.ok || found.value !== undefined)
80
+ return found;
81
+ return err(permanentFailure("invalid", `[extensions.linear] assignee names ${wanted}, and no user of this Linear workspace has that ${wanted.includes("@") ? "email" : "id"}`));
82
+ }
@@ -0,0 +1,142 @@
1
+ /** Every tool of the Linear extension, by the name the manifest gives it. */
2
+ export declare const tools: {
3
+ comment: import("@kana-ai/edgar-sdk").Tool<{
4
+ card: string;
5
+ text: string;
6
+ link?: string;
7
+ }, {
8
+ id: string;
9
+ }, "LINEAR_TOKEN">;
10
+ move: import("@kana-ai/edgar-sdk").Tool<{
11
+ card: string;
12
+ column: string;
13
+ }, {
14
+ column: string;
15
+ }, "LINEAR_TOKEN">;
16
+ close: import("@kana-ai/edgar-sdk").Tool<{
17
+ card: string;
18
+ reason: string;
19
+ }, {
20
+ state: string;
21
+ }, "LINEAR_TOKEN">;
22
+ create_card: import("@kana-ai/edgar-sdk").Tool<{
23
+ spec: {
24
+ title: string;
25
+ description: string;
26
+ column?: string;
27
+ labels?: string[];
28
+ block: {
29
+ kind: "defect" | "investigation" | "question" | "request";
30
+ service?: string;
31
+ environment?: string;
32
+ fingerprint?: string;
33
+ first_seen?: string;
34
+ last_seen?: string;
35
+ occurrences?: number;
36
+ severity?: string;
37
+ window?: string;
38
+ waits_for?: string;
39
+ decided?: Record<string, string>;
40
+ origin?: {
41
+ extension: string;
42
+ channel: string;
43
+ thread: string;
44
+ };
45
+ };
46
+ };
47
+ parent?: string;
48
+ }, {
49
+ id: string;
50
+ url: string;
51
+ }, "LINEAR_TOKEN">;
52
+ release_follow_ups: import("@kana-ai/edgar-sdk").Tool<{
53
+ card: string;
54
+ pull_request: string;
55
+ }, {
56
+ released: string[];
57
+ }, "LINEAR_TOKEN">;
58
+ /** A retry with the same `seen_at` finds the sighting counted and writes nothing; with no `seen_at`, a retry whose first answer was lost counts it twice. */
59
+ count_sighting: import("@kana-ai/edgar-sdk").Tool<{
60
+ card: string;
61
+ seen_at?: string;
62
+ }, {
63
+ id: string;
64
+ }, "LINEAR_TOKEN">;
65
+ batch_cards: import("@kana-ai/edgar-sdk").Tool<{
66
+ batch: string;
67
+ except: string;
68
+ only?: string[] | undefined;
69
+ }, {
70
+ cards: {
71
+ id: string;
72
+ title: string;
73
+ url: string;
74
+ description: string;
75
+ }[];
76
+ skipped?: string[] | undefined;
77
+ }, "LINEAR_TOKEN">;
78
+ find_cards: import("@kana-ai/edgar-sdk").Tool<{
79
+ text: string;
80
+ except?: string;
81
+ }, {
82
+ cards: {
83
+ id: string;
84
+ title: string;
85
+ url: string;
86
+ state: string;
87
+ created_at: string;
88
+ }[];
89
+ }, "LINEAR_TOKEN">;
90
+ /** A retry reads the card again and writes nothing when the person and the label are already there. */
91
+ hand_back: import("@kana-ai/edgar-sdk").Tool<{
92
+ card: string;
93
+ }, {
94
+ id: string;
95
+ to: string;
96
+ previous: string;
97
+ }, "LINEAR_TOKEN">;
98
+ /** A retry writes the same text again, which changes nothing; the lookup tells boot whether a call that did not end wrote it. */
99
+ update_description: import("@kana-ai/edgar-sdk").Tool<{
100
+ card: string;
101
+ description: string;
102
+ }, {
103
+ id: string;
104
+ previous?: string | undefined;
105
+ }, "LINEAR_TOKEN">;
106
+ restore_description: import("@kana-ai/edgar-sdk").Tool<{
107
+ stage_output: {
108
+ id: string;
109
+ previous?: string | undefined;
110
+ };
111
+ }, {
112
+ id: string;
113
+ }, "LINEAR_TOKEN">;
114
+ find_description: import("@kana-ai/edgar-sdk").Tool<{
115
+ card: string;
116
+ description: string;
117
+ }, {
118
+ id: string;
119
+ }, "LINEAR_TOKEN">;
120
+ /** A retry reads the card again and writes nothing when it already has that assignee; the lookup tells boot whether a call that did not end wrote it. */
121
+ assign: import("@kana-ai/edgar-sdk").Tool<{
122
+ card: string;
123
+ user: string;
124
+ }, {
125
+ id: string;
126
+ previous?: string | undefined;
127
+ }, "LINEAR_TOKEN">;
128
+ restore_assignee: import("@kana-ai/edgar-sdk").Tool<{
129
+ stage_output: {
130
+ id: string;
131
+ previous?: string | undefined;
132
+ };
133
+ }, {
134
+ id: string;
135
+ }, "LINEAR_TOKEN">;
136
+ find_assignee: import("@kana-ai/edgar-sdk").Tool<{
137
+ card: string;
138
+ user: string;
139
+ }, {
140
+ id: string;
141
+ }, "LINEAR_TOKEN">;
142
+ };
@@ -0,0 +1,130 @@
1
+ import { defineTool, done } from "@kana-ai/edgar-sdk";
2
+ import { apiAccess } from "#api/client";
3
+ import { assignTool, batchCardsTool, closeTool, commentTool, countSightingTool, createCardTool, descriptionTool, findCardsTool, handBackTool, moveTool, releaseFollowUpsTool, restoreTool, } from "#schemas/tools";
4
+ import { assign, findAssignee, restoreAssignee } from "#tracker/assignee";
5
+ import { batchCards, countSightingOn, createCard, findCards } from "#tracker/cards";
6
+ import { postComment } from "#tracker/comments";
7
+ import { findDescription, restoreDescription, updateDescription } from "#tracker/description";
8
+ import { handBack } from "#tracker/hand-back";
9
+ import { releaseFollowUps, transition } from "#tracker/transitions";
10
+ /** Every tool of the Linear extension, by the name the manifest gives it. */
11
+ export const tools = {
12
+ comment: defineTool({
13
+ description: "Post a comment on a card, with an optional link on its own line",
14
+ input: commentTool.input,
15
+ output: commentTool.output,
16
+ ...apiAccess,
17
+ execute: async ({ card, text, link }, ctx) => await postComment(ctx, card, link === undefined ? text : `${text}\n\n${link}`),
18
+ }),
19
+ move: defineTool({
20
+ description: "Move a card to the column of an engine state, forward only; skipped otherwise",
21
+ input: moveTool.input,
22
+ output: moveTool.output,
23
+ ...apiAccess,
24
+ execute: async ({ card, column }, ctx) => await transition(ctx, card, column),
25
+ }),
26
+ close: defineTool({
27
+ description: "Close a card by moving it to the done column",
28
+ input: closeTool.input,
29
+ output: closeTool.output,
30
+ ...apiAccess,
31
+ execute: async ({ card }, ctx) => {
32
+ const closed = await transition(ctx, card, "done", true);
33
+ return closed.outcome === "done" ? done({ state: closed.output.column }) : closed;
34
+ },
35
+ }),
36
+ create_card: defineTool({
37
+ description: "File a card, or return the open card that holds its fingerprint",
38
+ input: createCardTool.input,
39
+ output: createCardTool.output,
40
+ ...apiAccess,
41
+ execute: async ({ spec, parent }, ctx) => await createCard(ctx, spec, parent),
42
+ }),
43
+ release_follow_ups: defineTool({
44
+ description: "Move the cards that wait for a card's merged pull request to ready",
45
+ input: releaseFollowUpsTool.input,
46
+ output: releaseFollowUpsTool.output,
47
+ ...apiAccess,
48
+ execute: async ({ card }, ctx) => await releaseFollowUps(ctx, card),
49
+ }),
50
+ /** A retry with the same `seen_at` finds the sighting counted and writes nothing; with no `seen_at`, a retry whose first answer was lost counts it twice. */
51
+ count_sighting: defineTool({
52
+ description: "Count one more sighting of the fault that an open card holds: raise occurrences and last_seen in its block; a card with no block is not written",
53
+ input: countSightingTool.input,
54
+ output: countSightingTool.output,
55
+ ...apiAccess,
56
+ execute: async ({ card, seen_at }, ctx) => await countSightingOn(ctx, card, seen_at),
57
+ }),
58
+ batch_cards: defineTool({
59
+ description: "List the other open cards of the team whose decided.batch is the given batch, such as the scanner cards of one repository",
60
+ input: batchCardsTool.input,
61
+ output: batchCardsTool.output,
62
+ ...apiAccess,
63
+ execute: async ({ batch, except, only }, ctx) => await batchCards(ctx, batch, except, only),
64
+ }),
65
+ find_cards: defineTool({
66
+ description: "Search the open cards of the team for words of a fault; with except, only cards made before that card",
67
+ input: findCardsTool.input,
68
+ output: findCardsTool.output,
69
+ ...apiAccess,
70
+ execute: async ({ text, except }, ctx) => await findCards(ctx, text, except),
71
+ }),
72
+ /** A retry reads the card again and writes nothing when the person and the label are already there. */
73
+ hand_back: defineTool({
74
+ description: "Assign a card to the person who handed it to EDGAR, else to its writer, and label it edgar:waiting; skipped when nobody can be given it",
75
+ input: handBackTool.input,
76
+ output: handBackTool.output,
77
+ ...apiAccess,
78
+ execute: async ({ card }, ctx) => await handBack(ctx, card),
79
+ }),
80
+ /** A retry writes the same text again, which changes nothing; the lookup tells boot whether a call that did not end wrote it. */
81
+ update_description: defineTool({
82
+ description: "Replace a card's description, keeping its edgar:v0 block",
83
+ input: descriptionTool.input,
84
+ output: descriptionTool.output,
85
+ ...apiAccess,
86
+ side_effect: true,
87
+ compensate: "restore_description",
88
+ lookup: "find_description",
89
+ execute: async ({ card, description }, ctx) => await updateDescription(ctx, card, description),
90
+ }),
91
+ restore_description: defineTool({
92
+ description: "Put back the description a card had before update_description",
93
+ input: restoreTool.input,
94
+ output: restoreTool.output,
95
+ ...apiAccess,
96
+ execute: async ({ stage_output }, ctx) => await restoreDescription(ctx, stage_output.id, stage_output.previous),
97
+ }),
98
+ find_description: defineTool({
99
+ description: "Done when a card's description already reads as update_description writes it; skipped otherwise",
100
+ input: descriptionTool.input,
101
+ output: restoreTool.output,
102
+ ...apiAccess,
103
+ execute: async ({ card, description }, ctx) => await findDescription(ctx, card, description),
104
+ }),
105
+ /** A retry reads the card again and writes nothing when it already has that assignee; the lookup tells boot whether a call that did not end wrote it. */
106
+ assign: defineTool({
107
+ description: "Assign a card to a user by email or id, to the user of the token with `me`, or to nobody with an empty user",
108
+ input: assignTool.input,
109
+ output: assignTool.output,
110
+ ...apiAccess,
111
+ side_effect: true,
112
+ compensate: "restore_assignee",
113
+ lookup: "find_assignee",
114
+ execute: async ({ card, user }, ctx) => await assign(ctx, card, user),
115
+ }),
116
+ restore_assignee: defineTool({
117
+ description: "Set back the assignee a card had before assign",
118
+ input: restoreTool.input,
119
+ output: restoreTool.output,
120
+ ...apiAccess,
121
+ execute: async ({ stage_output }, ctx) => await restoreAssignee(ctx, stage_output.id, stage_output.previous),
122
+ }),
123
+ find_assignee: defineTool({
124
+ description: "Done when a card already has the assignee that assign sets; skipped otherwise",
125
+ input: assignTool.input,
126
+ output: restoreTool.output,
127
+ ...apiAccess,
128
+ execute: async ({ card, user }, ctx) => await findAssignee(ctx, card, user),
129
+ }),
130
+ };
@@ -0,0 +1,13 @@
1
+ import { type Failure, type Outcome, type Result } from "@kana-ai/edgar-sdk";
2
+ import { type LinearCtx } from "#api/client";
3
+ import type { State } from "#schemas/config";
4
+ /** Moves a card to the column of `target`: forward only unless `force`, and `skipped` for a move the mapping does not cover. A move to any column but `waiting_on_person`, and a close, take `edgar:waiting` off, so the card no longer waits on a person. */
5
+ export declare function transition(ctx: LinearCtx, card: string, target: string, force?: boolean): Promise<Outcome<{
6
+ column: State;
7
+ }>>;
8
+ /** Applies `input` to the issue `id`; Linear answering `success: false` is `tool_error`. */
9
+ export declare function update(ctx: LinearCtx, id: string, input: Readonly<Record<string, unknown>>): Promise<Result<null, Failure>>;
10
+ /** Moves each card in `intake` whose block waits for `card` to `ready`, and returns the ids it moved. */
11
+ export declare function releaseFollowUps(ctx: LinearCtx, card: string): Promise<Outcome<{
12
+ released: string[];
13
+ }>>;
@@ -0,0 +1,94 @@
1
+ import { blockLine, done, err, ok, permanentFailure, readBlock, 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, columnOf, forward, isState, settingsOf } from "#tracker/states";
6
+ /** Moves a card to the column of `target`: forward only unless `force`, and `skipped` for a move the mapping does not cover. A move to any column but `waiting_on_person`, and a close, take `edgar:waiting` off, so the card no longer waits on a person. */
7
+ export async function transition(ctx, card, target, force = false) {
8
+ const settings = settingsOf(ctx);
9
+ if (!settings.ok)
10
+ return settings.error;
11
+ if (!isState(target))
12
+ return skipped();
13
+ const read = await linear(ctx, "query Move($id: String!) { issue(id: $id) { id state { name } assignee { id } labels { nodes { id name } } team { states { nodes { id name } } } } }", { id: card }, z.object({
14
+ issue: z
15
+ .object({
16
+ id: z.string(),
17
+ state: z.object({ name: z.string() }),
18
+ assignee: z.object({ id: z.string() }).nullish(),
19
+ labels: idNames,
20
+ team: z.object({ states: idNames }),
21
+ })
22
+ .nullable(),
23
+ }));
24
+ if (!read.ok)
25
+ return read.error;
26
+ const found = read.value.issue;
27
+ if (found === null)
28
+ return permanentFailure("not_found", `linear: no card ${card}`);
29
+ const assignee = await assigneeOf(ctx, settings.value);
30
+ if (!assignee.ok)
31
+ return assignee.error;
32
+ const from = columnOf(settings.value, found.state.name, assignee.value, found.assignee?.id);
33
+ const kept = found.labels.nodes.filter((label) => label.name !== WAITING);
34
+ const labelIds = target === "waiting_on_person" || kept.length === found.labels.nodes.length
35
+ ? undefined
36
+ : kept.map((label) => label.id);
37
+ if (from === target) {
38
+ if (!force)
39
+ return skipped();
40
+ if (labelIds === undefined)
41
+ return done({ column: target });
42
+ const unlabelled = await update(ctx, found.id, { labelIds });
43
+ return unlabelled.ok ? done({ column: target }) : unlabelled.error;
44
+ }
45
+ if (!force && (from === undefined || !forward(from, target)))
46
+ return skipped();
47
+ const name = settings.value.columns[target];
48
+ const stateId = found.team.states.nodes.find((state) => state.name === name)?.id;
49
+ if (stateId === undefined) {
50
+ return permanentFailure("invalid", `linear: the team has no column ${name}`, { cause: name });
51
+ }
52
+ const moved = await update(ctx, found.id, labelIds === undefined ? { stateId } : { stateId, labelIds });
53
+ return moved.ok ? done({ column: target }) : moved.error;
54
+ }
55
+ /** Applies `input` to the issue `id`; Linear answering `success: false` is `tool_error`. */
56
+ export async function update(ctx, id, input) {
57
+ const updated = await linear(ctx, "mutation IssueUpdate($id: String!, $input: IssueUpdateInput!) { issueUpdate(id: $id, input: $input) { success } }", { id, input }, z.object({ issueUpdate: z.object({ success: z.boolean() }) }));
58
+ if (!updated.ok)
59
+ return updated;
60
+ return updated.value.issueUpdate.success
61
+ ? ok(null)
62
+ : err(permanentFailure("tool_error", "linear IssueUpdate: not applied", {
63
+ cause: "success: false",
64
+ }));
65
+ }
66
+ /** Moves each card in `intake` whose block waits for `card` to `ready`, and returns the ids it moved. */
67
+ export async function releaseFollowUps(ctx, card) {
68
+ const settings = settingsOf(ctx);
69
+ if (!settings.ok)
70
+ return settings.error;
71
+ const waiting = await linear(ctx, `query Waiting($team: String!, $text: String!, $intake: String!) { issues(first: 50, filter: { team: { key: { eq: $team } }, description: { contains: $text }, state: { name: { eq: $intake } } }) { nodes { identifier description } } }`, {
72
+ team: settings.value.team,
73
+ text: blockLine("waits_for", card),
74
+ intake: settings.value.columns.intake,
75
+ }, z.object({
76
+ issues: z.object({
77
+ nodes: z.array(z.object({ identifier: z.string(), description: z.string().nullable() })),
78
+ }),
79
+ }));
80
+ if (!waiting.ok)
81
+ return waiting.error;
82
+ const released = [];
83
+ for (const node of waiting.value.issues.nodes) {
84
+ const block = readBlock(node.description ?? "");
85
+ if (!block.ok || block.value?.waits_for !== card)
86
+ continue;
87
+ const moved = await transition(ctx, node.identifier, "ready");
88
+ if (moved.outcome === "done")
89
+ released.push(node.identifier);
90
+ else if (moved.outcome !== "skipped")
91
+ return moved;
92
+ }
93
+ return done({ released });
94
+ }