appydave-tools 0.76.6 → 0.76.8

data/docs/planning/library-boundary-cleanup/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,61 @@
+# IMPLEMENTATION_PLAN.md — library-boundary-cleanup
+
+**Goal**: Fix two architectural boundary violations introduced by extract-vat-cli, then fill the test gaps they blocked. Prerequisite for B007 (parallelism) and clean library boundaries.
+**Started**: 2026-03-19
+**Target**: 4 items complete; 847+ examples passing; rubocop 0 offenses; no regressions
+
+## Summary
+- Total: 4 | Complete: 0 | In Progress: 1 | Pending: 3 | Failed: 0
+
+## Pending
+- [ ] B035 — extract-env-side-effect — Remove `ENV['BRAND_PATH']` side-effect from S3ArgParser; return `brand_path:` in result hash; update VatCLI callers (DEPENDS ON B034)
+- [ ] B036 — tests-s3-scan-command — Rebuild S3ScanCommand spec from D-grade to B; 8–10 examples covering happy path, manifest missing, empty results, orphaned projects (DEPENDS ON B034)
+- [ ] B037 — tests-local-sync-status — Add :partial case, local_file_count assertion, Zone.Identifier exclusion, unknown format guard
+
+## In Progress
+- [~] B034 — extract-exit-calls — Replace `exit 1` with typed exceptions in S3ScanCommand + S3ArgParser; add `UsageError` to errors.rb
+
+## Complete
+
+## Failed / Needs Retry
+
+## Notes & Decisions
+
+### Wave Plan
+
+**Wave 1 — B034** (alone)
+- Touches: `s3_scan_command.rb`, `s3_arg_parser.rb`, `errors.rb`
+- No parallel candidates — all three files must be edited together
+
+**Wave 2 — B035** (after B034)
+- Touches: `s3_arg_parser.rb`, `bin/dam`
+- Cannot run with B034 (shared `s3_arg_parser.rb`)
+- No behaviour change — moves ENV side-effect to CLI layer only
+
+**Wave 3 — B036 + B037** (parallel — different spec files, no shared edits)
+- B036: `spec/appydave/tools/dam/s3_scan_command_spec.rb`
+- B037: `spec/appydave/tools/dam/local_sync_status_spec.rb`
+- Both depend on B034 being complete (exceptions must exist before testing them)
+
+### Sequencing Constraints
+- B034 must complete before B035 (both touch s3_arg_parser.rb)
+- B034 must complete before B036 (can't test raised exceptions until they exist)
+- B035 must complete before B036 + B037 (ENV side-effect removal may affect test setup)
+- B036 and B037 are fully parallel once B034 + B035 are done
+
+### Exit Locations Confirmed (read 2026-03-19)
+- `S3ScanCommand#scan_single` line 55: manifest not found → raise `ConfigurationError`
+- `S3ArgParser#parse_s3` line 25: PWD auto-detect fail → raise `UsageError`
+- `S3ArgParser#parse_s3` line 43: invalid brand → raise `UsageError`
+- `S3ArgParser#parse_discover` line 100: missing brand/project args → raise `UsageError`
+- `S3ArgParser#show_share_usage_and_exit` line 131: missing share args → raise `UsageError`
+
+### ENV Side-Effect Locations Confirmed (read 2026-03-19)
+- `S3ArgParser#parse_s3` line 51: `ENV['BRAND_PATH'] = ...`
+- `S3ArgParser#parse_share` line 82: `ENV['BRAND_PATH'] = ...`
+- `S3ArgParser#parse_discover` line 108: `ENV['BRAND_PATH'] = ...`
+- Fix: return `brand_path:` in each result hash; update VatCLI callers to set ENV there
+
+### VatCLI Rescue Blocks
+- `s3_scan_command`, `s3_up_command`, etc. already rescue `StandardError => e` and `puts "❌ Error: #{e.message}"`
+- No VatCLI rescue changes needed for B034 — existing rescues already catch DamError (which inherits from StandardError)

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

@@ -34,6 +34,9 @@ module Appydave
 
       # Raised when git operation fails
       class GitOperationError < DamError; end
+
+      # Raised when CLI arguments are invalid or missing
+      class UsageError < DamError; end
     end
   end
 end

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    module Dam
+      # Parses and validates CLI arguments for S3-related dam commands
+      # Handles brand resolution, project lookup, flag extraction, and ENV setup
+      module S3ArgParser
+        module_function
+
+        def parse_s3(args, command)
+          dry_run = args.include?('--dry-run')
+          force = args.include?('--force')
+          args = args.reject { |arg| arg.start_with?('--') }
+
+          brand_arg = args[0]
+          project_arg = args[1]
+
+          if brand_arg.nil?
+            # Auto-detect from PWD
+            brand, project_id = Appydave::Tools::Dam::ProjectResolver.detect_from_pwd
+            if brand.nil? || project_id.nil?
+              raise Appydave::Tools::Dam::UsageError,
+                    "Could not auto-detect brand/project from current directory. Usage: dam #{command} <brand> <project> [--dry-run]"
+            end
+            brand_key = brand # Already detected, use as-is
+          else
+            # Validate brand exists before trying to resolve project
+            unless valid_brand?(brand_arg)
+              raise Appydave::Tools::Dam::UsageError,
+                    "Invalid brand: '#{brand_arg}'. Valid brands: appydave, voz, aitldr, kiros, joy, ss. Usage: dam #{command} <brand> <project> [--dry-run]"
+            end
+
+            brand_key = brand_arg # Use the shortcut/key (e.g., 'appydave')
+            brand = Appydave::Tools::Dam::Config.expand_brand(brand_arg) # Expand for path resolution
+            project_id = Appydave::Tools::Dam::ProjectResolver.resolve(brand_arg, project_arg)
+          end
+
+          # Set ENV for compatibility with ConfigLoader
+          ENV['BRAND_PATH'] = Appydave::Tools::Dam::Config.brand_path(brand)
+
+          { brand: brand_key, project: project_id, dry_run: dry_run, force: force }
+        end
+
+        def parse_share(args)
+          # Extract --expires flag
+          expires = '7d' # default
+          if (expires_index = args.index('--expires'))
+            expires = args[expires_index + 1]
+            args.delete_at(expires_index + 1)
+            args.delete_at(expires_index)
+          end
+
+          # Extract --download flag
+          download = args.include?('--download')
+
+          # Remove other flags
+          args = args.reject { |arg| arg.start_with?('--') }
+
+          brand_arg = args[0]
+          project_arg = args[1]
+          file_arg = args[2]
+
+          raise_share_usage_error if brand_arg.nil? || project_arg.nil? || file_arg.nil?
+
+          brand_key = brand_arg
+          brand = Appydave::Tools::Dam::Config.expand_brand(brand_arg)
+          project_id = Appydave::Tools::Dam::ProjectResolver.resolve(brand_arg, project_arg)
+
+          # Set ENV for compatibility with ConfigLoader
+          ENV['BRAND_PATH'] = Appydave::Tools::Dam::Config.brand_path(brand)
+
+          { brand: brand_key, project: project_id, file: file_arg, expires: expires, download: download }
+        end
+
+        def parse_discover(args)
+          shareable = args.include?('--shareable')
+          args = args.reject { |arg| arg.start_with?('--') }
+
+          brand_arg = args[0]
+          project_arg = args[1]
+
+          if brand_arg.nil? || project_arg.nil?
+            raise Appydave::Tools::Dam::UsageError,
+                  'Usage: dam s3-discover <brand> <project> [--shareable]'
+          end
+
+          brand_key = brand_arg
+          brand = Appydave::Tools::Dam::Config.expand_brand(brand_arg)
+          project_id = Appydave::Tools::Dam::ProjectResolver.resolve(brand_arg, project_arg)
+
+          # Set ENV for compatibility with ConfigLoader
+          ENV['BRAND_PATH'] = Appydave::Tools::Dam::Config.brand_path(brand)
+
+          { brand_key: brand_key, project_id: project_id, shareable: shareable }
+        end
+
+        def valid_brand?(brand_key)
+          Appydave::Tools::Configuration::Config.configure
+          brands = Appydave::Tools::Configuration::Config.brands
+          brands.key?(brand_key) || brands.shortcut?(brand_key)
+        end
+
+        def raise_share_usage_error
+          raise Appydave::Tools::Dam::UsageError,
+                'Usage: dam s3-share <brand> <project> <file> [--expires 7d] [--download]'
+        end
+      end
+    end
+  end
+end

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

@@ -49,10 +49,8 @@ module Appydave
           manifest_path = File.join(brand_path, 'projects.json')
 
           unless File.exist?(manifest_path)
-            puts "❌ Manifest not found: #{manifest_path}"
-            puts "   Run: dam manifest #{brand_key}"
-            puts "   Then retry: dam s3-scan #{brand_key}"
-            exit 1
+            raise Appydave::Tools::Dam::ConfigurationError,
+                  "Manifest not found: #{manifest_path}. Run: dam manifest #{brand_key}"
           end
 
           manifest = JSON.parse(File.read(manifest_path), symbolize_names: true)

data/lib/appydave/tools/version.rb

@@ -2,6 +2,6 @@
 
 module Appydave
   module Tools
-    VERSION = '0.76.6'
+    VERSION = '0.76.8'
   end
 end

data/lib/appydave/tools.rb

@@ -80,6 +80,7 @@ require 'appydave/tools/dam/repo_sync'
 require 'appydave/tools/dam/repo_push'
 require 'appydave/tools/dam/local_sync_status'
 require 'appydave/tools/dam/s3_scan_command'
+require 'appydave/tools/dam/s3_arg_parser'
 
 require 'appydave/tools/jump/path_validator'
 require 'appydave/tools/jump/location'

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appydave-tools",
-  "version": "0.76.6",
+  "version": "0.76.8",
   "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.6
+  version: 0.76.8
 platform: ruby
 authors:
 - David Cruwys
@@ -302,12 +302,16 @@ files:
 - docs/planning/bugfix-and-security/assessment.md
 - docs/planning/extract-vat-cli/AGENTS.md
 - docs/planning/extract-vat-cli/IMPLEMENTATION_PLAN.md
+- docs/planning/extract-vat-cli/assessment.md
+- docs/planning/extract-vat-cli/learnings/wave-learnings.md
 - docs/planning/final-test-gaps/AGENTS.md
 - docs/planning/final-test-gaps/IMPLEMENTATION_PLAN.md
 - docs/planning/final-test-gaps/assessment.md
 - docs/planning/fr2-gpt-context-help/AGENTS.md
 - docs/planning/fr2-gpt-context-help/IMPLEMENTATION_PLAN.md
 - docs/planning/fr2-gpt-context-help/assessment.md
+- docs/planning/library-boundary-cleanup/AGENTS.md
+- docs/planning/library-boundary-cleanup/IMPLEMENTATION_PLAN.md
 - docs/planning/micro-cleanup/AGENTS.md
 - docs/planning/micro-cleanup/IMPLEMENTATION_PLAN.md
 - docs/planning/micro-cleanup/assessment.md
@@ -361,6 +365,7 @@ files:
 - lib/appydave/tools/dam/repo_push.rb
 - lib/appydave/tools/dam/repo_status.rb
 - lib/appydave/tools/dam/repo_sync.rb
+- lib/appydave/tools/dam/s3_arg_parser.rb
 - lib/appydave/tools/dam/s3_operations.rb
 - lib/appydave/tools/dam/s3_scan_command.rb
 - lib/appydave/tools/dam/s3_scanner.rb