@cvr/linear 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -28,7 +28,8 @@ linear auth whoami
28
28
  linear issue list
29
29
 
30
30
  # Start working on an issue
31
- linear issue start ABC-123
31
+ linear issue start ABC-123 --dry-run
32
+ linear issue start ABC-123 --json
32
33
 
33
34
  # View issue details
34
35
  linear issue view ABC-123
@@ -39,8 +40,8 @@ linear issue view ABC-123 ABC-124 --json
39
40
  # Include comments, sub-issues, and relations
40
41
  linear issue view ABC-123 --comments --children --relations --json
41
42
 
42
- # Create a new issue
43
- linear issue create
43
+ # Create a new issue with prompts
44
+ linear issue create --interactive
44
45
 
45
46
  # Non-interactive creation with validation
46
47
  linear issue create --team ABC --title "Title" --project "Tech Debt" --dry-run
@@ -63,13 +64,13 @@ linear team list
63
64
 
64
65
  ### Issues
65
66
 
66
- | Command | Description |
67
- | ------------------------- | ------------------------------------------------ |
68
- | `linear issue list` | List your assigned issues |
69
- | `linear issue view [id]` | View issue details (interactive picker if no ID) |
70
- | `linear issue start [id]` | Start working on an issue |
71
- | `linear issue create` | Create a new issue |
72
- | `linear issue comment ID` | Add a comment, with `--dry-run` support |
67
+ | Command | Description |
68
+ | ------------------------- | --------------------------------------------------- |
69
+ | `linear issue list` | List your assigned issues |
70
+ | `linear issue view [id]` | View issue details; prompts require `--interactive` |
71
+ | `linear issue start [id]` | Start work, with `--dry-run` and `--json` support |
72
+ | `linear issue create` | Create a new issue |
73
+ | `linear issue comment ID` | Add a comment, with `--dry-run` support |
73
74
 
74
75
  ### Teams
75
76
 
@@ -90,7 +91,10 @@ linear team list
90
91
  - `issue view --json` always returns an array and accepts multiple identifiers or Linear issue URLs.
91
92
  - Use `--comments`, `--children`, and `--relations` only when that context is needed.
92
93
  - Run supported mutations with `--dry-run` before executing them.
94
+ - Prompts are opt-in with `--interactive`; missing agent inputs fail fast.
93
95
  - Prefer typed commands. Use `linear api graphql` only for operations the typed CLI cannot express.
96
+ - Keep `--query-file` paths inside the current workspace; traversal and escaping symlinks are rejected.
97
+ - Raw GraphQL mutations require the explicit `--allow-mutation` flag.
94
98
  - Never read or interpolate the token directly; the CLI owns authentication.
95
99
 
96
100
  ## Configuration
package/bin/linear CHANGED
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cvr/linear",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "https://github.com/cevr/linear-cli.git"
@@ -36,7 +36,9 @@
36
36
  "dependencies": {
37
37
  "@effect/platform-bun": "4.0.0-beta.98",
38
38
  "@linear/sdk": "^88.2.0",
39
- "effect": "4.0.0-beta.98"
39
+ "effect": "4.0.0-beta.98",
40
+ "graphql": "^17.0.2",
41
+ "toml": "^5.0.0"
40
42
  },
