appydave-tools 0.15.0 → 0.16.0

data/bin/subtitle_manager.rb

@@ -7,8 +7,8 @@ $LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
 
 require 'appydave/tools'
 
-# Process command line arguments for SubtitleMaster operations
-class SubtitleMasterCLI
+# Process command line arguments for SubtitleProcessor operations
+class SubtitleProcessorCLI
   def initialize
     @commands = {
       'clean' => method(:clean_subtitles),
@@ -39,7 +39,7 @@ class SubtitleMasterCLI
 
     # Command-specific option parser
     clean_parser = OptionParser.new do |opts|
-      opts.banner = 'Usage: subtitle_manager.rb clean [options]'
+      opts.banner = 'Usage: subtitle_processor.rb clean [options]'
 
       opts.on('-f', '--file FILE', 'SRT file to process') do |v|
         options[:file] = v
@@ -70,8 +70,8 @@ class SubtitleMasterCLI
       exit
     end
 
-    # Assuming `Appydave::Tools::SubtitleMaster::Clean` exists
-    cleaner = Appydave::Tools::SubtitleMaster::Clean.new(file_path: options[:file])
+    # Assuming `Appydave::Tools::SubtitleProcessor::Clean` exists
+    cleaner = Appydave::Tools::SubtitleProcessor::Clean.new(file_path: options[:file])
     cleaner.clean
     cleaner.write(options[:output])
   end
@@ -87,7 +87,7 @@ class SubtitleMasterCLI
     }
 
     join_parser = OptionParser.new do |opts|
-      opts.banner = 'Usage: subtitle_manager.rb join [options]'
+      opts.banner = 'Usage: subtitle_processor.rb join [options]'
 
       opts.on('-d', '--directory DIR', 'Directory containing SRT files (default: current directory)') do |v|
         options[:folder] = v
@@ -134,19 +134,25 @@ class SubtitleMasterCLI
       exit
     end
 
-    # Assuming `Appydave::Tools::SubtitleMaster::Join` exists
-    joiner = Appydave::Tools::SubtitleMaster::Join.new(folder: options[:folder], files: options[:files], sort: options[:sort], buffer: options[:buffer], output: options[:output],
-                                                       log_level: options[:log_level])
+    # Assuming `Appydave::Tools::SubtitleProcessor::Join` exists
+    joiner = Appydave::Tools::SubtitleProcessor::Join.new(
+      folder: options[:folder],
+      files: options[:files],
+      sort: options[:sort],
+      buffer: options[:buffer],
+      output: options[:output],
+      log_level: options[:log_level]
+    )
     joiner.join
   end
 
   def print_help
-    puts 'Usage: subtitle_manager.rb [command] [options]'
+    puts 'Usage: subtitle_processor.rb [command] [options]'
     puts 'Commands:'
     puts '  clean          Clean and normalize SRT files'
     puts '  join           Join multiple SRT files'
-    puts "Run 'subtitle_manager.rb [command] --help' for more information on a command."
+    puts "Run 'subtitle_processor.rb [command] --help' for more information on a command."
   end
 end
 
-SubtitleMasterCLI.new.run
+SubtitleProcessorCLI.new.run

data/bin/subtitle_processor.rb

