linear-sdk-cli 0.1.3 → 0.2.1

package/src/services/comment.ts

@@ -26,6 +26,7 @@ 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";
+import { prependMentions } from "../lib/mentions.js";
 
 export interface CommentRow {
   id: string;
@@ -139,6 +140,8 @@ export interface AddCommentOptions {
   attachments?: string[];
   /** Upload the attachments to public, world-readable URLs (raster images only). */
   public?: boolean;
+  /** Explicit user references to emit as real Linear mentions before the body. */
+  mentions?: string[];
 }
 
 /** Add a comment to an issue, optionally with uploaded files embedded in it. */
@@ -152,10 +155,13 @@ export async function addComment(
   // 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 mentionedBody = await prependMentions(client, body, opts.mentions);
   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) })),
+    withRetry(() =>
+      client.createComment({ issueId: issue.id, body: appendEmbeds(mentionedBody, uploads) }),
+    ),
     "comment",
     "Comment creation",
   );
@@ -184,11 +190,23 @@ export interface CommentLookup {
  * 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) {
+export async function replyToComment(
+  client: LinearClient,
+  commentId: string,
+  body: string,
+  mentions: string[] = [],
+) {
   const parent = await getComment(client, commentId);
   if (!parent.issueId) throw usageError("Can only reply to comments that belong to an issue.");
+  const mentionedBody = await prependMentions(client, body, mentions);
   const comment = await unwrapMutation(
-    withRetry(() => client.createComment({ parentId: parent.id, issueId: parent.issueId!, body })),
+    withRetry(() =>
+      client.createComment({
+        parentId: parent.id,
+        issueId: parent.issueId!,
+        body: mentionedBody,
+      }),
+    ),
     "comment",
     "Reply creation",
   );
@@ -208,27 +226,37 @@ export async function updateComment(
   commentId: string,
   body: string,
   current?: string,
+  mentions: string[] = [],
 ) {
-  if (body.trim() === "") {
-    throw usageError("Refusing to blank the comment body. To remove a comment, use 'comment delete'.");
+  const mentionedBody = await prependMentions(client, body, mentions);
+  if (mentionedBody.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.");
+  if (current !== undefined && mentionedBody === current)
+    throw usageError("Comment body unchanged; nothing to update.");
   return unwrapMutation(
-    withRetry(() => client.updateComment(commentId, { body })),
+    withRetry(() => client.updateComment(commentId, { body: mentionedBody })),
     "comment",
     "Comment update",
   );
 }
 
 export async function deleteComment(client: LinearClient, commentId: string) {
-  await assertMutation(withRetry(() => client.deleteComment(commentId)), "Comment deletion");
+  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))),
+    withRetry(() =>
+      resolved ? client.commentResolve(commentId) : client.commentUnresolve(commentId),
+    ),
     "comment",
     `Comment ${resolved ? "resolve" : "unresolve"}`,
   );

package/src/services/cycle.ts

@@ -8,7 +8,7 @@
 import type { LinearClient } from "@linear/sdk";
 import { withRetry } from "../client.js";
 import { shape } from "../lib/shape.js";
-import { collect, pageSize } from "../lib/pagination.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";
@@ -44,11 +44,16 @@ export async function listCycles(
   const team = await resolveTeam(client, teamInput, defaultTeamKey);
   const teamModel = await withRetry(() => client.team(team.id));
   const conn = await withRetry(() => teamModel.cycles({ first: pageSize(limit) }));
-  const nodes = await collect(conn as any, 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 rows;
+  return setPaginationMetadata(
+    limit === Infinity ? rows : rows.slice(0, limit),
+    rows.length > limit,
+  );
 }
 
 /** The team's currently active cycle, if any. */
@@ -174,7 +179,9 @@ async function resolveCycleArg(
   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).");
+    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);
 }

package/src/services/document.ts

@@ -19,7 +19,7 @@
 import type { LinearClient } from "@linear/sdk";
 import { withRetry } from "../client.js";
 import { collectRawQuery } from "../lib/pagination.js";
