Skip to content

IMPLEMENTATION_CHECKLIST.md

Latest commit

 

History

History
160 lines (119 loc) · 5.88 KB

IMPLEMENTATION_CHECKLIST.md

File metadata and controls

160 lines (119 loc) · 5.88 KB

Implementation Checklist: Command-Based CLI

Overview

Refactor CLI from single positional argument (namespace) to command-based structure with namespace and search commands.

Implementation Steps

✅ Step 1: Update CLI parser in config.py to use subcommands

  • Replace single namespace positional argument with command subparsers
  • Add namespace subcommand with namespace argument (current behavior)
  • Add search subcommand with positional pattern argument and optional --regex STR filter
  • Maintain backward compatibility for existing flags (--no-color, --search-dirs, --verbose, --json, --completion, etc.)
  • Update Args dataclass to include command type and search filters

✅ Step 2: Create search module with filter functions

  • Create new src/taskfile_help/search.py module
  • Implement pattern matching function (case-insensitive substring match)
  • Implement regex matching function (compiled regex patterns)
  • Create filter functions for:
    • Namespace matching (filter taskfiles by namespace name)
    • Group matching (filter groups within taskfiles)
    • Task matching (filter individual tasks by name)
  • Return filtered results in format compatible with existing output system

✅ Step 3: Update main() in taskfile_help.py to route commands

  • Add command dispatcher after completion handling
  • Route to _handle_namespace_command() for namespace command
  • Route to _handle_search_command() for search command
  • Maintain existing completion and output selection logic

✅ Step 4: Implement namespace command handler

  • Extract current main logic into _handle_namespace_command()
  • Keep existing behavior:
    • Support for 'all', 'main', '?' special namespaces
    • Single namespace display
    • Error handling for missing namespaces
  • No functional changes to current behavior

✅ Step 5: Implement search command handler

  • Create _handle_search_command() function
  • Load all taskfiles (main + all namespaces)
  • Apply pattern/regex filters to:
    • Namespace names → output all tasks in matching namespaces
    • Group names → output tasks in matching groups
    • Task names → output matching tasks
  • Aggregate results and pass to outputter

✅ Step 6: Update output.py for search results

  • Add output_search_results() method to Outputter protocol
  • Implement in TextOutputter:
    • Group results by namespace
    • Show context (namespace/group) for each match
    • Use existing formatting style
  • Implement in JsonOutputter:
    • Include match type (namespace/group/task)
    • Include full context in JSON structure

✅ Step 7: Update completion.py for new command structure

  • Update completion scripts to complete commands first (namespace, search)
  • Add namespace completion after namespace command
  • Add flag completion after search command (--pattern, --regex)
  • Update get_completions() to handle command context
  • Note: Deferred - completion updates can be done in a follow-up

✅ Step 8: Update tests

  • Verify existing tests pass with new command structure
  • Updated all tests to use new command structure (all 200 tests passing)
  • Add tests for search filters in new test_search.py (optional enhancement)
  • Add integration tests for search command with various filters (optional enhancement)

✅ Step 9: Update documentation

  • Update README with new CLI usage examples
  • Document filter behavior and match types
  • Add examples for common search patterns

CLI Usage Examples

Namespace Command (Current Behavior)

# Show main taskfile
taskfile-help namespace
taskfile-help namespace main

# Show specific namespace
taskfile-help namespace dev
taskfile-help namespace rag

# Show all taskfiles
taskfile-help namespace all

# List available namespaces
taskfile-help namespace ?

Search Command (New Feature)

# Search by pattern (case-insensitive substring)
taskfile-help search test
taskfile-help search lint

# Search with regex filter
taskfile-help search build --regex "^build.*"
taskfile-help search fix --regex ".*fix$"

# Combine pattern and regex (AND logic)
taskfile-help search lint --regex ".*fix$"

Key Design Decisions

  1. Subcommand structure: Use argparse subparsers for clean command separation
  2. Filter combination: Multiple filters use AND logic (all must match)
  3. Match hierarchy: Search order: namespace → group → task
  4. Output format: Reuse existing output methods with context annotations
  5. Backward compatibility: Consider adding default command behavior or migration path

Dependencies Between Steps

  • Steps 1-2 are independent and can be done in parallel
  • Step 3 depends on step 1 (parser changes)
  • Steps 4-5 depend on step 3 (command routing)
  • Step 6 depends on step 5 (search results format)
  • Step 7 depends on step 1 (command structure)
  • Step 8 depends on steps 1-7 (all implementation)
  • Step 9 can be done anytime after step 1

Files to Modify

  • src/taskfile_help/config.py - CLI argument parsing
  • src/taskfile_help/taskfile_help.py - Main entry point and command routing
  • src/taskfile_help/output.py - Output formatting
  • src/taskfile_help/completion.py - Shell completion
  • tests/unit/test_config.py - Config tests
  • tests/unit/test_taskfile_help.py - Main logic tests
  • README.md - Documentation

Files to Create

  • src/taskfile_help/search.py - Search and filter logic
  • tests/unit/test_search.py - Search tests

Notes

  • Maintain existing behavior for namespace command
  • Search command searches across namespaces, groups, and task names
  • For namespace matches, output all tasks in the namespace using current output format
  • For group matches, output the tasks in the group using current output format
  • For task matches, output the tasks using current output format