appydave-tools 0.14.1 → 0.16.0

data/README.md

@@ -1,157 +1,333 @@
-# Appydave Tools
+# AppyDave Tools
 
-> AppyDave YouTube Automation Tools
+> **AppyDave's YouTube productivity toolkit** - Command-line utilities that automate the boring stuff so you can focus on creating content.
+
+## Why This Exists
+
+As a YouTuber, I got tired of repetitive tasks eating into my creative time. So I built tools to handle them.
+
+Instead of managing dozens of separate repositories, everything lives here - one codebase, easier maintenance, and each tool can be featured in its own video tutorial.
+
+**Quick wins:**
+- 🤖 Feed entire codebases to AI assistants in seconds
+- 📹 Batch update YouTube video metadata without clicking through the UI (update 50 videos in 5 minutes)
+- 📝 Process subtitle files - clean formatting, merge multi-part recordings, synchronize timelines
+- 🖼️ Organize downloaded images into project folders automatically (video asset workflow)
+- ⚙️ Manage multi-channel configurations from the command line (team-shareable JSON configs)
 
 ## Installation
 
-Add this line to your application's Gemfile:
+```bash
+gem install appydave-tools
+```
+
+Or add to your Gemfile:
 
 ```ruby
 gem 'appydave-tools'
 ```
 
-And then execute:
+## The Tools
+
+### 🤖 GPT Context Gatherer
+
+**The problem:** AI assistants need context about your code, but copying files is tedious.
+
+**The solution:** Automatically collect and format project files for AI context.
 
 ```bash
-bundle install
+# Gather all Ruby files, skip tests, save to clipboard
+gpt_context -i '**/*.rb' -e 'spec/**/*' -d
+
+# Get project structure as a tree
+gpt_context -i '**/*' -f tree -d
+
+# Multiple file types with custom output
+gpt_context -i 'apps/**/*.ts' -i 'apps/**/*.tsx' -e '**/node_modules/**/*' -o context.txt
 ```
 
-Or install it yourself as:
+**Use cases:** Working with ChatGPT, Claude, or any AI assistant on your codebase.
+
+[Full documentation →](./docs/usage/gpt-context.md)
+
+---
+
+### 📹 YouTube Manager
+
+**The problem:** Updating video metadata through YouTube Studio is slow and repetitive, especially for bulk operations.
+
+**The solution:** Manage YouTube video metadata via API from your terminal - CRUD operations on videos.
 
 ```bash
-gem install appydave-tools
-```
+# Get video details (title, description, tags, category, captions)
+youtube_manager get --video-id YOUR_VIDEO_ID
 
-## Stories
+# Update title and description
+youtube_manager update --video-id YOUR_VIDEO_ID \
+  --title "New Title" \
+  --description "Updated description"
 
-### Main Story
+# Update tags (replaces existing tags)
+youtube_manager update --video-id YOUR_VIDEO_ID --tags "tutorial,productivity,automation"
 
-As a Content Creator, I want accellerate my video creation, so that I can improve speed and quality of my content
+# Update category
+youtube_manager update --video-id YOUR_VIDEO_ID --category-id 28
+```
 
-See all [stories](./STORIES.md)
+**Specific use cases:**
+- **Post-rebrand updates**: Changed channel name? Update 50 video descriptions in minutes
+- **Tag standardization**: Ensure consistent tagging across your entire catalog
+- **Metadata retrieval**: Export video details for analysis or backup
+- **Batch corrections**: Fix typos in titles across multiple videos
+- **Category changes**: Recategorize videos when YouTube updates categories
+- **Series updates**: Add series links to descriptions across episode batches
 
+**What it does:**
+- **Get**: Retrieves complete video metadata including captions
+- **Update**: Modifies title, description, tags, or category via YouTube Data API v3
+- **Authorization**: Handles OAuth2 flow with local callback server
+- **Reporting**: Generates detailed reports of video metadata
 
-## Usage
+**Why use this vs YouTube Studio:**
+- **Speed**: Update 20 videos in 5 minutes vs 30+ minutes clicking through UI
+- **Scriptable**: Integrate into automation workflows
+- **Bulk operations**: Loop through video IDs from a CSV
+- **Version control**: Track metadata changes in Git
+- **Backup**: Export all video metadata as JSON
 
-### CLI Tools
+---
 
-This gem provides several command-line tools for content creation and YouTube automation:
+### 📝 Subtitle Processor
 
-#### GPT Context Gatherer
-Collect and organize project files for AI context analysis:
+**The problem:** Raw subtitle files need cleanup, and multi-part recordings need merged subtitles.
 
-```bash
-# Basic usage - gather all Ruby files, exclude specs
-gpt_context -i '**/*.rb' -e 'spec/**/*' -d -o context.txt
+**The solution:** Process and transform SRT files - clean formatting, merge duplicates, synchronize timelines.
 
