appydave-tools 0.15.0 → 0.16.0

data/docs/archive/purpose-and-philosophy.md

@@ -0,0 +1,110 @@
+# AppyDave Tools - Purpose & Philosophy
+
+## Overview
+
+**AppyDave Tools** is a consolidated productivity toolkit built for AppyDave's YouTube content creation workflow. All utilities live in one repository for easier maintenance compared to managing separate codebases.
+
+## Philosophy
+
+### Consolidated Toolkit
+- **One repository** - All tools in single codebase for easier management
+- **YouTube workflow focus** - Built specifically for content creator productivity
+- **Single-purpose utilities** - Each tool solves one specific problem
+- **Independent operation** - Tools work standalone, no forced dependencies
+- **Shareable individually** - Individual tools can be featured in standalone videos
+
+### AppyDave Context
+- Built for AppyDave's specific workflows and needs
+- Published publicly as part of AppyDave's knowledge sharing
+- Tools demonstrate productivity techniques for YouTube creators
+- Language-agnostic approach (currently Ruby, could be rewritten if needed)
+
+### Practical Implementation
+- Solve real workflow problems quickly
+- Iterate based on actual YouTube production usage
+- Simple, working implementations
+- Documentation reflects real content creation scenarios
+
+## Tool Categories
+
+### AI & Context Management
+- **GPT Context Gatherer** - Collect project files for AI context analysis
+- **Prompt Tools** - AI prompt completion workflows
+
+### Content & Media
+- **Subtitle Manager** - Process and join SRT subtitle files
+- **YouTube Manager** - Manage YouTube video metadata via API
+- **YouTube Automation** - Automated YouTube workflows with GPT agents
+- **Move Images** - Organize downloaded images into project folders
+
+### Configuration
+- **Configuration Tool** - Manage multi-channel and project configurations
+
+## Design Principles
+
+1. **CLI-First** - Command-line tools for speed and scriptability
+2. **Single-Purpose** - Each tool does one thing well
+3. **Independent** - No forced dependencies between tools
+4. **Documented** - Clear examples for real-world usage
+5. **Open Source** - MIT licensed for community benefit
+
+## Integration Options
+
+### Claude Code Integration
+- Future: Claude skill interface to access tools directly
+- Current: Standard CLI usage from terminal
+
+### Sharing with Other Projects
+When sharing these tools, three key paths to reference:
+1. **Project root** - `/Users/davidcruwys/dev/ad/appydave-tools/`
+2. **Tools directory** - `/Users/davidcruwys/dev/ad/appydave-tools/bin/`
+3. **Documentation** - `/Users/davidcruwys/dev/ad/appydave-tools/docs/`
+
+## Repository Strategy
+
+### Why One Codebase?
+- **Easier maintenance** - Single repo vs managing multiple separate repos
+- **Version control** - Already established with semantic-release
+- **Shared infrastructure** - Common testing, linting, CI/CD
+- **Cohesive documentation** - All tools documented together
+
+### Language Flexibility
+- Currently implemented in Ruby
+- Not tied to Ruby as identity - could be rewritten in another language
+- Implementation language is a practical choice, not a constraint
+
+## Use Cases
+
+Primary use case is **AppyDave's YouTube workflow**, including:
+- **Developers** - Gathering code context for AI assistants
+- **Content Creators** - Video subtitle management, metadata updates
+- **Automators** - Scripting repetitive YouTube tasks
+- **Multi-Channel Managers** - Managing configurations across channels
+
+## Future Direction
+
+- Add new tools as AppyDave workflow needs arise
+- Individual tools may be featured in standalone video tutorials
+- Keep tools independent and single-purpose
+- Maintain public access for community learning
+- Claude skill integration for easier access
+
+## Not Goals
+
+- ❌ Building a monolithic framework
+- ❌ Creating tool dependencies or required workflows
+- ❌ Enterprise-scale features or complexity
+- ❌ Forcing users to adopt the entire suite
+
+## Contributing
+
+Contributions welcome for:
+- Bug fixes to existing tools
+- Documentation improvements
+- New single-purpose tools that fit the workflow
+- Performance improvements
+
+Not looking for:
+- Tools that create dependencies between existing utilities
+- Framework-style architectures
+- Features that complicate simple tools

