appydave-tools 0.76.3 → 0.76.5

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

@@ -0,0 +1,181 @@
+# AGENTS.md — micro-cleanup
+
+> Inherited from final-test-gaps AGENTS.md. Self-contained.
+> Last updated: 2026-03-19
+
+---
+
+## 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.
+**This campaign:** 2 test additions + 1 production fix (1 line).
+**Commits:** Always use `kfix` — never `git commit`.
+
+---
+
+## Build & Run Commands
+
+```bash
+eval "$(rbenv init -)"
+
+RUBYOPT="-W0" bundle exec rspec                                                    # All tests
+bundle exec rspec spec/appydave/tools/jump/commands/add_spec.rb
+bundle exec rspec spec/appydave/tools/gpt_context/cli_spec.rb
+bundle exec rspec spec/appydave/tools/gpt_context/file_collector_spec.rb
+bundle exec rubocop --format clang
+```
+
+**Baseline:** 830 examples, 0 failures, 85.92% line coverage
+
+---
+
+## Directory Structure
+
+```
+lib/appydave/tools/gpt_context/
+  file_collector.rb         LINE 19 — change `return build_formats unless` to `return '' unless`
+
+spec/appydave/tools/jump/commands/
+  add_spec.rb               ADD `type` field to existing data integrity it block
+
+spec/appydave/tools/gpt_context/
+  cli_spec.rb               ADD new it block for `-f json` in the `-f format` describe block
+  file_collector_spec.rb    UPDATE nonexistent-dir test to confirm empty string (verify still passes)
+```
+
+---
+
+## Work Unit Details
+
+---
+
+### fix-b031 — add_spec: add type field to data integrity test
+
+**Read first:** `spec/appydave/tools/jump/commands/add_spec.rb`
+
+**Find the `'returns location data matching all input attrs'` it block** (added in final-test-gaps). It currently asserts: key, path, jump, tags, description.
+
+**Add one assertion** to that same it block:
+```ruby
+expect(location[:type]).to eq('tool')
+```
+
+`valid_attrs` has `type: 'tool'` so this will pass. The `location.to_h` in Location uses `.compact` — since type is set, it will be present.
+
+**Do NOT create a new it block** — add the assertion to the existing one.
+
+**Run:**
+```bash
+bundle exec rspec spec/appydave/tools/jump/commands/add_spec.rb
+```
+
+All 15 examples should pass. Then full suite. Then:
+```bash
+kfix "add type field assertion to add_spec location data integrity test"
+```
+
+---
+
+### fix-b032 — cli_spec: subprocess test for -f json
+
+**Read first:** `spec/appydave/tools/gpt_context/cli_spec.rb` — specifically the `-f format` describe block.
+
+**Add a new it block** to the `-f format` describe context:
+
+```ruby
+it 'outputs valid JSON when -f json specified' do
+  Dir.mktmpdir do |tmpdir|
+    File.write(File.join(tmpdir, 'test.rb'), '# test content')
+    outfile = File.join(tmpdir, 'output.txt')
+
+    `ruby #{script} -i '*.rb' -f json -b #{tmpdir} -o #{outfile} 2>&1`
+
+    content = File.read(outfile)
+    expect { JSON.parse(content) }.not_to raise_error
+    parsed = JSON.parse(content)
+    expect(parsed).to have_key('tree')
+    expect(parsed).to have_key('content')
+  end
+end
+```
+
+Note: `JSON` is available in the spec because Ruby stdlib is loaded. No require needed.
+
+**Run:**
+```bash
+bundle exec rspec spec/appydave/tools/gpt_context/cli_spec.rb
+```
+
+Then full suite. Then:
+```bash
+kfix "add subprocess test for -f json flag to cli_spec"
+```
+
+---
+
+### fix-b033 — file_collector.rb: fix silent CWD collection
+
+**Read first:** `lib/appydave/tools/gpt_context/file_collector.rb` line 19.
+
+Current code:
+```ruby
+return build_formats unless @working_directory && Dir.exist?(@working_directory)
+```
+
+**Change to:**
+```ruby
+return '' unless @working_directory && Dir.exist?(@working_directory)
+```
+
+This ensures a missing working directory always returns empty string rather than silently collecting files from the current process working directory.
+
+**Then verify the existing spec still passes:**
+```bash
+bundle exec rspec spec/appydave/tools/gpt_context/file_collector_spec.rb
+```
+
+The `'#build with nonexistent working directory'` example already asserts `expect(subject.build).to eq('')` — this should still pass (and now it's guaranteed by the code, not by an accident of the glob pattern).
+
+**Run rubocop:**
+```bash
+bundle exec rubocop lib/appydave/tools/gpt_context/file_collector.rb --format clang
+```
+
+Then full suite. Then:
+```bash
+kfix "fix file_collector silent collection from CWD when working directory does not exist"
+```
+
+---
+
+## Success Criteria
+
+- [ ] `RUBYOPT="-W0" bundle exec rspec` — 831+ examples, 0 failures
+- [ ] `bundle exec rubocop --format clang` — 0 offenses
+- [ ] Line coverage stays ≥ 85.92%
+- [ ] B031: `type` field asserted in add_spec data integrity test
+- [ ] B032: json format verified via subprocess in cli_spec
+- [ ] B033: `file_collector.rb:19` returns `''` not `build_formats` when dir missing
+
+---
+
+## Anti-Patterns to Avoid
+
+- ❌ Do NOT use `$?` — use `$CHILD_STATUS`
+- ❌ Do NOT use `git commit` — use `kfix`
+- ❌ Do NOT add `require 'spec_helper'`
+- ❌ Do NOT add multiple separate `before` blocks on same context (RSpec/ScatteredSetup)
+- ❌ Do NOT create new it blocks for B031 — add assertion to existing block
+
+---
+
+## Learnings (inherited from final-test-gaps)
+
+- **`$CHILD_STATUS` not `$?`** — rubocop Style/SpecialGlobalVars cop
+- **`options.format` defaults to `'tree,content'`** — never nil
+- **`options.prompt` defaults to nil** — aider format returns `''` when nil
+- **`location.to_h` uses symbol keys + `.compact`** — nil fields are dropped
+- **Agent pre-read pattern works** — read source files before writing assertions; zero wrong field name failures
+- **Parallel wave, all different files** — no merge conflicts expected
+- **JSON in subprocess test** — `JSON.parse(content)` in subprocess tests — ensure JSON output goes to outfile not stdout; use `-o outfile` flag

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

@@ -0,0 +1,29 @@
+# IMPLEMENTATION_PLAN.md — micro-cleanup
+
+**Goal**: Close 3 small items from the final-test-gaps quality audit: type field assertion (B031), -f json CLI test (B032), file_collector.rb silent-collection fix (B033)
+**Started**: 2026-03-19
+**Target**: All 3 complete; 830+ examples passing; rubocop clean; no regressions
+
+## Summary
+- Total: 3 | Complete: 3 | In Progress: 0 | Pending: 0 | Failed: 0
+
+## Pending
+
+## In Progress
+
+## 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
+
+## Failed / Needs Retry
+
+## Notes & Decisions
+- All 3 work units are independent — parallel wave
+- B033 is a production code change (1 line) — needs a spec update to confirm the behaviour
+- B031 and B032 are test-only
+- B033 fix: change `return build_formats unless` to `return '' unless` on line 19 of file_collector.rb
+- B031 fix: add `expect(location[:type]).to eq('tool')` to the existing 'returns location data matching all input attrs' it block
+- B032 fix: new it block in '-f format' describe context — subprocess with `-f json`, parse output as JSON, assert tree+content keys present

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/gpt_context/file_collector.rb

@@ -16,7 +16,7 @@ module Appydave
         end
 
         def build
-          return build_formats unless @working_directory && Dir.exist?(@working_directory)
+          return '' unless @working_directory && Dir.exist?(@working_directory)
 
           FileUtils.cd(@working_directory) { build_formats }
         end

data/lib/appydave/tools/version.rb

@@ -2,6 +2,6 @@
 
 module Appydave
   module Tools
-    VERSION = '0.76.3'
+    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.3",
+  "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.3
+  version: 0.76.5
 platform: ruby
 authors:
 - David Cruwys
@@ -300,12 +300,17 @@ 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
 - 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/next-round-brief.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
@@ -349,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

data/docs/planning/next-round-brief.md

@@ -1,42 +0,0 @@
-# Next Round Brief
-
-**Created:** 2026-03-19
-**Updated:** 2026-03-19 (after bugfix-and-security assessment)
-
----
-
-## Recommended Next Campaign: test-coverage-gaps
-
-### Goal
-
-Protect the B017 SSL security fix with a regression test, expand functional test coverage across gpt_context CLI and DAM range logic, and add the missing Jump Commands layer specs.
-
-### Background
-
-Quality audit after bugfix-and-security found:
-
-1. **B024** — `configure_ssl_options` has zero unit tests. The B017 SSL fix (removing unconditional `ssl_verify_peer: false`) has no regression protection. If reverted, all tests still pass. Must fix.
-2. **B022** — `cli_spec.rb` only tests `--help`, `--version`, no-args. No functional tests for `-i`, `-e`, `-f`, `-o`. Core behaviour untested at CLI level.
-3. **B026** — `determine_range` tests narrow (b40, b65, b99 only). Missing: b00, b9, a40. Both sync_from_ssd_spec and manifest_generator_spec need these.
-4. **B027** — gpt_context no-args spec only checks output string. Does not verify file collection stops.
-5. **B018** — Jump Commands (Remove/Add/Update) — zero dedicated specs.
-6. **B025** — Stale comment sync_from_ssd.rb line 173 (says 60-69, should say b50-b99).
-
-### Suggested Work Units (parallel — all test-only except B025)
-
-1. **fix-b024-ssl-tests** — Add `configure_ssl_options` unit tests to s3_operations_spec and share_operations_spec. Verify empty hash on default path; `{ssl_verify_peer: false}` when ENV override set. Stub ENV directly (`allow(ENV).to receive(:[]).with('AWS_SDK_RUBY_SKIP_SSL_VERIFICATION').and_return('true')`).
-2. **fix-b022-cli-tests** — Add functional subprocess tests to cli_spec.rb for -i, -e, -f, -o flags. Write to Tempfile, verify content. Use `Dir.mktmpdir` and clean up after.
-3. **fix-b026-b025-range-tests** — Add edge cases (b00, b9, a40) to sync_from_ssd_spec and manifest_generator_spec. Fix stale comment sync_from_ssd.rb line 173 while in the file.
-4. **fix-b027-noargs-test** — Strengthen no-args spec: `expect(Appydave::Tools::GptContext::FileCollector).not_to receive(:new)` when no patterns given.
-5. **fix-b018-jump-specs** — Add spec files for Jump Commands::Remove, Commands::Add, Commands::Update. Read existing Jump CLI spec first for setup pattern. Use JumpTestLocations + `with jump filesystem` context.
-
-### Mode Recommendation
-
-**Extend** — same stack, same patterns, test-only work. Inherit AGENTS.md.
-
-### Pre-Campaign Notes
-
-- Check if `climate_control` gem is in Gemfile before using ClimateControl — use direct ENV stubbing if not available
-- For B022 functional tests: subprocess writes to file, assert content includes `# file:` headers
-- For B027: stub at the class level, not instance — `expect(described_class).not_to receive(:new)`
-- For B018: read `spec/appydave/tools/jump/` existing specs before writing new command specs