41
43
  "devDependencies": {
42
44
  "@changesets/changelog-github": "^0.7.0",
@@ -16,8 +16,10 @@ Use the `linear` CLI for Linear work. It owns authentication, stable JSON output
16
16
  4. Treat issue identifiers and Linear issue URLs as equivalent inputs.
17
17
  5. Do not mutate Linear unless the user explicitly requested the mutation.
18
18
  6. For supported mutations, run `--dry-run` first, validate the result, then run the same command without `--dry-run`.
19
- 7. Use `linear api graphql` only when no typed command can express the operation. For GraphQL mutations, the user's request itself must explicitly authorize the write.
19
+ 7. Use `linear api graphql` only when no typed command can express the operation. For GraphQL mutations, the user's request itself must explicitly authorize the write and the command must include `--allow-mutation`.
20
20
  8. Trust exit codes: nonzero means the operation failed. Do not infer success from partial stdout.
21
+ 9. Prompts are opt-in. Pass `--interactive` only when a human is present; otherwise provide every required input.
22
+ 10. Keep `--query-file` inside the current workspace. The CLI rejects traversal and symlinks that escape it.
21
23
 
22
24
  If `/linear` is invoked without an issue or task, run `linear issue list --json` and summarize the available work.
23
25
 
@@ -57,17 +59,18 @@ Use the returned `branchName`; do not invent a branch name from the title.
57
59
  ### Start work
58
60
 
59
61
  ```bash
60
- linear issue start BITE-123
62
+ linear issue start BITE-123 --dry-run
63
+ linear issue start BITE-123 --json
61
64
  ```
62
65
 
63
- This moves the issue to the team's started state and returns the Linear branch name. It does not create or check out a Git branch.
66
+ The dry run resolves the issue and target state without updating Linear. The real command moves the issue to the team's started state and returns the Linear branch name. It does not create or check out a Git branch.
64
67
 
65
68
  ### Create an issue
66
69
 
67
70
  Interactive:
68
71
 
69
72
  ```bash
70
- linear issue create
73
+ linear issue create --interactive
71
74
  ```
72
75
 
73
76
  Non-interactive agent flow:
@@ -116,10 +119,12 @@ linear api graphql \
116
119
  For multiline documents, keep the query in a file:
117
120
 
118
121
  ```bash
119
- linear api graphql --query-file /path/to/query.graphql --variables '{"id":"BITE-123"}'
122
+ linear api graphql --query-file .linear/issue-query.graphql --variables '{"id":"BITE-123"}'
120
123
  ```
121
124
 
122
- The command uses the configured credential and emits only the GraphQL `data` object as JSON. Keep variables separate from the query. Prefer one bulk GraphQL operation over shell loops when migrating a large issue tree.
125
+ The query file must resolve inside the current workspace. The command uses the configured credential and emits only the GraphQL `data` object as JSON. Keep variables separate from the query. Prefer one bulk GraphQL operation over shell loops when migrating a large issue tree.
126
+
127
+ Raw GraphQL mutations are rejected unless `--allow-mutation` is present. Add that flag only after verifying that the user explicitly authorized the write and inspecting the complete mutation document and variables.
123
128
 
124
129
  ## Authentication and configuration
125
130
 
package/src/cli.ts ADDED
@@ -0,0 +1,14 @@
1
+ import { Command } from "effect/unstable/cli";
2
+ import packageJson from "../package.json" with { type: "json" };
3
+ import { api } from "./commands/api.js";
4
+ import { auth } from "./commands/auth.js";
5
+ import { issue } from "./commands/issue.js";
6
+ import { project } from "./commands/project.js";
7
+ import { team } from "./commands/team.js";
8
+
9
+ export const linear = Command.make("linear").pipe(
10
+ Command.withDescription("Manage Linear issues, teams, projects, and authentication"),
11
+ Command.withSubcommands([auth, team, project, issue, api]),
12
+ );
13
+
14
+ export const runCli = Command.runWith(linear, { version: packageJson.version });
@@ -1,5 +1,7 @@
1
- import { Console, Effect, FileSystem, Option, Schema } from "effect";
1
+ import { Console, Effect, FileSystem, Option, Path, Schema } from "effect";
2
2
  import { Command, Flag } from "effect/unstable/cli";
3
+ import { Kind } from "graphql/language/kinds.js";
4
+ import { parse } from "graphql/language/parser.js";
3
5
  import { InvalidInputError } from "../lib/errors.js";
4
6
  import { encodeJson } from "../lib/json.js";
5
7
  import { LinearService } from "../services/Linear.js";
@@ -19,13 +21,57 @@ const variablesOption = Flag.string("variables").pipe(
19
21
  Flag.withDefault("{}"),
20
22
  );
21
23
 
24
+ const allowMutationOption = Flag.boolean("allow-mutation").pipe(
25
+ Flag.withDescription("Explicitly authorize a raw GraphQL mutation"),
26
+ );
27
+
22
28
  const VariablesJson = Schema.fromJsonString(Schema.Record(Schema.String, Schema.Unknown));
23
29
  const decodeVariables = Schema.decodeUnknownEffect(VariablesJson);
30
+ const maximumInputLength = 1_000_000;
31
+
32
+ const containsMutation = Effect.fn("ApiCommand.containsMutation")(function* (document: string) {
33
+ const parsed = yield* Effect.try({
34
+ try: () => parse(document),
35
+ catch: (error) =>
36
+ InvalidInputError.make({ message: `Invalid GraphQL document: ${String(error)}` }),
37
+ });
38
+ return parsed.definitions.some(
39
+ (definition) =>
40
+ definition.kind === Kind.OPERATION_DEFINITION && definition.operation === "mutation",
41
+ );
42
+ });
43
+
44
+ const readWorkspaceQueryFile = Effect.fn("ApiCommand.readWorkspaceQueryFile")(function* (
45
+ requestedPath: string,
46
+ ) {
47
+ const fileSystem = yield* FileSystem.FileSystem;
48
+ const path = yield* Path.Path;
49
+ const workspace = yield* fileSystem.realPath(path.resolve("."));
50
+ const queryFile = yield* fileSystem.realPath(path.resolve(requestedPath));
51
+ const relative = path.relative(workspace, queryFile);
52
+ if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
53
+ return yield* InvalidInputError.make({
54
+ message: `--query-file must stay within the current workspace: ${requestedPath}`,
55
+ });
56
+ }
57
+ const document = yield* fileSystem.readFileString(queryFile);
58
+ if (document.length > maximumInputLength) {
59
+ return yield* InvalidInputError.make({
60
+ message: `GraphQL query files cannot exceed ${maximumInputLength} characters`,
61
+ });
62
+ }
63
+ return document;
64
+ });
24
65
 
