appydave-tools 0.70.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

@@ -75,6 +75,15 @@ 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,15 @@
+# [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)
 
 

data/CLAUDE.md

@@ -534,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/`)
@@ -580,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 ''
@@ -364,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')
@@ -742,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

data/bin/jump.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Jump Location Tool - Manage development folder locations
+#
+# Usage:
+#   jump search <terms>           # Fuzzy search locations
+#   jump get <key>                # Get by exact key
+#   jump list                     # List all locations
+#   jump add --key <key> --path <path>  # Add new location
+#   jump update <key> [options]   # Update location
+#   jump remove <key> --force     # Remove location
+#   jump validate [key]           # Check paths exist
+#   jump report <type>            # Generate reports
+#   jump generate <target>        # Generate aliases/help
+#   jump info                     # Show config info
+#
+# Examples:
+#   jump search appydave ruby
+#   jump add --key my-proj --path ~/dev/my-proj --brand appydave
+#   jump generate aliases --output ~/.oh-my-zsh/custom/aliases-jump.zsh
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'appydave/tools'
+
+cli = Appydave::Tools::Jump::CLI.new
+exit_code = cli.run(ARGV)
+exit(exit_code)

data/bin/subtitle_processor.rb

@@ -12,7 +12,8 @@ class SubtitleProcessorCLI
   def initialize
     @commands = {
       'clean' => method(:clean_subtitles),
-      'join' => method(:join_subtitles)
+      'join' => method(:join_subtitles),
+      'transcript' => method(:transcript_subtitles)
     }
   end
 
@@ -146,11 +147,63 @@ class SubtitleProcessorCLI
     joiner.join
   end
 
+  def transcript_subtitles(args)
+    options = {
+      file: nil,
+      output: nil,
+      paragraph_gap: 1
+    }
+
+    transcript_parser = OptionParser.new do |opts|
+      opts.banner = 'Usage: subtitle_processor.rb transcript [options]'
+
+      opts.on('-f', '--file FILE', 'SRT file to convert') do |v|
+        options[:file] = v
+      end
+
+      opts.on('-o', '--output FILE', 'Output file (default: stdout)') do |v|
+        options[:output] = v
+      end
+
+      opts.on('-g', '--gap LINES', Integer, 'Newlines between paragraphs (default: 1)') do |v|
+        options[:paragraph_gap] = v
+      end
+
+      opts.on('-h', '--help', 'Show this message') do
+        puts opts
+        exit
+      end
+    end
+
+    begin
+      transcript_parser.parse!(args)
+    rescue OptionParser::InvalidOption => e
+      puts "Error: #{e.message}"
+      puts transcript_parser
+      exit
+    end
+
+    if options[:file].nil?
+      puts 'Error: Input file is required.'
+      puts transcript_parser
+      exit
+    end
+
+    transcript = Appydave::Tools::SubtitleProcessor::Transcript.new(file_path: options[:file])
+
+    if options[:output]
+      transcript.write(options[:output], paragraph_gap: options[:paragraph_gap])
+    else
+      puts transcript.extract(paragraph_gap: options[:paragraph_gap])
+    end
+  end
+
   def print_help
     puts 'Usage: subtitle_processor.rb [command] [options]'
     puts 'Commands:'
     puts '  clean          Clean and normalize SRT files'
     puts '  join           Join multiple SRT files'
+    puts '  transcript     Convert SRT to plain text transcript'
     puts "Run 'subtitle_processor.rb [command] --help' for more information on a command."
   end
 end