linear-sdk-cli 0.1.0

package/src/services/label.ts

@@ -0,0 +1,193 @@
+/**
+ * Label service: all SDK access for issue labels lives here so commands stay thin.
+ *
+ * The list uses a tailored GraphQL query (one round-trip, no N+1 on the team
+ * name) and may be scoped to a single team; single mutations use the typed SDK
+ * client and unwrap the `{ success, issueLabel }` payload. Labels can be
+ * workspace-level (team-less) or scoped to one team.
+ */
+
+import type { LinearClient } from "@linear/sdk";
+import { withRetry } from "../client.js";
+import { shape } from "../lib/shape.js";
+import { collectRawQuery } from "../lib/pagination.js";
+import { usageError, notFound, ambiguous } from "../lib/errors.js";
+import { assertMutation, unwrapMutation } from "../lib/mutation.js";
+import { resolveTeam, resolveLabelIds, isUuid } from "../lib/resolve.js";
+
+export interface LabelRow {
+  id: string;
+  name: string;
+  color: string;
+  isGroup: boolean;
+  team: { key: string; name: string } | null;
+  parent: { name: string } | null;
+}
+
+/** The row's shape as `linear commands` advertises it (TES-610); checked against the interface. */
+export const LABEL_ROW_SHAPE = shape<LabelRow>({
+  id: "string",
+  name: "string",
+  color: "string",
+  isGroup: "boolean",
+  team: { nullable: { key: "string", name: "string" } },
+  parent: { nullable: { name: "string" } },
+});
+
+const LIST_QUERY = `
+query CliIssueLabels($filter: IssueLabelFilter, $first: Int!, $after: String) {
+  issueLabels(filter: $filter, first: $first, after: $after) {
+    nodes {
+      id name color isGroup
+      team { key name }
+      parent { name }
+    }
+    pageInfo { hasNextPage endCursor }
+  }
+}`;
+
+export interface ListOptions {
+  /** Ignore the team argument and the configured default; list the whole workspace. */
+  allTeams?: boolean;
+}
+
+/**
+ * List labels, scoped to the labels an issue in one team can carry.
+ *
+ * When `teamInput` (or the default team) resolves to a team, the result is that
+ * team's labels **plus the workspace-level (team-less) ones** — the same set
+ * `resolveLabelIds` accepts for that team, and the set Linear offers in the
+ * label picker. It used to filter on `team.key` alone, which silently dropped
+ * every workspace label whenever a default team was configured: `label list`
+ * showed 5 of the 8 labels valid on the team's issues, and every "no label
+ * matching X — run 'linear label list'" error pointed at that incomplete list.
+ *
+ * `allTeams` (or no team in scope at all) lists every label in the workspace.
+ */
+export async function listLabels(
+  client: LinearClient,
+  teamInput: string | undefined,
+  limit: number,
+  defaultTeamKey: string | undefined,
+  opts: ListOptions = {},
+): Promise<LabelRow[]> {
+  const teamKey = opts.allTeams ? undefined : (teamInput ?? defaultTeamKey);
+  let filter: Record<string, any> | undefined;
+  if (teamKey) {
+    const team = await resolveTeam(client, teamKey, undefined);
+    filter = { or: [{ team: { key: { eq: team.key } } }, { team: { null: true } }] };
+  }
+
+  return collectRawQuery<LabelRow>(
+    client as any,
+    LIST_QUERY,
+    { filter },
+    "issueLabels",
+    limit,
+    toLabelRow,
+  );
+}
+
+/** Map a tailored-query label node to a display row. */
+function toLabelRow(n: any): LabelRow {
+  return {
+    id: n.id,
+    name: n.name,
+    color: n.color,
+    isGroup: !!n.isGroup,
+    team: n.team ?? null,
+    parent: n.parent ?? null,
+  };
+}
+
+export interface CreateOptions {
+  name: string;
+  color?: string;
+  description?: string;
+  team?: string;
+  parent?: string;
+}
+
+/**
+ * Build an IssueLabelCreateInput, resolving every human reference to an id. A
+ * team is optional: without one the label is workspace-level. A parent label is
+ * resolved within the same team scope when a team is known.
+ */
+export async function createLabel(
+  client: LinearClient,
+  opts: CreateOptions,
+  defaultTeamKey: string | undefined,
+) {
+  const input: Record<string, any> = { name: opts.name };
+  if (opts.color !== undefined) input.color = opts.color;
+  if (opts.description !== undefined) input.description = opts.description;
+
+  // A team is optional; only resolve it when the user asked for one (an explicit
+  // --team), so that omitting it yields a workspace-level label.
+  let teamId: string | undefined;
+  if (opts.team !== undefined) {
+    teamId = (await resolveTeam(client, opts.team, defaultTeamKey)).id;
+    input.teamId = teamId;
+  }
+  if (opts.parent) {
+    const [parentId] = await resolveLabelIds(client, [opts.parent], teamId);
+    input.parentId = parentId;
+  }
+
+  return unwrapMutation(
+    withRetry(() => client.createIssueLabel(input as any)),
+    "issueLabel",
+    "Label creation",
+  );
+}
+
+export interface UpdateOptions {
+  name?: string;
+  color?: string;
+  description?: string;
+}
+
+export async function updateLabel(client: LinearClient, idArg: string, opts: UpdateOptions) {
+  const id = await resolveLabel(client, idArg);
+  const input: Record<string, any> = {};
+  if (opts.name !== undefined) input.name = opts.name;
+  if (opts.color !== undefined) input.color = opts.color;
+  if (opts.description !== undefined) input.description = opts.description;
+
+  if (Object.keys(input).length === 0)
+    throw usageError("Nothing to update; pass at least one of --name, --color, --description.");
+
+  return unwrapMutation(
+    withRetry(() => client.updateIssueLabel(id, input as any)),
+    "issueLabel",
+    "Label update",
+  );
+}
+
+export async function deleteLabel(client: LinearClient, idArg: string) {
+  const id = await resolveLabel(client, idArg);
+  // Fetch the label first so we can report its name after deletion.
+  const label = await withRetry(() => client.issueLabel(id));
+  await assertMutation(
+    withRetry(() => client.deleteIssueLabel(id)),
+    "Label deletion",
+  );
+  return label;
+}
+
+/**
+ * Resolve a single label reference (UUID or name) to its id. A UUID passes
+ * through; a name is matched workspace-wide and must be unambiguous.
+ */
+async function resolveLabel(client: LinearClient, idArg: string): Promise<string> {
+  if (isUuid(idArg)) return idArg;
+  const labels = await withRetry(() =>
+    client.issueLabels({ filter: { name: { eqIgnoreCase: idArg } } as any, first: 50 }),
+  );
+  if (labels.nodes.length === 0) throw notFound(`No label matching '${idArg}'.`);
+  const exact = labels.nodes.filter((l) => l.name === idArg);
+  const finalists = exact.length ? exact : labels.nodes;
+  if (finalists.length > 1)
+    throw ambiguous(`Multiple labels named '${idArg}'; pass the label id instead.`);
+  return finalists[0]!.id;
+}