@@ -0,0 +1,158 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'optparse'
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'appydave/tools'
+
+# Process command line arguments for SubtitleProcessor operations
+class SubtitleProcessorCLI
+  def initialize
+    @commands = {
+      'clean' => method(:clean_subtitles),
+      'join' => method(:join_subtitles)
+    }
+  end
+
+  def run
+    command, *args = ARGV
+    if command.nil?
+      puts 'No command provided. Use -h for help.'
+      print_help
+      exit
+    end
+
+    if @commands.key?(command)
+      @commands[command].call(args)
+    else
+      puts "Unknown command: #{command}"
+      print_help
+    end
+  end
+
+  private
+
+  def clean_subtitles(args)
+    options = { file: nil, output: nil }
+
+    # Command-specific option parser
+    clean_parser = OptionParser.new do |opts|
+      opts.banner = 'Usage: subtitle_processor.rb clean [options]'
+
+      opts.on('-f', '--file FILE', 'SRT file to process') do |v|
+        options[:file] = v
+      end
+
+      opts.on('-o', '--output FILE', 'Output file') do |v|
+        options[:output] = v
+      end
+
+      opts.on('-h', '--help', 'Show this message') do
+        puts opts
+        exit
+      end
+    end
+
+    begin
+      clean_parser.parse!(args)
+    rescue OptionParser::InvalidOption => e
+      puts "Error: #{e.message}"
+      puts clean_parser
+      exit
+    end
+
+    # Validate required options
+    if options[:file].nil? || options[:output].nil?
+      puts 'Error: Missing required options.'
+      puts clean_parser
+      exit
+    end
+
+    # Assuming `Appydave::Tools::SubtitleProcessor::Clean` exists
+    cleaner = Appydave::Tools::SubtitleProcessor::Clean.new(file_path: options[:file])
+    cleaner.clean
+    cleaner.write(options[:output])
+  end
+
+  def join_subtitles(args)
+    options = {
+      folder: './',
+      files: '*.srt',
+      sort: 'inferred',
+      buffer: 100,
+      output: 'merged.srt',
+      verbose: false
+    }
+
+    join_parser = OptionParser.new do |opts|
+      opts.banner = 'Usage: subtitle_processor.rb join [options]'
+
+      opts.on('-d', '--directory DIR', 'Directory containing SRT files (default: current directory)') do |v|
+        options[:folder] = v
+      end
+
+      opts.on('-f', '--files PATTERN', 'File pattern (e.g., "*.srt" or "part1.srt,part2.srt")') do |v|
+        options[:files] = v
+      end
+
+      opts.on('-s', '--sort ORDER', %w[asc desc inferred], 'Sort order (asc/desc/inferred)') do |v|
+        options[:sort] = v
+      end
+
+      opts.on('-b', '--buffer MS', Integer, 'Buffer between merged files in milliseconds') do |v|
+        options[:buffer] = v
+      end
+
+      opts.on('-o', '--output FILE', 'Output file') do |v|
+        options[:output] = v
+      end
+
+      opts.on('-L', '--log-level LEVEL', %w[none info detail], 'Log level (default: info)') do |v|
+        options[:log_level] = v.to_sym
+      end
+
+      opts.on('-h', '--help', 'Show this message') do
+        puts opts
+        exit
+      end
+    end
+
+    begin
+      join_parser.parse!(args)
+    rescue OptionParser::InvalidOption => e
+      puts "Error: #{e.message}"
+      puts join_parser
+      exit
+    end
+
+    # Validate required options
+    if options[:folder].nil? || options[:files].nil? || options[:output].nil?
+      puts 'Error: Missing required options.'
+      puts join_parser
+      exit
+    end
+
+    # Assuming `Appydave::Tools::SubtitleProcessor::Join` exists
+    joiner = Appydave::Tools::SubtitleProcessor::Join.new(
+      folder: options[:folder],
+      files: options[:files],
+      sort: options[:sort],
+      buffer: options[:buffer],
+      output: options[:output],
+      log_level: options[:log_level]
+    )
+    joiner.join
+  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 "Run 'subtitle_processor.rb [command] --help' for more information on a command."
+  end
+end
+
+SubtitleProcessorCLI.new.run

data/docs/archive/codebase-audit-2025-01.md

