Merge pull request #13 from bulgogi-whopper/feat/list-command

Feat/list command

Author: eannnnnn

.kiro/specs/taptik-list-command/design.md

@@ -0,0 +1,78 @@
+# Requirements Document
+
+## Introduction
+
+The ListCommand feature provides users with the ability to query and display available configuration packages from the Taptik cloud storage. This module enables users to discover, search, and explore configurations uploaded by themselves and other users through a simple CLI interface. The feature serves as the primary discovery mechanism for the Taptik ecosystem, focusing on essential listing functionality with basic filtering and sorting capabilities.
+
+## Requirements
+
+### Requirement 1
+
+**User Story:** As a CLI user, I want to view a list of available configuration packages from the cloud, so that I can discover and explore configurations that I might want to download and use.
+
+#### Acceptance Criteria
+
+1. WHEN I run `taptik list` THEN the system SHALL display a table of available public configuration packages
+2. WHEN displaying the list THEN the system SHALL show ID, Title, Created date, Size, and Access level for each configuration
+3. WHEN no configurations are available THEN the system SHALL display a helpful message indicating the empty state
+4. WHEN the list is long THEN the system SHALL limit results to 20 items by default
+5. IF I am not authenticated THEN the system SHALL only show public configurations
+
+### Requirement 2
+
+**User Story:** As a CLI user, I want to filter configuration packages by title, so that I can quickly find configurations relevant to my needs.
+
+#### Acceptance Criteria
+
+1. WHEN I use `--filter <query>` THEN the system SHALL search in configuration titles
+2. WHEN the filter matches configurations THEN the system SHALL display only matching results
+3. WHEN the filter matches no configurations THEN the system SHALL display "No configurations found matching your filter"
+4. WHEN I provide an empty filter THEN the system SHALL treat it as no filter applied
+5. IF the filter query contains special characters THEN the system SHALL handle them safely
+
+### Requirement 3
+
+**User Story:** As a CLI user, I want to sort configuration packages by different criteria, so that I can view them in my preferred order.
+
+#### Acceptance Criteria
+
+1. WHEN I use `--sort date` THEN the system SHALL sort configurations by creation date (newest first)
+2. WHEN I use `--sort name` THEN the system SHALL sort configurations alphabetically by title
+3. WHEN I don't specify sort THEN the system SHALL default to date sorting
+4. IF I provide an invalid sort option THEN the system SHALL show an error with valid options
+
+### Requirement 4
+
+**User Story:** As a CLI user, I want to control the number of results displayed, so that I can manage the output according to my needs.
+
+#### Acceptance Criteria
+
+1. WHEN I use `--limit <n>` THEN the system SHALL display at most n configurations
+2. WHEN I don't specify a limit THEN the system SHALL default to 20 results
+3. WHEN I specify a limit of 0 THEN the system SHALL show an error
+4. WHEN I specify a limit greater than 100 THEN the system SHALL cap it at 100
+5. IF the available configurations are fewer than the limit THEN the system SHALL show all available configurations
+
+### Requirement 5
+
+**User Story:** As an authenticated user, I want to view configurations that I have liked, so that I can easily access my favorite configurations.
+
+#### Acceptance Criteria
+
+1. WHEN I run `taptik list liked` THEN the system SHALL display configurations I have liked
+2. WHEN I am not authenticated THEN the system SHALL prompt me to log in first
+3. WHEN I have no liked configurations THEN the system SHALL display "You haven't liked any configurations yet"
+4. WHEN displaying liked configurations THEN the system SHALL use the same table format as regular list
+5. IF there's an error fetching liked configurations THEN the system SHALL show a clear error message
+
+### Requirement 6
+
+**User Story:** As a developer, I want the list command to handle errors gracefully and provide clear feedback, so that I can understand and resolve any issues.
+
+#### Acceptance Criteria
+
+1. WHEN there's a network error THEN the system SHALL display "Unable to connect to Taptik cloud. Please check your internet connection."
+2. WHEN there's an authentication error THEN the system SHALL display "Authentication failed. Please run 'taptik login' first."
+3. WHEN there's a server error THEN the system SHALL display "Taptik cloud is temporarily unavailable. Please try again later."
+4. WHEN an invalid option is provided THEN the system SHALL show command help with valid options
+5. IF any error occurs THEN the system SHALL exit with appropriate error code (non-zero)

.kiro/specs/taptik-list-command/requirements.md

