appydave-tools 0.69.0 → 0.71.0

data/.claude/commands/uat.md

@@ -0,0 +1,321 @@
+# UAT Agent
+
+You are the User Acceptance Testing agent for the AppyDave Tools project.
+
+## Your Role
+
+Create **manual test plans** for the human tester to execute. UAT is about the human verifying that features work correctly from an end-user perspective. You DO NOT execute the tests yourself.
+
+**Key distinction:**
+- **UAT (this agent)** - Creates test plans for humans to execute manually
+- **CLI Test agent (`/cli-test`)** - Automated CLI testing that Claude executes
+
+## What You Produce
+
+A checklist of manual tests the human will run in their terminal, with:
+- Clear commands to copy/paste
+- Expected outcomes to verify
+- Checkboxes for the human to mark pass/fail
+- Space for the human to record observations
+
+## Documentation Location
+
+All UAT plans live in: `docs/uat/`
+
+Pattern: `FR-{number}-{feature-name}.md` or `NFR-{number}-{feature-name}.md`
+
+## Process
+
+### Step 1: Read the Spec
+
+- Find the requirement in `docs/backlog.md`
+- Read any linked spec docs (e.g., `docs/specs/fr-003-*.md`)
+- Identify all acceptance criteria
+
+### Step 2: Create UAT Test Plan
+
+Create `docs/uat/FR-{number}-{feature-name}.md` using this template:
+
+```markdown
+# UAT: FR-{number} - {Feature Name}
+
+**Spec:** `docs/specs/fr-{number}-*.md`
+**Date:** YYYY-MM-DD
+**Tester:** [Your Name]
+**Status:** Pending
+
+## Prerequisites
+
+Before starting, ensure:
+
+1. [ ] Dependencies installed: `bundle install`
+2. [ ] [Any configuration requirements]
+3. [ ] [Any test data setup]
+
+## How to Use This Plan
+
+1. Run each command in your terminal
+2. Compare output to "Expected" description
+3. Mark the checkbox: `[x]` for pass, `[ ]` for fail
+4. Add notes if behavior differs from expected
+5. Complete the Summary section when done
+
+---
+
+## Tests
+
+### Test 1: [Description]
+
+**What to verify:** [Brief description of what this tests]
+
+**Command:**
+```bash
+[command to run]
+```
+
+**Expected:**
+- [Expected outcome 1]
+- [Expected outcome 2]
+
+**Result:** [ ] Pass / [ ] Fail
+**Notes:**
+
+---
+
+### Test 2: [Description]
+
+...
+
+---
+
+## Summary
+
+**Date completed:**
+**Passed:** __/__
+**Failed:** __/__
+
+### Issues Found
+
+[Describe any failures or unexpected behavior]
+
+### UX Observations
+
+[Note any friction, confusing output, or suggestions - even for passing tests]
+
+## Verdict
+
+[ ] Ready to ship
+[ ] Needs rework - see issues above
+```
+
+### Step 3: Organize Tests by Category
+
+Group tests logically:
+- **Happy path** - Core functionality works as expected
+- **Error handling** - Invalid inputs produce helpful errors
+- **Edge cases** - Boundary conditions, empty inputs, etc.
+- **Output formats** - Different format options work correctly
+
+### Step 4: Deliver the Plan
+
+Once the test plan is created:
+1. Tell the human the file location
+2. Summarize how many tests and categories
+3. Note any prerequisites they need to set up first
+4. Suggest running `/cli-test` first for automated verification
+
+## Writing Good Manual Tests
+
+### DO:
+- Write commands that can be copy/pasted directly
+- Be specific about expected output (exact text, exit codes)
+- Include cleanup commands if tests create data
+- Group related tests together
+- Note when tests depend on previous test data
+
+### DON'T:
+- Execute the tests yourself (that's `/cli-test`)
+- Fill in results (human does that)
+- Use placeholder values the human must replace
+- Assume the human knows implementation details
+
+## Test Categories
+
+| Category | What to Test | Example |
+|----------|--------------|---------|
+| Core CRUD | Create, read, update, delete operations | `jump add`, `jump get`, `jump remove` |
+| Search/Query | Finding and filtering data | `jump search ruby`, `jump list` |
+| Output Formats | Different display formats | `--format json`, `--format table` |
+| Error Handling | Invalid inputs, missing data | Missing required flags, unknown keys |
+| Exit Codes | Correct return codes | Success=0, Not found=1, Invalid=2 |
+| Generation | File/output generation | `jump generate aliases --output file` |
+| Help/Docs | Help text and documentation | `--help`, `--version` |
+
+## Example Test Plan
+
+```markdown
+# UAT: FR-3 - Jump Location Tool
+
+**Spec:** `docs/specs/fr-003-jump-location-tool.md`
+**Date:** 2025-12-14
+**Tester:** David
+**Status:** Pending
+
+## Prerequisites
+
+Before starting, ensure:
+
+1. [ ] Dependencies installed: `bundle install`
+2. [ ] No existing test locations (or willing to clean up after)
+
+---
+
+## Tests
+
+### Core CRUD
+
+#### Test 1: Add a location
+
+**What to verify:** Can add a new location with all metadata fields
+
+**Command:**
+```bash
+ruby bin/jump.rb add --key test-project --path ~/dev/test --brand testbrand --type tool --tags ruby,test --description "Test project" --format json
+```
+
+**Expected:**
+- Returns JSON with `success: true`
+- Location object includes all provided fields
+- `jump` field auto-generated as `jtest-project`
+
+**Result:** [ ] Pass / [ ] Fail
+**Notes:**
+
+---
+
+#### Test 2: List shows the new location
+
+**What to verify:** List command includes newly added location
+
+**Command:**
+```bash
+ruby bin/jump.rb list --format table
+```
+
+**Expected:**
+- Table includes `test-project` row
+- Shows key, jump alias, type, brand, description
+
+**Result:** [ ] Pass / [ ] Fail
+**Notes:**
+
+---
+
+### Cleanup
+
+After testing, remove test data:
+```bash
+ruby bin/jump.rb remove test-project --force
+```
+
+---
+
+## Summary
+
+**Date completed:**
+**Passed:** __/2
+**Failed:** __/2
+
+### Issues Found
+
+[To be filled by tester]
+
+### UX Observations
+
+[To be filled by tester]
+
+## Verdict
+
+[ ] Ready to ship
+[ ] Needs rework - see issues above
+```
+
+## Related Agents
+
+- `/cli-test` - Automated CLI testing (run this BEFORE UAT for quick verification)
+- `/dev` - Developer who implements features
+- `/po` - Product Owner who writes specs
+- `/progress` - Quick status check
+
+## Typical Workflow
+
+1. Feature is implemented by `/dev`
+2. Run `/cli-test FR-3` for automated verification (Claude executes)
+3. If cli-test passes, run `/uat FR-3` to create manual test plan
+4. Human executes manual test plan
+5. Human records results and verdict
+6. If passed → Feature is ready to ship
+
+## Bug Handover to Developer
+
+When a bug is discovered during UAT and fixed on the spot, create a **brief conversational handover** so the developer can add proper test coverage.
+
+**When to use:** User says "give me a handover" or "hand this to dev" after a bug fix.
+
+### Handover Format
+
+```
+## Bug Fix Handover: [Brief Description]
+
+**Status:** Fixed, needs test coverage
+
+### The Bug
+[One sentence: what was wrong]
+
+### Root Cause
+[One sentence: why it happened]
+
+**File:** `path/to/file.rb`
+
+### The Fix
+[Brief description of what was changed, with line numbers if helpful]
+
+### Developer Action
+Add test coverage:
+
+**File:** `spec/path/to/spec.rb`
+
+**Test case:**
+```ruby
+[Minimal test example that would catch this bug]
+```
+```
+
+### Example
+
+```
+## Bug Fix Handover: Jump `info` showing wrong message
+
+**Status:** Fixed, needs test coverage
+
+### The Bug
+`jump info` displayed "No locations found." instead of config metadata.
+
+### Root Cause
+TableFormatter checked `results.empty?` before checking result type. Info results have no `results` key, so it defaulted to empty array.
+
+**File:** `lib/appydave/tools/jump/formatters/table_formatter.rb`
+
+### The Fix
+Added `info_result?` check before `results.empty?` check, plus `format_info` method (lines 47-66).
+
+### Developer Action
+Add test for info formatting in `spec/appydave/tools/jump/formatters/table_formatter_spec.rb`
+```
+
+### Key Points
+
+- **Keep it brief** - just enough for dev to understand and write tests
+- **Always include the file path** - saves dev time finding it
+- **Suggest a test case** - even pseudocode helps
+- **No separate document** - handover is conversational, in the chat

data/.rubocop.yml

@@ -21,6 +21,7 @@ Metrics/BlockLength:
     - "**/spec/**/*"
     - "*.gemspec"
     - "bin/gpt_context.rb"
+    - "lib/appydave/tools/dam/project_listing.rb"
   AllowedMethods:
     - configure
     - context
@@ -73,6 +74,16 @@ Naming/VariableNumber:
 Naming/MethodParameterName:
   AllowedNames:
     - as
+    - s3
+
+Naming/PredicateMethod:
+  AllowedMethods:
+    - add
+    - update
+    - remove
+    - save
+    - delete
+    - create
 Style/EmptyMethod:    
   Exclude:
     - "**/spec/**/*"

data/AGENTS.md

@@ -18,5 +18,48 @@ Commits follow conventional commits consumed by semantic-release (`feat:`, `fix:
 ## Agent Coordination
 Claude is the primary automation agent; align with the collaboration notes in `CLAUDE.md` before introducing new flows or prompt templates. When scripting repeatable tasks (gpt_context runs, metadata syncs), document the expected Claude inputs/outputs so the agent can reproduce them. Flag breaking CLI changes in PR descriptions with a dedicated **Claude Impact** subsection to keep downstream automations in sync.
 
+## Slash Command Agents
+
+This project has specialized agents activated via slash commands:
+
+| Command | Agent | Purpose |
+|---------|-------|---------|
+| `/po` | Product Owner | Requirements gathering, spec writing, documentation |
+| `/dev` | Developer | Feature implementation, code changes |
+| `/uat` | UAT Tester | User acceptance testing, verification |
+| `/progress` | Status Check | Quick project status summary |
+
+### Workflow
+
+```
+/progress → Quick orientation, see what's pending
+    ↓
+/po → Discuss requirements, write specs to docs/backlog.md
+    ↓
+/dev → Implement features based on specs
+    ↓
+/uat → Test implementation against acceptance criteria
+    ↓
+/po → Review UAT results, update documentation
+```
+
+### Agent Files
+
+Located in `.claude/commands/`:
+- `po.md` - Product Owner agent instructions
+- `dev.md` - Developer agent instructions
+- `uat.md` - UAT tester agent instructions
+- `progress.md` - Status check command
+
+### Key Documentation Files
+
+| File | Purpose | Maintained By |
+|------|---------|---------------|
+| `docs/backlog.md` | Requirements (FR/NFR) with status | /po |
+| `docs/brainstorming-notes.md` | Ideas being explored | /po |
+| `docs/uat/` | UAT plans and results | /uat |
+| `CHANGELOG.md` | Version history | Auto (semantic-release) |
+| `CLAUDE.md` | Project context for Claude | Manual |
+
 ## Security & Configuration Tips
 Keep API keys and OAuth secrets in `.env` or `~/.config/appydave/` (managed via `ad_config`). Never commit those files; `.gitignore` already excludes them. Validate YouTube API changes against a test channel before touching production content, and rotate credentials when machines change owners.

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+# [0.70.0](https://github.com/appydave/appydave-tools/compare/v0.69.0...v0.70.0) (2025-11-26)
+
+
+### Bug Fixes
+
+* rename files_match? to compare_files to satisfy rubocop naming convention ([01140dc](https://github.com/appydave/appydave-tools/commit/01140dca0cfe277e7363e35726fab37204812ef6))
+
+
+### Features
+
+* handle multipart S3 ETags with size-based comparison for sync detection ([d29cf4b](https://github.com/appydave/appydave-tools/commit/d29cf4b704f7595ece902bb49af970d07540240e))
+
+# [0.69.0](https://github.com/appydave/appydave-tools/compare/v0.68.0...v0.69.0) (2025-11-22)
+
+
+### Bug Fixes
+
+* disable RedundantFormat cop for intentional header formatting ([e4f03be](https://github.com/appydave/appydave-tools/commit/e4f03be70e101e704a617cc9d0f5bf5df9474070))
+
+
+### Features
+
+* add fuzzy brand matching and improve table alignment ([bce8309](https://github.com/appydave/appydave-tools/commit/bce83093b3834b2f6a3c70d2fa5854b88f88d48b))
+
 # [0.68.0](https://github.com/appydave/appydave-tools/compare/v0.67.0...v0.68.0) (2025-11-22)
 
 

data/CLAUDE.md

@@ -48,6 +48,76 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - **Shareable individually** - Tools can be featured in standalone videos
 - **Language flexible** - Currently Ruby, could be rewritten if needed
 
+## Documentation Discovery Protocol
+
+**CRITICAL: When user asks about recent changes, work completed, or project history:**
+
+### 1. ALWAYS Check Existing Documentation FIRST
+
+**Check in this order:**
+
+1. **CHANGELOG.md** (PRIMARY SOURCE for recent changes)
+   - Location: `/CHANGELOG.md`
+   - Contains: Complete version history (v0.0.2 → current)
+   - Organized by: Semantic version with Features/Fixes categorized
+   - Updated: Automatically via semantic-release on every release
+   - **Use this for:** "What changed recently?", "What work was done?", "Sprint summary"
+
+2. **Git log** (SECONDARY - only if CHANGELOG lacks detail)
+   - Use for: Commit-level detail, specific date ranges, author information
+   - Command: `git log --since="1 week ago" --oneline`
+
+3. **docs/ folders** (TERTIARY - for architecture/design decisions)
+   - `docs/code-quality/` - Audit reports, retrospectives, UAT plans
+   - `docs/dam/` - DAM-specific requirements and architecture
+   - `docs/usage/` - Tool usage guides
+
+### 2. Before Creating New Documentation
+
+**ALWAYS verify:**
+- ✅ Does it already exist in CHANGELOG.md?
+- ✅ Does it exist in docs/ folders?
+- ✅ Does it exist in existing markdown files?
+- ✅ Is it redundant with automated changelogs?
+
+**Only create new documentation if:**
+- ❌ Information doesn't exist anywhere
+- ❌ Existing docs have gaps
+- ❌ New perspective/format is genuinely needed
+
+### 3. Common Mistakes to Avoid
+
+**DON'T:**
+- ❌ Jump straight to `git log` without checking CHANGELOG.md
+- ❌ Suggest creating new changelogs when CHANGELOG.md exists
+- ❌ Recreate information that's already in automated systems
+- ❌ Ignore existing documentation
+
+**DO:**
+- ✅ Trust CHANGELOG.md as source of truth for version history
+- ✅ Use existing docs before creating new ones
+- ✅ Reference existing documentation in responses
+- ✅ Supplement (not replace) existing docs
+
+### Example: User Asks "What work was done recently?"
+
+**Correct approach:**
+```
+1. Read CHANGELOG.md
+2. Summarize recent versions (e.g., v0.60.0 → v0.69.0)
+3. Group features by theme
+4. Reference specific versions/commits
+5. Supplement with git log if more detail needed
+```
+
+**Incorrect approach:**
+```
+❌ Run git log first
+❌ Manually count commits
+❌ Suggest creating new changelog
+❌ Ignore existing CHANGELOG.md
+```
+
 ## Common Commands
 
 ### Development Setup
@@ -464,6 +534,23 @@ gem build           # Build gemspec into .gem file
 - **Configuration System**: Flexible config management for multi-project workflows
 - **Type System**: Custom type classes for data validation and transformation
 
+### Architecture Documentation
+
+Comprehensive guides for understanding and extending the codebase:
+
+| Document | Location | Purpose |
+|----------|----------|---------|
+| **CLI Patterns Guide** | [docs/architecture/cli/cli-patterns.md](./docs/architecture/cli/cli-patterns.md) | 4 CLI architecture patterns with decision tree, code examples, migration guide |
+| **CLI Pattern Comparison** | [docs/architecture/cli/cli-pattern-comparison.md](./docs/architecture/cli/cli-pattern-comparison.md) | Visual diagrams, decision matrix, anti-patterns |
+| **exe/bin Convention** | [docs/architecture/cli/exe-bin-convention.md](./docs/architecture/cli/exe-bin-convention.md) | How exe/ wrappers load bin/ implementations for gem installation |
+| **Testing Patterns** | [docs/architecture/testing/testing-patterns.md](./docs/architecture/testing/testing-patterns.md) | RSpec conventions, fixtures, VCR mocking, Guard workflow |
+| **Configuration Systems** | [docs/architecture/configuration/configuration-systems.md](./docs/architecture/configuration/configuration-systems.md) | Config architecture and patterns |
+
+**Quick Reference:**
+- **New CLI tool?** → Read CLI Patterns Guide first, choose pattern 1-4
+- **Adding tests?** → Read Testing Patterns Guide
+- **Understanding exe/ vs bin/?** → Read exe/bin Convention
+
 ### Key Components
 
 #### CLI Actions (`lib/appydave/tools/cli_actions/`)
@@ -510,13 +597,19 @@ gem build           # Build gemspec into .gem file
 - No `require` statements needed in spec files (handled by spec_helper)
 - VCR for HTTP request mocking (YouTube API calls)
 - SimpleCov for coverage reporting
+- **Test business logic (`lib/`), not CLI executables (`bin/`)**
+
+**Full guide:** [docs/architecture/testing/testing-patterns.md](./docs/architecture/testing/testing-patterns.md)
 
 ### File Organization
-- CLI executables in `bin/`
-- Core library code in `lib/appydave/tools/`
-- Tests mirror lib structure in `spec/`
+- **`exe/`** - Thin wrappers installed as gem commands (no `.rb` extension)
+- **`bin/`** - Full CLI implementations (`.rb` extension, used during development)
+- **`lib/appydave/tools/`** - Core library code (business logic)
+- **`spec/`** - Tests mirror lib structure
 - Configuration examples and docs in respective `_doc.md` files
 
+**exe/ vs bin/ explained:** [docs/architecture/cli/exe-bin-convention.md](./docs/architecture/cli/exe-bin-convention.md)
+
 ## Key Dependencies
 - `google-api-client`: YouTube API integration
 - `ruby-openai`: OpenAI GPT integration  

data/README.md

@@ -426,6 +426,21 @@ guard
 bin/console
 ```
 
+### Architecture Documentation
+
+Before adding new tools or making significant changes, review these guides:
+
+| Guide | What It Covers |
+|-------|----------------|
+| [CLI Patterns](./docs/architecture/cli/cli-patterns.md) | 4 CLI architecture patterns, decision tree, code examples |
+| [exe/ vs bin/](./docs/architecture/cli/exe-bin-convention.md) | How executables are organized for gem installation |
+| [Testing Patterns](./docs/architecture/testing/testing-patterns.md) | RSpec conventions, fixtures, mocking, continuous testing |
+| [CLI Pattern Comparison](./docs/architecture/cli/cli-pattern-comparison.md) | Visual diagrams, decision matrix |
+
+**Quick start:**
+- Creating a CLI tool? → [CLI Patterns Guide](./docs/architecture/cli/cli-patterns.md)
+- Writing tests? → [Testing Patterns Guide](./docs/architecture/testing/testing-patterns.md)
+
 ### Semantic Versioning
 
 This project uses **automated versioning** via semantic-release. Don't manually edit version files.

data/bin/dam

@@ -22,6 +22,7 @@ class VatCLI
       'archive' => method(:archive_command),
       'manifest' => method(:manifest_command),
       'sync-ssd' => method(:sync_ssd_command),
+      'ssd-status' => method(:ssd_status_command),
       'repo-status' => method(:repo_status_command),
       'repo-sync' => method(:repo_sync_command),
       'repo-push' => method(:repo_push_command),
@@ -69,7 +70,7 @@ class VatCLI
       puts 'Available commands:'
       puts '  list, status, manifest'
       puts '  s3-up, s3-down, s3-status, s3-cleanup-remote, s3-cleanup-local'
-      puts '  archive, sync-ssd'
+      puts '  archive, sync-ssd, ssd-status'
       puts '  repo-status, repo-sync, repo-push'
       puts '  s3-share, s3-discover, s3-scan'
       puts ''
@@ -130,6 +131,7 @@ class VatCLI
   # List brands and projects
   def list_command(args)
     detailed = args.include?('--detailed')
+    s3 = args.include?('--s3')
     args = args.reject { |arg| arg.start_with?('--') || arg.start_with?('-') }
 
     brand_arg = args[0]
@@ -137,13 +139,13 @@ class VatCLI
 
     if brand_arg.nil?
       # List all brands with summary
-      Appydave::Tools::Dam::ProjectListing.list_brands_with_counts(detailed: detailed)
+      Appydave::Tools::Dam::ProjectListing.list_brands_with_counts(detailed: detailed, s3: s3)
     elsif pattern_arg
       # Pattern matching
       Appydave::Tools::Dam::ProjectListing.list_with_pattern(brand_arg, pattern_arg)
     else
       # Specific brand
-      Appydave::Tools::Dam::ProjectListing.list_brand_projects(brand_arg, detailed: detailed)
+      Appydave::Tools::Dam::ProjectListing.list_brand_projects(brand_arg, detailed: detailed, s3: s3)
     end
   rescue StandardError => e
     puts "❌ Error: #{e.message}"
@@ -363,6 +365,24 @@ class VatCLI
     exit 1
   end
 
+  # Show SSD mount status
+  def ssd_status_command(args)
+    all = args.include?('--all')
+    args = args.reject { |arg| arg.start_with?('--') }
+    brand_arg = args[0]
+
+    if all || brand_arg.nil?
+      # Show status for all brands
+      Appydave::Tools::Dam::SsdStatus.new.show_all
+    else
+      # Show status for specific brand
+      Appydave::Tools::Dam::SsdStatus.new.show(brand_arg)
+    end
+  rescue StandardError => e
+    puts "❌ Error: #{e.message}"
+    exit 1
+  end
+
   # Show git status for brand repositories
   def repo_status_command(args)
     all = args.include?('--all')
@@ -741,6 +761,7 @@ class VatCLI
         archive <brand> <project>        Copy project to SSD backup
         manifest <brand> [--all]         Generate project manifest
         sync-ssd <brand>                 Restore light files from SSD
+        ssd-status [brand]               Check SSD mount status for all/one brand
 
       List Modes:
         dam list                   All brands with counts/sizes
@@ -956,7 +977,7 @@ class VatCLI
     puts <<~HELP
       List Command
 
-      Usage: dam list [brand] [pattern]
+      Usage: dam list [brand] [pattern] [--s3] [--detailed]
 
       Modes:
         1. List all brands with summary:
@@ -969,10 +990,21 @@ class VatCLI
            dam list appydave 'b6*'       # All projects b60-b69
            dam list appydave 'b4*'       # All projects b40-b49
 
+      Options:
+        --s3          Show S3 sync status (slower, makes AWS API calls)
+        --detailed    Show extended metadata (PATH, SSD, file counts)
+
       Examples:
-        dam list                         # Tabular: brand, project count, size, modified
-        dam list voz                     # Tabular: all VOZ projects with size/date
-        dam list appydave 'b6*'          # Tabular: b60-b69 projects with size/date
+        dam list                         # Fast: brand, project count, size, modified, git
+        dam list --s3                    # Slower: adds S3 SYNC column
+        dam list voz                     # Fast: all VOZ projects (no S3 column)
+        dam list voz --s3                # Slower: VOZ projects with S3 sync status
+        dam list appydave 'b6*'          # Fast: b60-b69 projects
+        dam list appydave --detailed --s3  # Comprehensive: all columns including S3
+
+      Performance Note:
+        The --s3 flag makes AWS API calls for each project, which can be slow.
+        Default view omits S3 status for faster performance.
     HELP
   end