📦 deps(thirdparty): update snapshots

2026-05-29 08:33:53 +00:00
parent fdb52f1e96
commit 06e0d13d57
1615 changed files with 232858 additions and 0 deletions
@@ -0,0 +1,673 @@
+# Researching Tool Alternatives
+
+Guide for discovering and evaluating modern CLI tools when current tools underperform.
+
+## When to Research
+
+### Performance Triggers
+
+Research alternatives when you observe:
+
+- **Slow execution**: Command takes >5 seconds on typical workload
+- **Resource spikes**: High CPU/memory usage for simple operations
+- **Blocking behavior**: Tool blocks the terminal for extended periods
+- **Scale issues**: Performance degrades significantly with file count or size
+- **3x+ slower than expected**: Tool taking much longer than task size suggests
+
+### Ergonomic Triggers
+
+Consider alternatives when:
+
+- **Complex syntax**: Requiring frequent man page lookups for basic operations
+- **Poor defaults**: Always passing the same flags to get desired behavior
+- **Missing features**: Workarounds needed for common tasks
+- **Error messages**: Cryptic or unhelpful output on failure
+- **Repeated complex command chains**: Same multi-tool pipeline used frequently
+
+### Maintenance Triggers
+
+Look for replacements when:
+
+- **Unmaintained**: No updates in 2+ years, open issues piling up
+- **Deprecated**: Tool documentation marks it as legacy
+- **Security issues**: Known vulnerabilities without patches
+- **Compatibility**: Broken on modern OS/architecture
+
+### User Signal Triggers
+
+Always research when:
+
+- Explicit request: "Is there a better way to do this?"
+- Frustration indicators: "This is taking forever", "Why is this so slow?"
+- Performance complaints about specific tool
+- User asks about alternatives or modern equivalents
+
+### Context Triggers
+
+Consider research for:
+
+- **New categories**: Task type not in current tool catalog
+- **Building automation**: Tool will run frequently, performance matters
+- **New environment setup**: Opportunity to establish good defaults
+- **Cross-tool integration**: Multiple tools could be replaced by one
+
+## Where to Look
+
+### Primary Sources
+
+#### 1. GitHub Search
+
+**Search patterns**:
+
+```
+site:github.com {category} rust OR go language:Rust OR language:Go stars:>1000
+site:github.com {category} CLI tool stars:>500
+site:github.com modern {legacy-tool} alternative
+```
+
+**Examples**:
+
+```
+site:github.com file search rust language:Rust stars:>1000
+site:github.com grep alternative rust language:Rust stars:>1000
+site:github.com modern ls replacement stars:>500
+```
+
+**Why GitHub:**
+- Active development visible (commit history)
+- Star count indicates adoption and community validation
+- Issues/PRs show maintenance quality
+- README usually has benchmarks and comparisons
+
+#### 2. Curated Lists
+
+**awesome-cli-apps**: <https://github.com/agarrharr/awesome-cli-apps>
+- Categorized by function
+- Curated for quality
+- Regularly updated
+
+**modern-unix**: <https://github.com/ibraheemdev/modern-unix>
+- Specifically Unix tool replacements
+- Focus on performance and ergonomics
+- Comparison with legacy tools
+
+**awesome-tuis**: <https://github.com/rothgar/awesome-tuis>
+- Terminal UI applications
+- Interactive tools
+- Well-maintained list
+
+**Why curated lists:**
+- Pre-filtered for quality
+- Organized by category
+- Community-vetted
+
+#### 3. Language-Specific Ecosystems
+
+**Rust CLI Working Group**:
+- <https://rust-cli.github.io/book/>
+- <https://lib.rs/command-line-utilities>
+
+**Go CLI Tools**:
+- <https://github.com/avelino/awesome-go#command-line>
+
+**Why language ecosystems:**
+- Rust tools often fastest (native performance, zero-cost abstractions)
+- Go tools good balance (fast, easy distribution, single binary)
+- Language communities maintain tool lists
+
+### Secondary Sources
+
+#### Hacker News
+
+**Search patterns**:
+
+```
+site:news.ycombinator.com {tool} alternative
+site:news.ycombinator.com modern {category} tools
+site:news.ycombinator.com CLI productivity
+```
+
+**Why HN:**
+- Real-world usage discussions
+- Trade-off analysis from practitioners
+- Early visibility into trending tools
+- Critical perspectives, not just hype
+
+#### Reddit Communities
+
+**r/commandline** - Dedicated CLI tool discussions
+**r/rust** - Rust-based CLI tools (often performance-focused)
+**r/golang** - Go-based tools
+**r/programming** - General tool discussions
+
+**Why Reddit:**
+- User reviews and experiences
+- Comparison threads
+- Common pain points surfaced
+
+#### Tool Comparison Sites
+
+**AlternativeTo**: <https://alternativeto.net>
+- User ratings
+- Feature comparison matrices
+- Platform availability
+
+**Why comparison sites:**
+- Side-by-side feature lists
+- Community ratings
+- Discover tools you didn't know existed
+
+### Research Workflow
+
+**Query progression**:
+1. `{TASK} CLI tool 2025` or `{TASK} CLI tool 2024`
+2. `best {TASK} command line tool`
+3. `modern alternative to {LEGACY_TOOL}`
+4. `{LANGUAGE} {TASK} CLI` (try rust first, then go)
+
+**Initial filtering**:
+- Published/updated within last 2 years
+- Active development (commits within 6 months)
+- Community traction (GitHub stars >500 for niche, >1000 for common tools)
+- Clear documentation and examples
+- Available in package managers
+
+## Evaluation Criteria
+
+Evaluate candidates across these dimensions:
+
+### 1. Speed (Weight: High - 40%)
+
+**Measure:**
+- Benchmarks on representative workload
+- Compare with legacy tool on same task
+- Check scaling behavior (10 files vs 10,000 files)
+- Startup time (matters for frequently-run commands)
+
+**Thresholds:**
+- **2× faster**: Consider if other benefits exist
+- **5× faster**: Strong candidate, likely worth adoption
+- **10× faster**: High priority upgrade, significant productivity gain
+
+**How to benchmark:**
+
+```bash
+# Quick comparison with time
+time {old-tool} args
+time {new-tool} args
+
+# Statistical benchmark with hyperfine
+hyperfine '{old-tool} args' '{new-tool} args'
+
+# Test scaling
+hyperfine --parameter-scan num 10 10000 '{tool} args'
+```
+
+### 2. Ergonomics (Weight: Medium-High - 30%)
+
+**Evaluate:**
+- **Syntax simplicity**: Can you remember it without docs?
+- **Defaults**: Do common operations require flags?
+- **Output quality**: Readable, informative, well-formatted?
+- **Error messages**: Clear, actionable, helpful suggestions?
+- **Composability**: Works well in pipes and scripts?
+
+**Good indicators:**
+- Colored output by default
+- Smart defaults (respects .gitignore, etc.)
+- Short, memorable command names
+- Built-in help that's actually helpful (`--help` is clear)
+- Intuitive flag names
+
+**Red flags:**
+- Complex syntax requiring constant reference
+- Poor error messages ("error" with no context)
+- Unexpected default behavior
+- Verbose flags only (no short forms)
+
+### 3. Maintenance (Weight: High - 20%)
+
+**Check repository health:**
+- **Last commit**: <6 months is active, <3 months is excellent
+- **Issue response time**: Maintainer engagement (check recent issues)
+- **Release cadence**: Regular releases, not constant churn
+- **Contributor count**: Not single-maintainer ghost projects
+- **Organization backing**: Company/org-backed often more stable
+
+**Red flags:**
+- Archived repository
+- 100+ open issues with no maintainer responses
+- Last release >2 years ago
+- Single maintainer who's gone MIA
+- Major bugs unaddressed
+
+**Green flags:**
+- Active CI/CD
+- Regular security updates
+- Responsive to community
+- Clear governance or roadmap
+
+### 4. Installation Complexity (Weight: Medium - 10%)
+
+**Assess ease of installation:**
+- Available in major package managers (brew, apt, cargo, dnf)
+- Binary releases for major platforms (Linux, macOS, Windows)
+- Dependency count (fewer is better)
+- Binary size (under 50MB is reasonable for most tools)
+
+**Scoring:**
+- **Excellent**: `brew install`, `apt install`, or `cargo install`
+- **Good**: Binary releases on GitHub, one-liner install script
+- **Acceptable**: Build from source with standard toolchain
+- **Poor**: Complex build requirements, many dependencies
+- **Deal-breaker**: Requires specific versions of rare dependencies
+
+### 5. Adoption (Weight: Medium - Points to maturity)
+
+**Indicators of healthy adoption:**
+- GitHub stars (>1k is good, >5k is excellent, >10k is widely adopted)
+- Used by major projects (check GitHub dependents)
+- Mentioned in blog posts, tool lists, conference talks
+- Active community (Discord, discussions, Stack Overflow questions)
+- Production usage stories
+
+**Why adoption matters:**
+- More usage → more bugs found and fixed
+- Better documentation and examples
+- Higher probability of long-term maintenance
+- Easier to find help when stuck
+
+### 6. Compatibility (Weight: Medium-Low - Important for drop-in replacements)
+
+**Check replacement viability:**
+- **Drop-in replacement**: Can alias old command to new? (`alias cat=bat`)
+- **POSIX compliance**: Matters for portable scripts
+- **Output format**: Parseable by downstream tools?
+- **Configuration**: Reads old tool's config files?
+- **Flags**: Similar enough for muscle memory transfer?
+
+**Examples:**
+
+```bash
+# Safe drop-in replacements
+alias cat=bat       # Generally yes (bat mimics cat behavior)
+alias ls=eza        # Yes (eza designed as ls replacement)
+alias grep=rg       # Mostly (different flags, but core usage similar)
+
+# Risky drop-ins
+alias sed=sd        # No (sd is simpler, not full sed replacement)
+alias awk=...       # No good modern replacement (awk is unique)
+```
+
+## Testing Workflow
+
+### Stage 1: Quick Evaluation (5 minutes)
+
+**Install in isolated way:**
+
+```bash
+# Prefer cargo for isolated testing (doesn't require sudo)
+cargo install {tool}
+
+# Or homebrew
+brew install {tool}
+```
+
+**Basic functionality check:**
+
+```bash
+# Check help output
+{tool} --help
+
+# Test basic operation
+{tool} {simple-task}
+
+# Quick benchmark
+hyperfine '{old-tool} args' '{new-tool} args'
+```
+
+**Decision point:** If not obviously better (2×+ speed or significantly better UX), stop here.
+
+### Stage 2: Real-World Testing (15 minutes)
+
+**Test on actual project workloads:**
+
+```bash
+# Test on current project
+cd ~/Developer/current-project
+{new-tool} {typical-task}
+
+# Test on large directory
+cd ~/Developer  # or another large directory tree
+{new-tool} {typical-task}
+
+# Test common variations
+{new-tool} {variant-1}
+{new-tool} {variant-2}
+{new-tool} {variant-3}
+
+# Test error handling
+{new-tool} nonexistent-file
+{new-tool} --invalid-flag
+{new-tool} {edge-case}
+```
+
+**Evaluate results:**
+- Does output format work for your needs?
+- Are error messages helpful?
+- Any surprising behavior?
+- Performance consistent across different inputs?
+
+**Decision point:** If issues found, check GitHub issues. If widespread problems or dealbreaker bugs, stop.
+
+### Stage 3: Integration Testing (10 minutes)
+
+**Check fit with existing workflow:**
+
+```bash
+# Pipe compatibility
+{new-tool} args | other-command
+other-command | {new-tool} args
+
+# Script compatibility
+# - Create small test script using new tool
+# - Verify behavior matches expectations
+
+# Shell integration
+# - Tab completion working?
+# - Any shell-specific issues? (zsh vs bash)
+# - Works from different directories?
+
+# Alias trial
+alias {old}={new}
+# Use normally for a few minutes
+# Pay attention to muscle memory friction
+```
+
+**Decision point:** Integration issues are often deal-breakers for drop-in replacements. If tool doesn't fit workflow smoothly, consider fallback strategy or skip.
+
+### Testing Checklist
+
+- [ ] Installs cleanly
+- [ ] Help text is clear
+- [ ] Basic operation works as expected
+- [ ] Performance is measurably better (if speed is goal)
+- [ ] Output format is acceptable
+- [ ] Error messages are helpful
+- [ ] Works in pipes/scripts
+- [ ] No showstopper bugs on current project
+- [ ] Integrates smoothly with existing workflow
+- [ ] Documentation is adequate
+
+## Recommendation Format
+
+When presenting tool findings to user:
+
+### Template
+
+```
+Found: {TOOL_NAME} — {one-line description}
+
+Performance:
+- {benchmark result, e.g., "8× faster than find on this codebase"}
+- {specific improvement, e.g., "searched 10k files in 0.2s vs 2.1s"}
+
+Benefits:
+- {key advantage 1}
+- {key advantage 2}
+- {key advantage 3}
+
+Installation:
+```bash
+{install command}
+```
+
+Trade-offs:
+- {any downsides, or "None identified"}
+
+Confidence: {HIGH/MEDIUM/LOW}
+- HIGH: Widely adopted, clear win, drop-in replacement
+- MEDIUM: Good but niche, or requires workflow changes
+- LOW: Bleeding edge, or significant compatibility concerns
+
+Recommend: {INSTALL/TRY/SKIP}
+
+```
+
+### Example
+
+```
+
+Found: ripgrep (rg) — Fast line-oriented search tool
+
+Performance:
+- 15× faster than grep on this codebase
+- Searched 50k files in 0.3s vs 4.5s with grep -r
+
+Benefits:
+- Respects .gitignore by default (no node_modules noise)
+- Colored output with line numbers
+- Better regex support (PCRE2)
+- Automatic binary file detection
+
+Installation:
+
+```bash
+brew install ripgrep
+```
+
+Trade-offs:
+- Different flags than grep (muscle memory adjustment)
+- Recursive by default (explicit -r not needed)
+
+Confidence: HIGH
+- 40k+ GitHub stars
+- Used by major projects (VS Code search backend)
+- Drop-in for most grep use cases
+
+Recommend: INSTALL
+
+```
+
+## When to Recommend Installation
+
+### Recommend: INSTALL
+
+User should install when ALL of these are true:
+
+- **Clear performance win** (5×+ faster) OR **significantly better ergonomics**
+- **No significant downsides** (compatible, well-maintained)
+- **Easy installation** (brew/apt/cargo available)
+- **High confidence** in quality (mature, adopted, maintained)
+
+**Action:**
+- Include install command in response
+- Offer to add shell alias if appropriate
+- Provide example usage for current task
+
+### Recommend: TRY
+
+User might try when:
+
+- **Moderate improvement** (2-5× faster or notable UX improvement)
+- **Specialized use case** (benefits specific workflows)
+- **Learning curve exists** (different paradigm or syntax)
+- **Medium confidence** (newer tool, smaller community, or niche)
+
+**Action:**
+- Explain benefits clearly
+- Provide test command to evaluate
+- Let user decide based on their priorities
+- Offer to help with adoption if they choose to try
+
+### Recommend: SKIP
+
+Don't recommend when ANY of these are true:
+
+- **Marginal improvement** (<2× faster, minimal UX gain)
+- **Installation complexity** (build from source, many dependencies)
+- **Maintenance concerns** (abandoned, single maintainer MIA, security issues)
+- **Low confidence** (alpha quality, breaking changes, major bugs)
+- **User constraints** (no install access, strict portability requirements)
+
+**Action:**
+- Use fallback tool without mentioning limitation
+- Or briefly note why skipping: "Evaluated {TOOL} but marginal improvement doesn't justify installation"
+- Document finding for future reference if tool matures
+
+## Fallback Strategy
+
+Always maintain fallback support in scripts and automation:
+
+### Pattern 1: Check-then-run
+
+```bash
+if command -v rg &> /dev/null; then
+  rg pattern
+else
+  grep -r pattern .
+fi
+```
+
+### Pattern 2: Function Wrapper
+
+```bash
+search() {
+  if command -v rg &> /dev/null; then
+    rg "$@"
+  else
+    grep -r "$@" .
+  fi
+}
+```
+
+### Pattern 3: Conditional Alias
+
+```bash
+# In shell config (.zshrc, .bashrc)
+if command -v bat &> /dev/null; then
+  alias cat='bat --style=plain --paging=never'
+fi
+
+if command -v eza &> /dev/null; then
+  alias ls='eza'
+  alias l='eza -l'
+  alias la='eza -la'
+fi
+```
+
+**Why fallback matters:**
+
+- Scripts work on systems without modern tools installed
+- Shared code doesn't break for other developers
+- Graceful degradation in CI/CD environments
+- Portable across different environments
+
+## Example Research Session
+
+**Trigger**: User searching large codebase, `grep` taking 30+ seconds
+
+**Search query**: "fast code search CLI tool 2024"
+
+**Candidates found**:
+1. ripgrep (rg) — Rust-based, 10-100x faster than grep
+2. The Silver Searcher (ag) — C-based, 3-5x faster than grep
+3. ugrep — C++ with advanced regex, similar speed to rg
+
+**Initial evaluation**:
+
+| Tool | Speed | Ergonomics | Maintenance | Install |
+|------|-------|------------|-------------|---------|
+| rg | ★★★ | ★★★ | ★★★ | ★★★ |
+| ag | ★★ | ★★ | ★ | ★★★ |
+| ugrep | ★★★ | ★★ | ★★ | ★★ |
+
+**Hands-on test**:
+
+```bash
+brew install ripgrep
+
+# Current: grep -r "pattern" . (30s)
+time grep -r "authentication" .
+# Result: 28.4s
+
+# New: rg "pattern" (default recursive)
+time rg "authentication"
+# Result: 0.8s
+
+# Edge case: large binary files
+rg "pattern"  # Automatically skips binaries
+grep -r "pattern" .  # Hangs on binaries unless -I flag
+```
+
+**Findings**:
+
+```
+Found: ripgrep (rg) — Recursive line-oriented search tool
+
+Advantages:
+- 35x faster than grep on this codebase (0.8s vs 28s)
+- Respects .gitignore automatically (fewer false matches)
+- Colorized output with line numbers by default
+- Automatically skips binary files
+
+Install:
+brew install ripgrep
+
+Example (current task):
+rg "authentication" --type ts
+
+Trade-offs:
+- Different flag syntax than grep (learning curve)
+- Regex flavor differs slightly (PCRE2 vs POSIX)
+
+Recommendation: ★ ADOPT — 35x speedup justifies one-time learning cost
+```
+
+## Tool Discovery Resources
+
+### Curated Lists
+
+- [awesome-cli-apps](https://github.com/agarrharr/awesome-cli-apps)
+- [modern-unix](https://github.com/ibraheemdev/modern-unix)
+- [Rust CLI tools](https://lib.rs/command-line-utilities)
+- [Go CLI tools](https://github.com/avelino/awesome-go#command-line)
+
+### Communities
+
+- r/commandline — CLI tool discussions
+- r/rust — Rust-based tools (often fastest)
+- r/golang — Go-based tools (good balance)
+- Lobsters CLI tag — <https://lobste.rs/t/cli>
+
+### Benchmarking Tools
+
+When comparing performance:
+
+```bash
+# hyperfine - statistical benchmarking
+brew install hyperfine
+hyperfine '{COMMAND_1}' '{COMMAND_2}'
+
+# time - quick comparison
+time {COMMAND}
+
+# perf - detailed profiling (Linux)
+perf stat {COMMAND}
+```
+
+## Updating Tool Catalog
+
+When research yields strong candidate:
+
+1. Add to main selection table in SKILL.md
+2. Document in tool-catalog.md with:
+   - Purpose
+   - Key features
+   - Installation
+   - Common usage
+   - Performance notes
+3. Update detection script to check for new tool
+4. Add to any relevant workflow examples
+
+Keep tool catalog current — revisit every 6 months to prune abandoned tools and add emerging ones.