linear-sdk-cli 0.1.3 → 0.2.3

package/src/bin/linear.ts

@@ -10,6 +10,7 @@ import { createProgram, parsedGlobalOptions, usageHint, suppressedHelp } from ".
 import { Output } from "../output/format.js";
 import { CliError, ExitCode, normalizeError } from "../lib/errors.js";
 import { commandPath } from "../lib/options.js";
+import { isDebugEnabled, shouldUseColor } from "../output/color.js";
 
 // `linear schema | head -2` is a reader that stops early, and stdout closing
 // under us is that reader's business, not an error: exit quietly, as every
@@ -53,9 +54,14 @@ program.parseAsync(process.argv).catch((err) => {
   const json = globals.json === true;
   const out = new Output({
     json,
-    color: globals.noAnsi !== true && !json && process.stderr.isTTY === true,
+    color: shouldUseColor({
+      disabled: globals.noAnsi,
+      json,
+      isTTY: process.stderr.isTTY === true,
+    }),
     quiet: globals.quiet === true,
-    debug: globals.debug === true,
+    debug: isDebugEnabled(globals.debug),
+    isTTY: process.stderr.isTTY === true,
   });
   out.error(cliError);
   process.exit(cliError.exitCode);
@@ -70,14 +76,18 @@ function fromCommander(err: CommanderError): CliError {
   if (err.code === "commander.help") {
     const help = suppressedHelp(program);
     const path = help ? commandPath(help.command) : "linear";
-    return new CliError(`Missing subcommand. Run '${path} --help' to see the commands.`, "usage", err.code);
+    return new CliError(
+      "Missing subcommand.",
+      "usage",
+      err.code,
+      `Run '${path} --help' to see the commands.`,
+    );
   }
   return new CliError(
-    [stripErrorPrefix(err.message).replace(/\.?$/, "."), usageHint(program)]
-      .filter(Boolean)
-      .join(" "),
+    stripErrorPrefix(err.message).replace(/\.?$/, "."),
     "usage",
     err.code,
+    usageHint(program),
   );
 }
 

package/src/cli.ts

@@ -29,6 +29,7 @@ import { registerRoadmap } from "./commands/roadmap.js";
 import { registerNotification } from "./commands/notification.js";
 import { registerOrganization } from "./commands/organization.js";
 import { registerWebhook } from "./commands/webhook.js";
+import { registerOpen } from "./commands/open.js";
 import { registerCommands, registerSchema } from "./commands/discover.js";
 import { Context, type GlobalOptions } from "./context.js";
 import { currentIssueId } from "./git.js";
@@ -58,6 +59,7 @@ export function createProgram(): Command {
   registerMeta(program);
   registerApi(program);
   registerCompletion(program);
+  registerOpen(program);
   // Phase 1: issues. Agent sessions live on issues, so their group is mounted
   // under `issue` (`linear issue agent-session …`); so is file upload
   // (`linear issue attach <issue> <file...>`, TES-602).
@@ -108,7 +110,7 @@ export function createProgram(): Command {
       return;
     }
     const detail = await getIssueDetail(ctx.client, id);
-    await renderIssueDetail(ctx, detail, false);
+    await renderIssueDetail(ctx, detail, true);
   });
 
   // Make global options usable in any position (e.g. `linear whoami --json`),

package/src/commands/agent-session.ts

@@ -18,7 +18,12 @@ const ROW_COLUMNS: Column<svc.AgentSessionRow>[] = [
   { key: "agent", header: "Agent", value: (r) => r.agent?.displayName ?? "—", max: 20 },
   { key: "issue", header: "Issue", value: (r) => r.issue?.identifier ?? "—" },
   { key: "createdAt", header: "Created", value: (r) => r.createdAt.slice(0, 10) },
-  { key: "summary", header: "Summary", value: (r) => r.summary?.replace(/\n/g, " ") ?? "—", max: 60 },
+  {
+    key: "summary",
+    header: "Summary",
+    value: (r) => r.summary?.replace(/\n/g, " ") ?? "—",
+    max: 60,
+  },
   { key: "id", header: "ID", value: (r) => r.id },
 ];
 
@@ -88,7 +93,12 @@ export function registerAgentSession(issue: Command): void {
           ["Created", d.createdAt],
           ["Started", d.startedAt],
           ["Ended", d.endedAt],
-          ["Dismissed", d.dismissedAt ? `${d.dismissedAt}${d.dismissedBy ? ` by ${d.dismissedBy.displayName}` : ""}` : null],
+          [
+            "Dismissed",
+            d.dismissedAt
+              ? `${d.dismissedAt}${d.dismissedBy ? ` by ${d.dismissedBy.displayName}` : ""}`
+              : null,
+          ],
           ["External link", d.externalLink],
           ["URL", d.url],
           ["Summary", d.summary ? `\n${d.summary}` : null],
@@ -103,9 +113,7 @@ function renderActivities(d: svc.AgentSessionDetail): string {
   const lines = d.activities.map((a) => {
     const when = a.createdAt.slice(11, 19);
     const text =
-      a.action !== null
-        ? `${a.action}${a.parameter ? `: ${a.parameter}` : ""}`
-        : (a.body ?? "");
+      a.action !== null ? `${a.action}${a.parameter ? `: ${a.parameter}` : ""}` : (a.body ?? "");
     return `- ${when} ${a.type}: ${text.replace(/\s*\n\s*/g, " ")}`;
   });
   if (d.activitiesTruncated) lines.push(`… more activities not shown (use --json)`);

package/src/commands/api.ts

@@ -32,7 +32,12 @@ export function registerApi(program: Command): void {
     .command("api [query]")
     .description("Run a raw GraphQL query or mutation against the Linear API")
     .option("--query-file <path>", "read the query from a file ('-' for stdin)")
-    .option("--var <k=v...>", "set a variable (repeatable; string value)", collectKeyVal, {})
+    .option(
+      "--var <k=v...>",
+      "set a variable (repeatable; JSON literals are typed, other values are strings)",
+      collectKeyVal,
+      {},
+    )
     .option("--vars <json>", "variables as a JSON object")
     .option("--vars-file <path>", "read variables from a JSON file ('-' for stdin)")
     .option("--operation <name>", "run this operation of a multi-operation document")
@@ -102,6 +107,11 @@ function readFileOrThrow(path: string, label: string): string {
 }
 
 function resolveQuery(arg: string | undefined, file: string | undefined): string {
+  if (arg !== undefined && file !== undefined) {
+    throw usageError(
+      "Pass the GraphQL query either as an argument or with --query-file, not both.",
+    );
+  }
   let query: string | undefined;
   if (arg !== undefined) query = arg;
   else if (file !== undefined) query = readFileOrThrow(file, "--query-file");
@@ -119,7 +129,7 @@ function resolveVariables(opts: Record<string, any>): Record<string, unknown> {
     vars = { ...vars, ...parseJsonObject(text, "--vars-file") };
   }
   if (opts.vars) vars = { ...vars, ...parseJsonObject(opts.vars, "--vars") };
-  if (opts.var) vars = { ...vars, ...(opts.var as Record<string, string>) };
+  if (opts.var) vars = { ...vars, ...(opts.var as Record<string, unknown>) };
   return vars;
 }
 
@@ -217,10 +227,7 @@ function describeNames(operations: OperationDefinitionNode[]): string {
   return operations.map((o) => o.name?.value ?? "<unnamed>").join(", ");
 }
 
-function unknownOperationMessage(
-  requested: string,
-  operations: OperationDefinitionNode[],
-): string {
+function unknownOperationMessage(requested: string, operations: OperationDefinitionNode[]): string {
   const named = operations.filter((o) => o.name).map((o) => o.name!.value);
   const available = named.length
     ? `Available: ${named.join(", ")}.`
@@ -269,7 +276,6 @@ async function paginate(
   variables: Record<string, unknown>,
 ): Promise<{ nodes: unknown[]; pageCount: number; truncated: boolean }> {
   let after: string | undefined = variables.after as string | undefined;
-  let firstData: any;
   const allNodes: unknown[] = [];
   let pages = 0;
   let truncated = false;
@@ -278,10 +284,10 @@ async function paginate(
     const result: any = await withRetry(() =>
       (ctx.client.client as any).rawRequest(query, { ...variables, after }),
     );
-    if (!firstData) firstData = result.data;
     const conn = findConnection(result.data);
     if (!conn) {
-      if (pages === 0) throw new CliError("No connection (nodes/pageInfo) found to paginate.", "usage");
+      if (pages === 0)
+        throw new CliError("No connection (nodes/pageInfo) found to paginate.", "usage");
       break;
     }
     allNodes.push(...conn.nodes);

package/src/commands/attach.ts

@@ -27,8 +27,14 @@ export function registerAttach(issue: Command): void {
     .command("attach <issue> <file...>")
     .description("Upload files and attach them to an issue (private by default)")
     .option("--title <title>", "attachment title (single file only; default: the file name)")
-    .option("--comment <body>", "also post a comment with this body embedding the files as markdown")
-    .option("--public", "upload to a public, world-readable URL (raster images only; default: private)")
+    .option(
+      "--comment <body>",
+      "also post a comment with this body embedding the files as markdown",
+    )
+    .option(
+      "--public",
+      "upload to a public, world-readable URL (raster images only; default: private)",
+    )
     .addHelpText(
       "after",
       [
@@ -50,8 +56,13 @@ export function registerAttach(issue: Command): void {
           comment: opts.comment,
           public: opts.public === true,
           onAttached: (a, iss) => {
-            ctx.output.success(`Attached ${a.filename} (${formatBytes(a.size)}) to ${iss.identifier}`);
-            if (a.public) ctx.output.warn(`${a.filename} is on a public URL, readable by anyone: ${a.assetUrl}`);
+            ctx.output.success(
+              `Attached ${a.filename} (${formatBytes(a.size)}) to ${iss.identifier}`,
+            );
+            if (a.public)
+              ctx.output.warn(
+                `${a.filename} is on a public URL, readable by anyone: ${a.assetUrl}`,
+              );
           },
         });
         const identifier = result.issue.identifier;

package/src/commands/comment.ts

@@ -52,26 +52,37 @@ function buildAdd(_o: MountOptions): Command {
     .argument("[body]")
     .description("Add a comment to an issue (images uploaded with --attach render inline)")
     .option("--body-file <path>", "read comment body from a file ('-' = stdin)")
+    .option(
+      "--mention <user>",
+      "prepend a real Linear mention (name, email, me, or id; repeatable)",
+      collectArray,
+    )
     .option(
       "--attach <file>",
       "upload a file and embed it in the comment (images inline; repeatable; private by default)",
       collectArray,
     )
-    .option("--public", "upload the attachments to public, world-readable URLs (raster images only)")
+    .option(
+      "--public",
+      "upload the attachments to public, world-readable URLs (raster images only)",
+    )
     .action(
       action(async (ctx: Context, opts, issueArg: string, bodyArg?: string) => {
         const attachments: string[] = opts.attach ?? [];
+        const mentions: string[] = opts.mention ?? [];
         if (opts.public && attachments.length === 0) {
           throw usageError("--public applies to uploads; add --attach <file>, or drop --public.");
         }
-        // With attachments the body is optional (the embeds are the comment),
-        // so the editor is not opened for one — the reference CLI's rule too.
+        // With attachments or explicit mentions the body is optional, so the
+        // editor is not opened for one — the reference CLI's attachment rule,
+        // extended to mention-only comments.
         const body = resolveBody({
           arg: bodyArg,
           file: opts.bodyFile,
-          interactive: ctx.isTTY && attachments.length === 0,
+          interactive: ctx.isTTY && attachments.length === 0 && mentions.length === 0,
         });
-        if (!body && attachments.length === 0) throw usageError("No comment body provided.");
+        if (!body && attachments.length === 0 && mentions.length === 0)
+          throw usageError("No comment body provided.");
         const {
           issue,
           comment: created,
@@ -79,9 +90,11 @@ function buildAdd(_o: MountOptions): Command {
         } = await svc.addComment(ctx.client, issueArg, body ?? "", {
           attachments,
           public: opts.public === true,
+          mentions,
         });
         for (const u of uploads) {
-          if (u.public) ctx.output.warn(`${u.filename} is on a public URL, readable by anyone: ${u.assetUrl}`);
+          if (u.public)
+            ctx.output.warn(`${u.filename} is on a public URL, readable by anyone: ${u.assetUrl}`);
         }
         ctx.output.emit(
           {
@@ -110,7 +123,12 @@ function buildUpdate(o: MountOptions): Command {
     .argument("<commentId>")
     .argument("[body]")
     .description("Update a comment's body")
-    .option("--body-file <path>", "read new body from a file ('-' = stdin)");
+    .option("--body-file <path>", "read new body from a file ('-' = stdin)")
+    .option(
+      "--mention <user>",
+      "prepend a real Linear mention (name, email, me, or id; repeatable)",
+      collectArray,
+    );
   if (o.aliases !== false) cmd.alias("edit");
   return cmd.action(
     action(async (ctx: Context, opts, commentId: string, bodyArg?: string) => {
@@ -127,7 +145,13 @@ function buildUpdate(o: MountOptions): Command {
       if (body === undefined) throw usageError("No comment body provided.");
       // The editor path hands back a trimmed body, so compare against the
       // trimmed original: an untouched session must read as "unchanged".
-      const updated = await svc.updateComment(ctx.client, commentId, body, current.body.trim());
+      const updated = await svc.updateComment(
+        ctx.client,
+        commentId,
+        body,
+        current.body.trim(),
+        opts.mention ?? [],
+      );
       ctx.output.emit({ id: updated.id, url: updated.url }, () =>
         ctx.output.success(`Updated comment ${updated.id}`),
       );
@@ -168,11 +192,26 @@ export function registerComment(program: Command): void {
     .command("reply <commentId> [body]")
     .description("Reply to a comment (nested under it)")
     .option("--body-file <path>", "read reply body from a file ('-' = stdin)")
+    .option(
+      "--mention <user>",
+      "prepend a real Linear mention (name, email, me, or id; repeatable)",
+      collectArray,
+    )
     .action(
       action(async (ctx: Context, opts, commentId: string, bodyArg?: string) => {
-        const body = resolveBody({ arg: bodyArg, file: opts.bodyFile, interactive: ctx.isTTY });
-        if (!body) throw usageError("No reply body provided.");
-        const { comment: created, issue } = await svc.replyToComment(ctx.client, commentId, body);
+        const mentions: string[] = opts.mention ?? [];
+        const body = resolveBody({
+          arg: bodyArg,
+          file: opts.bodyFile,
+          interactive: ctx.isTTY && mentions.length === 0,
+        });
+        if (!body && mentions.length === 0) throw usageError("No reply body provided.");
+        const { comment: created, issue } = await svc.replyToComment(
+          ctx.client,
+          commentId,
+          body ?? "",
+          mentions,
+        );
         ctx.output.emit(
           { id: created.id, parent: commentId, issue: issue?.identifier ?? null, url: created.url },
           () => ctx.output.success(`Replied to comment${issue ? ` on ${issue.identifier}` : ""}`),

package/src/commands/completion.ts

@@ -47,12 +47,8 @@ compdef _linear linear lin
 `;
     case "fish":
       return `# linear fish completion:  linear completion fish > ~/.config/fish/completions/linear.fish
-${commands
-  .map((c) => `complete -c linear -n '__fish_use_subcommand' -a '${c}'`)
-  .join("\n")}
-${commands
-  .map((c) => `complete -c lin -n '__fish_use_subcommand' -a '${c}'`)
-  .join("\n")}
+${commands.map((c) => `complete -c linear -n '__fish_use_subcommand' -a '${c}'`).join("\n")}
+${commands.map((c) => `complete -c lin -n '__fish_use_subcommand' -a '${c}'`).join("\n")}
 `;
   }
 }

package/src/commands/cycle.ts

@@ -41,7 +41,12 @@ export function registerCycle(program: Command): void {
     .description("Show a cycle (by id, number, or 'current')")
     .action(
       action(async (ctx: Context, opts, id: string) => {
-        const detail = await svc.getCycleDetail(ctx.client, id, opts.team ?? ctx.defaultTeam, ctx.defaultTeam);
+        const detail = await svc.getCycleDetail(
+          ctx.client,
+          id,
+          opts.team ?? ctx.defaultTeam,
+          ctx.defaultTeam,
+        );
         emitDetail(ctx, detail);
       }),
     );

package/src/commands/discover.ts

@@ -26,7 +26,9 @@ import type { Context } from "../context.js";
 export function registerCommands(program: Command): void {
   program
     .command("commands [path...]")
-    .description("List every command in a machine-readable tree, or describe one (for scripts/agents)")
+    .description(
+      "List every command in a machine-readable tree, or describe one (for scripts/agents)",
+    )
     .addHelpText(
       "after",
       [
@@ -89,7 +91,9 @@ function renderTree(ctx: Context, nodes: CommandNode[], baseDepth = 0): void {
 
 /** One command in full: usage, aliases, options, and the `--json` output shape. */
 function renderOne(ctx: Context, n: CommandNode): void {
-  ctx.output.line(`Usage: linear ${[n.path, n.options.length ? "[options]" : "", usageArgs(n)].filter(Boolean).join(" ")}`);
+  ctx.output.line(
+    `Usage: linear ${[n.path, n.options.length ? "[options]" : "", usageArgs(n)].filter(Boolean).join(" ")}`,
+  );
   if (n.description) ctx.output.line(`  ${n.description}`);
   if (n.aliases.length) ctx.output.line(`Aliases: ${n.aliases.join(", ")}`);
   if (n.options.length) {

package/src/commands/document.ts

@@ -34,7 +34,10 @@ function addTargetOptions(cmd: Command, verb: string): Command {
     .option("-p, --project <name>", `${verb} a project (name or id)`)
     .option("--issue <id>", `${verb} an issue (identifier or id)`)
     .option("--initiative <name>", `${verb} an initiative (name or id)`)
-    .option(CYCLE_FLAG, `${verb} a cycle (number, name, id, or 'current'; team from --team or config)`)
+    .option(
+      CYCLE_FLAG,
+      `${verb} a cycle (number, name, id, or 'current'; team from --team or config)`,
+    )
     .option("--release <name>", `${verb} a release (name, version, or id)`);
 }
 

package/src/commands/initiative.ts

@@ -18,7 +18,11 @@ import type { Column } from "../output/table.js";
 const ROW_COLUMNS: Column<svc.InitiativeRow>[] = [
   { key: "name", header: "Name", value: (r) => r.name, max: 40 },
   { key: "status", header: "Status", value: (r) => r.status ?? "—", max: 12 },
-  { key: "priority", header: "Pri", value: (r) => (r.priority ? svc.priorityLabel(r.priority) : "—") },
+  {
+    key: "priority",
+    header: "Pri",
+    value: (r) => (r.priority ? svc.priorityLabel(r.priority) : "—"),
+  },
   { key: "targetDate", header: "Target", value: (r) => r.targetDate ?? "—" },
   { key: "health", header: "Health", value: (r) => r.health ?? "—", max: 12 },
 ];