linear-sdk-cli 0.1.0

package/src/commands/milestone.ts

@@ -0,0 +1,163 @@
+/**
+ * `linear milestone` (alias `m`) — project milestone management.
+ *
+ * Milestones live inside a project: `list`/`create` take a project reference
+ * (name or id), while `view`/`update`/`delete` take a milestone id — or a
+ * milestone *name* together with `--project`, since names are unique only
+ * within a project.
+ */
+
+import { Command } from "commander";
+import { action } from "../lib/action.js";
+import { resolveBody } from "../lib/body.js";
+import { confirmDestructive, promptInput } from "../lib/prompt.js";
+import { addAliasOption, readAlias } from "../lib/options.js";
+import type { Context } from "../context.js";
+import * as svc from "../services/milestone.js";
+import type { Column } from "../output/table.js";
+
+const ROW_COLUMNS: Column<svc.MilestoneRow>[] = [
+  { key: "name", header: "Name", value: (r) => r.name, max: 40 },
+  { key: "target", header: "Target", value: (r) => r.targetDate ?? "—" },
+  { key: "progress", header: "Progress", value: (r) => formatMilestoneProgress(r.progress) },
+  { key: "status", header: "Status", value: (r) => r.status, max: 14 },
+  { key: "id", header: "ID", value: (r) => r.id },
+];
+
+/**
+ * `ProjectMilestone.progress` is already a percentage — `38.46` for 38%
+ * (verified live) — unlike `Project.progress`, which is a fraction. Multiplying
+ * it by 100 as the project renderer does printed `3846%`. Exported for tests.
+ */
+export function formatMilestoneProgress(progress: number | null): string {
+  if (progress === null || progress === undefined) return "—";
+  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;
+
+export function registerMilestone(program: Command): void {
+  const milestone = program
+    .command("milestone")
+    .alias("m")
+    .description("Work with project milestones");
+
+  // list --------------------------------------------------------------------
+  milestone
+    .command("list <project>")
+    .alias("ls")
+    .description("List milestones in a project")
+    .action(
+      action(async (ctx: Context, _opts, project: string) => {
+        const rows = await svc.listMilestones(ctx.client, project, ctx.limit);
+        ctx.output.list(rows, ROW_COLUMNS, rows);
+      }),
+    );
+
+  // view --------------------------------------------------------------------
+  milestone
+    .command("view <id>")
+    .description("Show a milestone and the issues in it (by id, or by name with --project)")
+    .option(...PROJECT_SCOPE)
+    .action(
+      action(async (ctx: Context, opts, idArg: string) => {
+        const id = await svc.resolveMilestoneRef(ctx.client, idArg, opts.project);
+        const detail = await svc.getMilestoneDetail(ctx.client, id, ctx.limit);
+        const issueLines = detail.issues.map(
+          (i) => `  ${i.identifier}  ${i.state ? `[${i.state.name}] ` : ""}${i.title}`,
+        );
+        if (detail.issuesTruncated) issueLines.push("  … more (use --all)");
+        ctx.output.detail(detail, [
+          ["Milestone", detail.name],
+          ["Project", detail.project?.name ?? null],
+          ["Target", detail.targetDate],
+          ["Progress", formatMilestoneProgress(detail.progress)],
+          ["Status", detail.status],
+          ["Updated", detail.updatedAt],
+          ["ID", detail.id],
+          ["Issues", issueLines.length ? `\n${issueLines.join("\n")}` : null],
+          ["Description", detail.description ? `\n${detail.description}` : null],
+        ]);
+      }),
+    );
+
+  // create ------------------------------------------------------------------
+  const create = milestone
+    .command("create <project>")
+    .alias("new")
+    .description("Create a milestone in a project")
+    .option("--name <name>", "milestone name")
+    .option("-d, --description <text>", "milestone description (body)")
+    .option("--description-file <path>", "read description from a file ('-' = stdin)")
+    .option("--target <date>", "target date (YYYY-MM-DD)")
+    .action(
+      action(async (ctx: Context, opts, project: string) => {
+        let name: string | undefined = opts.name;
+        if (!name) name = await promptInput(ctx, "Name:", { required: true });
+        const description = resolveBody({
+          arg: opts.description,
+          file: opts.descriptionFile,
+          interactive: false,
+        });
+        const created = await svc.createMilestone(ctx.client, project, {
+          name,
+          description,
+          targetDate: readAlias(opts, "--target", "--target-date"),
+        });
+        ctx.output.emit({ id: created.id, name: created.name }, () =>
+          ctx.output.success(`Created milestone ${created.name}`),
+        );
+      }),
+    );
+  addAliasOption(create, "--target-date <date>", "--target");
+
+  // update ------------------------------------------------------------------
+  const update = milestone
+    .command("update <id>")
+    .alias("edit")
+    .description("Update a milestone (by id, or by name with --project)")
+    .option(...PROJECT_SCOPE)
+    .option("--name <name>", "new name")
+    .option("-d, --description <text>", "new description")
+    .option("--description-file <path>", "read description from a file ('-' = stdin)")
+    .option("--target <date>", "target date (YYYY-MM-DD)")
+    .action(
+      action(async (ctx: Context, opts, idArg: string) => {
+        const description = resolveBody({
+          arg: opts.description,
+          file: opts.descriptionFile,
+          interactive: false,
+        });
+        const id = await svc.resolveMilestoneRef(ctx.client, idArg, opts.project);
+        const updated = await svc.updateMilestone(ctx.client, id, {
+          name: opts.name,
+          description,
+          targetDate: readAlias(opts, "--target", "--target-date"),
+        });
+        ctx.output.emit({ id: updated.id, name: updated.name }, () =>
+          ctx.output.success(`Updated milestone ${updated.name}`),
+        );
+      }),
+    );
+  addAliasOption(update, "--target-date <date>", "--target");
+
+  // delete ------------------------------------------------------------------
+  milestone
+    .command("delete <id>")
+    .alias("rm")
+    .description("Delete a milestone (by id, or by name with --project)")
+    .option(...PROJECT_SCOPE)
+    .action(
+      action(async (ctx: Context, opts, idArg: string) => {
+        const id = await svc.resolveMilestoneRef(ctx.client, idArg, opts.project);
+        if (!(await confirmDestructive(ctx, `Delete milestone ${idArg}?`))) return;
+        const deleted = await svc.deleteMilestone(ctx.client, id);
+        ctx.output.emit({ id: deleted.id, name: deleted.name, deleted: true }, () =>
+          ctx.output.success(`Deleted milestone ${deleted.name}`),
+        );
+      }),
+    );
+}

package/src/commands/notification.ts

@@ -0,0 +1,110 @@
+/**
+ * `linear notification` (alias `notif`) — work with the viewer's notifications.
+ */
+
+import { Command } from "commander";
+import { action } from "../lib/action.js";
+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 },
+  { key: "subject", header: "Subject", value: (r) => r.subject ?? "—", max: 50 },
+  { key: "read", header: "Read", value: (r) => (r.read ? "✓" : "•") },
+  { key: "createdAt", header: "Created", value: (r) => r.createdAt.slice(0, 10) },
+];
+
+export function registerNotification(program: Command): void {
+  const notification = program
+    .command("notification")
+    .alias("notif")
+    .description("Work with your notifications");
+
+  // list --------------------------------------------------------------------
+  notification
+    .command("list")
+    .alias("ls")
+    .description("List your notifications")
+    .option("--include-archived", "include archived notifications")
+    .action(
+      action(async (ctx: Context, opts) => {
+        const rows = await svc.listNotifications(ctx.client, ctx.limit, !!opts.includeArchived);
+        ctx.output.list(rows, ROW_COLUMNS, rows);
+      }),
+    );
+
+  // read --------------------------------------------------------------------
+  notification
+    .command("read <id>")
+    .description("Mark a notification as read")
+    .action(
+      action(async (ctx: Context, _opts, id: string) => {
+        // The service throws unless the API confirmed the write, so this
+        // receipt is what happened rather than what was asked for.
+        const n = await svc.setRead(ctx.client, id, true);
+        ctx.output.emit(n, () => ctx.output.success(`Marked ${n.id} read`));
+      }),
+    );
+
+  // unread ------------------------------------------------------------------
+  notification
+    .command("unread <id>")
+    .description("Mark a notification as unread")
+    .action(
+      action(async (ctx: Context, _opts, id: string) => {
+        const n = await svc.setRead(ctx.client, id, false);
+        ctx.output.emit(n, () => ctx.output.success(`Marked ${n.id} unread`));
+      }),
+    );
+
+  // read-all ----------------------------------------------------------------
+  notification
+    .command("read-all")
+    .description("Mark all your notifications as read")
+    .action(
+      action(async (ctx: Context) => {
+        const res = await svc.markAllRead(ctx.client);
+        ctx.output.emit(res, () => {
+          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;
+      }),
+    );
+
+  // archive -----------------------------------------------------------------
+  notification
+    .command("archive <id>")
+    .description("Archive a notification")
+    .action(
+      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}`));
+      }),
+    );
+
+  // snooze ------------------------------------------------------------------
+  notification
+    .command("snooze <id> <untilISO>")
+    .description("Snooze a notification until an ISO timestamp (e.g. 2026-07-01T09:00:00Z)")
+    .action(
+      action(async (ctx: Context, _opts, id: string, untilISO: string) => {
+        const n = await svc.snoozeNotification(ctx.client, id, untilISO);
+        ctx.output.emit(n, () => ctx.output.success(`Snoozed ${n.id} until ${untilISO}`));
+      }),
+    );
+}

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/organization.ts

@@ -0,0 +1,79 @@
+/**
+ * `linear organization` (alias `org`) — inspect the current workspace.
+ *
+ * A read-only group: `view` shows workspace details, `members` lists workspace
+ * users, and `invites` lists pending organization invites. Admin/destructive
+ * operations are intentionally out of scope.
+ */
+
+import { Command } from "commander";
+import { action } from "../lib/action.js";
+import type { Context } from "../context.js";
+import * as svc from "../services/organization.js";
+import type { Column } from "../output/table.js";
+
+const MEMBER_COLUMNS: Column<svc.MemberRow>[] = [
+  { key: "name", header: "Name", value: (r) => r.displayName, max: 24 },
+  { key: "email", header: "Email", value: (r) => r.email, max: 40 },
+  { key: "admin", header: "Admin", value: (r) => (r.admin ? "yes" : "no") },
+  { key: "active", header: "Active", value: (r) => (r.active ? "yes" : "no") },
+];
+
+const INVITE_COLUMNS: Column<svc.InviteRow>[] = [
+  { key: "email", header: "Email", value: (r) => r.email, max: 40 },
+  { key: "status", header: "Status", value: (r) => r.status },
+  { key: "role", header: "Role", value: (r) => r.role },
+];
+
+export function registerOrganization(program: Command): void {
+  const org = program
+    .command("organization")
+    .alias("org")
+    .description("Inspect the current workspace");
+
+  // view --------------------------------------------------------------------
+  org
+    .command("view", { isDefault: true })
+    .alias("show")
+    .description("Show the current workspace")
+    .action(
+      action(async (ctx: Context) => {
+        const detail = await svc.getOrganizationDetail(ctx.client);
+        ctx.output.detail(detail, [
+          ["Workspace", detail.name],
+          ["URL key", detail.urlKey],
+          ["ID", detail.id],
+          ["Users", detail.userCount],
+          ["Issues created", detail.createdIssueCount],
+          ["SAML", detail.samlEnabled ? "yes" : "no"],
+          ["SCIM", detail.scimEnabled ? "yes" : "no"],
+          ["Roadmaps", detail.roadmapEnabled ? "yes" : "no"],
+          ["Logo", detail.logoUrl],
+          ["Created", detail.createdAt],
+          ["Updated", detail.updatedAt],
+        ]);
+      }),
+    );
+
+  // members -----------------------------------------------------------------
+  org
+    .command("members")
+    .description("List workspace members")
+    .action(
+      action(async (ctx: Context) => {
+        const rows = await svc.listMembers(ctx.client, ctx.limit);
+        ctx.output.list(rows, MEMBER_COLUMNS, rows);
+      }),
+    );
+
+  // invites -----------------------------------------------------------------
+  org
+    .command("invites")
+    .description("List organization invites")
+    .action(
+      action(async (ctx: Context) => {
+        const rows = await svc.listInvites(ctx.client, ctx.limit);
+        ctx.output.list(rows, INVITE_COLUMNS, rows);
+      }),
+    );
+}

package/src/commands/project-update.ts

@@ -0,0 +1,47 @@
+/**
+ * `linear project-update` (alias `pu`) — post and list project status updates.
+ */
+
+import { Command } from "commander";
+import { action } from "../lib/action.js";
+import { addUpdateFlags, resolveUpdateBody, UPDATE_COLUMNS } from "../lib/status-update.js";
+import type { Context } from "../context.js";
+import * as svc from "../services/project-update.js";
+
+export function registerProjectUpdate(program: Command): void {
+  const group = program
+    .command("project-update")
+    .alias("pu")
+    .description("Post and list project status updates");
+
+  // create ------------------------------------------------------------------
+  addUpdateFlags(
+    group
+      .command("create <project>")
+      .alias("new")
+      .description("Post a status update on a project (by name or id)"),
+  ).action(
+    action(async (ctx: Context, opts, projectArg: string) => {
+      const body = resolveUpdateBody(ctx, opts);
+      const created = await svc.createProjectUpdate(ctx.client, projectArg, {
+        body,
+        health: opts.health,
+      });
+      ctx.output.emit(created, () =>
+        ctx.output.success(`Posted project update${opts.health ? ` (${opts.health})` : ""}`),
+      );
+    }),
+  );
+
+  // list --------------------------------------------------------------------
+  group
+    .command("list <project>")
+    .alias("ls")
+    .description("List a project's status updates")
+    .action(
+      action(async (ctx: Context, _opts, projectArg: string) => {
+        const rows = await svc.listProjectUpdates(ctx.client, projectArg, ctx.limit);
+        ctx.output.list(rows, UPDATE_COLUMNS, rows);
+      }),
+    );
+}