linear-sdk-cli 0.1.3 → 0.2.3

package/src/commands/meta.ts

@@ -10,6 +10,8 @@ import { withRetry } from "../client.js";
 import { resolve } from "node:path";
 import {
   writeCredential,
+  probeKeyringCredential,
+  adoptKeyringCredential,
   removeCredential,
   setDefaultWorkspace,
   listCredentials,
@@ -25,8 +27,8 @@ import {
 } from "../config.js";
 import { keyring } from "../lib/keyring.js";
 import { readStdinSync } from "../lib/body.js";
-import { authError, usageError } from "../lib/errors.js";
-import { promptSecret, promptSelect } from "../lib/prompt.js";
+import { authError, normalizeError, usageError } from "../lib/errors.js";
+import { confirmDestructive, promptSecret, promptSelect } from "../lib/prompt.js";
 import { listTeams } from "../services/team.js";
 import { ISSUE_SORTS } from "../services/issue.js";
 import { firstTeam, type Context } from "../context.js";
@@ -58,6 +60,79 @@ const whoamiAction = action(async (ctx: Context) => {
   );
 });
 
+interface AuthIdentity {
+  user: { id: string; name: string; email: string };
+  organization: { id: string; name: string; urlKey: string };
+}
+
+interface AuthValidationClient {
+  viewer: Promise<{ id: string; name: string; email: string }>;
+  organization: Promise<{ id: string; name: string; urlKey: string }>;
+}
+
+export type AuthValidationClientFactory = (apiKey: string) => AuthValidationClient;
+
+const defaultAuthValidationClientFactory: AuthValidationClientFactory = (apiKey) =>
+  new LinearClient({ apiKey }) as unknown as AuthValidationClient;
+let authValidationClientFactory = defaultAuthValidationClientFactory;
+
+/** Test seam for command-level auth tests; production always uses LinearClient. */
+export function setAuthValidationClientFactoryForTests(
+  factory: AuthValidationClientFactory | undefined,
+): void {
+  authValidationClientFactory = factory ?? defaultAuthValidationClientFactory;
+}
+
+/** Merge the local and global login spellings without silently choosing one. */
+export function selectLoginKey(
+  localKey: string | undefined,
+  globalKey: string | undefined,
+): string | undefined {
+  if (localKey !== undefined && globalKey !== undefined) {
+    throw usageError("Pass only one of --key or --api-key to `auth login`.");
+  }
+  return localKey ?? globalKey;
+}
+
+/** Validate a credential and prove that an explicitly requested slug matches it. */
+export async function validateAuthCredential(
+  apiKey: string,
+  requestedWorkspace?: string,
+): Promise<AuthIdentity> {
+  const client = authValidationClientFactory(apiKey);
+  let me;
+  let org;
+  try {
+    me = await withRetry(() => client.viewer);
+    org = await withRetry(() => client.organization);
+  } catch (err) {
+    const normalized = normalizeError(err);
+    if (normalized.code === "auth" || normalized.code === "forbidden") {
+      throw authError("That API key was rejected by Linear.");
+    }
+    throw normalized;
+  }
+  if (requestedWorkspace && requestedWorkspace !== org.urlKey) {
+    throw usageError(
+      `--workspace '${requestedWorkspace}' does not match the key's workspace '${org.urlKey}'. Store credentials under their Linear workspace slug.`,
+    );
+  }
+  return {
+    user: { id: me.id, name: me.name, email: me.email },
+    organization: { id: org.id, name: org.name, urlKey: org.urlKey },
+  };
+}
+
+function explicitWorkspaceSlug(input: string): string {
+  const slug = input.trim();
+  if (!/^[a-z0-9](?:[a-z0-9-]{0,98}[a-z0-9])?$/.test(slug)) {
+    throw usageError(
+      "Workspace slug must be its lowercase Linear URL key (letters, numbers, and hyphens).",
+    );
+  }
+  return slug;
+}
+
 export function registerMeta(program: Command): void {
   program.command("whoami").description("Show the authenticated user").action(whoamiAction);
 
@@ -75,10 +150,7 @@ export function registerMeta(program: Command): void {
     .command("login")
     .description("Validate and store a Linear API key for a workspace")
     .option("--key <key>", "API key (otherwise prompted; '-' reads it from stdin)")
-    .option(
-      "--plaintext",
-      "Store the key in the config file (0600) instead of the system keyring",
-    )
+    .option("--plaintext", "Store the key in the config file (0600) instead of the system keyring")
     .action(
       // The global `--workspace <slug>` selects the slug to store under
       // (default: derived from the key's organization urlKey).
@@ -87,14 +159,14 @@ export function registerMeta(program: Command): void {
         // it is a credential, and it must not reach the screen or scrollback.
         // Nothing below echoes it either: the receipt reports the user and
         // where the key went, never the value.
-        let key: string | undefined = opts.key;
+        let key: string | undefined = selectLoginKey(opts.key, ctx.options.apiKey);
         if (key === "-") {
           key = readStdinSync();
         } else if (key) {
           // argv is world-readable (`ps`) and lands in shell history; say so
           // once, quietly, and carry on — the script author chose it.
           ctx.output.warn(
-            "--key on the command line is visible to other processes and shell history; prefer the prompt or `--key -` (stdin).",
+            "An API key on the command line is visible to other processes and shell history; prefer the prompt or `--key -` (stdin).",
           );
         } else {
           key = await promptSecret(ctx, "Linear API key:", { required: true });
@@ -102,25 +174,18 @@ export function registerMeta(program: Command): void {
         key = key.trim();
         if (!key) throw usageError("No API key provided.");
         // Validate before persisting and learn the workspace slug.
-        const client = new LinearClient({ apiKey: key });
-        let me;
-        let org;
-        try {
-          me = await client.viewer;
-          org = await client.organization;
-        } catch {
-          throw authError("That API key was rejected by Linear.");
-        }
-        const slug: string = ctx.options.workspace ?? org.urlKey;
+        const identity = await validateAuthCredential(key, ctx.options.workspace);
+        const { user: me, organization: org } = identity;
+        const slug: string = org.urlKey;
         const { path, storage, keyringLabel } = writeCredential(slug, key, {
           plaintext: opts.plaintext === true,
         });
         const where =
           storage === "keychain"
-            ? `Key saved to the ${keyringLabel} (service linear-cli, account '${slug}'); ${path} records the workspace.`
+            ? `Credential saved to the ${keyringLabel} (service linear-cli, account '${slug}'); ${path} records the workspace.`
             : opts.plaintext
-              ? `Key saved to ${path} (plaintext, 0600).`
-              : `Key saved to ${path} (plaintext, 0600 — no system keyring on this platform).`;
+              ? `Credential saved to ${path} (plaintext, 0600).`
+              : `Credential saved to ${path} (plaintext, 0600 — no system keyring on this platform).`;
         ctx.output.emit(
           {
             success: true,
@@ -137,6 +202,45 @@ export function registerMeta(program: Command): void {
       }),
     );
 
+  // adopt ------------------------------------------------------------------
+  auth
+    .command("adopt <slug>")
+    .description("Adopt an existing named credential from the shared OS keyring")
+    .action(
+      action(async (ctx: Context, _opts, input: string) => {
+        const slug = explicitWorkspaceSlug(input);
+        if (ctx.options.apiKey !== undefined) {
+          throw usageError(
+            "`auth adopt` reads only the named OS keyring entry; remove --api-key (or use `auth login --key -` to supply a key on stdin).",
+          );
+        }
+        if (ctx.options.workspace && ctx.options.workspace !== slug) {
+          throw usageError(
+            `The positional workspace '${slug}' conflicts with --workspace '${ctx.options.workspace}'.`,
+          );
+        }
+
+        // Probe one exact account only. No keyring enumeration and no secret
+        // on argv, stdout, stderr, or disk.
+        const found = probeKeyringCredential(slug);
+        const identity = await validateAuthCredential(found.apiKey, slug);
+        const adopted = adoptKeyringCredential(slug, found.apiKey);
+        ctx.output.emit(
+          {
+            success: true,
+            workspace: slug,
+            user: identity.user,
+            storage: adopted.storage,
+            path: adopted.path,
+          },
+          () =>
+            ctx.output.success(
+              `Adopted workspace '${slug}' from the ${adopted.keyringLabel}; ${adopted.path} now records the workspace without storing the secret.`,
+            ),
+        );
+      }),
+    );
+
   // list --------------------------------------------------------------------
   auth
     .command("list")
@@ -263,6 +367,7 @@ export function registerMeta(program: Command): void {
                 .join(", ")}). Pass --workspace <slug> to choose which to remove.`,
             );
         }
+        if (!(await confirmDestructive(ctx, `Remove credential for workspace '${slug}'?`))) return;
         const removed = removeCredential(slug);
         ctx.output.emit({ success: true, workspace: slug, removed }, () =>
           removed
@@ -279,7 +384,9 @@ export function registerMeta(program: Command): void {
   // show (default) ----------------------------------------------------------
   config
     .command("show", { isDefault: true })
-    .description("Show the resolved configuration and where each value came from (secrets redacted)")
+    .description(
+      "Show the resolved configuration and where each value came from (secrets redacted)",
+    )
     .action(
       action(async (ctx) => {
         // Re-resolve to expose sources/paths beyond what Context keeps.
@@ -299,8 +406,10 @@ export function registerMeta(program: Command): void {
           if (o.source === "none") return "default";
           return o.path ? `${o.source}: ${o.path}` : o.source;
         };
-        const show = (key: keyof typeof c.origins, value: string | undefined): string | undefined =>
-          value === undefined ? undefined : `${value}  (${from(key)})`;
+        const show = (
+          key: keyof typeof c.origins,
+          value: string | undefined,
+        ): string | undefined => (value === undefined ? undefined : `${value}  (${from(key)})`);
         ctx.output.detail(
           {
             apiKey: redactKey(c.apiKey),
@@ -309,7 +418,6 @@ export function registerMeta(program: Command): void {
             team: c.team ?? null,
             workspace: c.workspace ?? null,
             sort: c.sort,
-            vcs: c.vcs,
             origins: c.origins,
             userConfigPath: c.userConfigPath,
             projectConfigPath: c.projectConfigPath ?? null,
@@ -321,7 +429,6 @@ export function registerMeta(program: Command): void {
             ["Team", show("team", c.team)],
             ["Workspace", show("workspace", c.workspace)],
             ["Sort", show("sort", c.sort)],
-            ["VCS", show("vcs", c.vcs)],
             ["User config", c.userConfigPath],
             ["Project config", c.projectConfigPath],
             ["Global config", c.globalConfigPath],
@@ -358,11 +465,15 @@ export function registerMeta(program: Command): void {
               .map((t) => ({ name: `${t.name} (${t.key})`, value: t.key })),
           );
         }
-        const settings: Partial<Record<SettableKey, string>> = { team: validateSetting("team", team) };
+        const settings: Partial<Record<SettableKey, string>> = {
+          team: validateSetting("team", team),
+        };
         if (opts.sort !== undefined) settings.sort = validateSetting("sort", opts.sort);
         initProjectConfig(path, settings, { force: opts.force === true });
         ctx.output.emit({ success: true, path, ...settings }, () =>
-          ctx.output.success(`Wrote ${path} (team ${settings.team}${settings.sort ? `, sort ${settings.sort}` : ""}).`),
+          ctx.output.success(
+            `Wrote ${path} (team ${settings.team}${settings.sort ? `, sort ${settings.sort}` : ""}).`,
+          ),
         );
       }),
     );
@@ -411,9 +522,6 @@ function validateSetting(key: SettableKey, value: string): string {
         throw usageError(`Invalid sort '${v}'. Valid values: ${ISSUE_SORTS.join(", ")}.`);
       }
       return v;
-    case "vcs":
-      if (!["git", "jj"].includes(v)) throw usageError(`Invalid vcs '${v}'. Valid values: git, jj.`);
-      return v;
     case "team":
       // A team key: letters and digits, as Linear issues them (TES, ENG2).
       if (!/^[A-Za-z][A-Za-z0-9]*$/.test(v)) {

package/src/commands/milestone.ts

@@ -34,7 +34,10 @@ export function formatMilestoneProgress(progress: number | null): string {
   return `${Math.round(progress)}%`;
 }
 
-const PROJECT_SCOPE = ["-p, --project <name>", "the milestone's project, when <id> is a name (names are unique per project only)"] as const;
+const PROJECT_SCOPE = [
+  "-p, --project <name>",
+  "the milestone's project, when <id> is a name (names are unique per project only)",
+] as const;
 
 export function registerMilestone(program: Command): void {
   const milestone = program

package/src/commands/notification.ts

@@ -8,6 +8,7 @@ import { confirmDestructive } from "../lib/prompt.js";
 import type { Context } from "../context.js";
 import * as svc from "../services/notification.js";
 import type { Column } from "../output/table.js";
+import { ExitCode } from "../lib/errors.js";
 
 const ROW_COLUMNS: Column<svc.NotificationRow>[] = [
   { key: "type", header: "Type", value: (r) => r.type, max: 24 },
@@ -67,10 +68,20 @@ export function registerNotification(program: Command): void {
       action(async (ctx: Context) => {
         const res = await svc.markAllRead(ctx.client);
         ctx.output.emit(res, () => {
-          ctx.output.success(`Marked ${res.count} of ${res.attempted} notification(s) read`);
-          // A partial batch says so out loud instead of hiding behind the count.
-          for (const f of res.failed) ctx.output.warn(`${f.id}: ${f.error}`);
+          if (res.success) {
+            ctx.output.success(`Marked ${res.count} of ${res.attempted} notification(s) read`);
+          } else {
+            ctx.output.warn(
+              `Marked ${res.count} of ${res.attempted} notification(s) read; ${res.failed.length} failed`,
+            );
+            for (const f of res.failed) ctx.output.warn(`${f.id}: ${f.error}`);
+          }
         });
+        // A batch receipt belongs on stdout even when only part of the batch
+        // succeeded, but exit zero would let `read-all && ...` treat that as a
+        // complete success. Preserve the receipt and make the process outcome
+        // unambiguous.
+        if (!res.success) process.exitCode = ExitCode.Runtime;
       }),
     );
 
@@ -82,9 +93,7 @@ export function registerNotification(program: Command): void {
       action(async (ctx: Context, _opts, id: string) => {
         if (!(await confirmDestructive(ctx, `Archive notification ${id}?`))) return;
         const success = await svc.archiveNotification(ctx.client, id);
-        ctx.output.emit({ id, archived: success }, () =>
-          ctx.output.success(`Archived ${id}`),
-        );
+        ctx.output.emit({ id, archived: success }, () => ctx.output.success(`Archived ${id}`));
       }),
     );
 

package/src/commands/open.ts

@@ -0,0 +1,84 @@
+/** `linear open` — open a workspace, team, project, issue, or explicit URL. */
+
+import { Command } from "commander";
+import { action } from "../lib/action.js";
+import { usageError } from "../lib/errors.js";
+import { openUrl } from "../lib/open.js";
+import { normalizeIssueReference, resolveProjectId, resolveTeam } from "../lib/resolve.js";
+import type { Context } from "../context.js";
+import { getIssueDetail } from "../services/issue.js";
+import { getOrganizationDetail } from "../services/organization.js";
+import { getProjectDetail } from "../services/project.js";
+
+const ISSUE_REFERENCE = /^[a-zA-Z][a-zA-Z0-9]*-\d+$/;
+const URL = /^https?:\/\//i;
+type OpenTarget = "workspace" | "team" | "project" | "issue" | "url";
+
+export function registerOpen(program: Command): void {
+  program
+    .command("open [target]")
+    .description("Open the workspace, an issue, team, project, or URL")
+    .option("--app", "open in Linear.app (macOS)")
+    .option("-w, --web", "open in the default browser (the default)")
+    .addHelpText(
+      "after",
+      [
+        "",
+        "Targets: an issue id (TES-123), `team:<key>`, `project:<name>`, or an https URL.",
+        "With no target, opens the current workspace. A bare team key opens that team.",
+      ].join("\n"),
+    )
+    .action(
+      action(async (ctx: Context, opts, target?: string) => {
+        if (opts.app && opts.web) throw usageError("Pass either --web or --app, not both.");
+        const resolved = await resolveOpenTarget(ctx, target);
+        await openUrl(resolved.url, { app: opts.app === true });
+        ctx.output.emit({ ...resolved, opened: true }, () =>
+          ctx.output.success(
+            `Opened ${resolved.label} in ${opts.app ? "Linear.app" : "the browser"}`,
+          ),
+        );
+      }),
+    );
+}
+
+async function resolveOpenTarget(
+  ctx: Context,
+  target: string | undefined,
+): Promise<{ target: OpenTarget; url: string; label: string }> {
+  if (!target) {
+    const org = await getOrganizationDetail(ctx.client);
+    return { target: "workspace", url: `https://linear.app/${org.urlKey}`, label: org.name };
+  }
+  if (URL.test(target)) return { target: "url", url: target, label: target };
+  if (target.startsWith("team:")) {
+    const team = await resolveTeam(ctx.client, target.slice("team:".length), ctx.defaultTeam);
+    const org = await getOrganizationDetail(ctx.client);
+    return {
+      target: "team",
+      url: `https://linear.app/${org.urlKey}/team/${team.key}/all`,
+      label: `${team.key} (${team.name})`,
+    };
+  }
+  if (target.startsWith("project:")) {
+    const project = await getProjectDetail(
+      ctx.client,
+      await resolveProjectId(ctx.client, target.slice("project:".length)),
+    );
+    return { target: "project", url: project.url, label: project.name };
+  }
+  const issueReference = /^\d+$/.test(target)
+    ? normalizeIssueReference(target, ctx.defaultTeam)
+    : target;
+  if (ISSUE_REFERENCE.test(issueReference)) {
+    const issue = await getIssueDetail(ctx.client, issueReference, { includeComments: false });
+    return { target: "issue", url: issue.url, label: issue.identifier };
+  }
+  const team = await resolveTeam(ctx.client, target, ctx.defaultTeam);
+  const org = await getOrganizationDetail(ctx.client);
+  return {
+    target: "team",
+    url: `https://linear.app/${org.urlKey}/team/${team.key}/all`,
+    label: `${team.key} (${team.name})`,
+  };
+}

package/src/commands/project.ts

@@ -36,7 +36,10 @@ function formatProgress(p: number | null): string {
  * stderr, once; `--quiet` silences it, `--json` stdout never carries it.
  * Shared by `project list` and the issue queries.
  */
-export function noteWorkspaceWide(ctx: Context, opts: { team?: unknown; allTeams?: boolean }): void {
+export function noteWorkspaceWide(
+  ctx: Context,
+  opts: { team?: unknown; allTeams?: boolean },
+): void {
   const teamGiven = Array.isArray(opts.team) ? opts.team.length > 0 : opts.team !== undefined;
   if (!teamGiven && !opts.allTeams && !ctx.defaultTeam) {
     ctx.output.info(
@@ -97,8 +100,14 @@ export function registerProject(program: Command): void {
           ["Progress", detail.progress !== null ? formatProgress(detail.progress) : null],
           ["Priority", detail.priorityLabel],
           ["Lead", detail.lead?.displayName ?? null],
-          ["Teams", detail.teams.length ? detail.teams.map((t) => `${t.key} ${t.name}`).join(", ") : null],
-          ["Members", detail.members.length ? detail.members.map((m) => m.displayName).join(", ") : null],
+          [
+            "Teams",
+            detail.teams.length ? detail.teams.map((t) => `${t.key} ${t.name}`).join(", ") : null,
+          ],
+          [
+            "Members",
+            detail.members.length ? detail.members.map((m) => m.displayName).join(", ") : null,
+          ],
           ["Labels", detail.labels.length ? detail.labels.map((l) => l.name).join(", ") : null],
           ["Start", detail.startDate],
           ["Target", detail.targetDate],
@@ -317,7 +326,11 @@ export function registerProject(program: Command): void {
             { key: "name", header: "Name", value: (m) => m.name, max: 40 },
             { key: "target", header: "Target", value: (m) => m.targetDate ?? "—" },
             // A milestone's progress is already a percentage (TES-648), unlike a project's.
-            { key: "progress", header: "Progress", value: (m) => formatMilestoneProgress(m.progress) },
+            {
+              key: "progress",
+              header: "Progress",
+              value: (m) => formatMilestoneProgress(m.progress),
+            },
           ],
           rows,
         );

package/src/commands/team.ts

@@ -59,6 +59,19 @@ export function registerTeam(program: Command): void {
       }),
     );
 
+  // id ----------------------------------------------------------------------
+  team
+    .command("id [key]")
+    .description("Print a team's UUID (defaults to the configured team)")
+    .action(
+      action(async (ctx: Context, _opts, keyArg?: string) => {
+        const resolved = await svc.getTeamIdentity(ctx.client, keyArg, ctx.defaultTeam);
+        // Human mode is deliberately a single UUID for command substitution;
+        // JSON retains the resolved key and name as useful context.
+        ctx.output.emit(resolved, () => process.stdout.write(resolved.id + "\n"));
+      }),
+    );
+
   // view --------------------------------------------------------------------
   team
     .command("view [key]")

package/src/commands/user.ts

@@ -25,8 +25,8 @@ const ROW_COLUMNS: Column<svc.UserRow>[] = [
  * list` and `team members`. Ours is the global `--all` — exhaust pagination —
  * so a transplanted `linear user list --all` succeeds, and the deactivated
  * users it was asking for are quietly missing (TES-637 item 1). The global
- * keeps its one meaning (making it mean "and deactivated" here alone would be a
- * second meaning for one flag, the thing ALIGNMENT.md refuses); instead the
+ * keeps its one meaning (making it mean "and deactivated" here alone would give
+ * one flag two meanings); instead the
  * combination says what it did and names the flag that does the other thing.
  * A warning, not `info`: it survives `--quiet`, because a script is exactly
  * where a wrong result set goes unnoticed. Shared with `team members`.

package/src/commands/webhook.ts

@@ -91,7 +91,12 @@ export function registerWebhook(program: Command): void {
           secret: opts.secret,
         });
         ctx.output.emit(
-          { id: created.id, url: created.url, enabled: created.enabled, resourceTypes: created.resourceTypes },
+          {
+            id: created.id,
+            url: created.url,
+            enabled: created.enabled,
+            resourceTypes: created.resourceTypes,
+          },
           () => ctx.output.success(`Created webhook ${created.id}`),
         );
       }),
@@ -121,7 +126,12 @@ export function registerWebhook(program: Command): void {
           secret: opts.secret,
         });
         ctx.output.emit(
-          { id: updated.id, url: updated.url, enabled: updated.enabled, resourceTypes: updated.resourceTypes },
+          {
+            id: updated.id,
+            url: updated.url,
+            enabled: updated.enabled,
+            resourceTypes: updated.resourceTypes,
+          },
           () => ctx.output.success(`Updated webhook ${updated.id}`),
         );
       }),