25
66
  export const graphqlCommand = Command.make(
26
67
  "graphql",
27
- { query: queryOption, queryFile: queryFileOption, variables: variablesOption },
28
- ({ query, queryFile, variables }) =>
68
+ {
69
+ query: queryOption,
70
+ queryFile: queryFileOption,
71
+ variables: variablesOption,
72
+ allowMutation: allowMutationOption,
73
+ },
74
+ ({ query, queryFile, variables, allowMutation }) =>
29
75
  Effect.gen(function* () {
30
76
  if (Option.isSome(query) && Option.isSome(queryFile)) {
31
77
  return yield* InvalidInputError.make({
@@ -40,17 +86,33 @@ export const graphqlCommand = Command.make(
40
86
  onNone: () =>
41
87
  InvalidInputError.make({ message: "--query or --query-file is required" }),
42
88
  onSome: (path) =>
43
- FileSystem.FileSystem.use((fileSystem) =>
44
- fileSystem.readFileString(path).pipe(
45
- Effect.mapError((error) =>
46
- InvalidInputError.make({
47
- message: `Could not read GraphQL query file ${path}: ${error}`,
48
- }),
49
- ),
89
+ readWorkspaceQueryFile(path).pipe(
90
+ Effect.mapError((error) =>
91
+ error._tag === "InvalidInputError"
92
+ ? error
93
+ : InvalidInputError.make({
94
+ message: `Could not read GraphQL query file ${path}: ${error}`,
95
+ }),
50
96
  ),
51
97
  ),
52
98
  }),
53
99
  });
100
+ if (document.length > maximumInputLength) {
101
+ return yield* InvalidInputError.make({
102
+ message: `GraphQL documents cannot exceed ${maximumInputLength} characters`,
103
+ });
104
+ }
105
+ if (variables.length > maximumInputLength) {
106
+ return yield* InvalidInputError.make({
107
+ message: `--variables cannot exceed ${maximumInputLength} characters`,
108
+ });
109
+ }
110
+ if ((yield* containsMutation(document)) && !allowMutation) {
111
+ return yield* InvalidInputError.make({
112
+ message:
113
+ "Raw GraphQL mutations require explicit authorization with --allow-mutation. Preview and inspect the document before retrying.",
114
+ });
115
+ }
54
116
  const parsedVariables = yield* decodeVariables(variables).pipe(
55
117
  Effect.mapError((error) =>
56
118
  InvalidInputError.make({ message: `--variables must be a JSON object: ${error}` }),
@@ -60,8 +122,27 @@ export const graphqlCommand = Command.make(
60
122
  const data = yield* linear.rawQuery(document, parsedVariables);
61
123
  yield* Console.log(encodeJson(data));
62
124
  }),
125
+ ).pipe(
126
+ Command.withDescription("Execute an authenticated Linear GraphQL operation"),
127
+ Command.withExamples([
128
+ {
129
+ command: 'linear api graphql --query "query { viewer { id name } }"',
130
+ description: "Run an inline GraphQL query",
131
+ },
132
+ {
133
+ command: "linear api graphql --query-file query.graphql --variables '{}'",
134
+ description: "Run a GraphQL query from a file with variables",
135
+ },
136
+ {
137
+ command: "linear api graphql --query-file mutation.graphql --allow-mutation",
138
+ description: "Explicitly authorize a raw GraphQL mutation",
139
+ },
140
+ ]),
63
141
  );
64
142
 
65
143
  export const api = Command.make("api", {}, () =>
66
144
  Console.log("Use 'linear api graphql' for GraphQL operations not covered by typed commands."),
67
- ).pipe(Command.withSubcommands([graphqlCommand]));
145
+ ).pipe(
146
+ Command.withDescription("Access the Linear GraphQL API"),
147
+ Command.withSubcommands([graphqlCommand]),
148
+ );
@@ -1,61 +1,51 @@
1
- import { Command, Flag } from "effect/unstable/cli";
1
+ import { Command, Prompt } from "effect/unstable/cli";
2
+ import { ChildProcess } from "effect/unstable/process";
2
3
  import { Console, Effect } from "effect";
4
+ import { jsonFlag } from "../lib/flags.js";
3
5
  import { encodeJson } from "../lib/json.js";
4
- import { ConfigService } from "../services/Config.js";
5
6
  import { LinearService } from "../services/Linear.js";
6
- import { BrowserService } from "../services/Browser.js";
7
- import { StdinService } from "../services/Stdin.js";
8
7
 
9
8
  const LINEAR_API_KEY_URL = "https://linear.app/settings/account/security";
10
9
 
11
- const jsonOption = Flag.boolean("json").pipe(
12
- Flag.withDescription("Emit stable JSON for scripts and agents"),
13
- );
14
-
15
10
  // linear auth - Interactive authentication flow
16
11
  export const authCommand = Command.make("auth", {}, () =>
17
12
  Effect.gen(function* () {
18
- const browser = yield* BrowserService;
19
- const config = yield* ConfigService;
20
- const stdin = yield* StdinService;
21
-
22
13
  yield* Console.log(`\nTo authenticate, you'll need a Linear API key.`);
23
14
  yield* Console.log(`Opening: ${LINEAR_API_KEY_URL}\n`);
24
15
 
25
- // Open browser
26
- yield* browser
27
- .open(LINEAR_API_KEY_URL)
28
- .pipe(
29
- Effect.catch(() => Console.log(`Could not open browser. Please visit the URL manually.`)),
30
- );
16
+ const browserOpened = yield* Effect.gen(function* () {
17
+ const process = yield* ChildProcess.make("open", [LINEAR_API_KEY_URL], {
18
+ stdout: "ignore",
19
+ stderr: "ignore",
20
+ });
21
+ return (yield* process.exitCode) === 0;
22
+ }).pipe(
23
+ Effect.scoped,
24
+ Effect.catch(() => Effect.succeed(false)),
25
+ );
26
+ if (!browserOpened) {
27
+ yield* Console.log(`Could not open browser. Please visit the URL manually.`);
28
+ }
31
29
 
32
- // Simple prompt using readline
33
- const token = yield* stdin.readLine("Paste your API key: ");
30
+ const token = yield* Prompt.hidden({ message: "Paste your API key" });
34
31
 
35
32
  // Validate token by making an API call
36
33
  yield* Console.log("\nValidating token...");
37
34
 
38
- // Save token first so LinearService can use it
39
- yield* config.saveToken(token);
40
-
41
- // Now validate with the saved token
42
35
  const linear = yield* LinearService;
43
- const viewer = yield* linear.getViewer.pipe(
44
- Effect.catchTag("InvalidTokenError", (e) =>
45
- Effect.gen(function* () {
46
- yield* Console.error(`\nError: ${e.message}`);
47
- yield* Console.error("Please try again with a valid API key.");
48
- return yield* Effect.die(e);
49
- }),
50
- ),
51
- );
36
+ const viewer = yield* linear.authenticate(token);
52
37
 
53
38
  yield* Console.log(`\nAuthenticated as ${viewer.name} (${viewer.email})`);
54
39
  }),
40
+ ).pipe(
41
+ Command.withDescription("Authenticate with Linear"),
42
+ Command.withExamples([
43
+ { command: "linear auth", description: "Authenticate using a Linear API key" },
44
+ ]),
55
45
  );
56
46
 
57
47
  // linear auth whoami - Show current user
58
- export const whoamiCommand = Command.make("whoami", { json: jsonOption }, ({ json }) =>
48
+ export const whoamiCommand = Command.make("whoami", { json: jsonFlag }, ({ json }) =>
59
49
  Effect.gen(function* () {
60
50
  const linear = yield* LinearService;
61
51
  const viewer = yield* linear.getViewer;
@@ -67,10 +57,7 @@ export const whoamiCommand = Command.make("whoami", { json: jsonOption }, ({ jso
67
57
  name: viewer.name,
68
58
  email: viewer.email,
69
59
  admin: viewer.admin,
70
- status: {
71
- emoji: viewer.statusEmoji ?? undefined,
72
- label: viewer.statusLabel ?? undefined,
73
- },
60
+ status: viewer.status,
74
61
  }),
75
62
  );
76
63
  return;
@@ -80,10 +67,16 @@ export const whoamiCommand = Command.make("whoami", { json: jsonOption }, ({ jso
80
67
  yield* Console.log(` Name: ${viewer.name}`);
81
68
  yield* Console.log(` Email: ${viewer.email}`);
82
69
  yield* Console.log(` Admin: ${viewer.admin ? "Yes" : "No"}`);
83
- if (viewer.statusLabel !== undefined && viewer.statusLabel !== null) {
84
- yield* Console.log(` Status: ${viewer.statusEmoji ?? ""} ${viewer.statusLabel}`);
70
+ if (viewer.status?.label !== undefined) {
71
+ yield* Console.log(` Status: ${viewer.status.emoji ?? ""} ${viewer.status.label}`);
85
72
  }
86
73
  }),
74
+ ).pipe(
75
+ Command.withDescription("Show the authenticated Linear user"),
76
+ Command.withExamples([
77
+ { command: "linear auth whoami", description: "Show the authenticated user" },
78
+ { command: "linear auth whoami --json", description: "Show the authenticated user as JSON" },
79
+ ]),
87
80
  );
88
81
 
89
82
  // Combined auth command with subcommands