Merge pull request #53 from czottmann/feat/cursor-pagination

feat(pagination): add cursor-based pagination to all list commands

Author: iamfj

USAGE.md

@@ -58,8 +58,9 @@ arguments:
   <title>  string
 
 list options:
-  --query <text>  filter by text search
-  --limit <n>     max results (default: 50)
+  --query <text>    filter by text search
+  --limit <n>       max results (default: 50)
+  --after <cursor>  cursor for next page
 
 create options:
   --description <text>      issue body
@@ -129,7 +130,9 @@ commands:
   list [options]  list available labels
 
 list options:
-  --team <team>  filter by team (key, name, or UUID)
+  --team <team>     filter by team (key, name, or UUID)
+  --limit <n>       max results (default: 50)
+  --after <cursor>  cursor for next page
 
 see also: issues create --labels, issues update --labels
 
@@ -144,7 +147,8 @@ commands:
   list [options]  list projects
 
 list options:
-  --limit <n>  max results (default: 100)
+  --limit <n>       max results (default: 100)
+  --after <cursor>  cursor for next page
 
 see also: milestones list --project, documents list --project
 
@@ -163,9 +167,11 @@ arguments:
   <cycle>  cycle identifier (UUID or name)
 
 list options:
-  --team <team>  filter by team (key, name, or UUID)
-  --active       only show active cycles
-  --window <n>   active cycle +/- n neighbors (requires --team)
+  --team <team>     filter by team (key, name, or UUID)
+  --active          only show active cycles
+  --window <n>      active cycle +/- n neighbors (requires --team)
+  --limit <n>       max results (default: 50)
+  --after <cursor>  cursor for next page
 
 read options:
   --team <team>  scope name lookup to team
@@ -193,6 +199,7 @@ arguments:
 list options:
   --project <project>  target project (required)
   --limit <n>          max results (default: 50)
+  --after <cursor>     cursor for next page
 
 read options:
   --project <project>  scope name lookup to project
@@ -233,6 +240,7 @@ list options:
   --project <project>  filter by project name or ID
   --issue <issue>      filter by issue (shows documents attached to the issue)
   --limit <n>          max results (default: 50)
+  --after <cursor>     cursor for next page
 
 create options:
   --title <title>      document title (required)
@@ -279,7 +287,11 @@ a team is a group of users that owns issues, cycles, statuses, and
 labels. teams are identified by a short key (e.g. ENG), name, or UUID.
 
 commands:
-  list  list all teams
+  list [options]  list all teams
+
+list options:
+  --limit <n>       max results (default: 50)
+  --after <cursor>  cursor for next page
 
 ---
 
@@ -292,4 +304,6 @@ commands:
   list [options]  list workspace members
 
 list options:
-  --active  only show active users
+  --active          only show active users
+  --limit <n>       max results (default: 50)
+  --after <cursor>  cursor for next page

graphql/queries/cycles.graphql

