@theholocron/holocron-plugin-linear 5.0.0-alpha.500 → 5.0.0-alpha.502

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/dist/index.d.mts CHANGED
@@ -4,7 +4,7 @@
4
4
  * Implements `issues` and `projects` against Linear's GraphQL API, and `export`/`import` on `issues` so
5
5
  * `holocron migrate` can move issues between Linear and another tracker.
6
6
  */
7
- import { AuthError, BoardItem, BoardState, BoardSummary, BoardTemplate, EnsureReport, ExportInfo, ImportOptions, ImportResult, Issue, IssueRecord, IssueSearchFilter, IssueSelector, Issues, LifecycleResult, LifecycleSlot, MoveReport, PluginToken, Projects, ProviderAction, ResolveTokenInput, SyncResult, TrackerDoctorReport, TrackerUser, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
7
+ import { AuthError, BoardItem, BoardState, BoardSummary, BoardTemplate, EnsureReport, ExportInfo, ImportOptions, ImportResult, Issue, IssueCreateInput, IssuePatch, IssueRecord, IssueSearchFilter, IssueSelector, IssueUpdateResult, Issues, LifecycleResult, LifecycleSlot, MoveReport, PluginToken, Projects, ProviderAction, ResolveTokenInput, SyncResult, TrackerDoctorReport, TrackerUser, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
8
8
  import { LinearClient, LinearClientOptions, LinearTeam, createLinearClient } from "@theholocron/linear-client";
9
9
  /** Resolves the Linear token from `--token`, `HOLOCRON_LINEAR_TOKEN`, `LINEAR_API_KEY` or the keyring, and throws an `AuthError` when none is set. */
10
10
  export declare const resolveToken: import("@theholocron/cli").TokenResolver;
@@ -42,17 +42,17 @@ export declare class LinearIssues implements Issues {
42
42
  search(filter: IssueSearchFilter): Promise<Issue[]>;
43
43
  /** One issue by its key. */
44
44
  get(key: string): Promise<Issue>;
45
- /** Makes an issue; labels the team lacks are made, and `milestone` is a project's name or id. */
46
- create(input: {
47
- summary: string;
48
- body?: string;
49
- labels?: string[];
50
- milestone?: string;
51
- assignees?: string[];
52
- }): Promise<{
45
+ /**
46
+ * Makes an issue; labels the team lacks are made, and `milestone` is a project's name or id. Priority, the target
47
+ * date (Linear's due date) and the parent are set in the create call, the kind as its label, the estimate and the
48
+ * blockers after it; what Linear cannot hold (a start date) or refuses comes back in `dropped`.
49
+ */
50
+ create(input: IssueCreateInput): Promise<{
53
51
  key: string;
54
52
  dropped?: string[];
55
53
  }>;
54
+ /** Changes an issue; see {@link updateLinearIssue}. */
55
+ update(key: string, patch: IssuePatch): Promise<IssueUpdateResult>;
56
56
  /** Moves the issue to the state its slot names. Idempotent. */
57
57
  transition(key: string, slot: LifecycleSlot): Promise<LifecycleResult>;
58
58
  /** Adds a comment to the issue. */
@@ -66,6 +66,8 @@ export declare class LinearIssues implements Issues {
66
66
  /** Like `import`, and it also updates what an earlier import or sync made, for `holocron sync issues`. */
67
67
  sync(records: IssueRecord[], options?: ImportOptions): Promise<SyncResult[]>;
68
68
  private stateFor;
69
+ private findAssignee;
70
+ private projectId;
69
71
  private labelIds;
70
72
  }
71
73
  /** The names of the two automations the team settings expose, which a template's `rules` can ask for. */
package/dist/index.mjs CHANGED
@@ -437,6 +437,166 @@ async function syncIssues(scope, records, options = {}) {
437
437
  }
438
438
  return records.filter((r) => results.has(r.key)).map((r) => results.get(r.key));
439
439
  }
440
+ // src/capabilities/issues-update.ts
441
+ /** Linear's estimate for each effort, on the usual 1-3-5 scale. */
442
+ const ESTIMATE = {
443
+ low: 1,
444
+ medium: 3,
445
+ high: 5
446
+ };
447
+ /** The canonical label that stands for each kind where there is no Type. */
448
+ const KIND_LABELS = {
449
+ bug: "bug",
450
+ feature: "enhancement",
451
+ task: "chore"
452
+ };
453
+ /** A person can read why a call failed. */
454
+ const why = (err) => err instanceof Error ? err.message : String(err);
455
+ /** Runs one step; a failure becomes a `dropped` line, because the issue exists (or the rest of the patch is still good). */
456
+ async function attempt$1(what, dropped, step) {
457
+ try {
458
+ await step();
459
+ } catch (err) {
460
+ dropped.push(`${what} (${why(err)})`);
461
+ }
462
+ }
463
+ const sameDate = (a, b) => a !== null && a.slice(0, 10) === b;
464
+ /** Sets what Linear can hold of `fields` on `issue`, which was just made, and says what it cannot. */
465
+ async function applyNewIssueFields(scope, issue, fields) {
466
+ const dropped = [];
467
+ const { client } = scope;
468
+ if (fields.startDate) dropped.push(`startDate (Linear has no start date): ${fields.startDate}`);
469
+ if (fields.effort) await attempt$1(`effort ${fields.effort}`, dropped, async () => {
470
+ await client.issues.update(issue.id, { estimate: ESTIMATE[fields.effort] });
471
+ });
472
+ for (const key of fields.blockedBy ?? []) await attempt$1(`blocked by ${key}`, dropped, async () => {
473
+ const blocker = await client.issues.get(normalizeKey(key, scope.teamKey));
474
+ await client.issues.relate(blocker.id, issue.id, "blocks");
475
+ });
476
+ return dropped;
477
+ }
478
+ /** Changes a Linear issue to match the patch; whatever is already as asked is not written. */
479
+ async function updateLinearIssue(scope, key, patch, lookups) {
480
+ const { client } = scope;
481
+ const issue = await client.issues.get(normalizeKey(key, scope.teamKey));
482
+ const changed = [];
483
+ const dropped = [];
484
+ const clear = new Set(patch.clear ?? []);
485
+ const input = {};
486
+ if (patch.title !== void 0 && patch.title !== issue.title) {
487
+ input.title = patch.title;
488
+ changed.push("title");
489
+ }
490
+ if (patch.body !== void 0 && patch.body !== (issue.description ?? "")) {
491
+ input.description = patch.body;
492
+ changed.push("body");
493
+ }
494
+ if (patch.priority && patch.priority !== "none" && toLinearPriority(patch.priority) !== issue.priority) {
495
+ input.priority = toLinearPriority(patch.priority);
496
+ changed.push(`priority: ${patch.priority}`);
497
+ } else if (clear.has("priority") && issue.priority !== 0) {
498
+ input.priority = 0;
499
+ changed.push("priority cleared");
500
+ }
501
+ if (patch.targetDate && !sameDate(issue.dueDate, patch.targetDate)) {
502
+ input.dueDate = patch.targetDate;
503
+ changed.push(`targetDate: ${patch.targetDate}`);
504
+ } else if (clear.has("targetDate") && issue.dueDate) {
505
+ input.dueDate = null;
506
+ changed.push("targetDate cleared");
507
+ }
508
+ let estimate;
509
+ if (patch.effort && ESTIMATE[patch.effort] !== issue.estimate) estimate = {
510
+ value: ESTIMATE[patch.effort],
511
+ said: `effort: ${patch.effort}`
512
+ };
513
+ else if (clear.has("effort") && issue.estimate !== null) estimate = {
514
+ value: null,
515
+ said: "effort cleared"
516
+ };
517
+ if (patch.startDate) dropped.push(`startDate (Linear has no start date): ${patch.startDate}`);
518
+ if (clear.has("startDate")) dropped.push("startDate cleared (Linear has no start date)");
519
+ const [wanted, ...extra] = patch.assignees ?? [];
520
+ if (wanted) {
521
+ const found = await lookups.assignee(wanted);
522
+ if ("problem" in found) dropped.push(`assignee (${found.problem}): ${wanted}`);
523
+ else if (found.id !== issue.assignee?.id) {
524
+ input.assigneeId = found.id;
525
+ changed.push(`assignees: ${wanted}`);
526
+ }
527
+ if (extra.length > 0) dropped.push(`assignee (Linear holds one): ${extra.join(", ")}`);
528
+ } else if (clear.has("assignees") && issue.assignee) {
529
+ input.assigneeId = null;
530
+ changed.push("assignees cleared");
531
+ }
532
+ if (patch.milestone) {
533
+ const projectId = await lookups.project(patch.milestone);
534
+ if (projectId !== issue.project?.id) {
535
+ input.projectId = projectId;
536
+ changed.push(`milestone: ${patch.milestone}`);
537
+ }
538
+ } else if (clear.has("milestone") && issue.project) {
539
+ input.projectId = null;
540
+ changed.push("milestone cleared");
541
+ }
542
+ if (patch.parent) {
543
+ const parent = await client.issues.get(normalizeKey(patch.parent, scope.teamKey));
544
+ if (parent.id !== issue.parent?.id) {
545
+ input.parentId = parent.id;
546
+ changed.push(`parent: ${patch.parent}`);
547
+ }
548
+ } else if (clear.has("parent") && issue.parent) {
549
+ input.parentId = null;
550
+ changed.push("parent cleared");
551
+ }
552
+ const kindLabel = patch.kind ? KIND_LABELS[patch.kind] : void 0;
553
+ const have = new Map(issue.labels.nodes.map((l) => [l.name.toLowerCase(), l]));
554
+ const add = [...patch.addLabels ?? [], ...kindLabel ? [kindLabel] : []].filter((l) => !have.has(l.toLowerCase()));
555
+ const remove = [...patch.removeLabels ?? [], ...clear.has("kind") && !patch.kind ? Object.values(KIND_LABELS) : []].map((l) => have.get(l.toLowerCase())).filter((l) => l !== void 0);
556
+ if (add.length > 0 || remove.length > 0) {
557
+ const added = add.length > 0 ? await lookups.labelIds([...new Set(add)]) : [];
558
+ const removed = new Set(remove.map((l) => l.id));
559
+ input.labelIds = [.../* @__PURE__ */ new Set([...issue.labels.nodes.map((l) => l.id).filter((id) => !removed.has(id)), ...added])];
560
+ if (add.length > 0) changed.push(`labels added: ${[...new Set(add)].join(", ")}`);
561
+ for (const l of remove) changed.push(`label removed: ${l.name}`);
562
+ }
563
+ if (patch.state) {
564
+ const closed = patch.state === "closed";
565
+ const target = pickState(await client.teams.states((await scope.team()).id), { category: closed ? "done" : "open" });
566
+ if (!target) dropped.push(`state ${patch.state} (the team has no matching state)`);
567
+ else if (target.id !== issue.state.id) {
568
+ input.stateId = target.id;
569
+ changed.push(`state: ${patch.state}`);
570
+ }
571
+ }
572
+ if (Object.keys(input).length > 0) await client.issues.update(issue.id, input);
573
+ if (estimate) {
574
+ const { value, said } = estimate;
575
+ await attempt$1(said, dropped, async () => {
576
+ await client.issues.update(issue.id, { estimate: value });
577
+ changed.push(said);
578
+ });
579
+ }
580
+ const blocked = new Set(issue.inverseRelations.nodes.filter((r) => r.type === "blocks").map((r) => r.issue.identifier));
581
+ for (const blocker of patch.blockedBy ?? []) await attempt$1(`blocked by ${blocker}`, dropped, async () => {
582
+ const found = await client.issues.get(normalizeKey(blocker, scope.teamKey));
583
+ if (blocked.has(found.identifier)) return;
584
+ await client.issues.relate(found.id, issue.id, "blocks");
585
+ changed.push(`blocked by: ${blocker}`);
586
+ });
587
+ for (const blocker of patch.unblock ?? []) await attempt$1(`unblock ${blocker}`, dropped, async () => {
588
+ const identifier = normalizeKey(blocker, scope.teamKey);
589
+ const relation = issue.inverseRelations.nodes.find((r) => r.type === "blocks" && r.issue.identifier === identifier);
590
+ if (!relation) return;
591
+ await client.issues.unrelate(relation.id);
592
+ changed.push(`unblocked: ${blocker}`);
593
+ });
594
+ return {
595
+ key: issue.identifier,
596
+ changed,
597
+ ...dropped.length > 0 ? { dropped } : {}
598
+ };
599
+ }
440
600
  // src/capabilities/issues.ts
441
601
  function toUser(u) {
442
602
  return {
@@ -477,47 +637,61 @@ var LinearIssues = class {
477
637
  async get(key) {
478
638
  return mapIssue(await this.scope.client.issues.get(normalizeKey(key, this.scope.teamKey)));
479
639
  }
480
- /** Makes an issue; labels the team lacks are made, and `milestone` is a project's name or id. */
640
+ /**
641
+ * Makes an issue; labels the team lacks are made, and `milestone` is a project's name or id. Priority, the target
642
+ * date (Linear's due date) and the parent are set in the create call, the kind as its label, the estimate and the
643
+ * blockers after it; what Linear cannot hold (a start date) or refuses comes back in `dropped`.
644
+ */
481
645
  async create(input) {
482
646
  const { client } = this.scope;
483
647
  const dropped = [];
484
648
  let assigneeId;
485
649
  const [wanted, ...extra] = input.assignees ?? [];
486
650
  if (wanted) {
487
- if (/^@?me$/i.test(wanted)) assigneeId = (await client.teams.viewer()).user.id;
488
- else {
489
- const w = wanted.replace(/^@/, "").toLowerCase();
490
- const match = (await client.teams.users()).find((u) => [
491
- u.id,
492
- u.email,
493
- u.displayName,
494
- u.name
495
- ].some((v) => v?.toLowerCase() === w));
496
- assigneeId = match?.id;
497
- if (!match) dropped.push(`assignee (no Linear user matches): ${wanted}`);
498
- }
651
+ const found = await this.findAssignee(wanted);
652
+ if ("problem" in found) dropped.push(`assignee (${found.problem}): ${wanted}`);
653
+ else assigneeId = found.id;
499
654
  if (extra.length > 0) dropped.push(`assignee (Linear holds one): ${extra.join(", ")}`);
500
655
  }
501
656
  const team = await this.scope.team();
502
- const labelIds = input.labels?.length ? await this.labelIds(team.id, input.labels) : [];
503
- let projectId;
504
- if (input.milestone) {
505
- const match = (await client.projects.list()).find((p) => p.id === input.milestone || p.name.toLowerCase() === input.milestone.toLowerCase());
506
- if (!match) throw new Error(`Project "${input.milestone}" not found in Linear. Use the id or an exact name.`);
507
- projectId = match.id;
657
+ const names = [...input.labels ?? [], ...input.kind ? [KIND_LABELS[input.kind]] : []];
658
+ const labelIds = names.length > 0 ? await this.labelIds(team.id, [...new Set(names)]) : [];
659
+ const projectId = input.milestone ? await this.projectId(input.milestone) : void 0;
660
+ let parentId;
661
+ if (input.parent) {
662
+ const parent = input.parent;
663
+ try {
664
+ parentId = (await client.issues.get(normalizeKey(parent, this.scope.teamKey))).id;
665
+ } catch (err) {
666
+ dropped.push(`parent ${parent} (${err instanceof Error ? err.message : String(err)})`);
667
+ }
508
668
  }
669
+ const priority = input.priority && input.priority !== "none" ? toLinearPriority(input.priority) : void 0;
670
+ const issue = await client.issues.create({
671
+ teamId: team.id,
672
+ title: input.summary,
673
+ ...input.body ? { description: input.body } : {},
674
+ ...labelIds.length > 0 ? { labelIds } : {},
675
+ ...projectId ? { projectId } : {},
676
+ ...assigneeId ? { assigneeId } : {},
677
+ ...parentId ? { parentId } : {},
678
+ ...priority ? { priority } : {},
679
+ ...input.targetDate ? { dueDate: input.targetDate } : {}
680
+ });
681
+ dropped.push(...await applyNewIssueFields(this.scope, issue, input));
509
682
  return {
510
- key: (await client.issues.create({
511
- teamId: team.id,
512
- title: input.summary,
513
- ...input.body ? { description: input.body } : {},
514
- ...labelIds.length > 0 ? { labelIds } : {},
515
- ...projectId ? { projectId } : {},
516
- ...assigneeId ? { assigneeId } : {}
517
- })).identifier,
683
+ key: issue.identifier,
518
684
  ...dropped.length > 0 ? { dropped } : {}
519
685
  };
520
686
  }
687
+ /** Changes an issue; see {@link updateLinearIssue}. */
688
+ update(key, patch) {
689
+ return updateLinearIssue(this.scope, key, patch, {
690
+ assignee: (who) => this.findAssignee(who),
691
+ labelIds: async (names) => this.labelIds((await this.scope.team()).id, names),
692
+ project: (ref) => this.projectId(ref)
693
+ });
694
+ }
521
695
  /** Moves the issue to the state its slot names. Idempotent. */
522
696
  async transition(key, slot) {
523
697
  const team = await this.scope.team();
@@ -589,6 +763,23 @@ var LinearIssues = class {
589
763
  category: slot === "inReview" ? "in-review" : "in-progress"
590
764
  });
591
765
  }
766
+ async findAssignee(wanted) {
767
+ const { client } = this.scope;
768
+ if (/^@?me$/i.test(wanted)) return { id: (await client.teams.viewer()).user.id };
769
+ const w = wanted.replace(/^@/, "").toLowerCase();
770
+ const match = (await client.teams.users()).find((u) => [
771
+ u.id,
772
+ u.email,
773
+ u.displayName,
774
+ u.name
775
+ ].some((v) => v?.toLowerCase() === w));
776
+ return match ? { id: match.id } : { problem: "no Linear user matches" };
777
+ }
778
+ async projectId(ref) {
779
+ const match = (await this.scope.client.projects.list()).find((p) => p.id === ref || p.name.toLowerCase() === ref.toLowerCase());
780
+ if (!match) throw new Error(`Project "${ref}" not found in Linear. Use the id or an exact name.`);
781
+ return match.id;
782
+ }
592
783
  async labelIds(teamId, names) {
593
784
  const have = new Map((await this.scope.client.teams.labels(teamId)).map((l) => [l.name.toLowerCase(), l.id]));
594
785
  const ids = [];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theholocron/holocron-plugin-linear",
3
- "version": "5.0.0-alpha.500",
3
+ "version": "5.0.0-alpha.502",
4
4
  "description": "Holocron plugin for Linear. Implements the issues and projects capabilities against the Linear GraphQL API, with export and import for migrating to and from other trackers.",
5
5
  "keywords": [
6
6
  "holocron",
@@ -40,18 +40,18 @@
40
40
  "tsdown": "^0.23.7",
41
41
  "typescript": "^5.9.3",
42
42
  "vitest": "^5.1.0",
43
- "@theholocron/cli": "5.0.0-alpha.500",
43
+ "@theholocron/cli": "5.0.0-alpha.502",
44
44
  "@theholocron/eslint-config": "^8.9.0-alpha.21",
45
- "@theholocron/linear-client": "^1.58.0-alpha.45",
46
- "@theholocron/misc-utils": "^1.17.0-alpha.5",
47
45
  "@theholocron/tsconfig": "^8.9.0-alpha.21",
48
- "@theholocron/tsdown-config": "^8.9.0-alpha.21",
49
- "@theholocron/vitest-config": "^8.9.0-alpha.21"
46
+ "@theholocron/misc-utils": "^1.17.0-alpha.5",
47
+ "@theholocron/vitest-config": "^8.9.0-alpha.21",
48
+ "@theholocron/linear-client": "^1.58.0-alpha.45",
49
+ "@theholocron/tsdown-config": "^8.9.0-alpha.21"
50
50
  },
51
51
  "peerDependencies": {
52
52
  "@theholocron/linear-client": "^1.58.0",
53
53
  "@theholocron/misc-utils": "^1.16.0",
54
- "@theholocron/cli": "5.0.0-alpha.500"
54
+ "@theholocron/cli": "5.0.0-alpha.502"
55
55
  },
56
56
  "peerDependenciesMeta": {
57
57
  "@theholocron/linear-client": {}