-# Multiple patterns with tree and content output
-gpt_context -i 'lib/**/*.rb' -i 'bin/**/*.rb' -f tree,content -d
+```bash
+# Clean auto-generated subtitles (removes HTML tags, merges duplicates, normalizes spacing)
+subtitle_processor clean -f input.srt -o cleaned.srt
 
-# Advanced filtering for web projects  
-gpt_context -i 'apps/**/*.ts' -i 'apps/**/*.tsx' -e '**/node_modules/**/*' -e '**/_generated/**/*' -d -f tree -o typescript-files.txt
+# Merge multiple subtitle files with timeline synchronization
+subtitle_processor join -d ./parts -f "*.srt" -o final.srt
 
-# Documentation and config files
-gpt_context -i 'docs/**/*' -i '**/*.json' -i '**/*.config.*' -e '**/node_modules/**/*' -d -f tree
+# Custom time buffer between merged sections (in milliseconds)
+subtitle_processor join -f "part1.srt,part2.srt" -b 200 -o merged.srt
 ```
 
-See detailed usage guide: [GPT Context Gatherer](./docs/usage/gpt-context.md)
+**What it does:**
+- **Clean**: Removes `<u>` tags, merges duplicate entries, normalizes line breaks and spacing
+- **Join**: Parses multiple SRT files, adjusts timestamps with buffers, merges into single timeline
 
-#### YouTube Manager
-```bash
-# Get video details
-bin/youtube_manager.rb get [options]
+**Use cases:** Cleaning messy YouTube auto-captions, merging FliVideo multi-part recording subtitles.
+
+**Note:** CLI command is `subtitle_processor` (renamed from `subtitle_manager` for accuracy - this tool *processes* files, not manages state).
+
+---
+
+### 🎯 Prompt Tools *(Experimental - Not actively used)*
+
+**The problem:** Running OpenAI prompts with placeholder substitution and output management.
+
+**The solution:** Execute OpenAI completion API calls with template support.
 
-# Update video metadata  
-bin/youtube_manager.rb update [options]
+```bash
+# Run prompt from text
+prompt_tools completion -p "Your prompt here" -o output.txt
+
+# Run prompt from file with placeholders
+prompt_tools completion -f prompt_template.md -k topic=Ruby,style=tutorial -c
+
+# Options:
+# -p, --prompt     Inline prompt text
+# -f, --file       Prompt template file
+# -k, --placeholders  Key-value pairs for {placeholder} substitution
+# -o, --output     Save to file
+# -c, --clipboard  Copy to clipboard
+# -m, --model      OpenAI model to use
 ```
 
-#### Subtitle Manager
+**What it does:**
+- Sends prompts to OpenAI Completion API (older GPT-3 models)
+- Supports template files with `{placeholder}` substitution
+- Outputs to file, clipboard, or stdout
+
+**Current status:** ⚠️ **Not in active use** - Uses deprecated OpenAI Completion API (`davinci-codex`). Modern alternative: Use ChatGPT or Claude directly, or migrate to Chat API.
+
+**Potential use cases:** Template-based content generation, automated prompt workflows (if migrated to Chat API).
+
+---
+
+### ⚡ YouTube Automation *(Internal/Experimental)*
+
+**The problem:** Video content creation workflows involve multiple steps: research → scripting → production.
+
+**The solution:** Run predefined prompt sequences against OpenAI API to automate research and content generation steps.
+
 ```bash
-# Clean subtitle files
-bin/subtitle_manager.rb clean [options]
+# Run automation sequence (requires configuration)
+youtube_automation -s 01-1
 
-# Join multiple subtitle parts
-bin/subtitle_manager.rb join [options]
+# With debug output
+youtube_automation -s 01-1 -d
 ```
 
-#### Prompt Tools
+**What it does:**
+- Loads sequence configuration from `~/.config/appydave/youtube_automation.json`
+- Reads prompt templates from Dropbox (`_common/raw_prompts/`)
+- Executes OpenAI API calls for each sequence step
+- Saves responses to output files
+
+**Configuration required:**
+- Sequence definitions in `youtube_automation.json`
+- Prompt template files in configured Dropbox path
+- `OPENAI_ACCESS_TOKEN` environment variable
+
+**Current status:** ⚠️ **Internal tool** - Hardcoded Dropbox paths, uses deprecated Completion API, not documented for external use.
+
+**Relationship to other tools:** This is separate from **Move Images** tool (which organizes downloaded images into video project asset folders).
+
+**Use cases:** Automated content research, script outline generation, multi-step prompt workflows.
+
+---
+
+### ⚙️ Configuration Manager
+
+**The problem:** Managing settings for multiple YouTube channels, project paths, and automation sequences gets messy.
+
+**The solution:** Centralized JSON-based configuration stored in `~/.config/appydave/`.
+
 ```bash