data/docs/archive/test-coverage-quick-wins.md

@@ -0,0 +1,342 @@
+# Test Coverage Quick Wins
+
+**Current Coverage:** 85.84% (1655 / 1928 lines)
+
+**Goal:** Increase to 90%+ with minimal effort
+
+---
+
+## Missing Test Files (Quick Wins)
+
+### 🎯 Priority 1: CLI Actions (0/4 specs) - HIGH IMPACT
+
+**Files without specs:**
+1. `lib/appydave/tools/cli_actions/base_action.rb` ⭐ **CRITICAL**
+2. `lib/appydave/tools/cli_actions/get_video_action.rb`
+3. `lib/appydave/tools/cli_actions/prompt_completion_action.rb`
+4. `lib/appydave/tools/cli_actions/update_video_action.rb`
+
+**Why high impact:**
+- BaseAction is a template class used by all actions
+- Testing BaseAction tests the pattern used across the codebase
+- CLI actions are user-facing entry points
+
+**Estimated effort:** 2-3 hours for all 4
+
+**RSpec convention adherence:**
+- ✅ Template Method Pattern - Already established in codebase
+- ✅ Use `described_class` for class under test
+- ✅ Group by method with `describe '#method_name'`
+- ✅ Use `context` for different scenarios
+- ✅ No `require` statements (handled by spec_helper)
+
+**Example test structure for BaseAction:**
+
+```ruby
+# spec/appydave/tools/cli_actions/base_action_spec.rb
+# frozen_string_literal: true
+
+RSpec.describe Appydave::Tools::CliActions::BaseAction do
+  # Create concrete test class since BaseAction is abstract
+  let(:test_action_class) do
+    Class.new(described_class) do
+      protected
+
+      def define_options(opts, options)
+        opts.on('-t', '--test VALUE', 'Test option') { |v| options[:test] = v }
+      end
+
+      def validate_options(options)
+        raise ArgumentError, 'Test option required' unless options[:test]
+      end
+
+      def execute(options)
+        "Executed with: #{options[:test]}"
+      end
+    end
+  end
+
+  let(:test_action) { test_action_class.new }
+
+  describe '#action' do
+    context 'with valid options' do
+      it 'executes successfully' do
+        expect { test_action.action(['-t', 'value']) }.not_to raise_error
+      end
+    end
+
+    context 'with missing required options' do
+      it 'raises ArgumentError' do
+        expect { test_action.action([]) }.to raise_error(ArgumentError, 'Test option required')
+      end
+    end
+
+    context 'with help flag' do
+      it 'displays help and exits' do
+        expect { test_action.action(['-h']) }.to raise_error(SystemExit)
+      end
+    end
+  end
+
+  describe 'template method pattern' do
+    it 'calls define_options during initialization' do
+      # Test that subclass hook is called
+    end
+
+    it 'calls validate_options before execute' do
+      # Test validation happens
+    end
+
+    it 'calls execute with parsed options' do
+      # Test execution happens
+    end
+  end
+end
+```
+
+---
+
+### 🎯 Priority 2: GPT Context Options (1 file) - MEDIUM IMPACT
+
+**File without spec:**
+- `lib/appydave/tools/gpt_context/options.rb`
+
+**Why medium impact:**
+- Already have specs for FileCollector and OutputHandler
+- Options class is smaller, focused
+- Completes the gpt_context module coverage
+
+**Estimated effort:** 30-45 minutes
+
+**Test structure:**
+
+```ruby
+# spec/appydave/tools/gpt_context/options_spec.rb
+# frozen_string_literal: true
+
+RSpec.describe Appydave::Tools::GptContext::Options do
+  describe '#initialize' do
+    context 'with default options' do
+      it 'sets default values' do
+        options = described_class.new([])
+        expect(options.include_patterns).to be_empty
+        expect(options.exclude_patterns).to be_empty
+      end
+    end
+
+    context 'with include patterns' do
+      it 'parses multiple -i flags' do
+        options = described_class.new(['-i', '*.rb', '-i', '*.md'])
+        expect(options.include_patterns).to eq(['*.rb', '*.md'])
+      end
+    end
+
+    context 'with exclude patterns' do
+      it 'parses -e flags' do
+        options = described_class.new(['-e', 'spec/**/*'])
+        expect(options.exclude_patterns).to eq(['spec/**/*'])
+      end
+    end
+
+    context 'with format option' do
+      it 'parses format flag' do
+        options = described_class.new(['-f', 'tree'])
+        expect(options.format).to eq('tree')
+      end
+    end
+
+    context 'with output file' do
+      it 'parses output flag' do
+        options = described_class.new(['-o', 'output.txt'])
+        expect(options.output_file).to eq('output.txt')
+      end
+    end
+
+    context 'with line limit' do
+      it 'parses line limit flag' do
+        options = described_class.new(['-l', '100'])
+        expect(options.line_limit).to eq(100)
+      end
+    end
+  end
+
+  describe '#valid?' do
+    context 'with no include patterns' do
+      it 'returns false' do
+        options = described_class.new([])
+        expect(options.valid?).to be false
+      end
+    end
+
+    context 'with include patterns' do
+      it 'returns true' do
+        options = described_class.new(['-i', '*.rb'])
+        expect(options.valid?).to be true
+      end
+    end
+  end
+end
+```
+
+---
+
+### 🎯 Priority 3: Root-level Files (2 files) - LOW IMPACT
+
+**Files without specs:**
+- `lib/appydave/tools/debuggable.rb` - Likely a simple module
+- `lib/appydave/tools/version.rb` - Auto-generated version file
+
+**Why low impact:**
+- Version file is auto-generated (should not be tested)
+- Debuggable is likely a simple concern/module
+
+**Estimated effort:** 15-30 minutes (only test debuggable)
+
+**Skip version.rb** - It's auto-generated by semantic-release
+
+---
+
+## RSpec Conventions to Follow
+
+Based on existing specs in the codebase:
+
+### ✅ DO:
+1. **Use `described_class`** instead of explicit class name
+2. **Group by method** with `describe '#method_name'` (instance) or `describe '.method_name'` (class)
+3. **Use `context` for scenarios** - "with valid input", "when error occurs"
+4. **Use `let` for test data** - lazy evaluation, cleaner setup
+5. **Freeze string literals** - `# frozen_string_literal: true` at top
+6. **No require statements** - spec_helper handles all requires
+7. **Use RSpec matchers** - `expect(...).to eq(...)`, not `should`
+8. **Test behavior, not implementation** - Focus on public API
+
+### ❌ DON'T:
+1. **Don't use `should` syntax** - Use `expect` instead
+2. **Don't manually require files** - spec_helper does this
+3. **Don't test private methods directly** - Test through public API
+4. **Don't duplicate setup** - Use `let`, `let!`, `before` blocks
+5. **Don't write brittle tests** - Avoid testing internal state unless necessary
+
+---
+
+## Example from Existing Codebase
+
+**Good example:** `spec/appydave/tools/subtitle_processor/clean_spec.rb`
+
+```ruby
+RSpec.describe Appydave::Tools::SubtitleProcessor::Clean do
+  let(:file_path) { File.expand_path('../../../fixtures/subtitle_processor/test.srt', __dir__) }
+  let(:simple_content) do
+    <<~SRT
+      1
+      00:00:00,060 --> 00:00:01,760
+      <u>The</u> quick
+    SRT
+  end
+
+  describe '#initialize' do
+    it 'initializes with file_path' do
+      expect { described_class.new(file_path: file_path) }.not_to raise_error
+    end
+
+    it 'raises error when both file_path and srt_content are provided' do
+      expect { described_class.new(file_path: file_path, srt_content: simple_content) }
+        .to raise_error(ArgumentError, 'You cannot provide both a file path and an SRT content stream.')
+    end
+  end
+
+  describe '#clean' do
+    context 'when initialized with file_path' do
+      let(:cleaner) { described_class.new(file_path: file_path) }
+
+      it 'normalizes the subtitles correctly' do
+        cleaned_content = cleaner.clean
+        expect(cleaned_content.strip.encode('UTF-8')).to eq(expected_content.strip.encode('UTF-8'))
+      end
+    end
+  end
+end
+```
+
+**Why this is good:**
+- ✅ Uses `described_class`
+- ✅ Groups by method
+- ✅ Uses `context` for scenarios
+- ✅ Uses `let` for test data
+- ✅ Frozen string literal
+- ✅ No requires
+- ✅ Tests behavior (clean works) not implementation
+
+---
+
+## Implementation Plan
+
+### Step 1: BaseAction (Highest Priority)
+```bash
+# Create spec file
+touch spec/appydave/tools/cli_actions/base_action_spec.rb
+
+# Run tests for just this file
+bundle exec rspec spec/appydave/tools/cli_actions/base_action_spec.rb
+```
+
+### Step 2: CLI Action Subclasses
+```bash
+# Create spec files
+touch spec/appydave/tools/cli_actions/get_video_action_spec.rb
+touch spec/appydave/tools/cli_actions/update_video_action_spec.rb
+touch spec/appydave/tools/cli_actions/prompt_completion_action_spec.rb
+
+# Run tests
+bundle exec rspec spec/appydave/tools/cli_actions/
+```
+
+### Step 3: GPT Context Options
+```bash
+# Create spec file
+touch spec/appydave/tools/gpt_context/options_spec.rb
+
+# Run tests
+bundle exec rspec spec/appydave/tools/gpt_context/
+```
+
+### Step 4: Verify Coverage
+```bash
+# Run full suite
+bundle exec rspec
+
+# Check new coverage (should be 90%+)
+cat coverage/.last_run.json
+```
+
+---
+
+## Estimated Impact
+
+**Current:** 85.84% (1655 / 1928 lines)
+
+**After Priority 1 (CLI Actions):**
+- Estimated lines in cli_actions: ~150 lines
+- Assuming 80% test coverage of those lines: +120 lines
+- New total: ~1775 / 1928 = **92.1%**
+
+**After Priority 2 (Options):**
+- Estimated lines in options.rb: ~50 lines
+- Assuming 80% coverage: +40 lines
+- New total: ~1815 / 1928 = **94.1%**
+
+**Target: 94% coverage with ~4-5 hours of effort**
+
+---
+
+## Notes
+
+- **BaseAction is abstract** - Test via concrete subclass or test doubles
+- **Integration vs unit** - CLI actions may need integration-style tests (harder to unit test)
+- **VCR cassettes** - YouTube actions may need VCR for API mocking (already in use)
+- **Don't test version.rb** - It's auto-generated
+- **Focus on public API** - Don't test private methods directly
+
+---
+
+**Recommendation:** Start with BaseAction spec - it will establish the pattern for all other CLI action specs and provide the biggest coverage boost.

