linear-sdk-cli 0.1.0

package/src/services/roadmap.ts

@@ -0,0 +1,177 @@
+/**
+ * Roadmap service: all SDK access for roadmaps lives here so commands stay thin.
+ *
+ * Roadmaps are workspace-level and relatively few, so the list uses the typed
+ * SDK connection (paginated via collect()); single `view`, its associated
+ * projects, and all mutations use the typed SDK models. Mutations return SDK
+ * payloads ({ success, roadmap }) — we await and unwrap the entity.
+ *
+ * There is no RoadmapFilter in the SDK, so name lookups match client-side
+ * against the (small) set of workspace roadmaps.
+ */
+
+import type { LinearClient } from "@linear/sdk";
+import { withRetry } from "../client.js";
+import { shape } from "../lib/shape.js";
+import { collect, inheritPaginationMetadata, pageSize } from "../lib/pagination.js";
+import { usageError, notFound, ambiguous } from "../lib/errors.js";
+import { assertMutation, unwrapMutation } from "../lib/mutation.js";
+import { resolveUserId, isUuid } from "../lib/resolve.js";
+
+export interface RoadmapRow {
+  id: string;
+  name: string;
+  description: string | null;
+  url: string;
+}
+
+/** The row's shape as `linear commands` advertises it (TES-610); checked against the interface. */
+export const ROADMAP_ROW_SHAPE = shape<RoadmapRow>({
+  id: "string",
+  name: "string",
+  description: "string|null",
+  url: "string",
+});
+
+/** Project a Roadmap SDK model to a table row. Exported for tests. */
+export function toRow(r: any): RoadmapRow {
+  return {
+    id: r.id,
+    name: r.name,
+    description: r.description ?? null,
+    url: r.url,
+  };
+}
+
+export async function listRoadmaps(client: LinearClient, limit: number): Promise<RoadmapRow[]> {
+  const conn = await withRetry(() => client.roadmaps({ first: pageSize(limit) }));
+  const nodes = await collect(conn as any, limit);
+  return inheritPaginationMetadata(nodes.map(toRow), nodes);
+}
+
+export interface RoadmapDetail {
+  id: string;
+  name: string;
+  description: string | null;
+  color: string | null;
+  url: string;
+  slugId: string;
+  owner: string | null;
+  creator: string | null;
+  createdAt: string;
+  updatedAt: string;
+  projects: string[];
+}
+
+/** The detail's shape; checked against `RoadmapDetail`. */
+export const ROADMAP_DETAIL_SHAPE = shape<RoadmapDetail>({
+  id: "string",
+  name: "string",
+  description: "string|null",
+  color: "string|null",
+  url: "string",
+  slugId: "string",
+  owner: "string|null",
+  creator: "string|null",
+  createdAt: "string",
+  updatedAt: "string",
+  projects: ["string"],
+});
+
+export async function getRoadmapDetail(
+  client: LinearClient,
+  idArg: string,
+): Promise<RoadmapDetail> {
+  const roadmap = await resolveRoadmap(client, idArg);
+  const [owner, creator, projects] = await Promise.all([
+    roadmap.owner,
+    roadmap.creator,
+    withRetry(() => roadmap.projects({ first: 100 })),
+  ]);
+  const projectConn = projects as { nodes: Array<{ name: string }> };
+  return {
+    id: roadmap.id,
+    name: roadmap.name,
+    description: roadmap.description ?? null,
+    color: roadmap.color ?? null,
+    url: roadmap.url,
+    slugId: roadmap.slugId,
+    owner: owner?.displayName ?? null,
+    creator: creator?.displayName ?? null,
+    createdAt: roadmap.createdAt.toISOString(),
+    updatedAt: roadmap.updatedAt.toISOString(),
+    projects: projectConn.nodes.map((p) => p.name),
+  };
+}
+
+export interface CreateOptions {
+  name: string;
+  description?: string;
+  owner?: string;
+  color?: string;
+}
+
+/** Build a RoadmapCreateInput, resolving the owner reference to a user id. */
+export async function createRoadmap(client: LinearClient, opts: CreateOptions) {
+  const input: Record<string, any> = { name: opts.name };
+  if (opts.description !== undefined) input.description = opts.description;
+  if (opts.owner) input.ownerId = await resolveUserId(client, opts.owner);
+  if (opts.color) input.color = opts.color;
+
+  return unwrapMutation(
+    withRetry(() => client.createRoadmap(input as any)),
+    "roadmap",
+    "Roadmap creation",
+  );
+}
+
+export interface UpdateOptions {
+  name?: string;
+  description?: string;
+  owner?: string;
+  color?: string;
+}
+
+export async function updateRoadmap(client: LinearClient, idArg: string, opts: UpdateOptions) {
+  const roadmap = await resolveRoadmap(client, idArg);
+  const input: Record<string, any> = {};
+  if (opts.name !== undefined) input.name = opts.name;
+  if (opts.description !== undefined) input.description = opts.description;
+  if (opts.owner) input.ownerId = await resolveUserId(client, opts.owner);
+  if (opts.color) input.color = opts.color;
+
+  if (Object.keys(input).length === 0)
+    throw usageError("Nothing to update; pass at least one field.");
+  return unwrapMutation(
+    withRetry(() => client.updateRoadmap(roadmap.id, input as any)),
+    "roadmap",
+    "Roadmap update",
+  );
+}
+
+export async function deleteRoadmap(client: LinearClient, idArg: string) {
+  const roadmap = await resolveRoadmap(client, idArg);
+  await assertMutation(
+    withRetry(() => client.deleteRoadmap(roadmap.id)),
+    "Roadmap deletion",
+  );
+  return roadmap;
+}
+
+/**
+ * Resolve a roadmap by id (UUID, fetched directly) or by name. The `roadmaps`
+ * query takes no filter argument in @linear/sdk v87, so matching is client-side
+ * — but we exhaust pagination (via collect) so a match past the first page is
+ * not missed.
+ */
+async function resolveRoadmap(client: LinearClient, idArg: string) {
+  if (isUuid(idArg)) return withRetry(() => client.roadmap(idArg));
+  const conn = await withRetry(() => client.roadmaps({ first: 100 }));
+  const all = await collect<any>(conn as any, Infinity);
+  const lower = idArg.toLowerCase();
+  const matches = all.filter((r: any) => r.name.toLowerCase() === lower);
+  if (matches.length === 0) throw notFound(`No roadmap matching '${idArg}'.`);
+  if (matches.length > 1)
+    throw ambiguous(`Multiple roadmaps match '${idArg}'; pass the roadmap id instead.`);
+  return matches[0]!;
+}

