appydave-tools 0.70.0 → 0.71.0

data/docs/backlog.md

@@ -0,0 +1,120 @@
+# AppyDave Tools - Backlog
+
+Requirements tracking for AppyDave Tools development.
+
+---
+
+## Requirements Table
+
+| # | Requirement | Added | Status |
+|---|-------------|-------|--------|
+| 1 | FR-1: GPT Context token counting (see below) | 2025-12-06 | Pending |
+| 2 | FR-2: GPT Context AI-friendly help system (see below) | 2025-12-07 | Pending |
+| 3 | NFR-1: Improve test coverage for DAM commands | 2025-12-06 | Pending |
+| 4 | FR-3: Jump Location Tool (see spec) | 2025-12-13 | ✅ Implemented 2025-12-13 |
+| 5 | NFR-2: Claude Code Skill for Jump Tool (see below) | 2025-12-14 | ✅ Implemented 2025-12-14 |
+
+---
+
+## Pending Requirements
+
+### FR-1: GPT Context Token Counting
+
+**User Story**: As a developer using GPT Context, I want to see estimated token counts so I can ensure my context fits within LLM limits.
+
+**Acceptance Criteria**:
+- [ ] Display estimated token count in output
+- [ ] Support common tokenizers (cl100k for GPT-4, claude for Claude)
+- [ ] Show warning when exceeding common thresholds (100k, 200k)
+- [ ] Optional via `--tokens` flag
+
+**Technical Notes**:
+- Consider tiktoken gem for OpenAI tokenization
+- May need to estimate for Claude (no official Ruby tokenizer)
+
+---
+
+### FR-2: GPT Context AI-Friendly Help System
+
+**Spec**: [docs/specs/fr-002-gpt-context-help-system.md](./specs/fr-002-gpt-context-help-system.md)
+
+**User Story**: As an AI agent using GPT Context via skills, I want structured, comprehensive help output so I can understand all options and use the tool correctly.
+
+**Priority**: High - enables AI skill integration
+
+**Status**: Ready for Development - full spec available
+
+---
+
+### NFR-1: Improve Test Coverage for DAM Commands
+
+**Goal**: Increase test coverage for DAM command implementations.
+
+**Scope**:
+- [ ] Add specs for `ListCommand`
+- [ ] Add specs for `S3UpCommand` with mocked S3
+- [ ] Add specs for `S3DownCommand` with mocked S3
+- [ ] Add specs for `S3StatusCommand`
+
+**Notes**:
+- Use VCR or WebMock for S3 API calls
+- Focus on edge cases: missing config, network errors, permission issues
+
+---
+
+## Completed Requirements
+
+### NFR-2: Claude Code Skill for Jump Tool
+
+**Completed**: 2025-12-14
+
+**Implementation Summary**:
+- Personal skill at `~/.claude/skills/jump/SKILL.md`
+- Description includes brand names (appydave, voz, supportsignal, joy, aitldr, kiros), products (flivideo, storyline, klueless, dam), and trigger keywords
+- Primary mode: Jump CLI commands (`jump search`, `jump get`, `jump list`)
+- Fallback mode: Direct JSON read from `/ad/brains/brand-david/data-systems/collections/jump/current.json`
+- Tool restrictions: `allowed-tools: Read, Bash, Grep, Glob`
+- Includes natural language examples and key location reference table
+
+**Testing**: Restart Claude Code and test with prompts like "Where is FliVideo?"
+
+### FR-3: Jump Location Tool
+
+**Spec**: [docs/specs/fr-003-jump-location-tool.md](./specs/fr-003-jump-location-tool.md)
+
+**Completed**: 2025-12-13
+
+**Implementation Summary**:
+- CLI tool (`jump`) for managing development folder locations
+- Single JSON config file (`~/.config/appydave/locations.json`)
+- Fuzzy search with weighted scoring across all metadata
+- CRUD operations (add/update/remove) with validation
+- Reports by brand, client, type, tag
+- Generation of shell aliases and help content
+- 68 RSpec tests passing
+- Follows Pattern 4 (Method Dispatch Full) from CLI patterns guide
+- Dependency injection for PathValidator enables CI-compatible testing
+
+---
+
+## How to Use This File
+
+### Adding a New Requirement
+
+1. Add row to the Requirements Table
+2. Add a section below with:
+   - User story (for FRs)
+   - Acceptance criteria
+   - Technical notes
+
+### Updating Status
+
+- `Pending` - Not yet started
+- `🔄 In Progress` - Being worked on
+- `✅ Implemented YYYY-MM-DD` - Complete
+- `⚠️ Needs Rework` - Issues found
+
+### Requirement Types
+
+- **FR-X** - Functional Requirements (user-facing features)
+- **NFR-X** - Non-Functional Requirements (refactors, performance, tests)

