linear-sdk-cli 0.1.3 → 0.2.3

package/src/context.ts

@@ -8,6 +8,7 @@ import type { LinearClient } from "@linear/sdk";
 import { resolveConfig, type ResolvedConfig } from "./config.js";
 import { createClient, setRetryReporter } from "./client.js";
 import { Output } from "./output/format.js";
+import { isDebugEnabled, shouldUseColor } from "./output/color.js";
 
 /**
  * The globals as the parser actually stores them.
@@ -57,10 +58,17 @@ export class Context {
       // of the config (the default team for creates, cycle lookups, …) is
       // single-valued, so those commands read the full list off their own opts
       // and the config sees the first key.
-      flags: { apiKey: options.apiKey, team: firstTeam(options.team), workspace: options.workspace },
+      flags: {
+        apiKey: options.apiKey,
+        team: firstTeam(options.team),
+        workspace: options.workspace,
+      },
+    });
+    const color = shouldUseColor({
+      disabled: options.noAnsi,
+      json: options.json,
+      isTTY: process.stdout.isTTY === true,
     });
-    const color =
-      options.noAnsi !== true && options.json !== true && process.stdout.isTTY === true;
     // Four independent reasons not to prompt, and any one of them is enough.
     // The first two are the user saying so; the last two are the situation
     // saying so. `--json` counts because JSON is what a script or an agent
@@ -77,8 +85,9 @@ export class Context {
       json: options.json === true,
       color,
       quiet: options.quiet === true,
-      debug: options.debug === true,
+      debug: isDebugEnabled(options.debug),
       fields: options.fields,
+      isTTY: process.stdout.isTTY === true,
     });
     // Rate-limit waits are status, so they go through the same sink as every
     // other status line: stderr, silenced by --quiet, never on JSON stdout.

package/src/git.ts

@@ -5,6 +5,7 @@
  */
 
 import { execFileSync } from "node:child_process";
+import { CliError } from "./lib/errors.js";
 
 /**
  * Extract a Linear issue identifier (e.g. `TES-123`) from a git branch name.
@@ -74,7 +75,11 @@ export function buildTrailer(identifier: string, opts: { references?: boolean }
  * word directly before the id and links — and closes — the issue. The URL line is
  * for the humans reading the log.
  */