package/src/services/milestone.ts

@@ -0,0 +1,262 @@
+/**
+ * Project-milestone service: all SDK access for project milestones lives here so
+ * commands stay thin.
+ *
+ * Milestones are always scoped to a project. Lists go through the project's
+ * `projectMilestones` connection (paginated); single `view` and all mutations
+ * use the typed SDK models. Mutations return SDK payloads ({ success,
+ * projectMilestone }) — we await and unwrap the entity.
+ */
+
+import type { LinearClient } from "@linear/sdk";
+import { withRetry } from "../client.js";
+import { shape } from "../lib/shape.js";
+import {
+  collect,
+  inheritPaginationMetadata,
+  pageSize,
+  pageSizeForMore,
+} from "../lib/pagination.js";
+import { usageError, notFound } from "../lib/errors.js";
+import { assertMutation, unwrapMutation } from "../lib/mutation.js";
+import { resolveProjectId, resolveMilestoneId, isUuid } from "../lib/resolve.js";
+
+export interface MilestoneRow {
+  id: string;
+  name: string;
+  targetDate: string | null;
+  progress: number;
+  status: string;
+  description: string | null;
+}
+
+/** The row's shape as `linear commands` advertises it (TES-610); checked against the interface. */
+export const MILESTONE_ROW_SHAPE = shape<MilestoneRow>({
+  id: "string",
+  name: "string",
+  targetDate: "string|null",
+  progress: "number",
+  status: "string",
+  description: "string|null",
+});
+
+/** Project a ProjectMilestone (SDK model or raw node) to a table row. Exported for tests. */
+export function toRow(m: any): MilestoneRow {
+  return {
+    id: m.id,
+    name: m.name,
+    targetDate: m.targetDate ?? null,
+    progress: m.progress ?? 0,
+    status: m.status ?? "",
+    description: m.description ?? null,
+  };
+}
+
+export async function listMilestones(
+  client: LinearClient,
+  projectInput: string,
+  limit: number,
+): Promise<MilestoneRow[]> {
+  const projectId = await resolveProjectId(client, projectInput);
+  const project = await withRetry(() => client.project(projectId));
+  const conn = await withRetry(() => project.projectMilestones({ first: pageSize(limit) }));
+  const nodes = await collect(conn as any, limit);
+  return inheritPaginationMetadata(nodes.map(toRow), nodes);
+}
+
+export interface MilestoneDetail {
+  id: string;
+  name: string;
+  description: string | null;
+  targetDate: string | null;
+  progress: number;
+  status: string;
+  project: { id: string; name: string } | null;
+  createdAt: string;
+  updatedAt: string;
+  /** Issues assigned to this milestone, capped at `limit`. */
+  issues: Array<{
+    id: string;
+    identifier: string;
+    title: string;
+    state: { id: string; name: string; type: string } | null;
+  }>;
+  /** True when the cap hid some issues, so the caller can say so out loud. */
+  issuesTruncated: boolean;
+}
+
+/** The detail's shape; checked against `MilestoneDetail`. */
+export const MILESTONE_DETAIL_SHAPE = shape<MilestoneDetail>({
+  id: "string",
+  name: "string",
+  description: "string|null",
+  targetDate: "string|null",
+  progress: "number",
+  status: "string",
+  project: { nullable: { id: "string", name: "string" } },
+  createdAt: "string",
+  updatedAt: "string",
+  issues: [
+    {
+      id: "string",
+      identifier: "string",
+      title: "string",
+      state: { nullable: { id: "string", name: "string", type: "string" } },
+    },
+  ],
+  issuesTruncated: "boolean",
+});
+
+/**
+ * The milestone, its project and one page of its issues — with each issue's
+ * state selected in place. The SDK-model version awaited `issue.state` per
+ * issue, one request each: 16 requests for a 13-issue milestone, and `-n 50`
+ * on a full one cost ~53. The page size is `$first`; the milestone fields
+ * ride along on every page and are read off the first.
+ */
+const DETAIL_QUERY = `
+query CliMilestoneDetail($id: String!, $first: Int!, $after: String) {
+  projectMilestone(id: $id) {
+    id name description targetDate progress status createdAt updatedAt
+    project { id name }
+    issues(first: $first, after: $after) {
+      nodes { id identifier title state { id name type } }
+      pageInfo { hasNextPage endCursor }
+    }
+  }
+}`;
+
+/**
+ * Milestone detail plus the issues it contains, capped at `limit` (the global
+ * `-n/--limit`, or all of them under `--all`). `issuesTruncated` lets the caller
+ * say so out loud instead of quietly showing a partial list.
+ */
+export async function getMilestoneDetail(
+  client: LinearClient,
+  id: string,
+  limit = 50,
+): Promise<MilestoneDetail> {
+  const raw = (vars: Record<string, unknown>): Promise<{ data: any }> =>
+    (client as any).client.rawRequest(DETAIL_QUERY, vars);
+  // One extra issue is requested so truncation is a fact we hold, not a guess:
+  // the sentinel item is what tells "the last one fit" from "there is one more".
+  const want = limit === Infinity ? Infinity : limit + 1;
+  const first = pageSizeForMore(limit);
+  const page = await withRetry(() => raw({ id, first, after: undefined }));
+  const m = page.data?.projectMilestone;
+  if (!m) throw notFound(`No milestone ${id}.`);
+  const nodes: any[] = [...(m.issues?.nodes ?? [])];
+  let pageInfo = m.issues?.pageInfo ?? { hasNextPage: false };
+  while (nodes.length < want && pageInfo.hasNextPage) {
+    const after = pageInfo.endCursor;
+    const next = await withRetry(() => raw({ id, first, after }));
+    const conn = next.data?.projectMilestone?.issues;
+    if (!conn) break;
+    nodes.push(...conn.nodes);
+    pageInfo = conn.pageInfo;
+  }
+  const hasMore = nodes.length > limit;
+  return {
+    id: m.id,
+    name: m.name,
+    description: m.description ?? null,
+    targetDate: m.targetDate ?? null,
+    progress: m.progress ?? 0,
+    status: m.status ?? "",
+    project: m.project ?? null,
+    createdAt: m.createdAt,
+    updatedAt: m.updatedAt,
+    issues: nodes.slice(0, limit).map((i) => ({
+      id: i.id,
+      identifier: i.identifier,
+      title: i.title,
+      state: i.state ?? null,
+    })),
+    // We know only that more exist, never how many.
+    issuesTruncated: hasMore,
+  };
+}
+
+/**
+ * A milestone reference as `view`/`update`/`delete` take it: a UUID, or a name
+ * plus the project it lives in. Milestone names are unique only within a
+ * project, so a bare name has nothing to resolve against — the same rule
+ * `issue update --milestone` applies, where the scope is the issue's project
+ * or `--project`. Without a scope the error says what to pass, rather than the
+ * API's "Could not find referenced ProjectMilestone" for a name it never tried
+ * to match.
+ */
+export async function resolveMilestoneRef(
+  client: LinearClient,
+  input: string,
+  projectInput: string | undefined,
+): Promise<string> {
+  if (isUuid(input)) return input;
+  if (!projectInput) {
+    throw usageError(
+      `'${input}' is not a milestone id; pass --project <name|id> to look a milestone up by name.`,
+    );
+  }
+  const projectId = await resolveProjectId(client, projectInput);
+  return resolveMilestoneId(client, projectId, input);
+}
+
+/** The SDK model for a milestone id (mutations need the model's id only, but the name for the receipt). */
+async function resolveMilestone(client: LinearClient, id: string) {
+  return withRetry(() => client.projectMilestone(id));
+}
+
+export interface CreateOptions {
+  name: string;
+  description?: string;
+  targetDate?: string;
+}
+
+/** Build a ProjectMilestoneCreateInput; the milestone is scoped to a project. */
+export async function createMilestone(
+  client: LinearClient,
+  projectInput: string,
+  opts: CreateOptions,
+) {
+  const projectId = await resolveProjectId(client, projectInput);
+  const input: Record<string, any> = { projectId, name: opts.name };
+  if (opts.description !== undefined) input.description = opts.description;
+  if (opts.targetDate) input.targetDate = opts.targetDate;
+
+  return unwrapMutation(
+    withRetry(() => client.createProjectMilestone(input as any)),
+    "projectMilestone",
+    "Milestone creation",
+  );
+}
+
+export interface UpdateOptions {
+  name?: string;
+  description?: string;
+  targetDate?: string;
+}
+
+export async function updateMilestone(client: LinearClient, id: string, opts: UpdateOptions) {
+  const milestone = await resolveMilestone(client, id);
+  const input: Record<string, any> = {};
+  if (opts.name !== undefined) input.name = opts.name;
+  if (opts.description !== undefined) input.description = opts.description;
+  if (opts.targetDate !== undefined) input.targetDate = opts.targetDate;
+
+  if (Object.keys(input).length === 0)
+    throw usageError("Nothing to update; pass at least one field.");
+  return unwrapMutation(
+    withRetry(() => client.updateProjectMilestone(milestone.id, input as any)),
+    "projectMilestone",
+    "Milestone update",
+  );
+}
+
+export async function deleteMilestone(client: LinearClient, id: string) {
+  const milestone = await resolveMilestone(client, id);
+  await assertMutation(
+    withRetry(() => client.deleteProjectMilestone(milestone.id)),
+    "Milestone deletion",
+  );
+  return milestone;
+}