data/docs/archive/tool-discovery.md

@@ -0,0 +1,199 @@
+# AI Agent Tool Discovery Guide
+
+**Purpose:** Help AI agents quickly identify the right tool for user requests
+
+---
+
+## Quick Task Reference
+
+| User Says... | Use This Tool | Example Command |
+|--------------|---------------|-----------------|
+| "Feed my codebase to ChatGPT/Claude" | **GPT Context Gatherer** | `gpt_context -i '**/*.rb' -d` |
+| "Clean messy YouTube auto-captions" | **Subtitle Processor** | `subtitle_processor clean -f input.srt` |
+| "Merge subtitle files from multi-part recording" | **Subtitle Processor** | `subtitle_processor join -d ./parts` |
+| "Update 50 video titles" | **YouTube Manager** | `youtube_manager update --video-id ID --title "New"` |
+| "Get video metadata for backup" | **YouTube Manager** | `youtube_manager get --video-id ID` |
+| "Organize downloaded images into video project" | **Move Images** | `bin/move_images.rb -f b40 intro b40` |
+| "Setup tool configuration" | **Configuration** | `ad_config -c` |
+| "Edit channel configurations" | **Configuration** | `ad_config -e` |
+
+---
+
+## Problem → Tool Mapping
+
+### "I have subtitle problems"
+- **One messy SRT file** → `subtitle_processor clean`
+  - Removes HTML tags, merges duplicates, normalizes spacing
+- **Multiple SRT files to merge** → `subtitle_processor join`
+  - Adjusts timestamps, synchronizes timeline, handles buffers
+- **Upload/download YouTube captions** → `youtube_manager` (not subtitle_processor)
+
+### "I need to work with YouTube videos"
+- **Metadata operations (CRUD)** → `youtube_manager`
+  - Get, update title/description/tags/category
+- **Bulk updates across videos** → `youtube_manager` (loop through video IDs)
+- **Automation workflows** → `youtube_automation` (internal use, deprecated API)
+
+### "I need AI assistance"
+- **Feed codebase to AI** → `gpt_context` ⭐ PRIMARY USE CASE
+- **Template-based prompts** → `prompt_tools` (deprecated API, not recommended)
+- **Workflow automation** → `youtube_automation` (internal use)
+
+### "I need configuration"
+- **Setup tools** → `ad_config -c` (creates templates)
+- **Multi-channel management** → `ad_config -e` (edit channels.json)
+- **Team collaboration** → Share JSON configs via Git/Dropbox
+
+---
+
+## Tool Disambiguation
+
+### "subtitle_processor" vs "youtube_manager"
+- **subtitle_processor**: Transforms local SRT files (clean/merge/process)
+- **youtube_manager**: CRUD operations on YouTube video metadata via API
+- **Different purposes**: One is file processor, one is API manager
+
+### "prompt_tools" vs "youtube_automation"
+- **prompt_tools**: Single OpenAI Completion API call with template support
+- **youtube_automation**: Sequence runner executing multiple prompts
+- **Both use deprecated API**: Neither recommended for new work
+
+### "gpt_context" vs "prompt_tools"
+- **gpt_context**: Collects project files for AI context (no API calls)
+- **prompt_tools**: Executes OpenAI API calls with prompts
+- **Use gpt_context for**: Feeding code to Claude/ChatGPT
+- **Use prompt_tools for**: Automated API-based completions (if migrated to Chat API)
+
+---
+
+## Scenario-Based Discovery
+
+### Scenario: FliVideo Multi-Part Recording Workflow
+```
+1. Record video in 5 parts → 5 video files + 5 SRT subtitle files
+2. Generate subtitles → YouTube auto-captions (messy)
+3. Clean each subtitle → subtitle_processor clean
+4. Merge subtitle parts → subtitle_processor join
+5. Upload video → (external tool)
+6. Update metadata → youtube_manager
+7. Organize B-roll images → move_images
+```
+
+### Scenario: Post-Rebrand Bulk Video Updates
+```
+1. Changed channel name → Need to update 50 video descriptions
+2. Export video list → youtube_manager get (or YouTube Studio)
+3. Loop through videos → youtube_manager update --video-id ID --description "New"
+4. Verify changes → youtube_manager get
+```
+
+### Scenario: AI-Assisted Code Development
+```
+1. Need AI help with codebase → gpt_context
+2. Gather Ruby files → gpt_context -i '**/*.rb' -e 'spec/**/*' -d
+3. Feed to Claude/ChatGPT → Paste from clipboard or read file
+4. Iterate with AI → Re-run gpt_context as codebase changes
+```
+
+---
+
+## Tool Entry Points by User Type
+
+### 👨‍💻 Developer Using AI Assistants
+**Primary tool:** GPT Context Gatherer ⭐
+**Workflow:** Collect codebase → Feed to AI → Get help with development
+
+### 🎥 YouTuber with Multi-Part Recordings (FliVideo workflow)
+**Primary tools:** Subtitle Processor → YouTube Manager
+**Workflow:** Clean captions → Merge parts → Upload → Update metadata
+
+### 📹 YouTuber Managing Multiple Channels
+**Primary tools:** Configuration Manager → YouTube Manager
+**Workflow:** Setup channels.json → Switch contexts → Bulk update videos
+
+### ⚙️ Tool Administrator
+**Primary tool:** Configuration Manager
+**Workflow:** Create templates → Setup team configs → Share via Git/Dropbox
+
+---
+
+## Tool Relationships & Dependencies
+
+### Independent Tools (No Dependencies)
+- **gpt_context**: Standalone file collector
+- **subtitle_processor**: Standalone SRT file processor
+- **move_images**: Standalone image organizer
+
+### Configuration-Dependent Tools
+- **youtube_manager**: Needs channels.json (optional, for multi-channel)
+- **youtube_automation**: Requires youtube_automation.json + Dropbox paths
+- **prompt_tools**: No config needed (just OpenAI API key)
+
+### Workflow Sequences
+```
+Configuration Setup First:
+ad_config -c → Edit configs → Use other tools
+
+FliVideo Production:
+subtitle_processor clean → subtitle_processor join → youtube_manager
+
+Context Engineering:
+gpt_context → Feed to AI → Develop → Repeat
+```
+
+---
+
+## Active vs Deprecated Tools
+
+### ✅ ACTIVE TOOLS (Use these)
+1. **GPT Context Gatherer** ⭐ - Primary use case
+2. **YouTube Manager** - CRUD operations on videos
+3. **Subtitle Processor** - SRT file transformation
+4. **Configuration Manager** - JSON config management
+5. **Move Images** - Video asset organization
+
+### ⚠️ DEPRECATED API (Avoid for new work)
+6. **Prompt Tools** - Uses deprecated OpenAI Completion API
+7. **YouTube Automation** - Internal use only, deprecated API, hardcoded paths
+
+---
+
+## Common Pitfalls & Troubleshooting
+
+### "I can't find subtitle_manager"
+→ Renamed to `subtitle_processor` (more accurate naming)
+
+### "Bundler version mismatch"
+→ Run: `eval "$(rbenv init -)" && gem install bundler:2.6.2`
+
+### "YouTube Manager not authenticating"
+→ Check `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` in `.env`
+
+### "Move Images not working"
+→ Check hardcoded paths in bin/move_images.rb (development tool, may need customization)
+
+### "GPT Context output too large"
+→ Use `-e` to exclude node_modules, .git, spec directories
+
+---
+
+## Keywords for Discovery
+
+**GPT Context Gatherer:**
+- Keywords: AI, context, codebase, ChatGPT, Claude, feed code, token limit, files, patterns
+
+**YouTube Manager:**
+- Keywords: video metadata, title, description, tags, category, bulk update, YouTube API, CRUD
+
+**Subtitle Processor:**
+- Keywords: SRT, subtitle, captions, clean, merge, join, multi-part, FliVideo, timeline
+
+**Configuration:**
+- Keywords: settings, channels, multi-channel, team collaboration, JSON config, paths
+
+**Move Images:**
+- Keywords: video assets, B-roll, images, organize, download folder, project structure
+
+---
+
+**Last Updated:** January 2025