@@ -0,0 +1,70 @@
+# Implementation Plan
+
+- [x] 1. Create data models and interfaces for configuration listing
+  - Create ConfigBundle model interface with all required fields (id, title, createdAt, size, accessLevel)
+  - Create DisplayConfiguration interface for formatted CLI display
+  - Create ListOptions interface for command options (filter, sort, limit)
+  - Create ConfigurationListResult interface for service responses
+  - _Requirements: 1.2, 2.1, 3.1, 4.1_
+
+- [x] 2. Implement ListService for business logic
+  - Create ListService class in src/modules/info/services/list.service.ts
+  - Implement listConfigurations method with filtering, sorting, and pagination
+  - Implement listLikedConfigurations method for authenticated users
+  - Add private helper methods for filtering by title, sorting, and validation
+  - _Requirements: 1.1, 2.1, 2.2, 3.1, 3.2, 4.1, 4.2, 5.1_
+
+- [x] 3. Create ListCommand for CLI interface
+  - Create ListCommand class in src/modules/info/commands/list.command.ts
+  - Implement command options parsing (--filter, --sort, --limit)
+  - Add subcommand support for "liked" configurations
+  - Implement table formatting for configuration display
+  - Add proper error handling with specific error messages
+  - _Requirements: 1.1, 1.2, 1.3, 2.1, 2.3, 3.1, 3.3, 4.1, 4.3, 4.4, 5.1, 5.3, 6.4_
+
+- [x] 4. Implement Supabase database integration
+  - Add database query methods to ListService for public configurations
+  - Implement liked configurations query with user authentication
+  - Add proper error handling for network, authentication, and server errors
+  - Implement query filtering and sorting at database level
+  - _Requirements: 1.1, 1.5, 5.1, 5.2, 6.1, 6.2, 6.3_
+
+- [x] 5. Add input validation and error handling
+  - Implement validation for sort options (date/name only)
+  - Add limit validation (1-100 range with default 20)
+  - Implement specific error messages for different failure scenarios
+  - Add proper exit codes for different error types
+  - _Requirements: 3.3, 4.3, 4.4, 4.5, 6.1, 6.2, 6.3, 6.4, 6.5_
+
+- [x] 6. Implement table formatting and display logic
+  - Create table formatter with columns: ID, Title, Created, Size, Access
+  - Implement empty state messages for different scenarios
+  - Add proper date formatting and size display
+  - Implement result limiting and pagination display
+  - _Requirements: 1.2, 1.3, 1.4, 2.3, 4.5, 5.3_
+
+- [x] 7. Update InfoModule to include ListCommand and ListService
+  - Add ListCommand and ListService to InfoModule providers
+  - Export ListService for potential use by other modules
+  - Ensure proper dependency injection setup
+  - _Requirements: All requirements (module integration)_
+
+- [x] 8. Write comprehensive unit tests
+  - Create unit tests for ListService with mocked Supabase client
+  - Create unit tests for ListCommand with mocked ListService
+  - Test all error scenarios and edge cases
+  - Test filtering, sorting, and pagination logic
+  - _Requirements: All requirements (quality assurance)_
+
+- [x] 9. Write integration tests
+  - Create integration tests for end-to-end list command execution
+  - Test authentication flow for liked configurations
+  - Test database integration with real Supabase client
+  - Test CLI output formatting and error handling
+  - _Requirements: All requirements (end-to-end validation)_
+
+- [x] 10. Update CLI registration and help documentation
+  - Register ListCommand in the main CLI application
+  - Update help text and command documentation
+  - Ensure proper command discovery and execution
+  - _Requirements: 6.4 (command help and options)_

.kiro/specs/taptik-list-command/tasks.md

@@ -37,6 +37,78 @@ npm run cli -- --help
 | `build:test`     | Test build functionality  | `npm run build:test`          |
 | `test:cli`       | Run CLI integration tests | `npm run test:cli`            |
 