package/src/services/state.ts

@@ -0,0 +1,127 @@
+/**
+ * Workflow-state service: all SDK access for workflow states lives here so
+ * commands stay thin.
+ *
+ * A team is resolved from a friendly key/name/id via `resolveTeam`, then its
+ * states come from the typed `team.states()` connection (sorted client-side by
+ * position). The single `view` takes an id, or a name/type resolved within a team.
+ */
+
+import type { LinearClient } from "@linear/sdk";
+import { withRetry } from "../client.js";
+import { shape } from "../lib/shape.js";
+import { collect, pageSize, setPaginationMetadata } from "../lib/pagination.js";
+import { usageError } from "../lib/errors.js";
+import { resolveTeam, resolveStateId, isUuid } from "../lib/resolve.js";
+
+export interface StateRow {
+  id: string;
+  name: string;
+  type: string;
+  position: number;
+  color: string;
+}
+
+/** The row's shape as `linear commands` advertises it (TES-610); checked against the interface. */
+export const STATE_ROW_SHAPE = shape<StateRow>({
+  id: "string",
+  name: "string",
+  type: "string",
+  position: "number",
+  color: "string",
+});
+
+/** List a team's workflow states, sorted by position (ascending). */
+export async function listStates(
+  client: LinearClient,
+  teamInput: string | undefined,
+  defaultTeamKey: string | undefined,
+  limit: number,
+): Promise<StateRow[]> {
+  const team = await resolveTeam(client, teamInput, defaultTeamKey);
+  const teamModel = await withRetry(() => client.team(team.id));
+  const conn = await withRetry(() => teamModel.states({ first: pageSize(limit) }));
+  // The API's connection order is unrelated to workflow position. Sort the
+  // complete small state set, then apply the caller's limit.
+  const nodes = await collect(conn as any, Infinity);
+  const rows = nodes.map(toRow).sort((a, b) => a.position - b.position);
+  return setPaginationMetadata(
+    limit === Infinity ? rows : rows.slice(0, limit),
+    rows.length > limit,
+  );
+}
+
+export interface StateDetail {
+  id: string;
+  name: string;
+  type: string;
+  position: number;
+  color: string;
+  description: string | null;
+  team: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** The detail's shape; checked against `StateDetail`. */
+export const STATE_DETAIL_SHAPE = shape<StateDetail>({
+  id: "string",
+  name: "string",
+  type: "string",
+  position: "number",
+  color: "string",
+  description: "string|null",
+  team: "string|null",
+  createdAt: "string",
+  updatedAt: "string",
+});
+
+/**
+ * A single workflow state, by id or by name/type within a team.
+ *
+ * A name resolves through `resolveStateId` against `--team` or the configured
+ * default — the same lookup `issue create --state` uses — so `state view
+ * Backlog` works wherever `issue create --state Backlog` would. Without a team
+ * to scope the name, the error says what to pass; the API's own answer for a
+ * name was "Could not find referenced WorkflowState", which hid the fact that
+ * only ids were ever tried.
+ */
+export async function getStateDetail(
+  client: LinearClient,
+  input: string,
+  teamKey?: string,
+): Promise<StateDetail> {
+  let id = input;
+  if (!isUuid(input)) {
+    if (!teamKey) {
+      throw usageError(
+        `'${input}' is not a workflow state id; pass --team <KEY> (or set a default team) to look a state up by name.`,
+      );
+    }
+    const team = await resolveTeam(client, teamKey, undefined);
+    id = await resolveStateId(client, team.id, input);
+  }
+  const state = await withRetry(() => client.workflowState(id));
+  const team = await state.team;
+  return {
+    id: state.id,
+    name: state.name,
+    type: state.type,
+    position: state.position,
+    color: state.color,
+    description: state.description ?? null,
+    team: team?.key ?? null,
+    createdAt: state.createdAt.toISOString(),
+    updatedAt: state.updatedAt.toISOString(),
+  };
+}
+
+function toRow(s: any): StateRow {
+  return {
+    id: s.id,
+    name: s.name,
+    type: s.type,
+    position: s.position,
+    color: s.color,
+  };
+}

package/src/services/team.ts

@@ -0,0 +1,386 @@
+/**
+ * Team service: all SDK access for teams lives here so commands stay thin.
+ *
+ * Teams are resolved from a friendly key/name/id via `resolveTeam`; the single
+ * `view` and the sub-resource listings (members, states, labels, cycles) use the
+ * typed SDK connections, and mutations unwrap the `{ success, team }` payload.
+ */
+
+import type { LinearClient } from "@linear/sdk";
+import { withRetry } from "../client.js";
+import { shape } from "../lib/shape.js";
+import {
+  collect,
+  inheritPaginationMetadata,
+  pageSize,
+  setPaginationMetadata,
+} from "../lib/pagination.js";
+import { usageError } from "../lib/errors.js";
+import { assertMutation, unwrapMutation } from "../lib/mutation.js";
+import { resolveTeam, type ResolvedTeam } from "../lib/resolve.js";
+
+export interface TeamRow {
+  id: string;
+  key: string;
+  name: string;
+}
+
+/** The row's shape as `linear commands` advertises it (TES-610); checked against the interface. */
+export const TEAM_ROW_SHAPE = shape<TeamRow>({ id: "string", key: "string", name: "string" });
+
+/** Resolve the selected team to its canonical key, UUID, and name. */
+export async function getTeamIdentity(
+  client: LinearClient,
+  keyArg: string | undefined,
+  defaultTeamKey: string | undefined,
+): Promise<ResolvedTeam> {
+  return resolveTeam(client, keyArg, defaultTeamKey);
+}
+
+/** All teams (key, name, id). */
+export async function listTeams(client: LinearClient, limit: number): Promise<TeamRow[]> {
+  const conn = await withRetry(() => client.teams({ first: pageSize(limit) }));
+  const nodes = await collect(conn as any, limit);
+  return inheritPaginationMetadata(
+    nodes.map((t: any) => ({ id: t.id, key: t.key, name: t.name })),
+    nodes,
+  );
+}
+
+export interface TeamDetail {
+  id: string;
+  key: string;
+  name: string;
+  description: string | null;
+  private: boolean;
+  cyclesEnabled: boolean;
+  timezone: string | null;
+  color: string | null;
+  icon: string | null;
+  issueCount: number;
+  memberCount: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** The detail's shape; checked against `TeamDetail`. */
+export const TEAM_DETAIL_SHAPE = shape<TeamDetail>({
+  id: "string",
+  key: "string",
+  name: "string",
+  description: "string|null",
+  private: "boolean",
+  cyclesEnabled: "boolean",
+  timezone: "string|null",
+  color: "string|null",
+  icon: "string|null",
+  issueCount: "number",
+  memberCount: "number",
+  createdAt: "string",
+  updatedAt: "string",
+});
+
+export async function getTeamDetail(
+  client: LinearClient,
+  keyArg: string | undefined,
+  defaultTeamKey: string | undefined,
+): Promise<TeamDetail> {
+  const resolved = await resolveTeam(client, keyArg, defaultTeamKey);
+  const team = await withRetry(() => client.team(resolved.id));
+  // Count members via the connection (no direct count field on Team). Deactivated
+  // users are excluded — `includeDisabled` is passed explicitly rather than left
+  // to the server default so the intent is visible here.
+  const members = await collect(
+    (await withRetry(() => team.members({ first: 100, includeDisabled: false }))) as any,
+    Infinity,
+  );
+  return {
+    id: team.id,
+    key: team.key,
+    name: team.name,
+    description: team.description ?? null,
+    private: !!team.private,
+    cyclesEnabled: !!team.cyclesEnabled,
+    timezone: team.timezone ?? null,
+    color: team.color ?? null,
+    icon: team.icon ?? null,
+    issueCount: team.issueCount ?? 0,
+    memberCount: members.length,
+    createdAt: team.createdAt.toISOString(),
+    updatedAt: team.updatedAt.toISOString(),
+  };
+}
+
+export interface MemberRow {
+  id: string;
+  displayName: string;
+  name: string;
+  email: string;
+  active: boolean;
+}
+
+export const TEAM_MEMBER_ROW_SHAPE = shape<MemberRow>({
+  id: "string",
+  displayName: "string",
+  name: "string",
+  email: "string",
+  active: "boolean",
+});
+
+/**
+ * List a team's members. Linear defaults `includeDisabled` to false, so
+ * deactivated users are invisible (and the `active` column constantly true)
+ * unless the caller opts in.
+ */
+export async function listMembers(
+  client: LinearClient,
+  keyArg: string | undefined,
+  defaultTeamKey: string | undefined,
+  limit: number,
+  includeDisabled = false,
+): Promise<MemberRow[]> {
+  const resolved = await resolveTeam(client, keyArg, defaultTeamKey);
+  const team = await withRetry(() => client.team(resolved.id));
+  const nodes = await collect(
+    (await withRetry(() => team.members({ first: pageSize(limit), includeDisabled }))) as any,
+    limit,
+  );
+  return inheritPaginationMetadata(
+    nodes.map((u: any) => ({
+      id: u.id,
+      displayName: u.displayName,
+      name: u.name,
+      email: u.email,
+      active: !!u.active,
+    })),
+    nodes,
+  );
+}
+
+export interface StateRow {
+  id: string;
+  name: string;
+  type: string;
+  color: string;
+  position: number;
+}
+
+export const TEAM_STATE_ROW_SHAPE = shape<StateRow>({
+  id: "string",
+  name: "string",
+  type: "string",
+  color: "string",
+  position: "number",
+});
+
+export async function listStates(
+  client: LinearClient,
+  keyArg: string | undefined,
+  defaultTeamKey: string | undefined,
+  limit: number,
+): Promise<StateRow[]> {
+  const resolved = await resolveTeam(client, keyArg, defaultTeamKey);
+  const team = await withRetry(() => client.team(resolved.id));
+  const nodes = await collect((await withRetry(() => team.states())) as any, Infinity);
+  const rows = nodes
+    .map((s: any) => ({
+      id: s.id,
+      name: s.name,
+      type: s.type,
+      color: s.color,
+      position: s.position,
+    }))
+    .sort((a: StateRow, b: StateRow) => a.position - b.position);
+  return setPaginationMetadata(
+    limit === Infinity ? rows : rows.slice(0, limit),
+    rows.length > limit,
+  );
+}
+
+export interface LabelRow {
+  id: string;
+  name: string;
+  color: string;
+}
+
+export const TEAM_LABEL_ROW_SHAPE = shape<LabelRow>({
+  id: "string",
+  name: "string",
+  color: "string",
+});
+
+export async function listLabels(
+  client: LinearClient,
+  keyArg: string | undefined,
+  defaultTeamKey: string | undefined,
+  limit: number,
+): Promise<LabelRow[]> {
+  const resolved = await resolveTeam(client, keyArg, defaultTeamKey);
+  const team = await withRetry(() => client.team(resolved.id));
+  const nodes = await collect((await withRetry(() => team.labels())) as any, limit);
+  return inheritPaginationMetadata(
+    nodes.map((l: any) => ({ id: l.id, name: l.name, color: l.color })),
+    nodes,
+  );
+}
+
+export interface CycleRow {
+  id: string;
+  number: number;
+  name: string | null;
+  startsAt: string | null;
+  endsAt: string | null;
+}
+
+export const TEAM_CYCLE_ROW_SHAPE = shape<CycleRow>({
+  id: "string",
+  number: "number",
+  name: "string|null",
+  startsAt: "string|null",
+  endsAt: "string|null",
+});
+
+export async function listCycles(
+  client: LinearClient,
+  keyArg: string | undefined,
+  defaultTeamKey: string | undefined,
+  limit: number,
+): Promise<CycleRow[]> {
+  const resolved = await resolveTeam(client, keyArg, defaultTeamKey);
+  const team = await withRetry(() => client.team(resolved.id));
+  const nodes = await collect((await withRetry(() => team.cycles())) as any, Infinity);
+  const rows = nodes
+    .map((c: any) => ({
+      id: c.id,
+      number: c.number,
+      name: c.name ?? null,
+      startsAt: c.startsAt?.toISOString?.() ?? (c.startsAt ? String(c.startsAt) : null),
+      endsAt: c.endsAt?.toISOString?.() ?? (c.endsAt ? String(c.endsAt) : null),
+    }))
+    .sort((a, b) => b.number - a.number);
+  return setPaginationMetadata(
+    limit === Infinity ? rows : rows.slice(0, limit),
+    rows.length > limit,
+  );
+}
+
+export interface CreateTeamOptions {
+  name: string;
+  key?: string;
+  description?: string;
+  /** A private team is visible to its members only. Sent only when true (Linear's default is public). */
+  private?: boolean;
+}
+
+/** Create a team. `name` is required; `key` is generated by Linear when omitted. */
+export async function createTeam(client: LinearClient, opts: CreateTeamOptions) {
+  const input: Record<string, any> = { name: opts.name };
+  if (opts.key !== undefined) input.key = opts.key;
+  if (opts.description !== undefined) input.description = opts.description;
+  if (opts.private) input.private = true;
+  return unwrapMutation(
+    withRetry(() => client.createTeam(input as any)),
+    "team",
+    "Team creation",
+  );
+}
+
+export interface UpdateTeamOptions {
+  name?: string;
+  key?: string;
+  description?: string;
+}
+
+export async function updateTeam(
+  client: LinearClient,
+  keyArg: string | undefined,
+  defaultTeamKey: string | undefined,
+  opts: UpdateTeamOptions,
+) {
+  const resolved = await resolveTeam(client, keyArg, defaultTeamKey);
+  const input: Record<string, any> = {};
+  if (opts.name !== undefined) input.name = opts.name;
+  if (opts.key !== undefined) input.key = opts.key;
+  if (opts.description !== undefined) input.description = opts.description;
+  if (Object.keys(input).length === 0)
+    throw usageError("Nothing to update; pass at least one field (--name/--key/--description).");
+  return unwrapMutation(
+    withRetry(() => client.updateTeam(resolved.id, input as any)),
+    "team",
+    "Team update",
+  );
+}
+
+/** What `team delete` needs to know before it asks: the team, and how much goes with it. */
+export interface DeleteTeamPlan {
+  team: ResolvedTeam;
+  /** The team's live issues — the ones a delete takes with it, or `--move-issues` rescues. */
+  issueCount: number;
+  /** Set when `--move-issues` named a (different, existing) team. */
+  moveTo?: ResolvedTeam;
+}
+
+/**
+ * Resolve everything `team delete` will act on, so the confirmation can name
+ * the team, the issue count and the destination before anything is written.
+ * The key is required — a delete must never fall through to the configured
+ * default team the way `team view` does.
+ */
+export async function planDeleteTeam(
+  client: LinearClient,
+  keyArg: string,
+  moveIssuesTo: string | undefined,
+): Promise<DeleteTeamPlan> {
+  const team = await resolveTeam(client, keyArg, undefined);
+  const model = await withRetry(() => client.team(team.id));
+  const plan: DeleteTeamPlan = { team, issueCount: model.issueCount ?? 0 };
+  if (moveIssuesTo !== undefined) {
+    const moveTo = await resolveTeam(client, moveIssuesTo, undefined);
+    if (moveTo.id === team.id) {
+      throw usageError(`--move-issues names ${team.key} itself; pick a different team.`);
+    }
+    plan.moveTo = moveTo;
+  }
+  return plan;
+}
+
+/** Linear's cap on `issueBatchUpdate` ids per call. */
+const MOVE_BATCH = 50;
+
+/**
+ * Move every live issue on `from` to `to`, in batches. Returns how many moved.
+ * Archived and trashed issues stay where they are — the API's team listing
+ * excludes them and Linear takes them along with the team.
+ */
+export async function moveTeamIssues(
+  client: LinearClient,
+  from: ResolvedTeam,
+  to: ResolvedTeam,
+): Promise<number> {
+  const team = await withRetry(() => client.team(from.id));
+  const issues = await collect(
+    (await withRetry(() => team.issues({ first: 100 }))) as any,
+    Infinity,
+  );
+  const ids = issues.map((i: any) => i.id as string);
+  for (let i = 0; i < ids.length; i += MOVE_BATCH) {
+    const batch = ids.slice(i, i + MOVE_BATCH);
+    await assertMutation(
+      withRetry(() => client.updateIssueBatch(batch, { teamId: to.id })),
+      `Moving ${batch.length} issue(s) to ${to.key}`,
+    );
+  }
+  return ids.length;
+}
+
+/**
+ * Delete a team (`teamDelete`). Linear archives the team and everything on it;
+ * a plan that does not allow it answers with an API error, which reaches the
+ * user as `feature_not_accessible` like every other plan gate.
+ */
+export async function deleteTeam(client: LinearClient, team: ResolvedTeam): Promise<void> {
+  await assertMutation(
+    withRetry(() => client.deleteTeam(team.id)),
+    "Team deletion",
+  );
+}