Overview

Implement next page and previous page style pagination for listing instances in both the CLI and web interface. This will improve usability when there are a large number of instances, limiting results shown at once and allowing navigation through pages of results.

Requirements

CLI Implementation

• Add pagination support to the zy instances list command
• Add flags for page navigation:
  • --page <number> or -p <number>: Specify which page to display
  • --per-page <number>: Number of instances per page (default: 20)
• Display pagination information in the output:
  • Show current page number
  • Show total pages
  • Show "Next page" and "Previous page" indicators when applicable
• Preserve existing functionality (e.g., --page 0 or omitting the flag shows all instances)

Web Interface Implementation

• Add pagination controls to the /instances page (templates/instances.html)
• Implement pagination in the handler (src/handlers/instances.rs)
• Support query parameters for pagination:
  • ?page=<number>: Current page (1-indexed)
  • ?per_page=<number>: Items per page (default: 20)
• Display pagination controls with:
  • "Previous" button (disabled on first page)
  • Current page indicator (e.g., "Page 2 of 5")
  • "Next" button (disabled on last page)
• Style pagination controls consistently with existing UI

Implementation Details

Files to Modify

CLI:

• src/cli/commands/instances.rs - Add pagination flags and logic to list command
• src/cli/mod.rs - Update command parsing if needed

Web:

• src/handlers/instances.rs - Modify instances_real handler to accept pagination parameters
• templates/instances.html - Add pagination UI controls
• src/templates/instances_page_template.rs - Add pagination fields to template struct
• static/styles.css - Add styles for pagination controls (if needed)

Shared:

• src/api/instances.rs - Update load_instances_for_user to support pagination parameters
• Return both the paginated data and metadata (total count, current page, total pages)

Technical Approach

1. Backend Pagination Logic:

   • Modify load_instances_for_user to accept page and per_page parameters
   • Calculate offset: (page - 1) * per_page
   • Return a struct containing:
     • instances: Vec<InstanceView> - The paginated instances
     • total_count: usize - Total number of instances
     • current_page: usize - Current page number
     • total_pages: usize - Total number of pages

2. Web Handler:

   • Extract query parameters for page and per_page from the request
   • Pass to the instances loading function
   • Pass pagination metadata to the template

3. Web Template:

   • Add pagination controls below the instances table
   • Generate links with proper query parameters
   • Show/hide Previous/Next buttons based on current page

4. CLI Command:

   • Parse --page and --per-page flags
   • Display pagination info after the instance list
   • Show navigation hints (e.g., "Use --page 3 to view next page")

Acceptance Criteria

• ✅ CLI command zy instances list --page 2 --per-page 10 works correctly
• ✅ Web interface shows pagination controls on /instances page
• ✅ Navigation between pages works smoothly in both CLI and web
• ✅ Pagination respects user permissions (owners see all, users see assigned only)
• ✅ Edge cases handled (empty list, single page, invalid page numbers)
• ✅ Clear user feedback on current page and navigation options
• ✅ Existing functionality preserved (no pagination by default or page 0 shows all)