-export function buildTrailers(identifier: string, url: string, opts: { references?: boolean } = {}): string {
+export function buildTrailers(
+  identifier: string,
+  url: string,
+  opts: { references?: boolean } = {},
+): string {
   return `Linear-issue: ${buildTrailer(identifier, opts)}\nLinear-issue-url: ${url}`;
 }
 
@@ -136,14 +141,34 @@ export interface CheckoutResult {
   created: boolean;
 }
 
+/** Run the mutating checkout command and retain git's explanation on failure. */
+function gitCheckout(args: string[], cwd?: string): void {
+  try {
+    execFileSync("git", args, {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf8",
+    });
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException & { status?: number; stderr?: Buffer | string };
+    if (e.code === "ENOENT")
+      throw new CliError("Git is required to check out an issue branch.", "runtime");
+    const stderr = e.stderr ? e.stderr.toString().trim() : "";
+    throw new CliError(
+      stderr || `git ${args.join(" ")} exited with code ${e.status ?? 1}.`,
+      "runtime",
+    );
+  }
+}
+
 /** Checkout `branch`, creating it if it does not exist. */
 export function checkoutBranch(branch: string, cwd?: string): CheckoutResult {
   const exists =
     git(["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`], cwd) !== undefined;
   if (exists) {
-    execFileSync("git", ["checkout", branch], { cwd, stdio: "ignore" });
+    gitCheckout(["checkout", branch], cwd);
     return { branch, created: false };
   }
-  execFileSync("git", ["checkout", "-b", branch], { cwd, stdio: "ignore" });
+  gitCheckout(["checkout", "-b", branch], cwd);
   return { branch, created: true };
 }

package/src/lib/body.ts

@@ -30,7 +30,7 @@ export interface BodyInputs {
 }
 
 export function resolveBody(inputs: BodyInputs): string | undefined {
-  if (inputs.arg !== undefined) return inputs.arg;
+  if (inputs.arg !== undefined) return validateInlineBody(inputs.arg);
   if (inputs.file !== undefined) return readBodyFile(inputs.file);
   if (inputs.interactive) return openEditor(inputs.template ?? "");
   if (inputs.editorRequested) {
@@ -42,6 +42,27 @@ export function resolveBody(inputs: BodyInputs): string | undefined {
   return undefined;
 }
 
+/**
+ * A quoted shell argument does not interpret `\n`. This is an especially easy
+ * mistake for an agent composing Markdown in one command: Linear then stores
+ * and renders the two literal characters, often across an entire issue body.
+ *
+ * Do not silently unescape them. A literal backslash-n can be intentional in
+ * source code, JSON, or a regular expression, and changing it would corrupt
+ * user data. File/stdin input is the unambiguous route for both real newlines
+ * and intentional escape syntax.
+ */
+export function validateInlineBody(body: string): string {
+  if (body.includes("\\n")) {
+    throw usageError(
+      "Inline text contains a literal \\n sequence; shell quotes do not turn it into a line break. " +
+        "Use this command's *-file option with '-' and provide the Markdown on stdin. " +
+        "If the literal \\n is intentional, file input preserves it unchanged.",
+    );
+  }
+  return body;
+}
+
 function readBodyFile(file: string): string {
   if (file === "-") return readStdinSync();
   try {
@@ -66,7 +87,10 @@ export function readStdinSync(): string {
  * so it is split shell-style (quotes and backslashes honoured) into argv, and
  * the file is appended. Exported for tests.
  */
-export function editorCommand(env: NodeJS.ProcessEnv = process.env): { raw: string; argv: string[] } {
+export function editorCommand(env: NodeJS.ProcessEnv = process.env): {
+  raw: string;
+  argv: string[];
+} {
   const raw = env.VISUAL || env.EDITOR || "vi";
   return { raw, argv: shellSplit(raw) };
 }

package/src/lib/errors.ts

@@ -2,7 +2,7 @@
  * Error handling: a single `CliError` type the whole app throws, plus a
  * normalizer that maps Linear SDK errors into stable codes + exit codes.
  *
- * Exit codes (documented in PLAN.md):
+ * Exit codes (documented in README.md):
  *   0 ok · 1 runtime/API · 2 usage · 3 not-found/ambiguous · 4 auth · 5 rate-limited
  */
 
@@ -50,21 +50,28 @@ export class CliError extends Error {
   readonly exitCode: ExitCodeValue;
   /** Extra detail surfaced only with --debug (e.g. raw GraphQL errors). */
   readonly detail?: unknown;
+  /** A separately actionable hint; machine callers never have to parse prose. */
+  readonly suggestion?: string;
 
-  constructor(message: string, code: ErrorCode = "runtime", detail?: unknown) {
+  constructor(message: string, code: ErrorCode = "runtime", detail?: unknown, suggestion?: string) {
     super(message);
     this.name = "CliError";
     this.code = code;
     this.exitCode = EXIT_BY_CODE[code];
     this.detail = detail;
+    this.suggestion = suggestion;
   }
 }
 
 /** Convenience constructors for the common cases. */
-export const usageError = (m: string) => new CliError(m, "usage");
-export const notFound = (m: string) => new CliError(m, "not_found");
-export const ambiguous = (m: string) => new CliError(m, "ambiguous");
-export const authError = (m: string) => new CliError(m, "auth");
+export const usageError = (m: string, suggestion?: string) =>
+  new CliError(m, "usage", undefined, suggestion);
+export const notFound = (m: string, suggestion?: string) =>
+  new CliError(m, "not_found", undefined, suggestion);
+export const ambiguous = (m: string, suggestion?: string) =>
+  new CliError(m, "ambiguous", undefined, suggestion);
+export const authError = (m: string, suggestion?: string) =>
+  new CliError(m, "auth", undefined, suggestion);
 
 /**
  * Map an unknown thrown value (typically a Linear SDK error) into a CliError
@@ -77,7 +84,10 @@ export function normalizeError(err: unknown): CliError {
   if (err instanceof Error) {
     const name = err.constructor?.name ?? err.name ?? "";
     const anyErr = err as Record<string, any>;
-    const gqlErrors: any[] = anyErr.errors ?? anyErr.raw?.response?.errors ?? [];
+    const gqlErrors: any[] =
+      [anyErr.errors, anyErr.response?.errors, anyErr.raw?.response?.errors].find(
+        (errors) => Array.isArray(errors) && errors.length > 0,
+      ) ?? [];
     const type: string | undefined =
       anyErr.type ?? gqlErrors[0]?.extensions?.type ?? gqlErrors[0]?.extensions?.code;
     const message = pickMessage(err, gqlErrors);
@@ -91,7 +101,9 @@ export function normalizeError(err: unknown): CliError {
     // semantically it is a not-found — reclassify so `view <bad-id>` exits 3.
     if (
       (code === "validation" || code === "api") &&
-      /could ?n[o']t find|not found|does not exist|no such|referenced \w+\.?$/i.test(message)
+      /could ?n[o']t find|not found|does not exist|no such|referenced \w+\.?$/i.test(
+        messageCandidates(err, gqlErrors).join("; "),
+      )
     ) {
       code = "not_found";
     }
@@ -162,9 +174,22 @@ function classify(name: string, type: string | undefined): ErrorCode {
 }
 
 function pickMessage(err: Error, gqlErrors: any[]): string {
+  const presentable = gqlErrors
+    .map((e) => e?.extensions?.userPresentableMessage)
+    .find((message) => typeof message === "string" && message.trim().length > 0);
+  if (presentable) return presentable;
+
   const fromGql = gqlErrors
     .map((e) => e?.message)
     .filter(Boolean)
     .join("; ");
   return fromGql || err.message || "Unknown error";
 }
+
+/** All message forms are retained for classification even when a nicer one is displayed. */
+function messageCandidates(err: Error, gqlErrors: any[]): string[] {
+  return [
+    err.message,
+    ...gqlErrors.flatMap((error) => [error?.message, error?.extensions?.userPresentableMessage]),
+  ].filter((message): message is string => typeof message === "string" && message.length > 0);
+}

package/src/lib/introspect.ts

@@ -6,6 +6,13 @@
 import type { Command } from "commander";
 import type { OutputShape } from "./shape.js";
 import { outputShapeOf } from "./output-shapes.js";
+import {
+  FIELDS_COMMANDS,
+  LIMIT_COMMANDS,
+  TEAM_COMMANDS,
+  YES_COMMANDS,
+  globalOptionKeys,
+} from "./options.js";
 
 export interface CommandArgument {
   name: string;
@@ -16,6 +23,18 @@ export interface CommandArgument {
 export interface CommandOption {
   flags: string;
   description: string;
+  /** Commander's destination key (e.g. `includeArchived`). */
+  attribute: string;
+  /** Whether the option's value is required/optional after the flag. */
+  valueRequired: boolean;
+  valueOptional: boolean;
+  variadic: boolean;
+  choices?: string[];
+  defaultValue?: unknown;
+  /** True for the flags inherited from the root CLI contract. */
+  global: boolean;
+  /** Whether this global has an effect on this command. Local options are always applicable. */
+  applicable: boolean;
 }
 
 export interface CommandNode {
@@ -58,17 +77,37 @@ export function walkCommands(root: Command): CommandNode[] {
 }
 
 function describe(cmd: Command, path: string[]): CommandNode {
-  const args: CommandArgument[] = (cmd as any).registeredArguments?.map((a: any) => ({
-    name: a.name(),
-    required: a.required === true,
-    variadic: a.variadic === true,
-  })) ?? [];
+  const args: CommandArgument[] =
+    (cmd as any).registeredArguments?.map((a: any) => ({
+      name: a.name(),
+      required: a.required === true,
+      variadic: a.variadic === true,
+    })) ?? [];
 
+  const joined = path.join(" ");
+  const defaultName = (cmd as any)._defaultCommandName as string | undefined;
+  const effectivePath = defaultName ? `${joined} ${defaultName}` : joined;
+  const runnable = Boolean((cmd as any)._actionHandler) || defaultName !== undefined;
+  const globalKeys = new Set(globalOptionKeys());
   const options: CommandOption[] = cmd.options
     .filter((o: any) => !o.hidden)
-    .map((o: any) => ({ flags: o.flags as string, description: (o.description as string) ?? "" }));
+    .map((o: any) => {
+      const attribute = o.attributeName() as string;
+      const global = globalKeys.has(attribute) && isGlobalFlag(o.long);
+      return {
+        flags: o.flags as string,
+        description: (o.description as string) ?? "",
+        attribute,
+        valueRequired: o.required === true,
+        valueOptional: o.optional === true,
+        variadic: o.variadic === true,
+        ...(Array.isArray(o.argChoices) ? { choices: [...o.argChoices] as string[] } : {}),
+        ...(o.defaultValue !== undefined ? { defaultValue: o.defaultValue as unknown } : {}),
+        global,
+        applicable: global ? globalApplies(effectivePath, o.long, runnable) : true,
+      };
+    });
 
-  const joined = path.join(" ");
   const output = outputShapeOf(joined);
   return {
     path: joined,
@@ -79,3 +118,33 @@ function describe(cmd: Command, path: string[]): CommandNode {
     ...(output ? { output } : {}),
   };
 }
+
+const GLOBAL_LONGS = new Set([
+  "--json",
+  "--no-ansi",
+  "--api-key",
+  "--workspace",
+  "--team",
+  "--limit",
+  "--all",
+  "--fields",
+  "--yes",
+  "--quiet",
+  "--no-input",
+  "--debug",
+]);
+
+function isGlobalFlag(long: string | undefined): boolean {
+  return long !== undefined && GLOBAL_LONGS.has(long);
+}
+
+function globalApplies(path: string, long: string | undefined, hasAction: boolean): boolean {
+  if (!hasAction) return false;
+  if (long === "--fields") return FIELDS_COMMANDS.has(path);
+  if (long === "--limit" || long === "--all") return LIMIT_COMMANDS.has(path);
+  if (long === "--team") return TEAM_COMMANDS.has(path);
+  if (long === "--yes") return YES_COMMANDS.has(path);
+  // The remaining globals control the shared parser/context/error/output
+  // boundary and are intentionally safe on every runnable command.
+  return true;
+}

package/src/lib/keyring.ts

@@ -71,7 +71,9 @@ function runSecurity(args: string[], input?: string) {
  */
 function quoteForSecurity(token: string, what: string): string {
   if (/[\r\n]/.test(token)) {
-    throw new KeyringError(`The ${what} contains a line break and cannot be stored in the keychain.`);
+    throw new KeyringError(
+      `The ${what} contains a line break and cannot be stored in the keychain.`,
+    );
   }
   return `"${token.replace(/[\\"]/g, (c) => `\\${c}`)}"`;
 }
@@ -98,7 +100,16 @@ export const macosKeychain: KeyringBackend = {
     // never an argv element. (`add-generic-password -w` as the LAST option
     // prompts instead — but on /dev/tty, so it hangs in a real terminal.)
     const line =
-      ["add-generic-password", "-a", quoteForSecurity(account, "workspace slug"), "-s", KEYRING_SERVICE, "-U", "-w", quoteForSecurity(secret, "API key")].join(" ") + "\n";
+      [
+        "add-generic-password",
+        "-a",
+        quoteForSecurity(account, "workspace slug"),
+        "-s",
+        KEYRING_SERVICE,
+        "-U",
+        "-w",
+        quoteForSecurity(secret, "API key"),
+      ].join(" ") + "\n";
     const r = runSecurity(["-i"], line);
     if (r.status !== 0) {
       throw new KeyringError(
@@ -150,7 +161,15 @@ export const linuxSecretService: KeyringBackend = {
 
   set(account, secret) {
     const r = runSecretTool(
-      ["store", "--label", `${KEYRING_SERVICE}: ${account}`, "service", KEYRING_SERVICE, "account", account],
+      [
+        "store",
+        "--label",
+        `${KEYRING_SERVICE}: ${account}`,
+        "service",
+        KEYRING_SERVICE,
+        "account",
+        account,
+      ],
       secret,
     );
     if (r.status !== 0) {
@@ -178,12 +197,24 @@ export const linuxSecretService: KeyringBackend = {
 // Selection
 // ---------------------------------------------------------------------------
 
-/** `undefined` = not decided yet; `null` = decided: no keyring here. */
-let selected: KeyringBackend | null | undefined;
+/** Explicit test/application override; `undefined` means automatic detection. */
+let overrideBackend: KeyringBackend | null | undefined;
+/** Automatic detection is cached only while HOME is unchanged. */
+let detectedBackend: KeyringBackend | null | undefined;
+let detectedHome: string | undefined;
 
 function detect(): KeyringBackend | null {
   if (process.platform === "darwin") {
-    return existsSync(SECURITY) ? macosKeychain : null;
+    if (!existsSync(SECURITY)) return null;
+    // `security add-generic-password` opens a system dialog when the process
+    // has no default user keychain (common with an isolated HOME in tests,
+    // containers, and launch agents). Probe first so that environment is
+    // treated like every other machine without a usable keyring and callers
+    // can fall back to the 0600 credential file without surprising UI.
+    const probe = spawnSync(SECURITY, ["default-keychain", "-d", "user"], {
+      encoding: "utf8",
+    });
+    return !probe.error && probe.status === 0 ? macosKeychain : null;
   }
   if (process.platform === "linux") {
     // With no arguments secret-tool prints usage and exits 2; a completed run
@@ -200,8 +231,13 @@ function detect(): KeyringBackend | null {
  * error condition, just a platform.
  */
 export function keyring(): KeyringBackend | null {
-  if (selected === undefined) selected = detect();
-  return selected;
+  if (overrideBackend !== undefined) return overrideBackend;
+  const home = process.env.HOME;
+  if (detectedBackend === undefined || detectedHome !== home) {
+    detectedBackend = detect();
+    detectedHome = home;
+  }
+  return detectedBackend;
 }
 
 /**
@@ -209,7 +245,13 @@ export function keyring(): KeyringBackend | null {
  * never touch the developer's real Keychain. `undefined` restores detection.
  */
 export function setKeyringBackend(backend: KeyringBackend | null | undefined): void {
-  selected = backend;
+  overrideBackend = backend;
+  if (backend === undefined) {
+    // Tests routinely swap HOME to an isolated fixture. Do not let a backend
+    // detected against the real login keychain escape into that environment.
+    detectedBackend = undefined;
+    detectedHome = undefined;
+  }
 }
 
 /** An in-memory backend for tests. */

package/src/lib/mentions.ts

@@ -0,0 +1,49 @@
+import type { LinearClient } from "@linear/sdk";
+import { withRetry } from "../client.js";
+import { usageError } from "./errors.js";
+import { resolveUserId } from "./resolve.js";
+
+/**
+ * Prepend explicit Linear mentions to a Markdown body.
+ *
+ * Linear stores a real user mention as `@[label](user-id)`. Ordinary `@name`
+ * text is deliberately not parsed: it is prose unless the caller also passes
+ * `--mention <user>`. Keeping the intent in an option prevents an innocent
+ * name in a pasted body from notifying somebody.
+ */
+export async function prependMentions(
+  client: LinearClient,
+  body: string,
+  references: string[] = [],
+): Promise<string> {
+  if (references.length === 0) return body;
+
+  const mentions: string[] = [];
+  const seen = new Set<string>();
+  for (const raw of references) {
+    const reference = normalizeMentionReference(raw);
+    const id = await resolveUserId(client, reference);
+    if (seen.has(id)) continue;
+    seen.add(id);
+
+    const user = await withRetry(() => client.user(id));
+    const label = escapeMentionLabel(user.displayName);
+    mentions.push(`@[${label}](${id})`);
+  }
+
+  const prefix = mentions.join(" ");
+  return body ? `${prefix}\n\n${body}` : prefix;
+}
+
+/** Accept the natural `@ada` spelling without confusing it with an email. */
+export function normalizeMentionReference(raw: string): string {
+  const reference = raw.trim();
+  if (!reference) throw usageError("--mention requires a non-empty user reference.");
+  if (reference.startsWith("@") && reference !== "@me") return reference.slice(1);
+  return reference;
+}
+
+/** Escape the Markdown-link label without changing Linear's mention grammar. */
+export function escapeMentionLabel(label: string): string {
+  return label.replace(/\\/g, "\\\\").replace(/\]/g, "\\]");
+}

package/src/lib/open.ts

@@ -0,0 +1,32 @@
+/** Open a Linear URL in the system browser or the macOS Linear app. */
+
+import { execFile } from "node:child_process";
+import { CliError, usageError } from "./errors.js";
+
+export async function openUrl(url: string, opts: { app?: boolean } = {}): Promise<void> {
+  if (opts.app && process.platform !== "darwin") {
+    throw usageError("--app currently requires macOS with Linear.app installed; use --web here.");
+  }
+  const command =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "rundll32.exe"
+        : "xdg-open";
+  const args =
+    process.platform === "darwin"
+      ? opts.app
+        ? ["-a", "Linear", url]
+        : [url]
+      : process.platform === "win32"
+        ? ["url.dll,FileProtocolHandler", url]
+        : [url];
+
+  await new Promise<void>((resolve, reject) => {
+    execFile(command, args, { encoding: "utf8" }, (err, _stdout, stderr) => {
+      if (!err) return resolve();
+      const detail = stderr.trim();
+      reject(new CliError(detail || `Failed to open ${url}: ${err.message}`, "runtime"));
+    });
+  });
+}