appydave-tools 0.16.0 → 0.17.1

data/docs/development/CODEX-recommendations.md

@@ -0,0 +1,230 @@
+# CODEX Recommendations - Review & Status
+
+> Last updated: 2025-11-10
+> Original recommendations provided by Codex (GPT-5) on 2025-11-09
+
+This document captures Codex's architectural recommendations with implementation status and verdicts after engineering review.
+
+## Executive Summary
+
+**Overall Assessment:** Mixed recommendations - some valuable, some outdated, some architecturally inappropriate.
+
+**Implemented:** ✅ P3 (Filesystem fixtures)
+**Rejected:** ❌ P0 (Configuration DI), P1 (RuboCop - already clean), P4 (method_missing removal)
+**Deferred:** ⚠️ P2 (IO separation - CLI tool doesn't need it)
+**Future Work:** 🔍 VAT Manifest bugs (valid technical debt)
+
+---
+
+## Priority Recommendations
+
+### ✅ P3: Standardize Filesystem Fixtures (IMPLEMENTED)
+
+**Recommendation:** Extract `Dir.mktmpdir + FileUtils.mkdir_p` boilerplate into shared RSpec context.
+
+**Status:** ✅ **Implemented** (2025-11-10)
+
+**What was done:**
+- Created `spec/support/vat_filesystem_helpers.rb` with shared contexts
+- `include_context 'vat filesystem'` - provides temp_folder, projects_root, auto-cleanup
+- `include_context 'vat filesystem with brands', brands: %w[appydave voz]` - adds brand path helpers
+- Refactored 3 VAT specs: config_spec, project_resolver_spec, config_loader_spec
+- All tests passing (149 examples, 0 failures)
+
+**Benefits delivered:**
+- Reduced duplication across VAT specs
+- Centralized cleanup logic (safer tests)
+- Easier to maintain and extend
+
+---
+
+### ❌ P1: RuboCop Cleanup (ALREADY COMPLETE)
+
+**Recommendation:** Run `rubocop --auto-correct` to fix 93 offenses, track 15 manual fixes.
+
+**Status:** ❌ **Obsolete** - RuboCop already clean
+
+**Current state:**
+```bash
+bundle exec rubocop
+# => 103 files inspected, no offenses detected
+```
+
+**Verdict:** The recommendations document was based on outdated codebase state. No action needed.
+
+---
+
+### ❌ P0: Configuration Dependency Injection (REJECTED)
+
+**Recommendation:** Replace `allow_any_instance_of(SettingsConfig)` with dependency injection pattern:
+```ruby
+# Proposed:
+Config.projects_root(settings: custom_settings)
+```
+
+**Status:** ❌ **Rejected** - Architecturally inappropriate
+
+**Why rejected:**
+1. **Singleton pattern is correct for configuration** - Global config state is intentional
+2. **Breaking API change** - Would require threading `settings:` through entire call chain:
+   - `bin/vat` → `ProjectResolver` → `Config.brand_path` → `Config.projects_root`
+   - Every method needs new parameter (massive churn)
+3. **Tests work correctly** - `allow_any_instance_of` is intentionally allowed in `.rubocop.yml`
+4. **No real benefit** - Adds complexity without solving actual problems
+
+**Codex's concern:** "Tests must stub *every* SettingsConfig instance"
+
+**Reality:** This is fine. Configuration is a singleton. Testing strategy is appropriate.
+
+**Lesson for Codex:** Dependency injection is not always superior to singleton patterns. Context matters. CLI tools with global configuration state don't benefit from DI complexity.
+
+---
+
+### ❌ P4: Remove method_missing from Configuration::Config (REJECTED)
+
+**Recommendation:** Replace `method_missing` with explicit reader methods or `Forwardable`.
+
+**Status:** ❌ **Rejected** - This is a design pattern, not a code smell
+
+**Why rejected:**
+1. **Registry pattern** - `method_missing` enables dynamic configuration registration:
+   ```ruby
+   Config.register(:settings, SettingsConfig)
+   Config.register(:channels, ChannelsConfig)
+   Config.settings  # Dynamic dispatch via method_missing
+   ```
+2. **Proper implementation** - Has `respond_to_missing?` (Ruby best practice ✅)
+3. **Good error handling** - Clear messages listing available configs
+4. **Plugin architecture** - Can add new configs without modifying `Config` class
+
+**Codex's concern:** "Hides failures until runtime and complicates auto-complete"
+
+**Reality:** This is a common Ruby pattern (Rails uses it extensively). The implementation is correct.
+
+**Lesson for Codex:** `method_missing` is not inherently bad. When properly implemented with `respond_to_missing?` and clear errors, it enables powerful metaprogramming patterns. Don't dogmatically avoid it.
+
+---
+
+### ⚠️ P2: Decouple Terminal IO from VAT Services (DEFERRED)
+
+**Recommendation:** Extract interactive prompts from `ProjectResolver.resolve` business logic.
+
+**Codex's concern:** Interactive `puts`/`$stdin.gets` blocks automation agents.
+
+**Status:** ⚠️ **Low priority** - Not needed for current use case
+
+**Why deferred:**
+1. **CLI-only tool** - VAT is a command-line interface, not a library
+2. **Intentional UX** - Interactive prompts provide good user experience for ambiguous cases
+3. **No automation use cases** - Agents use exact project names, don't trigger prompts
+4. **Current code location:** `lib/appydave/tools/vat/project_resolver.rb:41-49`
+
+**When to revisit:** If VAT needs programmatic API for automation tools, add non-interactive mode:
+```ruby
+def resolve(brand, project_hint, interactive: true)
+  # Return all matches if !interactive (for automation)
+end
+```
+
+**Lesson for Codex:** Not all code needs maximum abstraction. CLI tools can have terminal IO in business logic if that's their primary use case.
+
+---
+
+## Architecture-Wide Observations
+
+### ✅ Valid Technical Debt: VAT Manifest Generator
+
+**Issues identified (lines 116-125 in original doc):**
+
+1. **Archived projects silently dropped** - `collect_project_ids` rejects archived folder entirely
+2. **SSD paths lose grouping context** - Stores only `project_id`, not `range/project_id`
+3. **Heavy file detection shallow** - Only checks top-level, misses nested videos
+4. **Quadratic disk scanning** - Walks every file twice per project
+5. **Code duplication** - Standalone `bin/generate_manifest.rb` diverged from lib class
+
+**Status:** 🔍 **Acknowledged as real bugs** - Worth investigating
+
+**Note:** These are legitimate technical debt items, not style preferences. Recommend creating GitHub issues for tracking.
+
+---
+
+### ⚠️ CLI Standardization (Worth Auditing)
+
+**Observation:** Not all bin scripts use `BaseAction` pattern consistently.
+
+**Example:** `bin/gpt_context.rb` hand-rolls `OptionParser` instead of using `lib/appydave/tools/cli_actions/base_action.rb`.
+
+**Status:** ⚠️ **Worth reviewing** for consistency
+
+**Action:** Audit which CLI scripts follow standard patterns vs. custom implementations.
+
+---
+
+## Lessons Learned (for future Codex reviews)
+
+### What Codex got right:
+1. ✅ **Filesystem fixtures** - Practical refactoring with clear benefits
+2. ✅ **Manifest bugs** - Identified real logic issues worth fixing
+3. ✅ **CLI consistency** - Valid observation about pattern divergence
+
+### Where Codex was dogmatic:
+1. ❌ **Dependency injection everywhere** - Not all singletons need DI
+2. ❌ **Avoid method_missing** - Valid Ruby pattern when done correctly
+3. ❌ **Separate all IO** - CLI tools can mix IO with logic appropriately
+
+### What Codex missed:
+1. **Current state validation** - Recommended RuboCop fixes already applied
+2. **Cost/benefit analysis** - P0 config adapter would break entire API for minimal gain
+3. **Context awareness** - CLI tools have different constraints than libraries
+
+---
+
+## Conclusion
+
+**Codex recommendations score: 4/10**
+
+**Good advice:**
+- Filesystem fixture extraction (implemented ✅)
+- Manifest generator bugs (valid technical debt 🔍)
+- CLI standardization audit (worth reviewing ⚠️)
+
+**Bad advice:**
+- Configuration dependency injection (wrong pattern for this use case ❌)
+- Remove method_missing (misunderstands design pattern ❌)
+- Outdated RuboCop recommendations (already fixed ❌)
+
+**Key takeaway:** Mix pragmatic refactoring suggestions with dogmatic "purity" recommendations. Cherry-pick the valuable insights, reject the inappropriate ones.
+
+---
+
+## Implementation Notes
+
+### P3 Filesystem Fixtures - Details
+
+**Files created:**
+- `spec/support/vat_filesystem_helpers.rb`
+
+**Shared contexts:**
+```ruby
+# Basic fixture
+include_context 'vat filesystem'
+# => Provides: temp_folder, projects_root, auto-cleanup, config mocking
+
+# With brand directories
+include_context 'vat filesystem with brands', brands: %w[appydave voz]
+# => Also provides: appydave_path, voz_path (auto-created)
+```
+
+**Files refactored:**
+- `spec/appydave/tools/vat/config_spec.rb` (removed 11 lines boilerplate)
+- `spec/appydave/tools/vat/project_resolver_spec.rb` (removed 18 lines boilerplate)
+- `spec/appydave/tools/vat/config_loader_spec.rb` (removed 9 lines boilerplate)
+
+**Test results:**
+- 149 VAT spec examples, 0 failures
+- Coverage: 76.38% (2131/2790 lines)
+
+---
+
+**Document maintained by:** AppyDave engineering team
+**Next review:** After addressing VAT manifest bugs

data/docs/development/README.md

@@ -0,0 +1,100 @@
+# Development Documentation
+
+This directory contains comprehensive guides for developing and extending appydave-tools.
+
+## Quick Links
+
+### Architecture Guides
+- [CLI Architecture Patterns](./cli-architecture-patterns.md) - **START HERE** when creating new tools
+
+## Quick Pattern Selection
+
+When creating a new CLI tool, use this quick reference:
+
+### Single Operation Tool → Pattern 1
+**Use when:** Tool performs ONE operation with various options
+
+**Examples:** `gpt_context`, `move_images`
+
+**Key files:**
+```
+bin/tool_name.rb                    # CLI executable
+lib/appydave/tools/tool_name/
+  ├── options.rb                    # Options struct
+  └── main_logic.rb                 # Business logic
+```
+
+**Read:** [Pattern 1 Details](./cli-architecture-patterns.md#pattern-1-single-command-tools)
+
+---
+
+### 2-5 Commands → Pattern 2
+**Use when:** Tool has 2-5 related commands with simple routing
+
+**Examples:** `subtitle_processor`, `configuration`
+
+**Key files:**
+```
+bin/tool_name.rb                    # CLI with inline routing
+lib/appydave/tools/tool_name/
+  ├── command_one.rb                # Command implementation
+  └── command_two.rb                # Command implementation
+```
+
+**Read:** [Pattern 2 Details](./cli-architecture-patterns.md#pattern-2-multi-command-with-inline-routing)
+
+---
+
+### 6+ Commands or Shared Patterns → Pattern 3
+**Use when:** Tool has many commands OR commands share validation/execution patterns
+
+**Examples:** `youtube_manager`
+
+**Key files:**
+```
+bin/tool_name.rb                    # CLI with BaseAction routing
+lib/appydave/tools/
+  ├── cli_actions/
+  │   ├── base_action.rb            # Shared base (already exists)
+  │   ├── tool_cmd_one_action.rb    # Command as Action class
+  │   └── tool_cmd_two_action.rb
+  └── tool_name/
+      └── service.rb                # Business logic
+```
+
+**Read:** [Pattern 3 Details](./cli-architecture-patterns.md#pattern-3-multi-command-with-baseaction)
+
+---
+
+## Common Tasks
+
+### Adding a New Tool
+1. Choose pattern using [Decision Tree](./cli-architecture-patterns.md#decision-tree)
+2. Follow [Migration Guide](./cli-architecture-patterns.md#migration-guide)
+3. Register in `appydave-tools.gemspec`
+4. Document in `CLAUDE.md`
+
+### Understanding Existing Code
+- See [Directory Structure](./cli-architecture-patterns.md#directory-structure)
+- Review [Best Practices](./cli-architecture-patterns.md#best-practices)
+
+### Writing Tests
+- Read [Testing Approach](./cli-architecture-patterns.md#testing-approach)
+- No `require` statements in specs (handled by `spec_helper`)
+- Test business logic, not CLI executables
+
+---
+
+## Philosophy
+
+AppyDave Tools follows a **consolidated toolkit philosophy**:
+- Multiple independent tools in one repository
+- Each tool solves one specific problem
+- Clear separation between CLI and business logic
+- Business logic can be used programmatically (no CLI dependencies in `lib/`)
+
+**Full Philosophy:** [Purpose and Philosophy](../purpose-and-philosophy.md)
+
+---
+
+**Last updated:** 2025-11-08