appydave-tools 0.76.4 → 0.76.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63d45ba7b83fca823b63a907473c424701e50c117ccac57cccdc1d31f2ae277c
-  data.tar.gz: 1dff3941a4d00ecc51b84b5b955c7640c955ee0037f52040e4469f5d9b007c4f
+  metadata.gz: 0531bc72c6c4aeac9830f72f552a4d683775d7efc61ee483069d882cdbbbf5af
+  data.tar.gz: 1c8e032ddc4e8dfc4c196452465abea40958107d2d68c5e4063c1ec2c36a3a9d
 SHA512:
-  metadata.gz: fa0a3525cae67422cde5aa4cc880362fbeb24b6ee5d914ece224965daa07ce61878da662aec431edf3c10d9feae53cc8ec3e383bc10fa6c8267f92ade321a8ff
-  data.tar.gz: d36d104f67799d434b592effa0e6a029b92ec1e1005216c68269ea0637f67c5fdd2867505c42b900f497d16218a425f480503c6d18cffc6afc3d64b3c9313774
+  metadata.gz: 1787f781bdf758fae98c3388cce0437aca330a3161937f5c214651885c80e05598682e64afc3adea1e2ffd3b2f70d09287a9acca12c8fada89077b7d48791a39
+  data.tar.gz: 6cadabed0aa0f0be9d993b4dbda2c304c9a34f717fcc7b86b8cc059777e7cb0a57a494ddc2c3e5432fd4d4d85990330a6d401aa75c89bb7b0be5f5207c68d12b

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [0.76.4](https://github.com/appydave/appydave-tools/compare/v0.76.3...v0.76.4) (2026-03-19)
+
+
+### Bug Fixes
+
+* add subprocess test for -f json flag to cli_spec ([de6a28a](https://github.com/appydave/appydave-tools/commit/de6a28a39790d29f5141fbf313fa5e44782b90a6))
+* restore youtube_automation_config require accidentally removed in previous commit ([e4180db](https://github.com/appydave/appydave-tools/commit/e4180db9ad90040ec4faf2811fad713a20e6be8e))
+
 ## [0.76.3](https://github.com/appydave/appydave-tools/compare/v0.76.2...v0.76.3) (2026-03-19)
 
 

data/bin/dam

@@ -515,63 +515,6 @@ class VatCLI
     brands.key?(brand_key) || brands.shortcut?(brand_key)
   end
 
-  # Add local sync status to matched projects data
-  # Mutates the matched_projects hash to add :local_status key
-  # @param matched_projects [Hash] Map of project_id => S3 data
-  # @param brand_key [String] Brand key (e.g., 'appydave', 'ss')
-  # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-  def add_local_sync_status!(matched_projects, brand_key)
-    matched_projects.each do |project_id, data|
-      project_path = Appydave::Tools::Dam::Config.project_path(brand_key, project_id)
-      s3_staging_path = File.join(project_path, 's3-staging')
-
-      if !Dir.exist?(project_path)
-        data[:local_status] = :no_project # Project directory doesn't exist
-      elsif !Dir.exist?(s3_staging_path)
-        data[:local_status] = :no_files # Project exists but no downloads yet
-      else
-        # Count local files in s3-staging
-        local_files = Dir.glob(File.join(s3_staging_path, '**', '*'))
-                         .select { |f| File.file?(f) }
-                         .reject { |f| File.basename(f).include?('Zone.Identifier') } # Exclude Windows metadata
-
-        s3_file_count = data[:file_count]
-        local_file_count = local_files.size
-
-        data[:local_status] = if local_file_count.zero?
-                                :no_files
-                              elsif local_file_count == s3_file_count
-                                :synced # Fully synced
-                              else
-                                :partial # Some files downloaded
-                              end
-
-        data[:local_file_count] = local_file_count
-      end
-    end
-  end
-  # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-
-  # Format local sync status for display
-  # @param status [Symbol] :synced, :no_files, :partial, :no_project
-  # @param local_count [Integer, nil] Number of local files
-  # @param s3_count [Integer] Number of S3 files
-  # @return [String] Formatted status string
-  def format_local_status(status, local_count, s3_count)
-    case status
-    when :synced
-      '✓ Synced'
-    when :no_files
-      '⚠ None'
-    when :partial
-      "⚠ #{local_count}/#{s3_count}"
-    when :no_project
-      '✗ Missing'
-    else
-      'Unknown'
-    end
-  end
-
   def parse_share_args(args)
     # Extract --expires flag
     expires = '7d' # default
@@ -693,14 +636,14 @@ class VatCLI
 
       # Format columns
       file_col = filename.ljust(40)
-      size_col = format_bytes(size).rjust(10)
+      size_col = Appydave::Tools::Dam::FileHelper.format_size(size).rjust(10)
       date_col = last_modified ? last_modified.strftime('%Y-%m-%d %H:%M') : 'N/A'.ljust(16)
 
       puts "#{file_col} #{size_col}     #{date_col}"
     end
 
     puts '-' * 72
-    puts "Total: #{files.size} #{files.size == 1 ? 'file' : 'files'}, #{format_bytes(total_bytes)}"
+    puts "Total: #{files.size} #{files.size == 1 ? 'file' : 'files'}, #{Appydave::Tools::Dam::FileHelper.format_size(total_bytes)}"
 
     # Quick actions section
     puts ''
@@ -1478,7 +1421,7 @@ class VatCLI
     File.write(manifest_path, JSON.pretty_generate(manifest))
 
     # Add local sync status to matched projects
-    add_local_sync_status!(matched_projects, brand_key)
+    Appydave::Tools::Dam::LocalSyncStatus.enrich!(matched_projects, brand_key)
 
     # Display table
     display_s3_scan_table(matched_projects, orphaned_projects, bucket, prefix, region)
@@ -1507,8 +1450,8 @@ class VatCLI
     # Display matched projects first (sorted alphabetically)
     matched_projects.sort.each do |project_id, data|
       files = data[:file_count].to_s.rjust(5)
-      size = format_bytes(data[:total_bytes]).rjust(10)
-      local_status = format_local_status(data[:local_status], data[:local_file_count], data[:file_count])
+      size = Appydave::Tools::Dam::FileHelper.format_size(data[:total_bytes]).rjust(10)
+      local_status = Appydave::Tools::Dam::LocalSyncStatus.format(data[:local_status], data[:local_file_count], data[:file_count])
       modified = data[:last_modified] ? Time.parse(data[:last_modified]).strftime('%Y-%m-%d %H:%M') : 'N/A'
 
       puts format('%-36s %5s %10s  %-9s  %s', project_id, files, size, local_status, modified)
@@ -1520,7 +1463,7 @@ class VatCLI
     puts '-' * 92
     orphaned_projects.sort.each do |project_id, data|
       files = data[:file_count].to_s.rjust(5)
-      size = format_bytes(data[:total_bytes]).rjust(10)
+      size = Appydave::Tools::Dam::FileHelper.format_size(data[:total_bytes]).rjust(10)
       local_status = 'N/A'
       modified = data[:last_modified] ? Time.parse(data[:last_modified]).strftime('%Y-%m-%d %H:%M') : 'N/A'
 
@@ -1582,19 +1525,6 @@ class VatCLI
     puts "Total brands scanned: #{successful.size}/#{results.size}"
   end
   # rubocop:enable Metrics/MethodLength
-
-  # Format bytes in human-readable format
-  # rubocop:disable Style/FormatStringToken
-  def format_bytes(bytes)
-    return '0 B' if bytes.zero?
-
-    units = %w[B KB MB GB TB]
-    exp = (Math.log(bytes) / Math.log(1024)).to_i
-    exp = [exp, units.length - 1].min
-
-    format('%.1f %s', bytes.to_f / (1024**exp), units[exp])
-  end
-  # rubocop:enable Style/FormatStringToken
 end
 
 # Run CLI

data/docs/planning/AGENTS.md

@@ -14,6 +14,18 @@
 
 ---
 
+## ⚠️ Pre-Commit Check (Mandatory Every Commit)
+
+Before running `kfix`, always run:
+```bash
+git status
+```
+Confirm ONLY the files you intentionally changed are staged. If unexpected files appear, run `git diff` to investigate before proceeding.
+
+**Why:** micro-cleanup (2026-03-19) accidentally staged a pre-existing uncommitted change in `lib/appydave/tools.rb` when running `kfix`.
+
+---
+
 ## Build & Run Commands
 
 ```bash
@@ -33,7 +45,7 @@ kfeat "add feature description"             # Minor version bump
 kfix "fix bug description"                  # Patch version bump
 ```
 
-**Baseline (2026-03-19):** 748 examples, 0 failures, 84.88% line coverage (7680/9048)
+**Baseline (2026-03-19):** 831 examples, 0 failures, ~85.92% line coverage
 
 ---
 
@@ -82,9 +94,9 @@ docs/
 
 Every work unit must satisfy ALL of the following before marking `[x]`:
 
-- [ ] `bundle exec rspec` — 748+ examples, 0 failures
+- [ ] `bundle exec rspec` — 831+ examples, 0 failures
 - [ ] `bundle exec rubocop --format clang` — 0 offenses
-- [ ] Line coverage stays ≥ 84.88%
+- [ ] Line coverage stays ≥ 85.92%
 - [ ] Any new functionality has ≥ 1 spec covering it
 - [ ] All new `.rb` files start with `# frozen_string_literal: true`
 - [ ] No hardcoded brand transformation strings (always use BrandResolver)
@@ -209,9 +221,9 @@ Appydave::Tools::Configuration::Config.configure
 
 ## Quality Gates
 
-- **Tests:** `bundle exec rspec` — 748 examples, 0 failures (do not ship if any fail)
+- **Tests:** `bundle exec rspec` — 831 examples, 0 failures (do not ship if any fail)
 - **Lint:** `bundle exec rubocop --format clang` — 0 offenses (CI will reject)
-- **Coverage:** ≥ 84.88% line coverage
+- **Coverage:** ≥ 85.92% line coverage
 - **frozen_string_literal:** Required on every new `.rb` file
 - **Commit format:** `kfeat`/`kfix` only — triggers semantic versioning + CI wait
 

data/docs/planning/BACKLOG.md

@@ -1,7 +1,7 @@
 # Project Backlog — AppyDave Tools
 
-**Last updated**: 2026-03-19 (final-test-gaps campaign complete; B031/B032/B033 added from quality audit)
-**Total**: 33 | Pending: 11 | Done: 22 | Deferred: 0 | Rejected: 0
+**Last updated**: 2026-03-19 (micro-cleanup campaign complete)
+**Total**: 33 | Pending: 7 | In Progress: 1 | Done: 25 | Deferred: 0 | Rejected: 0
 
 ---
 
@@ -10,16 +10,11 @@
 ### Medium Priority
 - [ ] B001 — FR-1: GPT Context token counting | Priority: medium
 - [ ] B012 — Arch: add integration tests for brand resolution end-to-end | Priority: medium
-
-### Low Priority
-- [ ] B031 — Tests: add_spec.rb assert `type` field in location data integrity test | Priority: low
-- [ ] B032 — Tests: cli_spec.rb add subprocess test for `-f json` flag | Priority: low
-- [ ] B033 — Fix: file_collector.rb line 19 return `''` directly when working_directory doesn't exist | Priority: low
 - [ ] B007 — Performance: parallel git/S3 status checks for dam list | Priority: low
 - [ ] B008 — Performance: cache git/S3 status with 5-min TTL | Priority: low
 - [ ] B009 — UX: progress indicators for dam operations > 5s | Priority: low
 - [ ] B010 — UX: auto-adjust dam table column widths to terminal width | Priority: low
-- [ ] B011 — Arch: extract VatCLI business logic from bin/dam (1,600-line God class) | Priority: low
+- [~] B011 — Arch: extract VatCLI business logic from bin/dam (1,600-line God class) | Campaign: extract-vat-cli
 - [ ] B020 — Arch: split S3Operations (1,030 lines, mixed I/O + logic) | Priority: low
 
 ---
@@ -48,6 +43,9 @@
 - [x] B028 — Tests: cli_spec file body content assertions in -i/-e tests | Completed: final-test-gaps (2026-03-19)
 - [x] B029 — Tests: add_spec validate all returned location data fields | Completed: final-test-gaps (2026-03-19)
 - [x] B030 — Tests: update_spec verify non-updated fields unchanged | Completed: final-test-gaps (2026-03-19)
+- [x] B031 — Tests: add_spec `type` field assertion | Completed: already in commit 8eec40c; closed micro-cleanup (2026-03-19)
+- [x] B032 — Tests: cli_spec `-f json` subprocess test | Completed: micro-cleanup (2026-03-19), v0.76.4
+- [x] B033 — Fix: file_collector.rb return `''` when working_directory missing | Completed: already in commit 13d5f87; closed micro-cleanup (2026-03-19)
 
 ---
 

data/docs/planning/extract-vat-cli/AGENTS.md

@@ -0,0 +1,363 @@
+# AGENTS.md — AppyDave Tools / extract-vat-cli campaign
+
+> Operational knowledge for every background agent. Self-contained — you receive only this file + your work unit prompt.
+> Last updated: 2026-03-19 (extract-vat-cli campaign)
+
+---
+
+## Project Overview
+
+**What:** Ruby gem providing CLI productivity tools for AppyDave's YouTube content creation workflow.
+**Stack:** Ruby 3.4.2, Bundler 2.6.2, RSpec, RuboCop, semantic-release CI/CD.
+**Active campaign:** extract-vat-cli — extracting business logic from `bin/dam` (1,600-line God class) into proper library classes.
+**Commits:** Trigger automated semantic versioning via GitHub Actions. Always use `kfeat`/`kfix` — never `git commit`.
+
+---
+
+## ⚠️ Pre-Commit Check (Mandatory Every Commit)
+
+Before running `kfix`, always run:
+```bash
+git status
+```
+Confirm ONLY the files you intentionally changed are staged. If unexpected files appear, run `git diff` to investigate before proceeding. Never commit files you didn't intentionally change.
+
+**Why:** Prior campaign (micro-cleanup) accidentally staged a pre-existing uncommitted change in `lib/appydave/tools.rb` when running `kfix`. This required a follow-up fix commit.
+
+---
+
+## Build & Run Commands
+
+```bash
+# Initialize rbenv (required if rbenv not in PATH)
+eval "$(rbenv init -)"
+
+# Run tests
+bundle exec rspec                           # All tests
+bundle exec rspec spec/path/to/file_spec.rb # Single file
+RUBYOPT="-W0" bundle exec rspec             # Suppress Ruby 3.4 platform warnings
+
+# Lint
+bundle exec rubocop --format clang          # Standard lint check (matches CI)
+
+# Commit (never use git commit directly)
+kfeat "add feature description"             # Minor version bump
+kfix "fix bug description"                  # Patch version bump
+```
+
+**Baseline (2026-03-19):** 831 examples, 0 failures, ~85.92% line coverage
+
+---
+
+## Directory Structure
+
+```
+bin/                          CLI scripts (development, .rb extension)
+exe/                          Thin wrappers for gem installation (no .rb extension)
+lib/appydave/tools/
+  dam/                        Digital Asset Management — main active area
+    brand_resolver.rb         Centralizes ALL brand name transformations (appydave ↔ v-appydave)
+    errors.rb                 Custom exception hierarchy (DamError, BrandNotFoundError, etc.)
+    fuzzy_matcher.rb          Levenshtein distance for "did you mean?" suggestions
+    git_helper.rb             Extracted git command wrappers (current_branch, commits_ahead, etc.)
+    file_helper.rb            File utility methods (calculate_directory_size, format_size, format_age)
+    config.rb                 Delegates brand resolution to BrandResolver; memoized Config loading
+    project_resolver.rb       Project name resolution with regex pattern matching
+    project_listing.rb        Table display for `dam list` command (format() for headers + data)
+    s3_operations.rb          S3 upload/download/status with MD5 comparison
+    s3_scanner.rb             S3 bucket scanner for s3-scan command
+    status.rb                 Project git/S3 status display
+    manifest_generator.rb     Video project manifest
+    sync_from_ssd.rb          SSD sync operations
+    ssd_status.rb             SSD backup status
+    share_operations.rb       Pre-signed URL generation
+    config_loader.rb          Loads .video-tools.env per brand
+    repo_push.rb, repo_status.rb, repo_sync.rb
+    # NEW — being created in this campaign:
+    local_sync_status.rb      [WU2] Enrich project data with local s3-staging sync status
+    s3_scan_command.rb        [WU3] S3 scan orchestration + display (extracted from VatCLI)
+    s3_arg_parser.rb          [WU4] CLI argument parsing for S3 commands (extracted from VatCLI)
+lib/appydave/tools.rb         Require file — ADD new dam files here after creating them
+spec/
+  appydave/tools/dam/         One spec file per dam/ class
+  support/
+    dam_filesystem_helpers.rb Shared contexts for DAM filesystem testing
+```
+
+---
+
+## This Campaign: What We're Extracting from bin/dam
+
+`bin/dam` is a 1,600-line `VatCLI` class with 20+ `rubocop-disable` comments. Four clusters of business logic are being extracted.
+
+### Work Unit Dependencies
+
+All 4 work units touch `bin/dam`. Run SEQUENTIALLY — never in parallel.
+
+```
+WU1: extract-format-bytes        (no deps)
+WU2: extract-local-sync-status   (no deps — but WU3 depends on it)
+WU3: extract-s3-scan-command     (DEPENDS ON WU2 — uses LocalSyncStatus)
+WU4: extract-s3-arg-parser       (no deps on WU1-3 — run after WU3 for safety)
+```
+
+### WU1: extract-format-bytes
+
+**What:** `VatCLI#format_bytes` is a duplicate of `FileHelper.format_size` (already exists, already tested).
+
+**Change:**
+- Replace 3 callers in `bin/dam` with `Appydave::Tools::Dam::FileHelper.format_size(x)`:
+  - Line 1510 in `display_s3_scan_table`
+  - Line 696 in `display_s3_files`
+  - Line 702 in `display_s3_files`
+- Delete `format_bytes` method from VatCLI (lines 1586-1597, including rubocop-disable/enable wrapper)
+- No new spec needed — `FileHelper.format_size` already has specs
+
+**Done when:** rubocop 0 offenses, 831 examples passing, `format_bytes` gone from bin/dam.
+
+### WU2: extract-local-sync-status
+
+**What:** `add_local_sync_status!` and `format_local_status` are VatCLI private methods. They contain business logic (filesystem inspection + status classification) that belongs in a library class.
+
+**Create** `lib/appydave/tools/dam/local_sync_status.rb`:
+```ruby
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    module Dam
+      # Enriches S3 scan project data with local s3-staging sync status
+      module LocalSyncStatus
+        module_function
+
+        # Mutates matched_projects hash to add :local_status key
+        # @param matched_projects [Hash] Map of project_id => S3 data
+        # @param brand_key [String] Brand key (e.g., 'appydave')
+        def enrich!(matched_projects, brand_key)
+          # (move add_local_sync_status! body here — change Config.project_path call to use Dam::Config)
+        end
+
+        # Format local sync status for display
+        # @param status [Symbol] :synced, :no_files, :partial, :no_project
+        # @param local_count [Integer, nil] Number of local files
+        # @param s3_count [Integer] Number of S3 files
+        # @return [String] Formatted status string
+        def format(status, local_count, s3_count)
+          # (move format_local_status body here)
+        end
+      end
+    end
+  end
+end
+```
+
+**Update callers in bin/dam:**
+- `scan_single_brand_s3`: replace `add_local_sync_status!(matched_projects, brand_key)` with `Appydave::Tools::Dam::LocalSyncStatus.enrich!(matched_projects, brand_key)`
+- `display_s3_scan_table`: replace `format_local_status(data[:local_status], data[:local_file_count], data[:file_count])` with `Appydave::Tools::Dam::LocalSyncStatus.format(data[:local_status], data[:local_file_count], data[:file_count])`
+
+**Register** in `lib/appydave/tools.rb` after line 79: `require 'appydave/tools/dam/local_sync_status'`
+
+**Add spec** `spec/appydave/tools/dam/local_sync_status_spec.rb` — test `enrich!` with a temp filesystem (use `include_context 'with vat filesystem and brands'`), test `format` for all 4 status symbols.
+
+**Done when:** rubocop 0 offenses, 832+ examples passing (new specs), `add_local_sync_status!` and `format_local_status` gone from bin/dam.
+
+### WU3: extract-s3-scan-command
+
+**What:** `scan_single_brand_s3`, `scan_all_brands_s3`, and `display_s3_scan_table` are 140 lines of orchestration + display logic in VatCLI. Extract to a new class.
+
+**Prerequisite:** WU2 must be complete — `S3ScanCommand` uses `LocalSyncStatus.enrich!` and `LocalSyncStatus.format`.
+
+**Create** `lib/appydave/tools/dam/s3_scan_command.rb` — class with:
+- `scan_single(brand_key)` — body from `scan_single_brand_s3`
+- `scan_all` — body from `scan_all_brands_s3`
+- `display_table(matched_projects, orphaned_projects, bucket, prefix, region)` — body from `display_s3_scan_table` (private, called from scan_single)
+
+**Update bin/dam:**
+```ruby
+def s3_scan_command(args)
+  all_brands = args.include?('--all')
+  args = args.reject { |arg| arg.start_with?('--') }
+  brand_arg = args[0]
+
+  if all_brands
+    Appydave::Tools::Dam::S3ScanCommand.new.scan_all
+  elsif brand_arg
+    Appydave::Tools::Dam::S3ScanCommand.new.scan_single(brand_arg)
+  else
+    # show usage (keep inline — 4 lines)
+  end
+rescue StandardError => e
+  puts "❌ Error: #{e.message}"
+  puts e.backtrace.first(5).join("\n") if ENV['DEBUG']
+  exit 1
+end
+```
+Delete `scan_single_brand_s3`, `scan_all_brands_s3`, `display_s3_scan_table` from VatCLI.
+
+**Register** in `lib/appydave/tools.rb`: `require 'appydave/tools/dam/s3_scan_command'`
+
+**Add spec** `spec/appydave/tools/dam/s3_scan_command_spec.rb` — smoke test that the class loads and methods exist; mock `S3Scanner` and `Config`; no full S3 integration needed.
+
+**Done when:** rubocop 0 offenses, 832+ examples passing, 3 methods gone from bin/dam.
+
+### WU4: extract-s3-arg-parser
+
+**What:** `parse_s3_args`, `valid_brand?`, `parse_share_args`, `show_share_usage_and_exit`, `parse_discover_args` are 130 lines of argument parsing in VatCLI. All set `ENV['BRAND_PATH']` and share the same brand/project resolution chain.
+
+**Create** `lib/appydave/tools/dam/s3_arg_parser.rb` — module with `module_function`:
+- `parse_s3(args, command)` — from `parse_s3_args`
+- `parse_share(args)` — from `parse_share_args`
+- `parse_discover(args)` — from `parse_discover_args`
+- `valid_brand?(brand_key)` — from `valid_brand?` (private helper, keep as module_function)
+- `show_share_usage_and_exit` — from `show_share_usage_and_exit` (private helper)
+
+**Update callers in bin/dam** (5 methods to update):
+- `s3_up_command`, `s3_down_command`, `s3_status_command`, `s3_cleanup_remote_command`, `s3_cleanup_local_command`, `archive_command`: replace `parse_s3_args(args, '...')` with `Appydave::Tools::Dam::S3ArgParser.parse_s3(args, '...')`
+- `s3_share_command`: replace `parse_share_args(args)` with `Appydave::Tools::Dam::S3ArgParser.parse_share(args)`
+- `s3_discover_command`: replace `parse_discover_args(args)` with `Appydave::Tools::Dam::S3ArgParser.parse_discover(args)`
+
+**Register** in `lib/appydave/tools.rb`: `require 'appydave/tools/dam/s3_arg_parser'`
+
+**Add spec** `spec/appydave/tools/dam/s3_arg_parser_spec.rb` — test `parse_s3` with brand+project args, with PWD auto-detect (mock `ProjectResolver.detect_from_pwd`), with invalid brand; test `valid_brand?` with known brands.
+
+**Done when:** rubocop 0 offenses, 833+ examples passing, 5 methods gone from bin/dam.
+
+---
+
+## Success Criteria
+
+Every work unit must satisfy ALL of the following before marking `[x]`:
+
+- [ ] `RUBYOPT="-W0" bundle exec rspec` — 831+ examples, 0 failures
+- [ ] `bundle exec rubocop --format clang` — 0 offenses
+- [ ] Line coverage stays ≥ 85.92%
+- [ ] Any new `.rb` files start with `# frozen_string_literal: true`
+- [ ] New class/module registered in `lib/appydave/tools.rb`
+- [ ] At least 1 spec for each new library file
+- [ ] Extracted methods removed from VatCLI in `bin/dam`
+- [ ] `git status` confirmed clean before `kfix`
+
+---
+
+## Reference Patterns
+
+### Shared Context for DAM Specs — THE STANDARD PATTERN
+
+```ruby
+# spec/appydave/tools/dam/some_class_spec.rb
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Appydave::Tools::Dam::SomeClass do
+  include_context 'with vat filesystem and brands', brands: %w[appydave voz]
+
+  before do
+    FileUtils.mkdir_p(File.join(appydave_path, 'b65-test-project'))
+  end
+
+  describe '.some_method' do
+    it 'does the thing' do
+      expect(described_class.some_method('appydave')).to eq('expected')
+    end
+  end
+end
+```
+
+**Available from shared context:**
+- `temp_folder` — temp root (auto-cleaned after each example)
+- `projects_root` — `/path/to/temp/video-projects`
+- `appydave_path`, `voz_path`, etc. — brand dirs (created on demand)
+- `SettingsConfig#video_projects_root` is mocked to return `projects_root`
+
+### FileHelper — Use These, Don't Duplicate
+
+```ruby
+Appydave::Tools::Dam::FileHelper.format_size(bytes)          # "1.5 GB"
+Appydave::Tools::Dam::FileHelper.calculate_directory_size(path) # Integer bytes
+Appydave::Tools::Dam::FileHelper.format_age(time)            # "3d", "2w", etc.
+```
+
+### BrandResolver — All Brand Name Transformations
+
+```ruby
+BrandResolver.expand('appydave')      # => 'v-appydave'
+BrandResolver.expand('ad')            # => 'v-appydave' (shortcut)
+BrandResolver.normalize('v-appydave') # => 'appydave'
+BrandResolver.validate('appydave')    # => 'appydave' or raises BrandNotFoundError
+```
+
+### Typed Exception Pattern
+
+```ruby
+raise ProjectNotFoundError, 'Project name is required' if project_hint.nil?
+raise BrandNotFoundError.new(brand, available_brands, fuzzy_suggestions)
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+- ❌ Inline brand transformations — never write `"v-#{brand}"` outside BrandResolver
+- ❌ `format_bytes` — does not exist anymore; use `FileHelper.format_size`
+- ❌ Duplicating `format_size` / byte formatting logic — use `FileHelper.format_size`
+- ❌ Mocking Config class methods in DAM specs — use shared filesystem context instead
+- ❌ Multiple `before` blocks in same RSpec context — merge them (triggers RSpec/ScatteredSetup)
+- ❌ `$?` for subprocess status — use `$CHILD_STATUS` (rubocop Style/SpecialGlobalVars)
+- ❌ `raise 'string error'` in DAM module — use typed exceptions from `errors.rb`
+- ❌ `include FileUtils` — use dam's `FileHelper` instead
+- ❌ Hardcoded header strings for table output — always use `format()` matching data row format
+- ❌ Adding new `Config.configure` calls — memoized but called redundantly; don't spread further
+
+---
+
+## Mock Patterns
+
+### ENV Stubbing (if needed in specs)
+
+```ruby
+allow(ENV).to receive(:[]).and_call_original
+allow(ENV).to receive(:[]).with('BRAND_PATH').and_return('/tmp/test/v-appydave')
+```
+
+**Do NOT use climate_control gem** — project doesn't have it.
+
+### External Services
+
+```ruby
+# S3 calls
+stub_request(:get, /s3\.amazonaws\.com/).to_return(body: '...')
+```
+
+---
+
+## Quality Gates
+
+- **Tests:** `RUBYOPT="-W0" bundle exec rspec` — 831+ examples, 0 failures
+- **Lint:** `bundle exec rubocop --format clang` — 0 offenses (CI will reject)
+- **Coverage:** ≥ 85.92% line coverage
+- **frozen_string_literal:** Required on every new `.rb` file
+- **Commit format:** `kfeat`/`kfix` only — triggers semantic versioning + CI wait
+- **Pre-commit:** Always run `git status` before `kfix` — confirm staged files
+
+---
+
+## Learnings
+
+### From DAM Enhancement Sprint (Jan 2025)
+
+- **BrandResolver is the critical path.** All `dam` commands flow through it. Any change to brand resolution must be tested with all shortcuts.
+- **`Regexp.last_match` is reset by `.sub()` calls.** Always capture regex groups BEFORE any string transformation.
+- **`Config.configure` is memoized but called redundantly.** Don't add new calls.
+- **Table format() pattern is non-obvious.** Headers misaligned 3 times in UAT. Always verify with real data.
+
+### From micro-cleanup (2026-03-19)
+
+- **Dirty working tree + kfix = accidental staging.** Always run `git status` before committing. micro-cleanup accidentally staged a pre-existing `lib/appydave/tools.rb` change.
+- **Pre-existing "already fixed" items:** Check B-items aren't already done before acting (B031, B033 were already committed; B015, B019 also).
+
+### From Architectural Review (2026-03-19)
+
+- **bin/dam is the primary DAM CLI entry point.** Regressions here affect real workflows. Test every command path after extraction.
+- **`ENV['BRAND_PATH']` is set in 5 places in bin/dam.** Three are in parse methods (being extracted). Two remain in `generate_single_manifest` and `sync_ssd_command` — out of scope.
+- **Do NOT attempt B020 (split S3Operations) in this campaign.** Different class, different risk profile.

data/docs/planning/extract-vat-cli/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,61 @@
+# IMPLEMENTATION_PLAN.md — extract-vat-cli
+
+**Goal**: Extract 4 clusters of business logic from `bin/dam` (1,600-line VatCLI God class) into proper library classes. Prerequisite for parallelism (B007) and S3Operations split (B020).
+**Started**: 2026-03-19
+**Target**: All 4 complete; 831+ examples passing; rubocop 0 offenses; no regressions
+
+## Summary
+- Total: 4 | Complete: 0 | In Progress: 0 | Pending: 4 | Failed: 0
+
+## Pending
+- [x] extract-format-bytes — Replaced 4 callers (plan said 3; orphaned-projects loop in display_s3_scan_table was a 4th). format_bytes deleted. rubocop 0 offenses. Commit: 3cd362f.
+- [~] extract-local-sync-status — Extract `add_local_sync_status!` + `format_local_status` → new `LocalSyncStatus` module; add spec; update callers in bin/dam
+- [ ] extract-s3-scan-command — Extract `scan_single_brand_s3` + `scan_all_brands_s3` + `display_s3_scan_table` → new `S3ScanCommand` class; add spec; **depends on extract-local-sync-status completing first**
+- [ ] extract-s3-arg-parser — Extract `parse_s3_args` + `valid_brand?` + `parse_share_args` + `show_share_usage_and_exit` + `parse_discover_args` → new `S3ArgParser` class; add spec
+
+## In Progress
+
+## Complete
+
+## Failed / Needs Retry
+
+## Notes & Decisions
+
+### Sequencing
+All 4 work units touch `bin/dam` — they MUST run sequentially, not in parallel. Wave size = 1.
+Sequence: extract-format-bytes → extract-local-sync-status → extract-s3-scan-command → extract-s3-arg-parser
+`extract-s3-scan-command` depends on `LocalSyncStatus` created in `extract-local-sync-status`.
+
+### New files to create
+- `lib/appydave/tools/dam/local_sync_status.rb`
+- `lib/appydave/tools/dam/s3_scan_command.rb`
+- `lib/appydave/tools/dam/s3_arg_parser.rb`
+
+### Register new files
+Add require lines to `lib/appydave/tools.rb` after line 79 (after `repo_push`):
+```ruby
+require 'appydave/tools/dam/local_sync_status'
+require 'appydave/tools/dam/s3_scan_command'
+require 'appydave/tools/dam/s3_arg_parser'
+```
+
+### format_bytes caller locations in bin/dam
+- Line 1510: `display_s3_scan_table` → `format_bytes(data[:total_bytes])`
+- Line 696: `display_s3_files` → `format_bytes(size)`
+- Line 702: `display_s3_files` → `format_bytes(total_bytes)`
+Replace all with: `Appydave::Tools::Dam::FileHelper.format_size(x)`
+
+### FileHelper.format_size vs format_bytes
+Both return identical output. `format_size` uses named format tokens (`%<size>.1f`) which satisfies rubocop Style/FormatStringToken. `format_bytes` used positional tokens (`%.1f`) — hence the rubocop-disable. After extraction, the disable comment goes away.
+
+### parse_share_args scope decision
+Included `parse_share_args` + `show_share_usage_and_exit` + `parse_discover_args` in S3ArgParser (same ENV['BRAND_PATH'] pattern, same brand/project resolution chain). All 5 parser methods share identical structure and belong together.
+
+### ENV['BRAND_PATH'] residuals
+After S3ArgParser extraction, 2 ENV['BRAND_PATH'] assignments remain in VatCLI:
+- `generate_single_manifest` (line 278)
+- `sync_ssd_command` (line 325)
+These are out of scope — leave for a future campaign.
+
+### Do NOT attempt B020 (S3Operations split) in this campaign
+Scope is VatCLI extraction only. S3Operations refactor is a separate campaign.

data/docs/planning/micro-cleanup/IMPLEMENTATION_PLAN.md

@@ -5,14 +5,16 @@
 **Target**: All 3 complete; 830+ examples passing; rubocop clean; no regressions
 
 ## Summary
-- Total: 3 | Complete: 0 | In Progress: 3 | Pending: 0 | Failed: 0
+- Total: 3 | Complete: 3 | In Progress: 0 | Pending: 0 | Failed: 0
 
 ## Pending
 
 ## In Progress
-- [~] fix-b031 — add_spec: add `type` field assertion to location data integrity test
-- [~] fix-b032 — cli_spec: add subprocess test for `-f json` flag
-- [~] fix-b033 — file_collector.rb: return `''` directly when working_directory doesn't exist (line 19)
+
+## Complete
+- [x] fix-b031 — already committed in prior pass (commit 8eec40c). Assertion `expect(location[:type]).to eq('tool')` found at add_spec.rb line 51. Closed without action.
+- [x] fix-b033 — already fixed in commit 13d5f87 (`return '' unless` already in place). Closed without action.
+- [x] fix-b032 — added `-f json` subprocess test to cli_spec. 831 examples, 0 failures, v0.76.4. Side issue: kfix accidentally staged pre-existing uncommitted changes to lib/appydave/tools.rb (removed youtube_automation_config require). Fixed in follow-up commit.
 
 ## Complete
 

data/docs/planning/micro-cleanup/assessment.md

@@ -0,0 +1,68 @@
+# Assessment: micro-cleanup
+
+**Campaign**: micro-cleanup
+**Date**: 2026-03-19 → 2026-03-19
+**Results**: 3 complete, 0 failed
+**Version shipped**: v0.76.4
+**Quality audit**: code-quality-audit + test-quality-audit run post-campaign
+
+---
+
+## Results Summary
+
+| Work Unit | Action | Notes |
+|-----------|--------|-------|
+| fix-b031 | Already done | `expect(location[:type]).to eq('tool')` found committed in 8eec40c — closed without action |
+| fix-b033 | Already done | `return '' unless` on line 19 found committed in 13d5f87 — closed without action |
+| fix-b032 | +1 example | `-f json` subprocess test added to cli_spec. 831 examples, 0 failures, v0.76.4 |
+
+**830 → 831 examples (+1). Coverage stable at ~85.92%.**
+
+---
+
+## What Worked Well
+
+- **Agents check before acting.** Both B031 and B033 agents read the files, found the work already done, and correctly closed without creating duplicate commits. No false-positive churn.
+- **B032 json test is clean.** `Dir.mktmpdir` + subprocess + `JSON.parse` + key assertions — follows the established cli_spec pattern exactly.
+- **CI caught the staging error immediately.** The accidental require removal was detected by CI on the first push — the safety net worked as intended.
+
+---
+
+## What Didn't Work
+
+**kfix staged pre-existing uncommitted changes.**
+
+The B032 agent's `kfix` commit accidentally included local changes to `lib/appydave/tools.rb` that deleted `require 'appydave/tools/configuration/models/youtube_automation_config'` and related lines. These were pre-existing uncommitted modifications floating in the working tree — unrelated to fix-b032. CI failed. A follow-up commit restored the requires and CI passed.
+
+**Root cause:** A prior session left the working tree in a dirty state. The agent did not run `git status` before committing, so it didn't catch the unintended changes in the staging area.
+
+---
+
+## Key Learnings — Application
+
+- **Run `git status` before `kfix`.** Agents must check what's actually staged before committing. If unexpected files appear, abort and investigate. Add this to AGENTS.md as a mandatory pre-commit step.
+- **kfix commits everything staged** — it does not limit itself to files the agent touched. A dirty working tree is a silent risk on every campaign.
+- **B033 and B031 were already closed by prior agents.** This confirms the prior campaign agents were doing thorough work — they fixed things beyond their assigned scope. Good behaviour, but worth tracking so plans don't redundantly assign already-done work.
+
+---
+
+## New Backlog Items
+
+None. The quality audit found no new gaps. Suite is at B+ for GptContext CLI, B overall.
+
+---
+
+## Suggestions for Next Campaign
+
+**Start B011 — extract VatCLI from bin/dam.**
+
+The test suite is at B grade (75-80% regression catch rate). The production code is clean. The CI pipeline is reliable. All prerequisites for architectural work are met.
+
+**Pre-campaign mandatory steps for B011:**
+1. Run `git status` — confirm working tree is clean before launching agents
+2. Read `bin/dam` in full before writing AGENTS.md — 1,600 lines, surprises expected
+3. Run rubocop on bin/dam to count current offenses (20+ rubocop-disable comments)
+4. Baseline: 831 examples, 0 failures — confirm before starting
+
+**Add to AGENTS.md for B011:**
+> Before running `kfix`, always run `git status` and confirm only the expected files appear in the staged/unstaged list. If unexpected files appear, run `git diff` to investigate before committing.

data/lib/appydave/tools/dam/local_sync_status.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    module Dam
+      # Enriches S3 scan project data with local s3-staging sync status
+      module LocalSyncStatus
+        module_function
+
+        # Mutates matched_projects hash to add :local_status and :local_file_count keys
+        # @param matched_projects [Hash] Map of project_id => S3 data hash
+        # @param brand_key [String] Brand key (e.g., 'appydave')
+        def enrich!(matched_projects, brand_key)
+          matched_projects.each do |project_id, data|
+            project_path = Appydave::Tools::Dam::Config.project_path(brand_key, project_id)
+            s3_staging_path = File.join(project_path, 's3-staging')
+
+            if !Dir.exist?(project_path)
+              data[:local_status] = :no_project # Project directory doesn't exist
+            elsif !Dir.exist?(s3_staging_path)
+              data[:local_status] = :no_files # Project exists but no downloads yet
+            else
+              # Count local files in s3-staging
+              local_files = Dir.glob(File.join(s3_staging_path, '**', '*'))
+                               .select { |f| File.file?(f) }
+                               .reject { |f| File.basename(f).include?('Zone.Identifier') } # Exclude Windows metadata
+
+              s3_file_count = data[:file_count]
+              local_file_count = local_files.size
+
+              data[:local_status] = if local_file_count.zero?
+                                      :no_files
+                                    elsif local_file_count == s3_file_count
+                                      :synced # Fully synced
+                                    else
+                                      :partial # Some files downloaded
+                                    end
+
+              data[:local_file_count] = local_file_count
+            end
+          end
+        end
+
+        # Format local sync status symbol for display
+        # @param status [Symbol] :synced, :no_files, :partial, :no_project
+        # @param local_count [Integer, nil] Number of local files
+        # @param s3_count [Integer] Number of S3 files
+        # @return [String] Formatted status string
+        def format(status, local_count, s3_count)
+          case status
+          when :synced
+            '✓ Synced'
+          when :no_files
+            '⚠ None'
+          when :partial
+            "⚠ #{local_count}/#{s3_count}"
+          when :no_project
+            '✗ Missing'
+          else
+            'Unknown'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/appydave/tools/version.rb

@@ -2,6 +2,6 @@
 
 module Appydave
   module Tools
-    VERSION = '0.76.4'
+    VERSION = '0.76.5'
   end
 end

data/lib/appydave/tools.rb

@@ -78,6 +78,7 @@ require 'appydave/tools/dam/ssd_status'
 require 'appydave/tools/dam/repo_status'
 require 'appydave/tools/dam/repo_sync'
 require 'appydave/tools/dam/repo_push'
+require 'appydave/tools/dam/local_sync_status'
 
 require 'appydave/tools/jump/path_validator'
 require 'appydave/tools/jump/location'
@@ -96,8 +97,6 @@ require 'appydave/tools/jump/commands/report'
 require 'appydave/tools/jump/commands/generate'
 require 'appydave/tools/jump/cli'
 
-require 'appydave/tools/youtube_automation/gpt_agent'
-
 require 'appydave/tools/youtube_manager/models/youtube_details'
 require 'appydave/tools/youtube_manager/models/captions'
 require 'appydave/tools/youtube_manager/youtube_base'

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appydave-tools",
-  "version": "0.76.4",
+  "version": "0.76.5",
   "description": "AppyDave YouTube Automation Tools",
   "scripts": {
     "release": "semantic-release"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appydave-tools
 version: !ruby/object:Gem::Version
-  version: 0.76.4
+  version: 0.76.5
 platform: ruby
 authors:
 - David Cruwys
@@ -300,6 +300,8 @@ files:
 - docs/planning/bugfix-and-security/AGENTS.md
 - docs/planning/bugfix-and-security/IMPLEMENTATION_PLAN.md
 - docs/planning/bugfix-and-security/assessment.md
+- docs/planning/extract-vat-cli/AGENTS.md
+- docs/planning/extract-vat-cli/IMPLEMENTATION_PLAN.md
 - docs/planning/final-test-gaps/AGENTS.md
 - docs/planning/final-test-gaps/IMPLEMENTATION_PLAN.md
 - docs/planning/final-test-gaps/assessment.md
@@ -308,6 +310,7 @@ files:
 - docs/planning/fr2-gpt-context-help/assessment.md
 - docs/planning/micro-cleanup/AGENTS.md
 - docs/planning/micro-cleanup/IMPLEMENTATION_PLAN.md
+- docs/planning/micro-cleanup/assessment.md
 - docs/planning/test-coverage-gaps/AGENTS.md
 - docs/planning/test-coverage-gaps/IMPLEMENTATION_PLAN.md
 - docs/planning/test-coverage-gaps/assessment.md
@@ -351,6 +354,7 @@ files:
 - lib/appydave/tools/dam/file_helper.rb
 - lib/appydave/tools/dam/fuzzy_matcher.rb
 - lib/appydave/tools/dam/git_helper.rb
+- lib/appydave/tools/dam/local_sync_status.rb
 - lib/appydave/tools/dam/manifest_generator.rb
 - lib/appydave/tools/dam/project_listing.rb
 - lib/appydave/tools/dam/project_resolver.rb