668.3-consolidate-list-search Merge list and search into single list command

[codekiln]

Summary

Consolidate list and search commands into a single list [term] command with --all flag for pagination control.

Parent: #668 (ls-prompt-ux milestone)
Phase: 3 of 4 (Breaking Change)
Design: docs/implementation/ls-prompt-ux-command-redesign.md (section: Phase 3)
Depends on: #727 (Phase 1), #728 (Phase 2)

Goals

Eliminate the duplicate functionality between list and search by:

• Making list accept optional search term: list [term]
• Adding --all flag to control pagination (default: first page only)
• Deprecating search command with clear migration path

Current Problem

Users are confused about when to use list vs search:

langstar prompt list      # Lists all prompts
langstar prompt search rag  # Searches for prompts

Both do essentially the same thing (query the LangSmith API), but with different pagination defaults.

Proposed Solution

Single command with optional search:

langstar prompt list                    # First page of all prompts
langstar prompt list rag                # First page of "rag" search results
langstar prompt list --all              # All prompts (paginate till end)
langstar prompt list "structured output" --all  # All search results

Implementation Tasks

1. Update list command

• Add optional [search-term] positional argument
• Add --all flag for pagination control
  • Default (no flag): Fetch first page only
  • With --all: Paginate until no more results
• Support multi-word search terms (quoted)
• Update help documentation for new behavior
• Add progressive disclosure help

2. Deprecate search command

• Add deprecation warning to search command
  • "Warning: search is deprecated. Use list [term] instead."
• Hide search from main help output
• Keep search functional for backward compatibility
• Document migration path

3. Update documentation

• Update README with new list usage
• Update CLI help for list command
• Document migration from search to list
• Update examples in docs

Example Usage

List all prompts (first page):

langstar prompt list

List all prompts (all pages):

langstar prompt list --all

Search prompts (first page):

langstar prompt list rag
langstar prompt list "structured output"

Search prompts (all results):

langstar prompt list rag --all
langstar prompt list "structured output" --all

Migration Path

Document how to migrate from search to list:

# Old: langstar prompt search "term"
# New: langstar prompt list "term"

# Old: langstar prompt search "term" --limit 100
# New: langstar prompt list "term" --all

# Old: langstar prompt list
# New: langstar prompt list (unchanged)

Testing Requirements

Integration Tests

• Test list without arguments (first page, no search)
• Test list --all (all pages, no search)
• Test list <term> (first page, with search)
• Test list <term> --all (all pages, with search)
• Test multi-word search terms (quoted)
• Test empty results handling
• Test pagination exhaustion

Deprecation Tests

• Test search shows deprecation warning
• Test search still works functionally
• Test search is hidden from main help

Output Tests

• Verify output format is consistent (table with Handle, Type, Downloads, Description)
• Verify "Type" indicator shows "Regular" or "Structured"
• Test JSON output format (--output json)
• Test text output format (--output text)

Success Criteria

• list command accepts optional search term
• list --all paginates until exhaustion
• search command is deprecated but functional
• Migration path is clearly documented
• Help documentation reflects new behavior
• Tests verify all functionality
• Output format is consistent with design

Breaking Change Notice

This is a breaking change because it changes the default pagination behavior:

Before:

• list - First page only
• search <term> - All results (paginate till end)

After:

• list - First page only (unchanged)
• list --all - All pages (new flag required)
• list <term> - First page of search results (changed default)
• list <term> --all - All search results (new flag required)

Users who relied on search fetching all results by default will need to add --all flag.

Version Planning

This should be released as a minor version (not major) because:

• search command is deprecated but not removed (backward compatible)
• list behavior without arguments is unchanged
• New functionality (--all flag) is additive

Actual removal of search will happen in Phase 4 (major version).

References

• Design document: docs/implementation/ls-prompt-ux-command-redesign.md (section: "Phase 3: Consolidate List/Search")
• Parent issue: ls-prompt-ux milestone - Improve UX consistency across prompt commands #668