@theholocron/holocron-plugin-linear 0.0.0-stage → 5.0.0-alpha.132
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 +21 -0
- package/README.md +70 -2
- package/dist/index.d.mts +183 -0
- package/dist/index.mjs +1265 -0
- package/package.json +69 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Newton Koumantzelis
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,71 @@
|
|
|
1
|
-
|
|
1
|
+
<!-- editorconfig-checker-disable-file -->
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# `@theholocron/holocron-plugin-linear`
|
|
4
|
+
|
|
5
|
+
Linear plugin for [Holocron](../../cli/cli). Implements the `issues` and `projects` capabilities against the
|
|
6
|
+
[Linear GraphQL API](https://linear.app/developers), and `export` / `import` on `issues` so `holocron migrate` can move
|
|
7
|
+
issues between Linear and GitHub in either direction.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
<!-- prettier-ignore -->
|
|
12
|
+
```bash
|
|
13
|
+
pnpm add -D @theholocron/holocron-plugin-linear
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Auth
|
|
17
|
+
|
|
18
|
+
1. `--token <KEY>` on the holocron invocation
|
|
19
|
+
2. `HOLOCRON_LINEAR_TOKEN`
|
|
20
|
+
3. `LINEAR_API_KEY`
|
|
21
|
+
4. keyring `linear` (set with `holocron auth set linear <KEY>`)
|
|
22
|
+
|
|
23
|
+
Create a personal API key at **Linear → Settings → Account → Security**.
|
|
24
|
+
|
|
25
|
+
## Config
|
|
26
|
+
|
|
27
|
+
<!-- prettier-ignore -->
|
|
28
|
+
```ts
|
|
29
|
+
providers: {
|
|
30
|
+
issues: ["linear", { team: "ENG", states: { inProgress: "In Progress", inReview: "In Review" } }],
|
|
31
|
+
projects: ["linear", { team: "ENG" }],
|
|
32
|
+
}
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
`team` (the team key) is required. `states` names the states the `inProgress` and `inReview` lifecycle slots move an
|
|
36
|
+
issue to; left out, the team's first `started` state is used.
|
|
37
|
+
|
|
38
|
+
## Setup and doctor
|
|
39
|
+
|
|
40
|
+
`holocron provider linear setup` makes what the `issues` entry declares and `holocron provider linear doctor` compares
|
|
41
|
+
it with the team, one row per setting. Setup is idempotent, never deletes, supports `--dry-run` and asks first unless
|
|
42
|
+
`--yes`. Names only, no secrets:
|
|
43
|
+
|
|
44
|
+
<!-- prettier-ignore -->
|
|
45
|
+
```ts
|
|
46
|
+
issues: ["linear", {
|
|
47
|
+
team: "ENG",
|
|
48
|
+
labels: ["bug", "enhancement"], // made on the team when missing
|
|
49
|
+
project: "Roadmap", // made when missing
|
|
50
|
+
automation: {
|
|
51
|
+
autoClose: { months: 3, state: "Canceled" }, // teamUpdate: autoClosePeriod / autoCloseState
|
|
52
|
+
autoArchive: { months: 6 }, // teamUpdate: autoArchivePeriod
|
|
53
|
+
git: [ // rules by event (and exact branch)
|
|
54
|
+
{ event: "start", state: "In Progress" },
|
|
55
|
+
{ event: "merge", state: "Done", branch: "main" },
|
|
56
|
+
],
|
|
57
|
+
},
|
|
58
|
+
templates: [{ name: "Bug report", file: ".holocron/linear/bug.md" }], // validated; reported as skipped
|
|
59
|
+
}],
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Changing team settings needs a key with admin access to the team. Git automation is made and compared (events `draft`, `review`,
|
|
63
|
+
`start`, `mergeable`, `merge`). Issue templates are validated but reported as skipped: Linear does not document the issue
|
|
64
|
+
`templateData` shape, so a template can be neither written nor compared with certainty.
|
|
65
|
+
|
|
66
|
+
## Not the same as GitHub
|
|
67
|
+
|
|
68
|
+
Linear does not match GitHub feature for feature: statuses are per team, there are no custom fields or managed views,
|
|
69
|
+
automation is read-only, and priority is built in. The full table, and what it means for a migration back to GitHub, is
|
|
70
|
+
on the [plugin docs page](../../docs/src/content/docs/plugins/linear.mdx). A migration lists what it could not carry
|
|
71
|
+
at the end of every run.
|
package/dist/index.d.mts
ADDED
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
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";
|
|
2
|
+
import { LinearClient, LinearClientOptions, LinearTeam, createLinearClient } from "@theholocron/linear-client";
|
|
3
|
+
/** Resolves the Linear token from `--token`, `HOLOCRON_LINEAR_TOKEN`, `LINEAR_API_KEY` or the keyring, and throws an `AuthError` when none is set. */
|
|
4
|
+
export declare const resolveToken: import("@theholocron/cli").TokenResolver;
|
|
5
|
+
/** Every token this plugin takes, for `holocron doctor tokens`. */
|
|
6
|
+
export declare const tokens: PluginToken[];
|
|
7
|
+
/** The client and the team a capability works in. */
|
|
8
|
+
interface TeamScope {
|
|
9
|
+
/** The Linear client. */
|
|
10
|
+
client: LinearClient;
|
|
11
|
+
/** The configured team key, e.g. `ENG`. */
|
|
12
|
+
teamKey: string;
|
|
13
|
+
/** The team, looked up once. Throws when the token cannot see a team with that key. */
|
|
14
|
+
team(): Promise<LinearTeam>;
|
|
15
|
+
}
|
|
16
|
+
/** Options of the Linear `issues` capability. */
|
|
17
|
+
interface IssuesOptions {
|
|
18
|
+
/** Names of the states the `inProgress` and `inReview` slots move an issue to; the team's own states by type when left out. */
|
|
19
|
+
states?: {
|
|
20
|
+
inProgress?: string;
|
|
21
|
+
inReview?: string;
|
|
22
|
+
};
|
|
23
|
+
}
|
|
24
|
+
/** The Linear implementation of the `issues` capability. */
|
|
25
|
+
export declare class LinearIssues implements Issues {
|
|
26
|
+
private readonly scope;
|
|
27
|
+
private readonly opts;
|
|
28
|
+
/** Capability key, always `"issues"`. */
|
|
29
|
+
readonly key: "issues";
|
|
30
|
+
/** Provider name, always `"linear"`. */
|
|
31
|
+
readonly providerName = "linear";
|
|
32
|
+
constructor(scope: TeamScope, opts?: IssuesOptions);
|
|
33
|
+
/** The user the token belongs to. */
|
|
34
|
+
getMyself(): Promise<TrackerUser>;
|
|
35
|
+
/** The team's issues, newest update first. */
|
|
36
|
+
search(filter: IssueSearchFilter): Promise<Issue[]>;
|
|
37
|
+
/** One issue by its key. */
|
|
38
|
+
get(key: string): Promise<Issue>;
|
|
39
|
+
/** Makes an issue; labels the team lacks are made, and `milestone` is a project's name or id. */
|
|
40
|
+
create(input: {
|
|
41
|
+
summary: string;
|
|
42
|
+
body?: string;
|
|
43
|
+
labels?: string[];
|
|
44
|
+
milestone?: string;
|
|
45
|
+
}): Promise<{
|
|
46
|
+
key: string;
|
|
47
|
+
}>;
|
|
48
|
+
/** Moves the issue to the state its slot names. Idempotent. */
|
|
49
|
+
transition(key: string, slot: LifecycleSlot): Promise<LifecycleResult>;
|
|
50
|
+
/** Adds a comment to the issue. */
|
|
51
|
+
comment(key: string, body: string): Promise<void>;
|
|
52
|
+
/** Checks the user, the team and which states the lifecycle slots resolve to. */
|
|
53
|
+
doctor(): Promise<TrackerDoctorReport>;
|
|
54
|
+
/** Reads issues with comments, priority, labels, parent and blockers, for `holocron migrate`. */
|
|
55
|
+
export(selector: IssueSelector, info?: ExportInfo): Promise<IssueRecord[]>;
|
|
56
|
+
/** Makes the records as issues in the team; one already made by an earlier run is skipped. */
|
|
57
|
+
import(records: IssueRecord[], options?: ImportOptions): Promise<ImportResult[]>;
|
|
58
|
+
/** Like `import`, and it also updates what an earlier import or sync made, for `holocron sync issues`. */
|
|
59
|
+
sync(records: IssueRecord[], options?: ImportOptions): Promise<SyncResult[]>;
|
|
60
|
+
private stateFor;
|
|
61
|
+
private labelIds;
|
|
62
|
+
}
|
|
63
|
+
/** The names of the two automations the team settings expose, which a template's `rules` can ask for. */
|
|
64
|
+
export declare const AUTO_ARCHIVE_RULE = "Auto-archive closed issues";
|
|
65
|
+
/** See {@link AUTO_ARCHIVE_RULE}. */
|
|
66
|
+
export declare const AUTO_CLOSE_RULE = "Auto-close stale issues";
|
|
67
|
+
/** The Linear implementation of the `projects` capability, backed by Linear projects and the team's workflow. */
|
|
68
|
+
export declare class LinearProjects implements Projects {
|
|
69
|
+
private readonly scope;
|
|
70
|
+
/** Capability key, always `"projects"`. */
|
|
71
|
+
readonly key: "projects";
|
|
72
|
+
/** Provider name, always `"linear"`. */
|
|
73
|
+
readonly providerName = "linear";
|
|
74
|
+
constructor(scope: TeamScope);
|
|
75
|
+
/** Every project of the team, open and archived. The owner is the workspace, which the token already names. */
|
|
76
|
+
list(_owner: string): Promise<BoardSummary[]>;
|
|
77
|
+
/** The open project with exactly this name. */
|
|
78
|
+
find(owner: string, name: string): Promise<BoardSummary | undefined>;
|
|
79
|
+
/** Makes a project for the team and brings the team's statuses in line with the template. */
|
|
80
|
+
create(owner: string, name: string, template: BoardTemplate): Promise<BoardSummary>;
|
|
81
|
+
/** Archives the project. Reversible in Linear. */
|
|
82
|
+
close(_owner: string, board: BoardSummary): Promise<void>;
|
|
83
|
+
/** The team's statuses, the built-in priority, and the team's automation. */
|
|
84
|
+
read(_owner: string, board: BoardSummary): Promise<BoardState>;
|
|
85
|
+
/**
|
|
86
|
+
* Adds the template's missing statuses to the team (never removes or renames one). Everything Linear cannot
|
|
87
|
+
* create from the API is a `todo`.
|
|
88
|
+
*/
|
|
89
|
+
ensure(_owner: string, _board: BoardSummary, template: BoardTemplate): Promise<EnsureReport>;
|
|
90
|
+
/** The project's issues with status, whether they are open, priority and open blockers. */
|
|
91
|
+
items(_owner: string, board: BoardSummary, template: BoardTemplate): Promise<BoardItem[]>;
|
|
92
|
+
/** Puts an issue in the team state with this name; `transitioned` is false when it already is there. */
|
|
93
|
+
setStatus(_owner: string, _board: BoardSummary, key: string, status: string): Promise<LifecycleResult>;
|
|
94
|
+
/**
|
|
95
|
+
* Moves the open issues of one project into another. An issue is in one project, so there is nothing to keep on the
|
|
96
|
+
* target; status and priority belong to the issue and travel with it. Closed issues stay where they are.
|
|
97
|
+
*/
|
|
98
|
+
move(_owner: string, from: BoardSummary, to: BoardSummary, _template: BoardTemplate): Promise<MoveReport>;
|
|
99
|
+
/** A smoke check: how many projects the token can see for the team. */
|
|
100
|
+
whoami(): Promise<{
|
|
101
|
+
ok: boolean;
|
|
102
|
+
boards: number;
|
|
103
|
+
}>;
|
|
104
|
+
}
|
|
105
|
+
/** Options for {@link verifyToken}. */
|
|
106
|
+
interface VerifyTokenOptions {
|
|
107
|
+
/** Overrides the API root, for tests. */
|
|
108
|
+
baseUrl?: string;
|
|
109
|
+
/** Overrides `fetch`, for tests. */
|
|
110
|
+
fetch?: typeof fetch;
|
|
111
|
+
}
|
|
112
|
+
/** Checks a Linear token by reading the viewer; the success subject names the user and workspace. */
|
|
113
|
+
export declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
|
|
114
|
+
/** Options for the Linear plugin. */
|
|
115
|
+
export interface LinearPluginOptions extends ResolveTokenInput {
|
|
116
|
+
/** The key of the team the issues and boards belong to, e.g. `ENG`. Required by both capabilities. */
|
|
117
|
+
team?: string;
|
|
118
|
+
/** Names of the states the `inProgress` and `inReview` lifecycle slots move an issue to. */
|
|
119
|
+
states?: {
|
|
120
|
+
/** The state for work that has started. */
|
|
121
|
+
inProgress?: string;
|
|
122
|
+
/** The state for work waiting on review. */
|
|
123
|
+
inReview?: string;
|
|
124
|
+
};
|
|
125
|
+
/** The team's automation, set by `provider linear setup` and compared by `provider linear doctor`. */
|
|
126
|
+
automation?: {
|
|
127
|
+
/** Close an issue after `months` without activity (0 is off), into the state named `state` (the team's default if left out). */
|
|
128
|
+
autoClose?: {
|
|
129
|
+
/** Months of inactivity; 0 switches auto-close off. */
|
|
130
|
+
months: number;
|
|
131
|
+
/** The name of the team state an auto-closed issue is put in. */
|
|
132
|
+
state?: string;
|
|
133
|
+
};
|
|
134
|
+
/** Archive a closed issue after `months` (0 is off). */
|
|
135
|
+
autoArchive?: {
|
|
136
|
+
/** Months after closing; 0 switches auto-archive off. */
|
|
137
|
+
months: number;
|
|
138
|
+
};
|
|
139
|
+
/**
|
|
140
|
+
* Git automation rules `provider linear setup` makes (or repoints) and `provider linear doctor` compares. `event` is
|
|
141
|
+
* one of `draft`, `review`, `start`, `mergeable`, `merge`; `state` is a team state name; `branch` limits the rule to
|
|
142
|
+
* pull requests targeting that exact branch name.
|
|
143
|
+
*/
|
|
144
|
+
git?: Array<{
|
|
145
|
+
event: string;
|
|
146
|
+
state: string;
|
|
147
|
+
branch?: string;
|
|
148
|
+
}>;
|
|
149
|
+
};
|
|
150
|
+
/** Issue templates (`name`, and the `.holocron/linear/*.md` file). Validated and reported as skipped: not applied or compared. */
|
|
151
|
+
templates?: Array<{
|
|
152
|
+
name: string;
|
|
153
|
+
file: string;
|
|
154
|
+
}>;
|
|
155
|
+
/** Labels `provider linear setup` makes on the team when they are missing. */
|
|
156
|
+
labels?: string[];
|
|
157
|
+
/** A project `provider linear setup` makes when it is missing. */
|
|
158
|
+
project?: string;
|
|
159
|
+
/** Override the API root, for tests. Defaults to `https://api.linear.app`. */
|
|
160
|
+
baseUrl?: string;
|
|
161
|
+
/** Override `fetch`, for tests. */
|
|
162
|
+
fetch?: typeof fetch;
|
|
163
|
+
}
|
|
164
|
+
/** Builds the `issues` capability. */
|
|
165
|
+
export declare function issues(options: LinearPluginOptions): Issues;
|
|
166
|
+
/** Builds the `projects` capability. */
|
|
167
|
+
export declare function projects(options: LinearPluginOptions): Projects;
|
|
168
|
+
/** Creates the plugin: a `connection` probe, `setup` and `doctor`, and the `issues` and `projects` capabilities. */
|
|
169
|
+
export declare function createPlugin(options: LinearPluginOptions): {
|
|
170
|
+
name: string;
|
|
171
|
+
probes: {
|
|
172
|
+
connection: import("@theholocron/cli").Probe;
|
|
173
|
+
};
|
|
174
|
+
setup: ProviderAction;
|
|
175
|
+
doctor: ProviderAction;
|
|
176
|
+
capabilities: {
|
|
177
|
+
issues: () => Issues;
|
|
178
|
+
projects: () => Projects;
|
|
179
|
+
};
|
|
180
|
+
};
|
|
181
|
+
/** One-line hint shown by `holocron auth set linear` when no token is given or the token is rejected. */
|
|
182
|
+
export declare const AUTH_HINT: string;
|
|
183
|
+
export { AuthError, type LinearClient, type LinearClientOptions, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createLinearClient };
|