data/docs/cli-tests/FR-3-jump-location-tool.md

@@ -0,0 +1,515 @@
+# UAT: FR-3 - Jump Location Tool
+
+**Spec:** `docs/specs/fr-003-jump-location-tool.md`
+**Date:** 2025-12-13
+**Tester:** Claude
+**Mode:** Full UAT
+**Status:** In Progress
+
+## Prerequisites
+
+1. Gem dependencies: `bundle install`
+2. No existing locations.json (fresh config)
+3. Test directories may or may not exist (validates warning behavior)
+
+## Acceptance Criteria
+
+From the spec:
+
+### Core Functionality
+1. `jump search <terms>` returns fuzzy-matched results with scores
+2. `jump get <key>` returns single location or error with suggestion
+3. `jump list` shows all locations
+4. `jump add` creates new location with validation
+5. `jump update` modifies existing location
+6. `jump remove` deletes location (with `--force` for no prompt)
+7. `jump validate` checks all paths exist, reports results
+
+### Reports
+8. `jump report brands/clients/types/tags` shows counts
+9. `jump report by-brand/by-client/by-type/by-tag` groups locations
+10. `jump report summary` shows overview
+
+### Generation
+11. `jump generate aliases` outputs shell alias format
+12. `jump generate help` outputs fzf-friendly help format
+13. `--output <file>` writes to file instead of stdout
+
+### Output Formats
+14. `--format table` shows colored, pretty output (default)
+15. `--format json` returns structured JSON
+16. `--format paths` returns one path per line
+
+### Error Handling
+17. Invalid input returns structured error with code
+18. NOT_FOUND includes fuzzy suggestions
+19. Config errors handled gracefully (create defaults if missing)
+20. Exit codes match specification (0=success, 1=not found, 2=invalid input)
+
+---
+
+## Tests
+
+### Test 1: Help displays correctly (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb --help
+```
+
+**Expected:** Shows usage, commands, and examples
+
+**Result:** PASS
+**Notes:** Displays full help with all commands, options, and examples
+
+---
+
+### Test 2: Version displays correctly (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb --version
+```
+
+**Expected:** Shows version number
+
+**Result:** PASS
+**Notes:** Shows "Jump Location Tool v0.70.0"
+
+---
+
+### Test 3: Info command on fresh config (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb info --format json
+```
+
+**Expected:** Shows config info with exists=false or empty locations
+
+**Result:** PASS
+**Notes:** Returns JSON with config_path, exists=true, version, location_count
+
+---
+
+### Test 4: Add location with all fields (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb add --key ad-tools --path ~/dev/ad/appydave-tools --brand appydave --type tool --tags ruby,cli --description "AppyDave CLI tools" --format json
+```
+
+**Expected:** Success with location object returned
+
+**Result:** PASS
+**Notes:** Returns success=true with full location object including auto-generated jump alias "jad-tools"
+
+---
+
+### Test 5: Add second location (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb add --key ss-app --path ~/dev/clients/supportsignal/app --client supportsignal --type tool --tags typescript,nextjs --description "SupportSignal app" --format json
+```
+
+**Expected:** Success with location object returned
+
+**Result:** PASS
+**Notes:** Returns success=true with client-based location including jump alias "jss-app"
+
+---
+
+### Test 6: Add duplicate key fails (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb add --key ad-tools --path ~/other/path --format json
+```
+
+**Expected:** Error with DUPLICATE_KEY code
+
+**Result:** PASS
+**Notes:** Returns success=false with code="DUPLICATE_KEY" and helpful error message
+
+---
+
+### Test 7: Add with invalid key fails (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb add --key Invalid-Key --path ~/dev/test --format json
+```
+
+**Expected:** Error with INVALID_INPUT code
+
+**Result:** PASS
+**Notes:** Returns success=false with code="INVALID_INPUT", validates key format (lowercase, alphanumeric, hyphens only)
+
+---
+
+### Test 8: List all locations (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb list --format json
+```
+
+**Expected:** Returns array with 2 locations (ad-tools, ss-app)
+
+**Result:** PASS
+**Notes:** Returns success=true with count=2 and results array containing both locations with index numbers
+
+---
+
+### Test 9: Get by exact key (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb get ad-tools --format json
+```
+
+**Expected:** Returns single location with success=true
+
+**Result:** PASS
+**Notes:** Returns success=true with result object containing full location details
+
+---
+
+### Test 10: Get unknown key returns suggestion (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb get ad-tool --format json
+```
+
+**Expected:** Error with NOT_FOUND code and suggestion
+
+**Result:** PASS
+**Notes:** Returns success=false with code="NOT_FOUND" and suggestion="Did you mean 'ad-tools'?"
+
+---
+
+### Test 11: Search by key (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb search tools --format json
+```
+
+**Expected:** Returns ad-tools with score > 0
+
+**Result:** PASS
+**Notes:** Returns ad-tools with score=50 (key contains term)
+
+---
+
+### Test 12: Search by tag (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb search ruby --format json
+```
+
+**Expected:** Returns ad-tools (has ruby tag)
+
+**Result:** PASS
+**Notes:** Returns ad-tools with score=30 (tag match)
+
+---
+
+### Test 13: Search by multiple terms (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb search supportsignal typescript --format json
+```
+
+**Expected:** Returns ss-app with combined score
+
+**Result:** PASS
+**Notes:** Returns ss-app with combined score from client match + tag match
+
+---
+
+### Test 14: Search no matches (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb search nonexistent --format json
+```
+
+**Expected:** Empty results array, success=true
+
+**Result:** PASS
+**Notes:** Returns success=true with count=0 and empty results array
+
+---
+
+### Test 15: Update location (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb update ad-tools --description "Updated CLI tools" --format json
+```
+
+**Expected:** Success with updated location
+
+**Result:** PASS
+**Notes:** Returns success=true with updated location showing new description
+
+---
+
+### Test 16: Validate all locations (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb validate --format json
+```
+
+**Expected:** Returns results array with valid=true/false for each
+
+**Result:** PASS
+**Notes:** Returns count=2, valid_count=1, invalid_count=1 with results showing ad-tools valid=true, ss-app valid=false (path doesn't exist)
+
+---
+
+### Test 17: Report brands (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb report brands --format json
+```
+
+**Expected:** Shows brands with location counts
+
+**Result:** PASS
+**Notes:** Returns success=true with report="brands" and results array (empty when no brands defined in config)
+
+---
+
+### Test 18: Report types (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb report types --format json
+```
+
+**Expected:** Shows types with location counts
+
+**Result:** PASS
+**Notes:** Returns success=true with results showing type="tool" with location_count=2
+
+---
+
+### Test 19: Report summary (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb report summary --format json
+```
+
+**Expected:** Shows total counts for locations, brands, clients
+
+**Result:** PASS
+**Notes:** Returns comprehensive summary with total_locations=2, by_type, by_brand, by_client breakdowns, and config_info
+
+---
+
+### Test 20: Report by-type (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb report by-type --format json
+```
+
+**Expected:** Groups locations by type
+
+**Result:** PASS
+**Notes:** Returns success=true with groups hash containing "tool" key with array of both locations
+
+---
+
+### Test 21: Generate aliases to stdout (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb generate aliases 2>&1 | grep -E "^alias"
+```
+
+**Expected:** Outputs alias lines for each location
+
+**Result:** PASS
+**Notes:** Outputs alias jad-tools="cd '...'" and alias jss-app="cd '...'" with descriptions as comments
+
+---
+
+### Test 22: Generate help to stdout (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb generate help 2>&1 | head -5
+```
+
+**Expected:** Outputs help content with tab-separated fields
+
+**Result:** PASS
+**Notes:** Outputs header comment and tab-separated fields: alias, path, brand, type, description (fzf-friendly format)
+
+---
+
+### Test 23: Generate aliases to file (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb generate aliases --output /tmp/test-aliases.zsh --format json && cat /tmp/test-aliases.zsh | head -10
+```
+
+**Expected:** File created with alias content
+
+**Result:** PASS
+**Notes:** Returns JSON with success=true, path, lines=12. File contains header, usage comment, and alias definitions
+
+---
+
+### Test 24: Format paths (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb list --format paths
+```
+
+**Expected:** One path per line, no other output
+
+**Result:** PASS
+**Notes:** Outputs one expanded path per line, suitable for piping to other commands
+
+---
+
+### Test 25: Format table (Auto/Manual)
+
+**Command:**
+```bash
+ruby bin/jump.rb list --format table
+```
+
+**Expected:** Colored table with headers (Manual verification of colors)
+
+**Result:** PASS
+**Notes:** Displays formatted table with header row, separator line, numbered rows with KEY, JUMP, TYPE, BRAND/CLIENT, DESCRIPTION columns, and total count footer
+
+---
+
+### Test 26: Exit code 0 on success (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb list --format json; echo "Exit code: $?"
+```
+
+**Expected:** Exit code: 0
+
+**Result:** PASS
+**Notes:** Returns exit code 0 for successful operations
+
+---
+
+### Test 27: Exit code 1 on NOT_FOUND (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb get nonexistent --format json; echo "Exit code: $?"
+```
+
+**Expected:** Exit code: 1
+
+**Result:** PASS
+**Notes:** Returns exit code 1 with code="NOT_FOUND" when key doesn't exist
+
+---
+
+### Test 28: Exit code 2 on invalid input (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb add --format json; echo "Exit code: $?"
+```
+
+**Expected:** Exit code: 2 (missing required --key)
+
+**Result:** PASS
+**Notes:** Returns exit code 2 with usage message when required --key is missing
+
+---
+
+### Test 29: Remove without --force fails (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb remove ad-tools --format json
+```
+
+**Expected:** Error with CONFIRMATION_REQUIRED code
+
+**Result:** PASS
+**Notes:** Returns success=false with code="CONFIRMATION_REQUIRED" and helpful message about using --force
+
+---
+
+### Test 30: Remove with --force succeeds (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb remove ad-tools --force --format json
+```
+
+**Expected:** Success with removed location returned
+
+**Result:** PASS
+**Notes:** Returns success=true with message and full removed location object
+
+---
+
+### Test 31: Cleanup - remove second location (Auto)
+
+**Command:**
+```bash
+ruby bin/jump.rb remove ss-app --force --format json
+```
+
+**Expected:** Success
+
+**Result:** PASS
+**Notes:** Successfully cleaned up test data
+
+---
+
+## Summary
+
+**Passed:** 31/31
+**Failed:** 0/31
+
+### Failures
+
+None.
+
+### Observations
+
+1. **All acceptance criteria met**: Core functionality, reports, generation, output formats, and error handling all work as specified.
+
+2. **Fuzzy search scoring works correctly**: Exact key match (100), key contains (50), tag match (30), type match (20) - all verified.
+
+3. **Exit codes conform to spec**: 0 (success), 1 (NOT_FOUND), 2 (invalid input/confirmation required).
+
+4. **Dependency injection enables clean testing**: TestPathValidator allows CI-friendly tests without filesystem dependencies. 68 RSpec tests passing.
+
+5. **Generate aliases produces shell-ready output**: Properly formatted with comments, grouped by brand/client, suitable for sourcing in .zshrc.
+
+6. **Validation correctly identifies invalid paths**: ss-app path didn't exist and was correctly flagged as invalid.
+
+7. **Table formatter is readable**: Clean column alignment with headers and totals.
+
+## Verdict
+
+[x] Ready to ship
+[ ] Needs rework - see failures above