linear-sdk-cli 0.1.0

package/src/services/comment.ts

@@ -0,0 +1,262 @@
+/**
+ * Comment service: all SDK access for comments lives here so commands stay thin.
+ *
+ * This is the ONE comment implementation: `comment add|list|update|delete|reply`,
+ * `issue comment`, `issue comments`, and `issue view --comments` all come here.
+ * There used to be a second copy in the issue service (typed SDK, one request
+ * per comment for the author, and a different JSON shape — `user` string vs
+ * `author` string, no `url`), which is exactly how the same data came out with
+ * two key sets depending on which command asked for it.
+ *
+ * Lists use a tailored GraphQL query so the author, thread parent and resolved
+ * state are fetched inline (one round-trip per page). The mutations use the
+ * typed SDK and unwrap the `{ success, comment }` payloads.
+ *
+ * NOTE: the typed `client.comment(id)` getter is broken in @linear/sdk v87 (it
+ * mis-serializes the id as the GraphQL `variables` body), so looking a comment
+ * up by id — to learn a reply's parent issue, or the current body before an
+ * edit — uses a tailored rawRequest instead.
+ */
+
+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 } from "../lib/errors.js";
+import { assertMutation, unwrapMutation } from "../lib/mutation.js";
+import { resolveIssue } from "../lib/resolve.js";
+import { appendEmbeds, uploadFile, validateUploads, type UploadResult } from "../lib/upload.js";
+
+export interface CommentRow {
+  id: string;
+  body: string;
+  /** The author — an object like every other list row's relations; null for a deleted account. */
+  user: { id: string; displayName: string } | null;
+  createdAt: string;
+  /** Set once the body has been edited; null for a comment as first written. */
+  editedAt: string | null;
+  /** Set when the thread has been resolved (`comment resolve`); null while open. */
+  resolvedAt: string | null;
+  /** The comment this one replies to (`comment reply`); null for a top-level comment. */
+  parent: { id: string } | null;
+  url: string;
+}
+
+/** The row's shape as `linear commands` advertises it (TES-610); checked against the interface. */
+export const COMMENT_ROW_SHAPE = shape<CommentRow>({
+  id: "string",
+  body: "string",
+  user: { nullable: { id: "string", displayName: "string" } },
+  createdAt: "string",
+  editedAt: "string|null",
+  resolvedAt: "string|null",
+  parent: { nullable: { id: "string" } },
+  url: "string",
+});
+
+const LIST_QUERY = `
+query CliComments($id: String!, $first: Int!, $after: String) {
+  issue(id: $id) {
+    comments(first: $first, after: $after) {
+      nodes {
+        id body createdAt editedAt resolvedAt url
+        user { id displayName }
+        parent { id }
+      }
+      pageInfo { hasNextPage endCursor }
+    }
+  }
+}`;
+
+/**
+ * List the comments on an issue (resolved by identifier/UUID), in thread order:
+ * top-level comments as the API returns them (newest first), each followed by
+ * its replies oldest-first, so a thread reads top to bottom.
+ */
+export async function listComments(
+  client: LinearClient,
+  issueArg: string,
+  limit: number,
+): Promise<CommentRow[]> {
+  const issue = await resolveIssue(client, issueArg);
+  const rows = await collectRawQuery<CommentRow>(
+    client as any,
+    LIST_QUERY,
+    { id: issue.id },
+    "issue.comments",
+    limit,
+    toCommentRow,
+  );
+  return threadOrder(rows);
+}
+
+/** Map a tailored-query comment node to a row. Exported for tests. */
+export function toCommentRow(c: any): CommentRow {
+  return {
+    id: c.id,
+    body: c.body,
+    user: c.user ? { id: c.user.id, displayName: c.user.displayName } : null,
+    createdAt: c.createdAt,
+    editedAt: c.editedAt ?? null,
+    resolvedAt: c.resolvedAt ?? null,
+    parent: c.parent ? { id: c.parent.id } : null,
+    url: c.url,
+  };
+}
+
+/**
+ * Group replies under their parent. Top-level rows keep their incoming order;
+ * replies follow their parent oldest-first. A reply whose parent is not in the
+ * page (it fell outside `--limit`) stays where it was, still marked by
+ * `parent`, rather than being dropped. Exported for tests.
+ */
+export function threadOrder(rows: CommentRow[]): CommentRow[] {
+  const ids = new Set(rows.map((r) => r.id));
+  const replies = new Map<string, CommentRow[]>();
+  for (const r of rows) {
+    if (r.parent && ids.has(r.parent.id)) {
+      const list = replies.get(r.parent.id) ?? [];
+      list.push(r);
+      replies.set(r.parent.id, list);
+    }
+  }
+  const out: CommentRow[] = [];
+  for (const r of rows) {
+    if (r.parent && ids.has(r.parent.id)) continue; // emitted under its parent
+    out.push(r);
+    const kids = replies.get(r.id);
+    if (kids) out.push(...kids.sort((a, b) => a.createdAt.localeCompare(b.createdAt)));
+  }
+  return out;
+}
+
+export interface AddCommentOptions {
+  /**
+   * `--attach <file>` (repeatable): files to upload and embed in the body — a
+   * blank line after it, then one markdown embed per line (images inline,
+   * anything else as a link). Validated as a batch before any is uploaded.
+   */
+  attachments?: string[];
+  /** Upload the attachments to public, world-readable URLs (raster images only). */
+  public?: boolean;
+}
+
+/** Add a comment to an issue, optionally with uploaded files embedded in it. */
+export async function addComment(
+  client: LinearClient,
+  issueArg: string,
+  body: string,
+  opts: AddCommentOptions = {},
+) {
+  const paths = opts.attachments ?? [];
+  // Every file first — a missing one fails before anything is uploaded or resolved.
+  validateUploads(paths, { public: opts.public });
+  const issue = await resolveIssue(client, issueArg);
+  const uploads: UploadResult[] = [];
+  for (const path of paths) uploads.push(await uploadFile(client, path, { public: opts.public }));
+  const comment = await unwrapMutation(
+    withRetry(() => client.createComment({ issueId: issue.id, body: appendEmbeds(body, uploads) })),
+    "comment",
+    "Comment creation",
+  );
+  return { issue, comment, uploads };
+}
+
+const LOOKUP_QUERY = `
+query CliCommentLookup($id: String!) {
+  comment(id: $id) {
+    id
+    body
+    issueId
+    issue { id identifier }
+  }
+}`;
+
+export interface CommentLookup {
+  id: string;
+  body: string;
+  issueId: string | null;
+  issue: { id: string; identifier: string } | null;
+}
+
+/**
+ * Reply to an existing comment. Linear nests replies via `parentId`, but the API
+ * still requires the owning entity, so we look the parent up (for its issueId)
+ * and pass both. Returns the new comment plus the parent's issue for output.
+ */
+export async function replyToComment(client: LinearClient, commentId: string, body: string) {
+  const parent = await getComment(client, commentId);
+  if (!parent.issueId) throw usageError("Can only reply to comments that belong to an issue.");
+  const comment = await unwrapMutation(
+    withRetry(() => client.createComment({ parentId: parent.id, issueId: parent.issueId!, body })),
+    "comment",
+    "Reply creation",
+  );
+  return { parent, comment, issue: parent.issue };
+}
+
+/**
+ * Replace a comment's body. An empty or whitespace-only body is refused: the
+ * only way to produce one from the CLI is quitting a blank editor or passing
+ * `""`, and neither is a request to blank a comment (there is `comment delete`
+ * for getting rid of one). An unchanged body is refused too, so an editor
+ * session closed without edits does not write a no-op — and does not stamp
+ * `editedAt` on a comment nobody edited.
+ */
+export async function updateComment(
+  client: LinearClient,
+  commentId: string,
+  body: string,
+  current?: string,
+) {
+  if (body.trim() === "") {
+    throw usageError(
+      "Refusing to blank the comment body. To remove a comment, use 'comment delete'.",
+    );
+  }
+  if (current !== undefined && body === current)
+    throw usageError("Comment body unchanged; nothing to update.");
+  return unwrapMutation(
+    withRetry(() => client.updateComment(commentId, { body })),
+    "comment",
+    "Comment update",
+  );
+}
+
+export async function deleteComment(client: LinearClient, commentId: string) {
+  await assertMutation(
+    withRetry(() => client.deleteComment(commentId)),
+    "Comment deletion",
+  );
+  return { id: commentId };
+}
+
+/** Resolve (or unresolve) a comment thread. */
+export async function setResolved(client: LinearClient, commentId: string, resolved: boolean) {
+  return unwrapMutation(
+    withRetry(() =>
+      resolved ? client.commentResolve(commentId) : client.commentUnresolve(commentId),
+    ),
+    "comment",
+    `Comment ${resolved ? "resolve" : "unresolve"}`,
+  );
+}
+
+/**
+ * Look a comment up by id via rawRequest (the typed getter is broken in v87):
+ * its current body, and the issue it belongs to. Used to seed the editor for
+ * `comment update` and to find a reply's owning issue.
+ */
+export async function getComment(client: LinearClient, commentId: string): Promise<CommentLookup> {
+  const data: any = await withRetry(() =>
+    (client.client as any).rawRequest(LOOKUP_QUERY, { id: commentId }),
+  );
+  const node = data?.data?.comment;
+  if (!node) throw notFound(`No comment with id '${commentId}'.`);
+  return {
+    id: node.id,
+    body: node.body ?? "",
+    issueId: node.issueId ?? null,
+    issue: node.issue ?? null,
+  };
+}