-import { usageError, notFound } from "../lib/errors.js";
+import { usageError, notFound, normalizeError } from "../lib/errors.js";
 import { assertMutation, unwrapMutation } from "../lib/mutation.js";
 import {
   resolveProjectId,
@@ -100,7 +100,9 @@ export async function resolveTarget(
     case "cycle": {
       const teamKey = sel.team ?? defaultTeamKey;
       if (!teamKey)
-        throw usageError("--cycle needs a team to look the cycle up in: pass --team <KEY> or set a default team.");
+        throw usageError(
+          "--cycle needs a team to look the cycle up in: pass --team <KEY> or set a default team.",
+        );
       const team = await resolveTeam(client, teamKey, undefined);
       return { kind: "cycle", id: await resolveCycleId(client, team.id, sel.value) };
     }
@@ -169,7 +171,9 @@ function targets(n: any): DocumentTargets {
     initiative: n.initiative ?? null,
     team: n.team ?? null,
     cycle: n.cycle ? { id: n.cycle.id, number: n.cycle.number, name: n.cycle.name ?? null } : null,
-    release: n.release ? { id: n.release.id, name: n.release.name, version: n.release.version ?? null } : null,
+    release: n.release
+      ? { id: n.release.id, name: n.release.name, version: n.release.version ?? null }
+      : null,
   };
 }
 
@@ -184,7 +188,8 @@ export function describeTarget(t: DocumentTargets): string | null {
   if (t.initiative) return `Initiative: ${t.initiative.name}`;
   if (t.team) return `Team: ${t.team.key} ${t.team.name}`;
   if (t.cycle) return `Cycle: #${t.cycle.number}${t.cycle.name ? ` ${t.cycle.name}` : ""}`;
-  if (t.release) return `Release: ${t.release.name}${t.release.version ? ` (${t.release.version})` : ""}`;
+  if (t.release)
+    return `Release: ${t.release.name}${t.release.version ? ` (${t.release.version})` : ""}`;
   return null;
 }
 
@@ -233,10 +238,15 @@ query CliDocumentDetail($id: String!) {
   }
 }`;
 
-export async function getDocumentDetail(client: LinearClient, idArg: string): Promise<DocumentDetail> {
+export async function getDocumentDetail(
+  client: LinearClient,
+  idArg: string,
+): Promise<DocumentDetail> {
   // An unknown id is an API error ("Could not find referenced Document"), which
   // the error boundary already reads as not-found (exit 3); a null is guarded too.
-  const data: any = await withRetry(() => (client as any).client.rawRequest(DETAIL_QUERY, { id: idArg }));
+  const data: any = await withRetry(() =>
+    (client as any).client.rawRequest(DETAIL_QUERY, { id: idArg }),
+  );
   const n = data?.data?.document;
   if (!n) throw notFound(`No document matching '${idArg}'.`);
   return {
@@ -267,7 +277,11 @@ export interface CreateOptions extends DocumentTargetOptions {
  * NOT a fallback here: the command decides that, so the service never turns
  * "no target" into "the team from config" behind the caller's back.
  */
-export async function createDocument(client: LinearClient, opts: CreateOptions, defaultTeamKey?: string) {
+export async function createDocument(
+  client: LinearClient,
+  opts: CreateOptions,
+  defaultTeamKey?: string,
+) {
   const sel = selectTarget(opts);
   if (!sel) throw usageError(`A document needs a target: pass one of ${TARGET_FLAGS}.`);
   const input: Record<string, any> = { title: opts.title };
@@ -318,7 +332,10 @@ export async function updateDocument(
 
 export async function deleteDocument(client: LinearClient, idArg: string) {
   const document = await resolveDocument(client, idArg);
-  await assertMutation(withRetry(() => client.deleteDocument(document.id)), "Document deletion");
+  await assertMutation(
+    withRetry(() => client.deleteDocument(document.id)),
+    "Document deletion",
+  );
   return document;
 }
 
@@ -332,7 +349,9 @@ async function resolveDocument(client: LinearClient, idArg: string) {
   // The SDK's document() also resolves a slugId; fall back to it directly.
   try {
     return await withRetry(() => client.document(idArg));
-  } catch {
-    throw notFound(`No document matching '${idArg}'.`);
+  } catch (err) {
+    const normalized = normalizeError(err);
+    if (normalized.code === "not_found") throw notFound(`No document matching '${idArg}'.`);
+    throw normalized;
   }
 }

package/src/services/favorite.ts

@@ -13,7 +13,7 @@
 import type { LinearClient } from "@linear/sdk";
 import { withRetry } from "../client.js";
 import { shape } from "../lib/shape.js";
-import { collect, pageSize } from "../lib/pagination.js";
+import { collect, inheritPaginationMetadata, pageSize } from "../lib/pagination.js";
 import { usageError } from "../lib/errors.js";
 import { assertMutation, unwrapMutation } from "../lib/mutation.js";
 import { resolveIssue, resolveProjectId, isUuid } from "../lib/resolve.js";
@@ -69,13 +69,16 @@ export function entityLabel(entity: any): string {
 export async function listFavorites(client: LinearClient, limit: number): Promise<FavoriteRow[]> {
   const conn = await withRetry(() => client.favorites({ first: pageSize(limit) }));
   const nodes = await collect(conn as any, limit);
-  return Promise.all(
-    nodes.map(async (f: any) => ({
-      id: f.id,
-      type: f.type,
-      name: await favoriteName(f),
-      url: f.url ?? null,
-    })),
+  return inheritPaginationMetadata(
+    await Promise.all(
+      nodes.map(async (f: any) => ({
+        id: f.id,
+        type: f.type,
+        name: await favoriteName(f),
+        url: f.url ?? null,
+      })),
+    ),
+    nodes,
   );
 }
 
@@ -136,6 +139,9 @@ export async function addFavorite(client: LinearClient, opts: AddOptions) {
 
 /** Delete a favorite by id. */
 export async function removeFavorite(client: LinearClient, id: string) {
-  await assertMutation(withRetry(() => client.deleteFavorite(id)), "Favorite removal");
+  await assertMutation(
+    withRetry(() => client.deleteFavorite(id)),
+    "Favorite removal",
+  );
   return { id };
 }

package/src/services/initiative-update.ts

@@ -7,7 +7,7 @@
 
 import type { LinearClient } from "@linear/sdk";
 import { withRetry } from "../client.js";
-import { collect } from "../lib/pagination.js";
+import { collect, inheritPaginationMetadata, pageSize } from "../lib/pagination.js";
 import { normalizeUpdatePayload, type Health, type UpdateRow } from "../lib/status-update.js";
 import { resolveInitiative } from "./initiative.js";
 
@@ -20,21 +20,22 @@ export async function listInitiativeUpdates(
   limit: number,
 ): Promise<UpdateRow[]> {
   const initiative = await resolveInitiative(client, idArg);
-  const conn = await withRetry(() =>
-    initiative.initiativeUpdates({ first: Math.min(limit === Infinity ? 100 : limit, 100) }),
-  );
+  const conn = await withRetry(() => initiative.initiativeUpdates({ first: pageSize(limit) }));
   const nodes = await collect(conn as any, limit);
-  return Promise.all(
-    nodes.map(async (u: any) => {
-      const user = await u.user;
-      return {
-        id: u.id,
-        createdAt: u.createdAt?.toISOString?.() ?? String(u.createdAt),
-        user: user?.displayName ?? "unknown",
-        body: u.body ?? "",
-        health: u.health ?? null,
-      };
-    }),
+  return inheritPaginationMetadata(
+    await Promise.all(
+      nodes.map(async (u: any) => {
+        const user = await u.user;
+        return {
+          id: u.id,
+          createdAt: u.createdAt?.toISOString?.() ?? String(u.createdAt),
+          user: user?.displayName ?? "unknown",
+          body: u.body ?? "",
+          health: u.health ?? null,
+        };
+      }),
+    ),
+    nodes,
   );
 }
 

package/src/services/initiative.ts

@@ -164,7 +164,9 @@ export const INITIATIVE_DETAIL_SHAPE = shape<InitiativeDetail>({
   archivedAt: "string|null",
   owner: "string|null",
   creator: "string|null",
-  projects: [{ id: "string", name: "string", status: { nullable: { name: "string", type: "string" } } }],
+  projects: [
+    { id: "string", name: "string", status: { nullable: { name: "string", type: "string" } } },
+  ],
 });
 
 /** How many linked projects `view` reads; more than this is unusual and shows a truncation note. */
@@ -187,7 +189,11 @@ export async function getInitiativeDetail(
   const projectRows = await Promise.all(
     (projects?.nodes ?? []).map(async (p: any) => {
       const status = await p.status;
-      return { id: p.id, name: p.name, status: status ? { name: status.name, type: status.type } : null };
+      return {
+        id: p.id,
+        name: p.name,
+        status: status ? { name: status.name, type: status.type } : null,
+      };
     }),
   );
   return {
@@ -257,11 +263,7 @@ export interface UpdateOptions {
   color?: string;
 }
 
-export async function updateInitiative(
-  client: LinearClient,
-  idArg: string,
-  opts: UpdateOptions,
-) {
+export async function updateInitiative(client: LinearClient, idArg: string, opts: UpdateOptions) {
   const initiative = await resolveInitiative(client, idArg);
   const input: Record<string, any> = {};
   if (opts.name !== undefined) input.name = opts.name;
@@ -420,7 +422,11 @@ export async function resolveInitiative(
   const matches: any[] = [];
   for (;;) {
     const conn = await withRetry(() =>
-      client.initiatives({ first: 100, after, includeArchived: opts.includeArchived === true } as any),
+      client.initiatives({
+        first: 100,
+        after,
+        includeArchived: opts.includeArchived === true,
+      } as any),
     );
     for (const n of conn.nodes) {
       if (n.name.toLowerCase() === lower) matches.push(n);
@@ -438,7 +444,6 @@ export async function resolveInitiative(
 export function resolveStatus(input: string): string {
   const lower = input.toLowerCase();
   const match = STATUSES.find((s) => s.toLowerCase() === lower);
-  if (!match)
-    throw usageError(`Invalid status '${input}'. Valid: ${STATUSES.join(", ")}.`);
+  if (!match) throw usageError(`Invalid status '${input}'. Valid: ${STATUSES.join(", ")}.`);
   return match;
 }