@@ -0,0 +1,424 @@
+# AppyDave Tools - Codebase Audit
+
+**Date:** January 2025
+**Auditor:** Claude Code
+**Scope:** Complete codebase review for consistency, patterns, and quality
+
+---
+
+## Executive Summary
+
+**Overall Assessment: GOOD - Sound and Consistent Codebase** ✅
+
+The codebase demonstrates solid engineering practices with consistent patterns, good test coverage, and clear organization. While there are opportunities for improvement, no critical issues were found that would impede functionality or maintenance.
+
+**Key Metrics:**
+- **Total Code:** 2,946 lines (lib/)
+- **Total Tests:** 2,483 lines (spec/)
+- **Test Ratio:** 0.84 (84% as much test code as production code)
+- **Frozen String Literal:** 40/42 files (95%)
+- **Ruby Files:** 42 production, 33 test files
+- **RuboCop Config:** Comprehensive, well-configured
+
+---
+
+## 1. Project Structure & Organization
+
+### ✅ Strengths
+
+**Well-Organized Directory Structure:**
+```
+lib/appydave/tools/
+├── cli_actions/           # CLI command handlers
+├── configuration/         # Config management with models
+├── gpt_context/          # GPT context gathering
+├── youtube_manager/      # YouTube API integration
+├── youtube_automation/   # Automation workflows
+├── subtitle_manager/     # SRT file processing
+├── prompt_tools/         # AI prompt tools
+├── llm/                  # LLM integration
+├── types/                # Type system (BaseModel, HashType, etc.)
+├── name_manager/         # Project naming
+└── deprecated/           # Properly segregated old code
+```
+
+**Clear Separation of Concerns:**
+- CLI actions separate from business logic
+- Models properly separated in `/models` subdirectories
+- Reports in dedicated `/reports` folders
+- Deprecated code isolated and marked
+
+**Main Entry Point:**
+- `/lib/appydave/tools.rb` - Clean, well-organized require statements
+- Proper module namespacing (`Appydave::Tools`)
+- Configuration setup on load
+
+### ⚠️ Issues Found
+
+1. **Unexpected Directory: `lib/mj-paste-test/`**
+   - Contains unrelated code (main.rb, prompts.txt, readme-leonardo.md)
+   - Non-standard naming (`mj-paste-test` instead of snake_case)
+   - Appears to be experimental/test code that should be removed or moved
+
+2. **Inconsistent Module Naming:**
+   - `subtitle_manager/` contains `SubtitleMaster` class (should be `SubtitleManager`)
+   - Bin script is `subtitle_manager.rb` but internal module is `SubtitleMaster`
+
+---
+
+## 2. Ruby Coding Conventions
+
+### ✅ Strengths
+
+**Frozen String Literal Compliance:** 95% (40/42 files)
+```ruby
+# frozen_string_literal: true  # ✅ Found in 95% of files
+```
+
+**Consistent Code Style:**
+- Proper module nesting
+- Clear class/method documentation
+- Good use of private methods
+- Template method pattern in BaseAction
+
+**RuboCop Configuration:**
+- Comprehensive `.rubocop.yml`
+- Excludes deprecated code properly
+- Sensible metric thresholds
+- RSpec and Rake plugins configured
+
+### ⚠️ Issues Found
+
+1. **Debug Output (puts) in Production Code:**
+   - Found in 25 files with ~30+ puts statements
+   - Examples:
+     - `file_collector.rb:15` - `puts @working_directory`
+     - `youtube_automation/gpt_agent.rb` - Multiple debug puts
+     - `configuration/config.rb:56` - `puts "Edit configuration..."`
+
+   **Impact:** Low (mostly in CLI tools where output is expected)
+   **Recommendation:** Replace with proper logging (KLog already available)
+
+2. **Commented Code:**
+   - `youtube_manager/get_video.rb` - Commented caption code
+   - `configuration/config.rb` - Commented print method
+   - Main `tools.rb:70` - Commented bank_reconciliation config
+
+   **Recommendation:** Remove dead code or add TODO comments
+
+3. **Method Missing Usage:**
+   - `Configuration::Config` uses `method_missing` for dynamic configuration access
+   - Has `respond_to_missing?` (good)
+   - **Acceptable pattern** for DSL-style configuration
+
+---
+
+## 3. Anti-Patterns & Code Smells
+
+### ✅ No Major Anti-Patterns Found
+
+**Good Patterns Observed:**
+- Template Method Pattern (BaseAction)
+- Strategy Pattern (OutputHandler formats)
+- Factory Pattern (Configuration registration)
+- Proper inheritance hierarchies
+
+### ⚠️ Minor Code Smells
+
+1. **Large RuboCop Exclusions:**
+```yaml
+Metrics/AbcSize:
+  Exclude:
+    - "lib/appydave/**/*.rb"  # Excludes ALL appydave code!
+```
+   - Entire `lib/appydave/**/*.rb` excluded from complexity metrics
+   - Makes metrics cops ineffective for the codebase
+   - **Recommendation:** Remove blanket exclusions, fix specific files
+
+2. **Empty Else Clauses:**
+   - Some conditional logic has implicit nil returns
+   - Not necessarily bad, but could be more explicit
+
+3. **Tight Coupling to CLI:**
+   - Many tools use `puts` directly instead of injected output handler
+   - Makes testing harder
+   - **Recommendation:** Consider output abstraction layer
+
+---
+
+## 4. Test Coverage & Testing Patterns
+
+### ✅ Strengths
+
+**Good Test Ratio:** 0.84 (2,483 test lines / 2,946 code lines)
+
+**Test Organization:**
+- Mirrors lib/ structure well
+- Uses RSpec properly
+- VCR for API mocking
+- SimpleCov for coverage
+
+**Test File Examples:**
+```
+spec/appydave/tools/
+├── subtitle_master/
+│   ├── clean_spec.rb
+│   ├── join_spec.rb
+│   └── join/              # Sub-component specs
+├── configuration/
+│   ├── config_spec.rb
+│   └── models/
+```
+
+**RSpec Configuration:**
+- Max 25 line example length
+- Up to 8 nested groups
+- Multiple expectations allowed
+
+### ⚠️ Gaps
+
+1. **No Dedicated Spec for BaseAction:**
+   - Template class not directly tested
+   - Tested through subclasses (acceptable but not ideal)
+
+2. **Missing Deprecation Tests:**
+   - Bank reconciliation code not tested (acceptable since deprecated)
+
+3. **No Integration Tests Visible:**
+   - All tests appear to be unit tests
+   - No end-to-end CLI tests found
+
+---
+
+## 5. Configuration & Dependency Management
+
+### ✅ Strengths
+
+**Clean Gemspec:**
+- Proper metadata
+- Semantic release configured
+- MIT licensed
+- Clear dependencies
+
+**Key Dependencies:**
+```ruby
+google-api-client  # YouTube API
+ruby-openai       # OpenAI integration
+activemodel       # Validation
+clipboard         # System clipboard
+k_log            # Logging
+```
+
+**Configuration System:**
+- JSON-based config files
+- `~/.config/appydave` default path
+- Registrable config models
+- Environment variable support (dotenv)
+
+### ⚠️ Issues
+
+1. **Pry in Production:**
+```ruby
+# lib/appydave/tools.rb:19
+require 'pry'
+```
+   - Pry should be development/test only
+   - **Recommendation:** Move to Gemfile development group
+
+2. **Missing exe/ Directory:**
+   - Gemspec references `exe/` for executables
+   - Directory was recently created but may need verification
+   - All tools currently in `bin/`
+
+3. **Commented Configuration:**
+```ruby
+# config.register(:bank_reconciliation, ...)
+```
+   - Dead configuration registration
+   - Should be removed
+
+---
+
+## 6. Error Handling & Edge Cases
+
+### ✅ Strengths
+
+**Custom Error Class:**
+```ruby
+Appydave::Tools::Error = Class.new(StandardError)
+```
+
+**File Handling:**
+- Proper permission error handling in subtitle_manager
+- FileUtils used correctly
+- Path expansion with File.expand_path
+
+**API Error Handling:**
+- YouTube API errors caught
+- OpenAI errors caught
+- User-friendly error messages
+
+### ⚠️ Gaps
+
+1. **Inconsistent Error Messages:**
+   - Some use `puts "Error: ..."`
+   - Some use logger
+   - Some raise exceptions
+   - **Recommendation:** Standardize error handling
+
+2. **No Validation in Some Actions:**
+   - BaseAction has validation template but some subclasses leave it empty
+   - Could lead to nil errors
+
+3. **File Existence Checks Missing:**
+   - Some file operations don't check File.exist? first
+   - Could raise confusing errors
+
+---
+
+## 7. Specific File Issues
+
+### Critical Issues: NONE ✅
+
+### High Priority Issues:
+
+1. **lib/mj-paste-test/** - Unrelated experimental code
+   - **Action:** Remove or move to separate experiment repo
+   - **Impact:** Confusing for contributors, unnecessary in gem
+
+2. **Blanket RuboCop Exclusions**
+   - **Action:** Remove `lib/appydave/**/*.rb` from complexity cops
+   - **Impact:** Metrics become meaningless
+
+### Medium Priority Issues:
+
+3. **Debug puts Statements**
+   - **Action:** Replace with KLog or remove
+   - **Impact:** Production code has debug output
+
+4. **Module Naming Mismatch (SubtitleMaster vs subtitle_manager)**
+   - **Action:** Rename class to match directory
+   - **Impact:** Confusing for new developers
+
+5. **Pry in Production Dependencies**
+   - **Action:** Move to development group in Gemfile
+   - **Impact:** Unnecessary production dependency
+
+### Low Priority Issues:
+
+6. **Commented Code**
+   - **Action:** Remove or add TODO with context
+   - **Impact:** Code noise
+
+7. **Missing Integration Tests**
+   - **Action:** Add CLI integration tests
+   - **Impact:** Harder to catch CLI-level bugs
+
+---
+
+## 8. Security Considerations
+
+### ✅ Strengths
+
+**Secret Management:**
+- Uses dotenv for API keys
+- `.env` in `.gitignore`
+- Bank reconciliation data in deprecated/ and gitignored
+
+**Git Hooks:**
+- Pre-commit hooks for debug code
+- **NEW:** Gitleaks integration added
+- Blocks binding.pry, byebug, debugger
+
+**File Permissions:**
+- Proper permission error handling
+- No hardcoded paths to sensitive locations
+
+### ⚠️ Concerns
+
+1. **No Input Sanitization Visible:**
+   - File paths from user input not sanitized
+   - Could allow path traversal
+   - **Recommendation:** Add path validation
+
+2. **API Keys in Config Files:**
+   - YouTube OAuth tokens stored in `~/.config/appydave`
+   - Proper location but should document permissions
+
+---
+
+## 9. Documentation Quality
+
+### ✅ Strengths
+
+**Good Documentation Files:**
+- `docs/purpose-and-philosophy.md` - Excellent
+- `docs/usage/gpt-context.md` - Comprehensive
+- `CLAUDE.md` - Detailed for AI assistance
+- `README.md` - Recently updated, engaging
+
+**Code Comments:**
+- Classes have descriptive comments
+- Complex logic explained
+- No TODO/FIXME spam (0 found)
+
+### ⚠️ Gaps
+
+1. **Missing API Documentation:**
+   - No YARD or RDoc generation
+   - Public API not formally documented
+
+2. **No Architecture Diagram:**
+   - Complex system with many moving parts
+   - Would benefit from visual overview
+
+---
+
+## 10. Recommendations Summary
+
+### Immediate Actions (Do Now):
+
+1. ✅ **Remove `lib/mj-paste-test/`** - Unrelated code
+2. ✅ **Move Pry to development dependencies**
+3. ✅ **Remove commented code** in tools.rb and config.rb
+
+### Short Term (Next Sprint):
+
+4. **Replace puts with KLog** in production code
+5. **Remove blanket RuboCop exclusions** - Fix specific files instead
+6. **Rename SubtitleMaster → SubtitleManager** for consistency
+7. **Add input path sanitization** for security
+
+### Long Term (Nice to Have):
+
+8. **Add CLI integration tests**
+9. **Generate API documentation** (YARD)
+10. **Create architecture diagram**
+11. **Standardize error handling** patterns
+
+---
+
+## Conclusion
+
+**The AppyDave Tools codebase is SOUND and CONSISTENT.** ✅
+
+**Strengths:**
+- Well-organized structure
+- Good test coverage (84%)
+- Consistent coding style
+- Proper use of Ruby idioms
+- Clean separation of concerns
+
+**Weaknesses:**
+- Debug output in production code (minor)
+- Blanket RuboCop exclusions (reduces effectiveness)
+- Experimental code in lib/ (cleanup needed)
+- Missing some edge case handling
+
+**Overall Grade: B+ (Good)**
+
+The codebase demonstrates solid engineering practices and is well-maintained. The identified issues are minor and easily addressable. No critical flaws or anti-patterns that would impede development or require major refactoring.
+
+---
+
+**Audit Complete** ✅