package/src/services/cycle.ts

@@ -0,0 +1,224 @@
+/**
+ * Cycle service: all SDK access for cycles lives here so commands stay thin.
+ *
+ * Lists go through the typed `team.cycles()` connection (server-side sorted by
+ * number); single `view`/`current` and the mutations use the typed SDK models.
+ */
+
+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, notFound } from "../lib/errors.js";
+import { unwrapMutation } from "../lib/mutation.js";
+import { resolveTeam, resolveCycleId, isUuid } from "../lib/resolve.js";
+
+export interface CycleRow {
+  id: string;
+  number: number;
+  name: string | null;
+  startsAt: string;
+  endsAt: string;
+  progress: number;
+  completedAt: string | null;
+}
+
+/** The row's shape as `linear commands` advertises it (TES-610); checked against the interface. */
+export const CYCLE_ROW_SHAPE = shape<CycleRow>({
+  id: "string",
+  number: "number",
+  name: "string|null",
+  startsAt: "string",
+  endsAt: "string",
+  progress: "number",
+  completedAt: "string|null",
+});
+
+/** List a team's cycles, newest (highest number) first. */
+export async function listCycles(
+  client: LinearClient,
+  teamInput: string | undefined,
+  limit: number,
+  defaultTeamKey: string | undefined,
+): Promise<CycleRow[]> {
+  const team = await resolveTeam(client, teamInput, defaultTeamKey);
+  const teamModel = await withRetry(() => client.team(team.id));
+  const conn = await withRetry(() => teamModel.cycles({ first: pageSize(limit) }));
+  // Cycle connection order is not its user-facing number order. Sort first so
+  // `--limit` means the newest cycles, not an arbitrary API prefix.
+  const nodes = await collect(conn as any, Infinity);
+  const rows = nodes.map(toRow);
+  // Surface most-recent (highest number) cycle first.
+  rows.sort((a, b) => b.number - a.number);
+  return setPaginationMetadata(
+    limit === Infinity ? rows : rows.slice(0, limit),
+    rows.length > limit,
+  );
+}
+
+/** The team's currently active cycle, if any. */
+export async function getCurrentCycle(
+  client: LinearClient,
+  teamInput: string | undefined,
+  defaultTeamKey: string | undefined,
+): Promise<CycleDetail> {
+  const team = await resolveTeam(client, teamInput, defaultTeamKey);
+  const teamModel = await withRetry(() => client.team(team.id));
+  const cycle = await teamModel.activeCycle;
+  if (!cycle) throw notFound(`No active cycle for team ${team.key}.`);
+  return toDetail(cycle, team.key);
+}
+
+export interface CycleDetail {
+  id: string;
+  number: number;
+  name: string | null;
+  description: string | null;
+  startsAt: string;
+  endsAt: string;
+  completedAt: string | null;
+  progress: number;
+  team: string | null;
+}
+
+/** The detail's shape; checked against `CycleDetail`. */
+export const CYCLE_DETAIL_SHAPE = shape<CycleDetail>({
+  id: "string",
+  number: "number",
+  name: "string|null",
+  description: "string|null",
+  startsAt: "string",
+  endsAt: "string",
+  completedAt: "string|null",
+  progress: "number",
+  team: "string|null",
+});
+
+/**
+ * Resolve a cycle id from `idArg`. A UUID is taken directly; a number or
+ * `current` needs a team (from --team / default) to resolve against.
+ */
+export async function getCycleDetail(
+  client: LinearClient,
+  idArg: string,
+  teamInput: string | undefined,
+  defaultTeamKey: string | undefined,
+): Promise<CycleDetail> {
+  const cycleId = await resolveCycleArg(client, idArg, teamInput, defaultTeamKey);
+  const cycle = await withRetry(() => client.cycle(cycleId));
+  const team = await cycle.team;
+  return toDetail(cycle, team?.key ?? null);
+}
+
+export interface CreateOptions {
+  team?: string;
+  name?: string;
+  startsAt: string;
+  endsAt: string;
+}
+
+export async function createCycle(
+  client: LinearClient,
+  opts: CreateOptions,
+  defaultTeamKey: string | undefined,
+) {
+  const team = await resolveTeam(client, opts.team, defaultTeamKey);
+  const input: Record<string, any> = {
+    teamId: team.id,
+    startsAt: opts.startsAt,
+    endsAt: opts.endsAt,
+  };
+  if (opts.name !== undefined) input.name = opts.name;
+
+  return unwrapMutation(
+    withRetry(() => client.createCycle(input as any)),
+    "cycle",
+    "Cycle creation",
+  );
+}
+
+export interface UpdateOptions {
+  name?: string;
+  startsAt?: string;
+  endsAt?: string;
+}
+
+export async function updateCycle(
+  client: LinearClient,
+  idArg: string,
+  opts: UpdateOptions,
+  teamInput: string | undefined,
+  defaultTeamKey: string | undefined,
+) {
+  const cycleId = await resolveCycleArg(client, idArg, teamInput, defaultTeamKey);
+  const input: Record<string, any> = {};
+  if (opts.name !== undefined) input.name = opts.name;
+  if (opts.startsAt !== undefined) input.startsAt = opts.startsAt;
+  if (opts.endsAt !== undefined) input.endsAt = opts.endsAt;
+
+  if (Object.keys(input).length === 0)
+    throw usageError("Nothing to update; pass at least one of --name, --start, --end.");
+
+  return unwrapMutation(
+    withRetry(() => client.updateCycle(cycleId, input as any)),
+    "cycle",
+    "Cycle update",
+  );
+}
+
+/**
+ * Resolve a cycle reference (UUID, number, or `current`) to a cycle id. A UUID
+ * is unambiguous; a number/`current` needs a team to scope against.
+ */
+async function resolveCycleArg(
+  client: LinearClient,
+  idArg: string,
+  teamInput: string | undefined,
+  defaultTeamKey: string | undefined,
+): Promise<string> {
+  if (isUuid(idArg)) return idArg;
+  const teamKey = teamInput ?? defaultTeamKey;
+  if (!teamKey)
+    throw usageError(
+      "Resolving a cycle by number or 'current' requires --team (or pass a cycle id).",
+    );
+  const team = await resolveTeam(client, teamKey, undefined);
+  return resolveCycleId(client, team.id, idArg);
+}
+
+function toRow(c: any): CycleRow {
+  return {
+    id: c.id,
+    number: c.number,
+    name: c.name ?? null,
+    startsAt: dateStr(c.startsAt),
+    endsAt: dateStr(c.endsAt),
+    progress: c.progress,
+    completedAt: c.completedAt ? dateStr(c.completedAt) : null,
+  };
+}
+
+function toDetail(c: any, teamKey: string | null): CycleDetail {
+  return {
+    id: c.id,
+    number: c.number,
+    name: c.name ?? null,
+    description: c.description ?? null,
+    startsAt: dateStr(c.startsAt),
+    endsAt: dateStr(c.endsAt),
+    completedAt: c.completedAt ? dateStr(c.completedAt) : null,
+    progress: c.progress,
+    team: teamKey,
+  };
+}
+
+/** Normalize a Date (SDK model) or string into an ISO string. */
+export function dateStr(v: unknown): string {
+  if (v instanceof Date) return v.toISOString();
+  return String(v);
+}
+
+/** Human-friendly progress percentage (0..1 → "42%"). Exported for tests. */
+export function formatProgress(progress: number): string {
+  return `${Math.round((progress ?? 0) * 100)}%`;
+}