-# Run AI prompt completion
-bin/prompt_tools.rb completion [options]
+# List all configurations
+ad_config -l
+
+# Create missing config files with templates
+ad_config -c
+
+# Edit configurations in VS Code
+ad_config -e
+
+# View specific configuration values
+ad_config -p settings,channels
+
+# View all configurations
+ad_config -p
 ```
 
+**What it manages:**
+- **settings.json**: Project folder paths (content, video, published, abandoned)
+- **channels.json**: YouTube channel definitions (code, name, youtube_handle)
+- **youtube_automation.json**: Automation sequence configurations
 
-## Development
+**Use cases:**
+- **Multi-channel management**: Switch between different YouTube channels
+- **Team collaboration**: Share configuration files via Git/Dropbox (excluding secrets)
+- **Workflow standardization**: Consistent paths across team members
+- **Automation setup**: Define reusable prompt sequences
+
+**Team collaboration notes:**
+- Configuration files can be version-controlled (they contain no secrets)
+- Each team member can maintain their own `~/.config/appydave/` directory
+- Paths can be customized per developer machine
+- Secrets (API keys) stored separately in `.env` files (gitignored)
+
+---
 
-Checkout the repo
+### 🖼️ Move Images *(Development tool)*
+
+**The problem:** Downloaded images need organizing with proper naming.
+
+**The solution:** Batch move and rename to project folders.
 
 ```bash
-git clone https://github.com/appydave/appydave-tools
+# Organize intro images for video project
+bin/move_images.rb -f b40 intro b40
+# Result: b40-intro-1.jpg, b40-intro-2.jpg in assets/intro/
 ```
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. 
+**Use cases:** B-roll organization, thumbnail preparation.
 
-You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+---
 
-```bash
-bin/console
+## Philosophy
 
-Appydave::Tools::VERSION
-# => "0.14.0"
+**One codebase, multiple tools.** Easier to maintain than dozens of repos.
 
-# Access configuration
-config = Appydave::Tools::Configuration::Config.new
-# => #<Appydave::Tools::Configuration::Config:...>
-```
+**Single-purpose utilities.** Each tool does one thing well.
+
+**YouTube workflow focus.** Built for content creators who code.
+
+**Language-agnostic.** Currently Ruby, but could be rewritten if needed.
+
+[Read the full philosophy →](./docs/purpose-and-philosophy.md)
 
-`appydave-tools` is setup with Guard, run `guard`, this will watch development file changes and run tests automatically, if successful, it will then run rubocop for style quality.
+---
 
-To release a new version, update the version number in `version.rb`, build the gem and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## Development
 
 ```bash
-rake publish
-rake clean
+# Clone the repo
+git clone https://github.com/appydave/appydave-tools
+
+# Setup
+bin/setup
+
+# Run tests
+rake spec
+
+# Auto-run tests on file changes
+guard
+
+# Interactive console
+bin/console
 ```
 
-## Git helpers used by this project
+### Semantic Versioning
 
-Add the follow helpers to your `alias` file
+This project uses **automated versioning** via semantic-release. Don't manually edit version files.
 
+**Commit message format:**
 ```bash
-function kcommit()
-{
-  echo 'git add .'
-  git add .
-  echo "git commit -m "$1""
-  git commit -m "$1"
-  echo 'git pull'
-  git pull
-  echo 'git push'
-  git push
-  sleep 3
-  run_id="$(gh run list --limit 1 | grep -Eo "[0-9]{9,11}")"
-  gh run watch $run_id --exit-status && echo "run completed and successful" && git pull && git tag | sort -V | tail -1
-}
-function kchore     () { kcommit "chore: $1" }
-function kdocs      () { kcommit "docs: $1" }
-function kfix       () { kcommit "fix: $1" }
-function kfeat      () { kcommit "feat: $1" }
-function ktest      () { kcommit "test: $1" }
-function krefactor  () { kcommit "refactor: $1" }
+feat: add new feature    # Minor version bump
+fix: bug fix            # Patch version bump
+chore: maintenance      # No version bump
+
+# Breaking changes
+feat!: breaking change
 ```
 
+CI/CD automatically handles versioning, changelog, and RubyGems publishing.
+
+---
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/appydave/appydave-tools. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+**Welcome:**
+- 🐛 Bug fixes
+- 📝 Documentation improvements
+- ⚡ Performance enhancements
+- 🎯 New single-purpose tools that fit the workflow
+
+**Not looking for:**
+- ❌ Framework-style architectures
+- ❌ Tools that create dependencies between utilities
+- ❌ Enterprise complexity
+
+[Code of Conduct →](./CODE_OF_CONDUCT.md)
+
+---
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+MIT License - Copyright (c) David Cruwys
+
+See [LICENSE.txt](LICENSE.txt) for details.
 
-## Code of Conduct
+---
 
-Everyone interacting in the Appydave Tools project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/appydave/appydave-tools/blob/master/CODE_OF_CONDUCT.md).
+## Connect
 
-## Copyright
+- 🌐 Website: [appydave.com](http://appydave.com)
+- 📺 YouTube: [@AppyDave](https://youtube.com/@appydave)
+- 🐙 GitHub: [appydave](https://github.com/appydave)
 
-Copyright (c) David Cruwys. See [MIT License](LICENSE.txt) for further details.
+Built with ☕ by [David Cruwys](https://davidcruwys.com)

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