linear-sdk-cli 0.1.0

package/src/lib/introspect.ts

@@ -0,0 +1,150 @@
+/**
+ * Walk a commander program tree into a flat, machine-readable description of
+ * every (sub)command — used by `linear commands` for discovery by agents.
+ */
+
+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;
+  required: boolean;
+  variadic: boolean;
+}
+
+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 {
+  /** Space-joined command path, e.g. "issue create". */
+  path: string;
+  description: string;
+  aliases: string[];
+  arguments: CommandArgument[];
+  options: CommandOption[];
+  /**
+   * What the command prints under `--json` (TES-610): the row/object keys with
+   * their types, from `lib/output-shapes.ts`. Absent on a group that only holds
+   * subcommands and prints nothing of its own.
+   */
+  output?: OutputShape;
+}
+
+/**
+ * Produce a flat array of command nodes for `root` and all descendants. The
+ * root program itself is skipped; only its (sub)commands are emitted. Help and
+ * version pseudo-options are omitted from each command's option list. Sorted by
+ * path for stable output.
+ */
+export function walkCommands(root: Command): CommandNode[] {
+  const out: CommandNode[] = [];
+
+  const visit = (cmd: Command, prefix: string[]): void => {
+    for (const sub of cmd.commands) {
+      // Commander models help as a hidden command; skip it.
+      if (sub.name() === "help") continue;
+      const path = [...prefix, sub.name()];
+      out.push(describe(sub, path));
+      visit(sub, path);
+    }
+  };
+
+  visit(root, []);
+  out.sort((a, b) => a.path.localeCompare(b.path));
+  return out;
+}
+
+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 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) => {
+      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 output = outputShapeOf(joined);
+  return {
+    path: joined,
+    description: cmd.description() ?? "",
+    aliases: cmd.aliases(),
+    arguments: args,
+    options,
+    ...(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

@@ -0,0 +1,270 @@
+/**
+ * OS keyring access for stored API keys.
+ *
+ * The service name and the account convention are the reference CLI's
+ * (schpet/linear-cli 2.x): service `linear-cli`, account = workspace slug. That
+ * is deliberate — a user migrating from it already has an entry, and we find it
+ * without a re-login. The flip side is that the entry is SHARED: `auth logout`
+ * here removes it for both CLIs, and `auth login` here overwrites theirs.
+ *
+ * Backends are synchronous (spawnSync) because config resolution is
+ * synchronous and runs before any command body. Only macOS Keychain and the
+ * Linux Secret Service (`secret-tool`) are implemented; everywhere else — and
+ * wherever the tool is missing — `keyring()` returns null and the callers fall
+ * back to the plaintext file without complaint.
+ *
+ * The secret never travels on argv (visible to every process via `ps`): on
+ * macOS it goes through `security -i`, which reads its command line from stdin;
+ * on Linux `secret-tool store` reads the secret from stdin by design.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { CliError } from "./errors.js";
+
+export const KEYRING_SERVICE = "linear-cli";
+
+export type KeyringName = "keychain" | "secret-service";
+
+export interface KeyringBackend {
+  /** How the backend is named in receipts and `auth status`. */
+  readonly name: KeyringName;
+  /** Human label for the store, e.g. "macOS Keychain". */
+  readonly label: string;
+  /** Read the secret for an account; null when there is no entry. */
+  get(account: string): string | null;
+  /** Create or replace the entry. */
+  set(account: string, secret: string): void;
+  /** Remove the entry. Returns false when there was none. */
+  delete(account: string): boolean;
+}
+
+/** Thrown when the keyring tool ran but failed for a reason other than "no such item". */
+export class KeyringError extends CliError {
+  constructor(message: string) {
+    super(message, "runtime");
+    this.name = "KeyringError";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// macOS: /usr/bin/security
+// ---------------------------------------------------------------------------
+
+const SECURITY = "/usr/bin/security";
+/** `security` exit status for errSecItemNotFound. */
+const ERR_SEC_ITEM_NOT_FOUND = 44;
+
+function runSecurity(args: string[], input?: string) {
+  const r = spawnSync(SECURITY, args, { encoding: "utf8", input });
+  if (r.error) {
+    throw new KeyringError(`Could not run ${SECURITY}: ${r.error.message}`);
+  }
+  return { status: r.status ?? -1, stdout: r.stdout ?? "", stderr: (r.stderr ?? "").trim() };
+}
+
+/**
+ * Quote one token for `security -i`, whose line parser understands double
+ * quotes with backslash escapes (verified: `-a "x\"y"` stores account `x"y`).
+ * A newline would end the command mid-way, so it is refused outright rather
+ * than escaped — no workspace slug or Linear key contains one anyway.
+ */
+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.`,
+    );
+  }
+  return `"${token.replace(/[\\"]/g, (c) => `\\${c}`)}"`;
+}
+
+export const macosKeychain: KeyringBackend = {
+  name: "keychain",
+  label: "macOS Keychain",
+
+  get(account) {
+    const r = runSecurity(["find-generic-password", "-a", account, "-s", KEYRING_SERVICE, "-w"]);
+    if (r.status === 0) {
+      // `-w` prints the secret and a trailing newline.
+      const secret = r.stdout.replace(/\r?\n$/, "");
+      return secret.length > 0 ? secret : null;
+    }
+    if (r.status === ERR_SEC_ITEM_NOT_FOUND) return null;
+    throw new KeyringError(
+      `security find-generic-password failed (exit ${r.status})${r.stderr ? `: ${r.stderr}` : ""}`,
+    );
+  },
+
+  set(account, secret) {
+    // Interactive mode reads the whole command from stdin, so the secret is
+    // 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";
+    const r = runSecurity(["-i"], line);
+    if (r.status !== 0) {
+      throw new KeyringError(
+        `security add-generic-password failed (exit ${r.status})${r.stderr ? `: ${r.stderr}` : ""}`,
+      );
+    }
+  },
+
+  delete(account) {
+    const r = runSecurity(["delete-generic-password", "-a", account, "-s", KEYRING_SERVICE]);
+    if (r.status === 0) return true;
+    if (r.status === ERR_SEC_ITEM_NOT_FOUND) return false;
+    throw new KeyringError(
+      `security delete-generic-password failed (exit ${r.status})${r.stderr ? `: ${r.stderr}` : ""}`,
+    );
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Linux: secret-tool (libsecret) — the reference CLI's backend, same attributes
+// ---------------------------------------------------------------------------
+
+function runSecretTool(args: string[], input?: string) {
+  const r = spawnSync("secret-tool", args, { encoding: "utf8", input });
+  if (r.error) {
+    throw new KeyringError(
+      `Could not run secret-tool (install libsecret, e.g. \`apt install libsecret-tools\`): ${r.error.message}`,
+    );
+  }
+  return { status: r.status ?? -1, stdout: r.stdout ?? "", stderr: (r.stderr ?? "").trim() };
+}
+
+export const linuxSecretService: KeyringBackend = {
+  name: "secret-service",
+  label: "system keyring (Secret Service)",
+
+  get(account) {
+    const r = runSecretTool(["lookup", "service", KEYRING_SERVICE, "account", account]);
+    if (r.status === 0) {
+      // secret-tool writes the secret verbatim (no newline) when piped.
+      return r.stdout.length > 0 ? r.stdout : null;
+    }
+    // Exit 1 with a silent stderr is "no match"; anything on stderr is a failure.
+    if (r.status === 1 && r.stderr === "") return null;
+    throw new KeyringError(
+      `secret-tool lookup failed (exit ${r.status})${r.stderr ? `: ${r.stderr}` : ""}`,
+    );
+  },
+
+  set(account, secret) {
+    const r = runSecretTool(
+      [
+        "store",
+        "--label",
+        `${KEYRING_SERVICE}: ${account}`,
+        "service",
+        KEYRING_SERVICE,
+        "account",
+        account,
+      ],
+      secret,
+    );
+    if (r.status !== 0) {
+      throw new KeyringError(
+        `secret-tool store failed (exit ${r.status})${r.stderr ? `: ${r.stderr}` : ""}`,
+      );
+    }
+  },
+
+  delete(account) {
+    // `clear` succeeds whether or not an item matched, so probe first to
+    // report the truth.
+    const existed = this.get(account) !== null;
+    const r = runSecretTool(["clear", "service", KEYRING_SERVICE, "account", account]);
+    if (r.status !== 0) {
+      throw new KeyringError(
+        `secret-tool clear failed (exit ${r.status})${r.stderr ? `: ${r.stderr}` : ""}`,
+      );
+    }
+    return existed;
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Selection
+// ---------------------------------------------------------------------------
+
+/** 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") {
+    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
+    // (any status) proves the executable is on PATH.
+    const r = spawnSync("secret-tool", [], { encoding: "utf8" });
+    return r.error ? null : linuxSecretService;
+  }
+  return null;
+}
+
+/**
+ * The keyring for this machine, or null when there is none — in which case
+ * callers keep the plaintext file and say nothing, because that is not an
+ * error condition, just a platform.
+ */
+export function keyring(): KeyringBackend | null {
+  if (overrideBackend !== undefined) return overrideBackend;
+  const home = process.env.HOME;
+  if (detectedBackend === undefined || detectedHome !== home) {
+    detectedBackend = detect();
+    detectedHome = home;
+  }
+  return detectedBackend;
+}
+
+/**
+ * Test seam: install a fake backend (or `null` for "no keyring") so unit tests
+ * never touch the developer's real Keychain. `undefined` restores detection.
+ */
+export function setKeyringBackend(backend: KeyringBackend | null | undefined): void {
+  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. */
+export function memoryKeyring(initial: Record<string, string> = {}): KeyringBackend & {
+  readonly store: Map<string, string>;
+} {
+  const store = new Map(Object.entries(initial));
+  return {
+    name: "keychain",
+    label: "test keyring",
+    store,
+    get: (a) => store.get(a) ?? null,
+    set: (a, s) => void store.set(a, s),
+    delete: (a) => store.delete(a),
+  };
+}

package/src/lib/mutation.ts

@@ -0,0 +1,53 @@
+/**
+ * Mutation payload unwrapping — the one place that decides a mutation worked.
+ *
+ * Every Linear mutation answers with a payload carrying a non-null
+ * `success: Boolean!`; most also carry the entity they touched
+ * (`{ success, issue }`, `{ success, projectMilestone }`, …) while a few carry
+ * nothing but bookkeeping (`{ success, lastSyncId }` — deletes, archives,
+ * subscribe/unsubscribe, notification updates). A service that ignores
+ * `success`, or that substitutes the pre-mutation entity when the payload has
+ * none, reports a success it never checked: the CLI prints `Updated TES-1` and
+ * exits 0 while nothing changed. Both forms go through here instead.
+ *
+ * `success: false` is the API refusing the write, not the user mistyping, so it
+ * is an `api` error (exit 1 — runtime), not a usage error (exit 2).
+ */
+
+import { CliError } from "./errors.js";
+
+/** The shape every Linear mutation payload has in common. */
+export interface MutationPayload {
+  success: boolean;
+}
+
+const failed = (action: string, why: string) => new CliError(`${action} failed: ${why}.`, "api");
+
+/**
+ * Assert that a mutation reported success, for the payloads that carry no
+ * entity of their own. Returns the payload so a caller can read `lastSyncId`.
+ */
+export async function assertMutation<P extends MutationPayload>(
+  payload: P | Promise<P>,
+  action: string,
+): Promise<P> {
+  const p = await payload;
+  if (p?.success !== true) throw failed(action, "the API reported success: false");
+  return p;
+}
+
+/**
+ * Assert success *and* return the entity the payload is supposed to carry.
+ * A missing entity on a successful payload is still a failure — we have nothing
+ * to report back, and the pre-mutation entity would be a lie.
+ */
+export async function unwrapMutation<P extends MutationPayload, K extends keyof P>(
+  payload: P | Promise<P>,
+  key: K,
+  action: string,
+): Promise<NonNullable<Awaited<P[K]>>> {
+  const p = await assertMutation(payload, action);
+  const entity = await p[key];
+  if (entity == null) throw failed(action, `the API returned no ${String(key)}`);
+  return entity as NonNullable<Awaited<P[K]>>;
+}

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"));
+    });
+  });
+}