@@ -58,11 +58,15 @@ fragment CycleWithIssuesFields on Cycle {
 # Variables:
 #   $first: Maximum number of cycles to return (default: 50)
 #   $filter: Optional CycleFilter for team/status filtering
-query GetCycles($first: Int = 50, $filter: CycleFilter) {
-  cycles(first: $first, filter: $filter) {
+query GetCycles($first: Int = 50, $after: String, $filter: CycleFilter) {
+  cycles(first: $first, after: $after, filter: $filter) {
     nodes {
       ...CycleFields
     }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
   }
 }
 

graphql/queries/documents.graphql

@@ -35,10 +35,14 @@ query GetDocument($id: String!) {
 # List documents with optional filtering
 #
 # Fetches a list of documents with optional filtering criteria.
-query ListDocuments($first: Int!, $filter: DocumentFilter) {
-  documents(first: $first, filter: $filter) {
+query ListDocuments($first: Int!, $after: String, $filter: DocumentFilter) {
+  documents(first: $first, after: $after, filter: $filter) {
     nodes {
       ...DocumentFields
     }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
   }
 }

graphql/queries/issues.graphql

@@ -191,15 +191,20 @@ fragment CompleteIssueSearchFields on IssueSearchResult {
 # Fetches paginated issues excluding completed ones,
 # ordered by most recently updated. Includes all relationships
 # for comprehensive issue data.
-query GetIssues($first: Int!, $orderBy: PaginationOrderBy) {
+query GetIssues($first: Int!, $after: String, $orderBy: PaginationOrderBy) {
   issues(
     first: $first
+    after: $after
     orderBy: $orderBy
     filter: { state: { type: { neq: "completed" } } }
   ) {
     nodes {
       ...CompleteIssueFields
     }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
   }
 }
 
@@ -243,11 +248,20 @@ query GetIssueTeam($issueId: String!) {
 #
 # Provides full-text search across Linear issues with complete
 # relationship data for each match.
-query SearchIssues($term: String!, $first: Int!) {
-  searchIssues(term: $term, first: $first, includeArchived: false) {
+query SearchIssues($term: String!, $first: Int!, $after: String) {
+  searchIssues(
+    term: $term
+    first: $first
+    after: $after
+    includeArchived: false
+  ) {
     nodes {
       ...CompleteIssueSearchFields
     }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
   }
 }
 
@@ -257,18 +271,24 @@ query SearchIssues($term: String!, $first: Int!) {
 # Used by the advanced search functionality with multiple criteria.
 query FilteredSearchIssues(
   $first: Int!
+  $after: String
   $filter: IssueFilter
   $orderBy: PaginationOrderBy
 ) {
   issues(
     first: $first
+    after: $after
     filter: $filter
     orderBy: $orderBy
     includeArchived: false
   ) {
     nodes {
       ...CompleteIssueFields
     }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
   }
 }
 

graphql/queries/labels.graphql

@@ -31,10 +31,14 @@ fragment LabelFields on IssueLabel {
 # Variables:
 #   $first: Maximum number of labels to return (default: 50)
 #   $filter: Optional filter (e.g., { team: { id: { eq: "team-uuid" } } })
-query GetLabels($first: Int = 50, $filter: IssueLabelFilter) {
-  issueLabels(first: $first, filter: $filter) {
+query GetLabels($first: Int = 50, $after: String, $filter: IssueLabelFilter) {
+  issueLabels(first: $first, after: $after, filter: $filter) {
     nodes {
       ...LabelFields
     }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
   }
 }

graphql/queries/project-milestones.graphql

@@ -8,11 +8,11 @@
 # List project milestones in a project
 #
 # Fetches a list of project milestones for a given project.
-query ListProjectMilestones($projectId: String!, $first: Int!) {
+query ListProjectMilestones($projectId: String!, $first: Int!, $after: String) {
   project(id: $projectId) {
     id
     name
-    projectMilestones(first: $first) {
+    projectMilestones(first: $first, after: $after) {
       nodes {
         id
         name
@@ -22,6 +22,10 @@ query ListProjectMilestones($projectId: String!, $first: Int!) {
         createdAt
         updatedAt
       }
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
     }
   }
 }

graphql/queries/projects.graphql

@@ -32,10 +32,14 @@ fragment ProjectFields on Project {
 #
 # Variables:
 #   $first: Maximum number of projects to return (default: 50)
-query GetProjects($first: Int = 50) {
-  projects(first: $first) {
+query GetProjects($first: Int = 50, $after: String) {
+  projects(first: $first, after: $after) {
     nodes {
       ...ProjectFields
     }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
   }
 }

graphql/queries/teams.graphql

@@ -28,10 +28,14 @@ fragment TeamFields on Team {
 #
 # Variables:
 #   $first: Maximum number of teams to return (default: 50)
-query GetTeams($first: Int = 50) {
-  teams(first: $first) {
+query GetTeams($first: Int = 50, $after: String) {
+  teams(first: $first, after: $after) {
     nodes {
       ...TeamFields
     }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
   }
 }

graphql/queries/users.graphql

@@ -31,10 +31,14 @@ fragment UserFields on User {
 # Variables:
 #   $first: Maximum number of users to return (default: 50)
 #   $filter: Optional filter (e.g., { active: { eq: true } })
-query GetUsers($first: Int = 50, $filter: UserFilter) {
-  users(first: $first, filter: $filter) {
+query GetUsers($first: Int = 50, $after: String, $filter: UserFilter) {
+  users(first: $first, after: $after, filter: $filter) {
     nodes {
       ...UserFields
     }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
   }
 }

src/commands/cycles.ts

@@ -5,7 +5,7 @@ import {
   notFoundError,
   requiresParameterError,
 } from "../common/errors.js";
-import { handleCommand, outputSuccess } from "../common/output.js";
+import { handleCommand, outputSuccess, parseLimit } from "../common/output.js";
 import { type DomainMeta, formatDomainUsage } from "../common/usage.js";
 import { resolveCycleId } from "../resolvers/cycle-resolver.js";
 import { resolveTeamId } from "../resolvers/team-resolver.js";
@@ -15,6 +15,8 @@ interface CycleListOptions extends CommandOptions {
   team?: string;
   active?: boolean;
   window?: string;
+  limit: string;
+  after?: string;
 }
 
 interface CycleReadOptions extends CommandOptions {
@@ -46,12 +48,20 @@ export function setupCyclesCommands(program: Command): void {
     .option("--team <team>", "filter by team (key, name, or UUID)")
     .option("--active", "only show active cycles")
     .option("--window <n>", "active cycle +/- n neighbors (requires --team)")
+    .option("-l, --limit <n>", "max results", "50")
+    .option("--after <cursor>", "cursor for next page")
     .action(
       handleCommand(async (...args: unknown[]) => {
         const [options, command] = args as [CycleListOptions, Command];
         if (options.window && !options.team) {
           throw requiresParameterError("--window", "--team");
         }
+        if (options.window && options.after) {
+          throw invalidParameterError(
+            "--after",
+            "cannot be used with --window",
+          );
+        }
 
         const ctx = createContext(command.parent!.parent!.opts());
 
@@ -61,10 +71,11 @@ export function setupCyclesCommands(program: Command): void {
           : undefined;
 
         // Fetch cycles
-        const allCycles = await listCycles(
+        const result = await listCycles(
           ctx.gql,
           teamId,
           options.active || false,
+          { limit: parseLimit(options.limit), after: options.after },
         );
 
         if (options.window) {
@@ -76,7 +87,7 @@ export function setupCyclesCommands(program: Command): void {
             );
           }
 
-          const activeCycle = allCycles.find((c: Cycle) => c.isActive);
+          const activeCycle = result.nodes.find((c: Cycle) => c.isActive);
           if (!activeCycle) {
             throw notFoundError("Active cycle", options.team ?? "", "for team");
           }
@@ -85,15 +96,18 @@ export function setupCyclesCommands(program: Command): void {
           const min = activeNumber - n;
           const max = activeNumber + n;
 
-          const filtered = allCycles
+          const filteredNodes = result.nodes
             .filter((c: Cycle) => c.number >= min && c.number <= max)
             .sort((a: Cycle, b: Cycle) => a.number - b.number);
 
-          outputSuccess(filtered);
+          outputSuccess({
+            nodes: filteredNodes,
+            pageInfo: { hasNextPage: false, endCursor: null },
+          });
           return;
         }
 
-        outputSuccess(allCycles);
+        outputSuccess(result);
       }),
     );
 
@@ -116,7 +130,7 @@ export function setupCyclesCommands(program: Command): void {
         const cycleResult = await getCycle(
           ctx.gql,
           cycleId,
-          parseInt(options.limit || "50", 10),
+          parseLimit(options.limit || "50"),
         );
 
         outputSuccess(cycleResult);