Objective: Implement the most commonly used commands for immediate usability: query, create, current-user, and auth-token.

Overview

This phase delivers the core functionality needed for basic MistDemo usage. After this phase, users can:

• Authenticate and obtain web auth tokens
• Verify their identity
• Query records
• Create new records

Commands to Implement

1. auth-token

• Starts local HTTP server on specified port
• Opens browser to CloudKit auth URL (unless --no-browser)
• Receives auth callback with token
• Outputs token to stdout
• Handles timeout gracefully
• Handles port conflicts
• Unit tests with mock server
• Integration test with mock auth flow

2. current-user

• Loads configuration properly
• Calls MistKit client.currentUser()
• Supports field filtering
• Outputs in all formats
• Handles authentication errors
• Unit tests with mock client
• Integration test

3. query

• Parses multiple filter expressions
• Parses sort field and direction
• Validates limit (1-200)
• Supports field selection
• Handles continuation markers
• Calls MistKit client.queryRecords()
• Outputs in all formats
• Handles errors gracefully
• Unit tests for parsing
• Integration test with mock data

4. create

• Parses field definitions (name:type:value)
• Validates field types match schema
• Loads fields from JSON file
• Reads fields from stdin
• Generates record name if not provided
• Calls MistKit client.createRecord()
• Outputs created record
• Handles validation errors
• Unit tests for field parsing
• Integration test with mock client

Implementation Order

1. auth-token - Required for other commands' testing
2. current-user - Simple command, validates auth
3. query - Most complex, most useful
4. create - Builds on query patterns

Dependencies

Blocked By: Phase 1 (core infrastructure) - #212

Blocks: Phase 3, Phase 4

Complexity: Medium-High

Key Challenges:

• auth-token local server implementation
• Field parsing and validation
• Filter expression parsing
• Pagination support

Definition of Done

• All four commands implemented
• Unit tests pass with >85% coverage
• Integration tests pass
• Help text comprehensive
• Examples documented
• Code review complete
• Users can perform basic CloudKit operations

📖 Full Details: .claude/docs/mistdemo/phases/phase-2-essential-commands.md