+## 📋 List Command Deep Dive
+
+### Overview
+
+The list command provides discovery and exploration of configuration packages stored in the Taptik cloud. It allows users to browse, filter, and sort available configurations through an intuitive command-line interface.
+
+### Basic Usage
+
+```bash
+# List all public configurations
+npm run cli -- list
+
+# Filter configurations by title
+npm run cli -- list --filter "frontend"
+npm run cli -- list --filter "typescript"
+
+# Sort configurations
+npm run cli -- list --sort date    # Sort by creation date (default)
+npm run cli -- list --sort name    # Sort alphabetically by title
+
+# Limit results
+npm run cli -- list --limit 10     # Show 10 results
+npm run cli -- list --limit 50     # Show 50 results (max: 100)
+
+# Combine options
+npm run cli -- list --filter "react" --sort name --limit 20
+```
+
+### Subcommands
+
+#### Liked Configurations
+
+```bash
+# List configurations you've liked (requires authentication)
+npm run cli -- list liked
+npm run cli -- list liked --sort date --limit 10
+```
+
+### Command Options
+
+| Option | Description | Default | Example |
+|--------|-------------|---------|---------|
+| `--filter <query>` | Filter by configuration title | None | `--filter "frontend"` |
+| `--sort <field>` | Sort by date or name | `date` | `--sort name` |
+| `--limit <n>` | Limit results (1-100) | `20` | `--limit 50` |
+
+### Output Format
+
+The list command displays configurations in a table format:
+
+```
+ID       Title                    Created      Size     Access
+─────────────────────────────────────────────────────────────
+abc12345 Frontend React Setup     2 days ago   2.3MB    Public
+def67890 TypeScript Backend       1 week ago   1.8MB    Public
+ghi11121 Full Stack Template      3 days ago   4.1MB    Public
+```
+
+### Error Handling
+
+The list command provides specific error messages for different scenarios:
+
+- **Network Error**: "Unable to connect to Taptik cloud. Please check your internet connection."
+- **Authentication Error**: "Authentication failed. Please run 'taptik login' first."
+- **Server Error**: "Taptik cloud is temporarily unavailable. Please try again later."
+- **Invalid Options**: Shows help with valid options
+
+### Authentication Requirements
+
+- **Public listings**: No authentication required
+- **Liked configurations**: Requires authentication with `taptik login`
+
 ## 🏗️ Build Command Deep Dive
 
 ### Architecture Overview
@@ -117,6 +189,12 @@ npm run cli -- build --platform kiro --output ./dist/taptik-config --quiet
 npm run cli -- build --categories personal     # User context only
 npm run cli -- build --categories project      # Project context only
 npm run cli -- build --categories prompts      # Templates only
+
+# 6. List available configurations
+npm run cli -- list                            # List public configurations
+npm run cli -- list --filter "frontend"        # Filter by title
+npm run cli -- list --sort name --limit 50     # Sort and limit results
+npm run cli -- list liked                      # List liked configurations (requires auth)
 ```
 
 ### Advanced Options

CLI_GUIDE.md

@@ -262,16 +262,73 @@ taptik pull --latest --target cursor
 taptik pull --dry-run  # Preview without applying
 ```
 
+### List Command
+
+The `list` command helps you discover and explore configuration packages available in the Taptik cloud.
+
+#### Basic Usage
+
+```bash
+# List all public configurations
+taptik list
+
+# Filter configurations by title
+taptik list --filter "frontend"
+taptik list --filter "typescript setup"
+
+# Sort configurations
+taptik list --sort date    # Sort by creation date (default)
+taptik list --sort name    # Sort alphabetically by title
+
+# Limit number of results
+taptik list --limit 10     # Show 10 results
+taptik list --limit 50     # Show up to 50 results (max: 100)
+
+# Combine options for precise discovery
+taptik list --filter "react" --sort name --limit 20
+```
+
+#### Subcommands
+
+```bash
+# List configurations you've liked (requires authentication)
+taptik list liked
+taptik list liked --sort date --limit 10
+```
+
+#### Command Options
+
+| Option | Description | Default | Valid Values |
+|--------|-------------|---------|--------------|
+| `--filter <query>` | Filter by configuration title | None | Any string |
+| `--sort <field>` | Sort results | `date` | `date`, `name` |
+| `--limit <n>` | Limit number of results | `20` | 1-100 |
+
+#### Output Format
+
+Results are displayed in a clean table format showing:
+- **ID**: Short identifier for the configuration
+- **Title**: Configuration name/title
+- **Created**: When the configuration was created (relative time)
+- **Size**: File size of the configuration package
+- **Access**: Whether the configuration is Public or Private
+
+#### Authentication
+
+- **Public listings**: No authentication required
+- **Liked configurations**: Requires login with `taptik login`
+
 ### Information & Discovery
 
 ```bash
 # Show current status
 taptik info
 
 # List available configurations
-taptik list
-taptik list --filter "typescript"
-taptik list --sort date --limit 10
+taptik list                              # List all public configurations
+taptik list --filter "typescript"       # Filter by title
+taptik list --sort name --limit 10       # Sort alphabetically, limit results
+taptik list liked                        # List your liked configurations (requires auth)
 
 # Version information
 taptik --version