package/src/services/notification.ts

@@ -0,0 +1,190 @@
+/**
+ * Notification service: all SDK access for the viewer's notifications lives here
+ * so commands stay thin.
+ *
+ * The list uses a tailored GraphQL query with inline fragments on the
+ * notification subtypes, so the human-facing "subject" (issue identifier/title,
+ * project name, document title, …) is pulled in a single round-trip with no
+ * N+1. Mutations use the typed SDK (updateNotification / archiveNotification /
+ * notificationMarkReadAll).
+ */
+
+import type { LinearClient } from "@linear/sdk";
+import { withRetry } from "../client.js";
+import { shape } from "../lib/shape.js";
+import { collectRawQuery } from "../lib/pagination.js";
+import { assertMutation } from "../lib/mutation.js";
+import { normalizeError, usageError } from "../lib/errors.js";
+
+export interface NotificationRow {
+  id: string;
+  type: string;
+  subject: string | null;
+  read: boolean;
+  readAt: string | null;
+  snoozedUntilAt: string | null;
+  archivedAt: string | null;
+  createdAt: string;
+}
+
+/** The row's shape as `linear commands` advertises it (TES-610); checked against the interface. */
+export const NOTIFICATION_ROW_SHAPE = shape<NotificationRow>({
+  id: "string",
+  type: "string",
+  subject: "string|null",
+  read: "boolean",
+  readAt: "string|null",
+  snoozedUntilAt: "string|null",
+  archivedAt: "string|null",
+  createdAt: "string",
+});
+
+const LIST_QUERY = `
+query CliNotifications($first: Int!, $after: String, $includeArchived: Boolean) {
+  notifications(first: $first, after: $after, includeArchived: $includeArchived) {
+    nodes {
+      __typename
+      id type readAt snoozedUntilAt archivedAt createdAt
+      ... on IssueNotification { issue { identifier title } comment { id } }
+      ... on ProjectNotification { project { name } projectUpdate { id } }
+      ... on DocumentNotification { documentId }
+      ... on InitiativeNotification { initiative { name } }
+      ... on CustomerNotification { customer { name } }
+    }
+    pageInfo { hasNextPage endCursor }
+  }
+}`;
+
+/**
+ * Derive a short human "subject" line from the typed notification node. The base
+ * Notification type has no title scalar in @linear/sdk v87, so we synthesize one
+ * from the related entity. DocumentNotification exposes only `documentId` (no
+ * nested document relation), so document notifications fall back to that id.
+ */
+function subjectOf(n: any): string | null {
+  if (n.issue) {
+    const id = n.issue.identifier;
+    const title = n.issue.title;
+    return id && title ? `${id} ${title}` : (id ?? title ?? null);
+  }
+  if (n.project?.name) return n.project.name;
+  if (n.initiative?.name) return n.initiative.name;
+  if (n.customer?.name) return n.customer.name;
+  if (n.documentId) return `document ${n.documentId}`;
+  return null;
+}
+
+export async function listNotifications(
+  client: LinearClient,
+  limit: number,
+  includeArchived: boolean,
+): Promise<NotificationRow[]> {
+  return collectRawQuery<NotificationRow>(
+    client as any,
+    LIST_QUERY,
+    { includeArchived },
+    "notifications",
+    limit,
+    (n) => ({
+      id: n.id,
+      type: n.type ?? n.__typename ?? "",
+      subject: subjectOf(n),
+      read: !!n.readAt,
+      readAt: n.readAt ?? null,
+      snoozedUntilAt: n.snoozedUntilAt ?? null,
+      archivedAt: n.archivedAt ?? null,
+      createdAt: n.createdAt,
+    }),
+  );
+}
+
+/**
+ * Mark a single notification read (now) or unread (null).
+ *
+ * NotificationPayload exposes only {success,lastSyncId} (no notification body),
+ * so there is no entity to unwrap — `assertMutation` is the whole check, and a
+ * refused write throws instead of being handed back as `{success:false}` for a
+ * caller to ignore.
+ */
+export async function setRead(client: LinearClient, id: string, read: boolean) {
+  const input = { readAt: read ? new Date().toISOString() : null };
+  await assertMutation(
+    withRetry(() => client.updateNotification(id, input as any)),
+    read ? "Marking notification read" : "Marking notification unread",
+  );
+  return { id, read };
+}
+
+/** One notification's outcome within `markAllRead`. */
+export interface MarkAllItem {
+  id: string;
+  read: boolean;
+  error?: string;
+}
+
+export const MARK_ALL_ITEM_SHAPE = shape<MarkAllItem>({
+  id: "string",
+  read: "boolean",
+  "error?": "string",
+});
+
+/**
+ * Mark all of the viewer's unread notifications as read. The SDK's
+ * `notificationMarkReadAll` requires a specific entity type (an empty input is
+ * rejected with "entity type is not supported"), so we instead enumerate unread
+ * notifications and mark each read.
+ *
+ * This is a batch of independent mutations, so it reports what actually
+ * happened per item rather than a hardcoded aggregate: `count` is the number
+ * that really went through, and `failed` carries the ones that did not, with the
+ * API's reason. One bad notification does not abort the rest — but it can no
+ * longer be reported as a success.
+ */
+export async function markAllRead(
+  client: LinearClient,
+): Promise<{ success: boolean; count: number; attempted: number; failed: MarkAllItem[] }> {
+  const rows = await listNotifications(client, Infinity, false);
+  const unread = rows.filter((r) => !r.readAt);
+  const readAt = new Date().toISOString();
+  const failed: MarkAllItem[] = [];
+  let count = 0;
+  for (const r of unread) {
+    try {
+      await assertMutation(
+        withRetry(() => client.updateNotification(r.id, { readAt } as any)),
+        "Marking notification read",
+      );
+      count += 1;
+    } catch (err) {
+      failed.push({ id: r.id, read: false, error: normalizeError(err).message });
+    }
+  }
+  return { success: failed.length === 0, count, attempted: unread.length, failed };
+}
+
+export async function archiveNotification(client: LinearClient, id: string): Promise<boolean> {
+  await assertMutation(
+    withRetry(() => client.archiveNotification(id)),
+    "Notification archive",
+  );
+  return true;
+}
+
+/** Snooze a notification until the given ISO timestamp. */
+export async function snoozeNotification(client: LinearClient, id: string, untilISO: string) {
+  if (
+    !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})$/.test(
+      untilISO,
+    ) ||
+    !Number.isFinite(Date.parse(untilISO))
+  ) {
+    throw usageError(
+      `Invalid snooze timestamp '${untilISO}'. Use ISO 8601 with a timezone, e.g. 2026-07-01T09:00:00Z.`,
+    );
+  }
+  await assertMutation(
+    withRetry(() => client.updateNotification(id, { snoozedUntilAt: untilISO } as any)),
+    "Notification snooze",
+  );
+  return { id, snoozedUntilAt: untilISO };
+}