appydave-tools 0.21.2 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72844960d0580ea65b08a7d8be703910946ae6b095bac290a594cc9a1288a208
-  data.tar.gz: 6ff9f2b0a5254a0ef2dc5fd1e07722e7635f9368a7ec6fd8deb3ffe016b01bc0
+  metadata.gz: 93dd9f15e347dfb0b0cb8bc5897e936317cbc8af13af40d3b51fd912d9c7cb7b
+  data.tar.gz: a7b21ab65386f0291c584263f0247513b4ad35513246e68bf873330e70221836
 SHA512:
-  metadata.gz: 9ee56f7cafc8e772ee75dbf809860148c26a3a229c2b1da5f04899fad658185169f83f25eb2dab3ce2b395d7b7067e6f13a86936967f11da844c1da58bfdaa5f
-  data.tar.gz: cd5def0f4db1f1fef7aac06bcd17cd6f480322da95da18453efe40285b37ac51d17f7be504204e5f84363d0dc0286ce2a324c6b06049a4020d808a364b7b99d8
+  metadata.gz: 54f08c9a7b2d340fbe0a6600b239a0fa02bb3e7d869923bcf5ddb8e29ed911f3aac066ae358f078c07f9f75d9025464b10fd355bf245125c7ab6ba4e279d0b02
+  data.tar.gz: bf5358fd24eb33c6533ba6593c3195d45285d6f5ad5e926d4db2a34ce3bb0b1fc7557cca4d4b5978b7c5171ef68c3ef20589ca2369e23a9a4479ccacb7ab7e61

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [0.21.2](https://github.com/appydave/appydave-tools/compare/v0.21.1...v0.21.2) (2025-11-17)
+
+
+### Bug Fixes
+
+* fix exe/dam wrapper to properly execute bin/dam by setting PROGRAM_NAME ([cec43c3](https://github.com/appydave/appydave-tools/commit/cec43c3489ab868d120293daebf3456819ae6b11))
+
 ## [0.21.1](https://github.com/appydave/appydave-tools/compare/v0.21.0...v0.21.1) (2025-11-17)
 
 

data/bin/dam

@@ -27,6 +27,7 @@ class VatCLI
       'repo-push' => method(:repo_push_command),
       's3-share' => method(:s3_share_command),
       's3-discover' => method(:s3_discover_command),
+      's3-scan' => method(:s3_scan_command),
       # Deprecated aliases (for backward compatibility)
       's3-cleanup' => method(:s3_cleanup_remote_command),
       'cleanup-local' => method(:s3_cleanup_local_command)
@@ -565,6 +566,9 @@ class VatCLI
         s3-discover <brand> <project>    List files available in S3
         s3-share <brand> <project> <file> Generate shareable pre-signed URL
 
+        S3 Data Commands:
+        s3-scan <brand> [--all]          Scan S3 bucket for actual file data
+
         Archive Commands:
         archive <brand> <project>        Copy project to SSD backup
         manifest <brand> [--all]         Generate project manifest
@@ -593,6 +597,8 @@ class VatCLI
         dam s3-discover appydave b70 --shareable
         dam s3-share appydave b70 video.mp4
         dam s3-share appydave b70 video.mp4 --expires 24h
+        dam s3-scan appydave
+        dam s3-scan --all
         dam s3-cleanup-remote appydave b65 --force
 
       For more information: https://github.com/appydave/appydave-tools
@@ -1092,6 +1098,137 @@ class VatCLI
   end
   # rubocop:enable Metrics/CyclomaticComplexity
   # rubocop:enable Metrics/MethodLength
+
+  # S3 Scan - Query AWS S3 for actual file listings
+  def s3_scan_command(args)
+    all_brands = args.include?('--all')
+    args = args.reject { |arg| arg.start_with?('--') }
+    brand_arg = args[0]
+
+    if all_brands
+      scan_all_brands_s3
+    elsif brand_arg
+      scan_single_brand_s3(brand_arg)
+    else
+      puts 'Usage: dam s3-scan <brand> [--all]'
+      puts ''
+      puts 'Scan S3 bucket to update project manifests with actual S3 file data.'
+      puts ''
+      puts 'Examples:'
+      puts '  dam s3-scan appydave      # Scan AppyDave S3 bucket'
+      puts '  dam s3-scan --all         # Scan all brands'
+      exit 1
+    end
+  rescue StandardError => e
+    puts "❌ Error: #{e.message}"
+    puts e.backtrace.first(5).join("\n") if ENV['DEBUG']
+    exit 1
+  end
+
+  # rubocop:disable Metrics/MethodLength
+  def scan_single_brand_s3(brand_arg)
+    puts "🔄 Scanning S3 for #{brand_arg}..."
+    puts ''
+
+    brand_key = brand_arg
+    scanner = Appydave::Tools::Dam::S3Scanner.new(brand_key)
+
+    # Scan all projects
+    results = scanner.scan_all_projects
+
+    if results.empty?
+      puts ''
+      puts "⚠️  No projects found in S3 for #{brand_key}"
+      puts '   This may indicate:'
+      puts '   - No files uploaded to S3 yet'
+      puts '   - S3 bucket or prefix misconfigured'
+      puts '   - AWS credentials issue'
+      return
+    end
+
+    # Load existing manifest
+    Appydave::Tools::Configuration::Config.configure
+    brand_path = Appydave::Tools::Dam::Config.brand_path(brand_key)
+    manifest_path = File.join(brand_path, 'projects.json')
+
+    unless File.exist?(manifest_path)
+      puts ''
+      puts "❌ Manifest not found: #{manifest_path}"
+      puts "   Run: dam manifest #{brand_key}"
+      puts "   Then retry: dam s3-scan #{brand_key}"
+      exit 1
+    end
+
+    manifest = JSON.parse(File.read(manifest_path), symbolize_names: true)
+
+    # Merge S3 scan data into manifest
+    updated_count = 0
+    manifest[:projects].each do |project|
+      project_id = project[:id]
+      s3_data = results[project_id]
+      next unless s3_data
+
+      project[:storage][:s3] = s3_data
+      updated_count += 1
+    end
+
+    # Update timestamp and note
+    manifest[:config][:last_updated] = Time.now.utc.iso8601
+    manifest[:config][:note] = 'Auto-generated manifest with S3 scan data. Regenerate with: dam s3-scan'
+
+    # Write updated manifest
+    File.write(manifest_path, JSON.pretty_generate(manifest))
+
+    puts ''
+    puts "✅ Updated manifest with S3 data: #{manifest_path}"
+    puts "   Scanned #{results.size} projects in S3"
+    puts "   Updated #{updated_count} projects in manifest"
+    puts ''
+  end
+  # rubocop:enable Metrics/MethodLength
+
+  # rubocop:disable Metrics/MethodLength
+  def scan_all_brands_s3
+    Appydave::Tools::Configuration::Config.configure
+    brands_config = Appydave::Tools::Configuration::Config.brands
+
+    results = []
+    brands_config.brands.each do |brand_info|
+      brand_key = brand_info.key
+      puts ''
+      puts '=' * 60
+
+      begin
+        scan_single_brand_s3(brand_key)
+        results << { brand: brand_key, success: true }
+      rescue StandardError => e
+        puts "❌ Failed to scan #{brand_key}: #{e.message}"
+        results << { brand: brand_key, success: false, error: e.message }
+      end
+    end
+
+    puts ''
+    puts '=' * 60
+    puts '📋 Summary - S3 Scans:'
+    puts ''
+
+    successful = results.select { |r| r[:success] }
+    failed = results.reject { |r| r[:success] }
+
+    successful.each do |result|
+      brand_display = result[:brand].ljust(15)
+      puts "✅ #{brand_display} Scanned successfully"
+    end
+
+    failed.each do |result|
+      brand_display = result[:brand].ljust(15)
+      puts "❌ #{brand_display} #{result[:error]}"
+    end
+
+    puts ''
+    puts "Total brands scanned: #{successful.size}/#{results.size}"
+  end
+  # rubocop:enable Metrics/MethodLength
 end
 
 # Run CLI

data/docs/README.md

@@ -1,65 +1,131 @@
 # AppyDave Tools Documentation
 
-**Welcome to the AppyDave Tools documentation!**
+**Documentation organized by purpose:** guides (how to), architecture (why/how it works), templates (copy these), development (contribute).
 
-This directory contains comprehensive documentation for all tools, features, and development guides.
+---
+
+## 📖 Guides (How To Use)
+
+### Tools
+
+- **[DAM - Digital Asset Management](./guides/tools/dam/)** - Video project storage orchestration
+  - [Usage Guide](./guides/tools/dam/dam-usage.md) ✅
+  - [Testing Plan](./guides/tools/dam/dam-testing-plan.md) ✅
+- **[GPT Context](./guides/tools/gpt-context.md)** - Gather files for AI context ✅
+- **[YouTube Manager](./guides/tools/youtube-manager.md)** - Manage YouTube metadata ✅
+- **[Subtitle Processor](./guides/tools/subtitle-processor.md)** - Clean/merge SRT files ✅
+- **[Configuration Tool](./guides/tools/configuration.md)** - Manage config files ✅
+- **[YouTube Automation](./guides/tools/youtube-automation.md)** - Automation workflows ✅
+- **[Prompt Tools](./guides/tools/prompt-tools.md)** - OpenAI completion wrapper ✅
+- **[Move Images](./guides/tools/move-images.md)** - Organize video assets ✅
+- **[Bank Reconciliation](./guides/tools/bank-reconciliation.md)** - DEPRECATED ✅
+- **[Name Manager](./guides/tools/name-manager.md)** - Naming utilities ✅
+- **[CLI Actions](./guides/tools/cli-actions.md)** - CLI base actions ✅
+
+### Platform-Specific
+
+- **[Windows Setup](./guides/platforms/windows/)** - Windows/WSL installation ✅
+  - [Installation Guide](./guides/platforms/windows/installation.md) ✅
+  - [Testing Plan](./guides/platforms/windows/dam-testing-plan-windows-powershell.md) ✅
+
+### Configuration
+
+- **[Configuration Setup Guide](./guides/configuration-setup.md)** - Complete configuration reference ✅
+  - Quick start, file locations, settings reference
+  - Migration from legacy configs
+  - Backup and recovery
+
+### Future Configuration Guides
+
+More detailed configuration guides (not yet created):
+
+- **Settings Deep Dive** 📝 (detailed explanation of each setting)
+- **Channels System** 📝 (YouTube channel management)
+- **Brands System** 📝 (multi-brand/multi-tenant architecture)
+- **Advanced Configuration** 📝 (environment-specific configs, team setups)
 
 ---
 
-## 📚 Quick Navigation
+## 🏗️ Architecture (Understanding How It Works)
+
+### DAM (Digital Asset Management)
+
+**Complete documentation for DAM visualization and CLI system:**
+
+- **[Implementation Roadmap](./architecture/dam/implementation-roadmap.md)** ⭐ START HERE - Complete development guide ✅
+- **[DAM Vision](./architecture/dam/dam-vision.md)** - Strategic vision and roadmap ✅
+- **[Data Model](./architecture/dam/dam-data-model.md)** - Complete entity schema and relationships ✅
+- **[Visualization Requirements](./architecture/dam/dam-visualization-requirements.md)** - Astro dashboard specification ✅
+- **[CLI Enhancements](./architecture/dam/dam-cli-enhancements.md)** - Command requirements specification ✅
+- **[CLI Implementation Guide](./architecture/dam/dam-cli-implementation-guide.md)** - Code-level implementation details ✅
+- **[Jan Collaboration Guide](./architecture/dam/jan-collaboration-guide.md)** - Team workflow reference ✅
+
+**DAM Design Decisions:**
+- **[002 - Client Sharing](./architecture/dam/design-decisions/002-client-sharing.md)** 🔄 IN PROGRESS
+- **[003 - Git Integration](./architecture/dam/design-decisions/003-git-integration.md)** 📋 PLANNED
+
+### CLI Architecture
 
-### User Documentation
+- **[CLI Patterns](./architecture/cli/cli-patterns.md)** - CLI architecture patterns ✅
+- **[CLI Pattern Comparison](./architecture/cli/cli-pattern-comparison.md)** - Visual pattern guide ✅
 
-- **[VAT (Video Asset Tools)](./vat/)** - Video project storage orchestration
-  - [Usage Guide](./vat/usage.md) - Complete usage reference
-  - [Testing Plan](./vat/vat-testing-plan.md) - User acceptance testing
-  - [Implementation Status](./vat/vat-implementation-status.md) - Feature matrix
-  - [Integration Plan](./vat/vat-integration-plan.md) - Migration details
-  - [Refactoring Summary](./vat/vat-refactoring-summary.md) - Architecture changes
+### Configuration Systems
 
-- **[Tools](./tools/)** - Individual tool documentation
-  - GPT Context Gatherer
-  - YouTube Manager
-  - Subtitle Processor
-  - Configuration Management
-  - And more...
+- **[Configuration Systems Analysis](./architecture/configuration/configuration-systems.md)** - How brands/channels/NameManager relate ✅
 
-### Developer Documentation
+### Design Decisions (General)
 
-- **[Development Guides](./development/)** - How to build tools
-  - [CLI Architecture Patterns](./development/cli-architecture-patterns.md) - Pattern reference
-  - [Pattern Comparison](./development/pattern-comparison.md) - Visual guide
-  - [Quick Reference](./development/README.md) - Fast pattern selection
+- **[001 - Unified Brands Configuration](./architecture/design-decisions/001-unified-brands-config.md)** ✅ COMPLETED
+- **[Session: 2025-11-09 DAM Refactoring](./architecture/design-decisions/session-2025-11-09.md)** ✅
 
-### System Documentation
+---
+
+## 📋 Templates (Copy These)
+
+Ready-to-use configuration templates:
+
+- **[settings.example.json](./templates/settings.example.json)** - Settings template ✅
+- **[channels.example.json](./templates/channels.example.json)** - Channels template ✅
+- **[.env.example](./templates/.env.example)** - Environment variables template ✅
+- **brands.example.json** 📝 (not yet created - should mirror brands.json structure with placeholders)
 
-- **[Project & Brand Systems Analysis](./project-brand-systems-analysis.md)** - Deep dive into overlapping systems
-  - VAT system (storage orchestration)
-  - Channels configuration (YouTube metadata)
-  - NameManager (naming conventions)
-  - Integration points and recommendations
+**To use templates:**
+```bash
+# Copy to config directory
+cp docs/templates/settings.example.json ~/.config/appydave/settings.json
+cp docs/templates/channels.example.json ~/.config/appydave/channels.json
 
-### Archive
+# Copy .env to project root
+cp docs/templates/.env.example .env
 
-- **[Archive](./archive/)** - Deprecated documentation
-  - Old versions of documentation
-  - Historical reference material
+# Edit with your values
+ad_config -e
+```
 
 ---
 
-## 🎯 Common Tasks
+## 🛠️ Development (Contributing)
+
+Documentation for contributors and developers:
+
+- **[CODEX Recommendations](./development/codex-recommendations.md)** - AI coding guidelines ✅
+
+### Future Development Topics
 
-### "I want to use a tool"
-→ See individual tool documentation in [`tools/`](./tools/) or [`vat/`](./vat/)
+Planned documentation for contributors:
 
-### "I want to build a new tool"
-→ Start with [`development/README.md`](./development/README.md) for CLI pattern selection
+- **Contributing Guide** 📝 (how to contribute, PR process, coding standards)
+- **Testing Guide** 📝 (how to run tests, write specs, coverage requirements)
+- **Release Process** 📝 (semantic versioning, CI/CD, gem publishing)
+- **Development Setup** 📝 (rbenv, bundler, guard, development workflow)
 
-### "I want to understand the architecture"
-→ Read [`development/cli-architecture-patterns.md`](./development/cli-architecture-patterns.md)
+---
+
+## 🗄️ Archive
 
-### "I want to understand how systems relate"
-→ Read [`project-brand-systems-analysis.md`](./project-brand-systems-analysis.md)
+Historical and deprecated documentation:
+
+- **[Archive](./archive/)** - Deprecated documentation ✅
 
 ---
 
@@ -68,72 +134,100 @@ This directory contains comprehensive documentation for all tools, features, and
 ```
 docs/
 ├── README.md (this file)                          # Documentation index
-├── project-brand-systems-analysis.md              # System overlap analysis
 │
-├── vat/                                           # VAT documentation
-│   ├── usage.md                                   # User guide
-│   ├── vat-testing-plan.md                        # Testing guide
-│   ├── vat-implementation-status.md               # Feature status
-│   ├── vat-integration-plan.md                    # Integration details
-│   └── vat-refactoring-summary.md                 # Architecture changes
+├── guides/                                        # HOW TO use things
+│   ├── tools/                                     # Individual tool guides
+│   │   ├── dam/                                   # DAM-specific guides
+│   │   │   ├── dam-usage.md
+│   │   │   └── dam-testing-plan.md
+│   │   ├── gpt-context.md
+│   │   ├── youtube-manager.md
+│   │   ├── subtitle-processor.md
+│   │   ├── configuration.md
+│   │   └── ... (11 tool guides total)
+│   │
+│   └── platforms/                                 # Platform-specific setup
+│       └── windows/                               # Windows/WSL guides
+│           ├── README.md
+│           ├── installation.md
+│           └── dam-testing-plan-windows-powershell.md
+│
+├── architecture/                                  # WHY/HOW systems work
+│   ├── dam/                                       # DAM system documentation
+│   │   ├── implementation-roadmap.md              # ⭐ START HERE - Complete dev guide
+│   │   ├── dam-vision.md                          # Strategic vision
+│   │   ├── dam-data-model.md                      # Entity schema
+│   │   ├── dam-visualization-requirements.md      # Astro dashboard spec
+│   │   ├── dam-cli-enhancements.md                # CLI implementation
+│   │   ├── jan-collaboration-guide.md             # Team workflow
+│   │   └── design-decisions/                      # DAM-specific PRDs
+│   │       ├── 002-client-sharing.md
+│   │       └── 003-git-integration.md
+│   │
+│   ├── cli/                                       # CLI architecture
+│   │   ├── cli-patterns.md                        # CLI patterns
+│   │   └── cli-pattern-comparison.md              # Pattern guide
+│   │
+│   ├── configuration/                             # Configuration system
+│   │   └── configuration-systems.md               # System overlap analysis
+│   │
+│   └── design-decisions/                          # General PRDs, ADRs, session logs
+│       ├── 001-unified-brands-config.md
+│       └── session-2025-11-09.md
 │
-├── tools/                                         # Individual tool docs
-│   ├── gpt-context.md
-│   ├── youtube-manager.md
-│   ├── subtitle-processor.md
-│   └── ... (more tools)
+├── templates/                                     # COPY THESE files
+│   ├── settings.example.json
+│   ├── channels.example.json
+│   └── .env.example
 │
-├── development/                                   # Developer guides
-│   ├── README.md                                  # Quick reference
-│   ├── cli-architecture-patterns.md               # Pattern guide
-│   └── pattern-comparison.md                      # Visual comparison
+├── development/                                   # FOR CONTRIBUTORS
+│   └── codex-recommendations.md
 │
-└── archive/                                       # Old documentation
-    └── ... (deprecated docs)
+└── archive/                                       # OLD/DEPRECATED
+    └── ... (historical docs)
 ```
 
 ---
 
-## 🔍 Finding What You Need
-
-### By Tool Name
-
-| Tool | Documentation |
-|------|---------------|
-| **VAT** | [`vat/usage.md`](./vat/usage.md) |
-| **GPT Context** | [`tools/gpt-context.md`](./tools/gpt-context.md) |
-| **YouTube Manager** | [`tools/youtube-manager.md`](./tools/youtube-manager.md) |
-| **Subtitle Processor** | [`tools/subtitle-processor.md`](./tools/subtitle-processor.md) |
-| **Configuration** | [`tools/configuration.md`](./tools/configuration.md) |
+## 🔍 Quick Reference
 
 ### By Task
 
 | Task | Documentation |
 |------|---------------|
-| **Video storage management** | [`vat/usage.md`](./vat/usage.md) |
-| **S3 sync for collaboration** | [`vat/usage.md`](./vat/usage.md) |
-| **Gather AI context** | [`tools/gpt-context.md`](./tools/gpt-context.md) |
-| **Manage YouTube videos** | [`tools/youtube-manager.md`](./tools/youtube-manager.md) |
-| **Process subtitles** | [`tools/subtitle-processor.md`](./tools/subtitle-processor.md) |
-| **Build new CLI tool** | [`development/cli-architecture-patterns.md`](./development/cli-architecture-patterns.md) |
+| **DAM development** | [Implementation Roadmap](./architecture/dam/implementation-roadmap.md) ⭐ |
+| **Video storage management** | [DAM Usage](./guides/tools/dam/dam-usage.md) |
+| **S3 sync for collaboration** | [DAM Usage](./guides/tools/dam/dam-usage.md) |
+| **Understand DAM architecture** | [DAM Data Model](./architecture/dam/dam-data-model.md) |
+| **Build DAM dashboard** | [Visualization Requirements](./architecture/dam/dam-visualization-requirements.md) |
+| **Gather AI context** | [GPT Context](./guides/tools/gpt-context.md) |
+| **Manage YouTube videos** | [YouTube Manager](./guides/tools/youtube-manager.md) |
+| **Process subtitles** | [Subtitle Processor](./guides/tools/subtitle-processor.md) |
+| **Configure tools** | [Configuration Tool](./guides/tools/configuration.md) |
+| **Set up on Windows** | [Windows Setup](./guides/platforms/windows/) |
+| **Build new CLI tool** | [CLI Patterns](./architecture/cli/cli-patterns.md) |
+| **Understand system design** | [Configuration Systems](./architecture/configuration/configuration-systems.md) |
 
 ### By Audience
 
 | Audience | Start Here |
 |----------|------------|
-| **End Users** | Individual tool docs in [`tools/`](./tools/) or [`vat/`](./vat/) |
-| **Developers** | [`development/README.md`](./development/README.md) |
-| **Contributors** | [`development/cli-architecture-patterns.md`](./development/cli-architecture-patterns.md) |
-| **Architects** | [`project-brand-systems-analysis.md`](./project-brand-systems-analysis.md) |
+| **DAM Developers** | [Implementation Roadmap](./architecture/dam/implementation-roadmap.md) ⭐ |
+| **End Users** | [Guides](#-guides-how-to-use) - Individual tool documentation |
+| **Windows Users** | [Windows Setup](./guides/platforms/windows/) |
+| **Team Members (Jan)** | [Jan Collaboration Guide](./architecture/dam/jan-collaboration-guide.md) |
+| **Developers** | [Development](#%EF%B8%8F-development-contributing) - Contributing guides |
+| **Contributors** | [CLI Patterns](./architecture/cli/cli-patterns.md) |
+| **Architects** | [Architecture](#%EF%B8%8F-architecture-understanding-how-it-works) - System design |
 
 ---
 
-## 🆕 Recently Added
+## Legend
 
-- **2025-11-09**: VAT refactoring to Pattern 2 architecture
-- **2025-11-09**: CLI architecture patterns documentation
-- **2025-11-09**: Project & brand systems analysis
-- **2025-11-08**: VAT integration into appydave-tools
+- ✅ = Exists (real file with content)
+- 📝 = Placeholder (future documentation, not yet created)
+- 🔄 = In Progress
+- 📋 = Planned
 
 ---
 
@@ -148,15 +242,16 @@ All documentation in this repository follows the [AI Conventions](../../.ai-conv
 
 ---
 
-## 🤝 Contributing
+## 🤝 Contributing Documentation
 
 When adding new documentation:
 
 1. **Choose the right location**:
-   - Tool documentation → `tools/`
-   - VAT-specific → `vat/`
-   - Developer guides → `development/`
-   - System analysis → root of `docs/`
+   - How-to guides → `guides/tools/` or `guides/platforms/`
+   - System understanding → `architecture/`
+   - Design decisions → `architecture/design-decisions/`
+   - Templates → `templates/`
+   - Contributor info → `development/`
 
 2. **Use kebab-case** for filenames (e.g., `my-new-tool.md`)
 
@@ -164,6 +259,8 @@ When adding new documentation:
 
 4. **Follow existing patterns** - check similar docs for style guidance
 
+5. **Mark status** - Use ✅ for complete docs, 📝 for placeholders
+
 ---
 
-**Last updated**: 2025-11-09
+**Last updated**: 2025-11-18