appydave-tools 0.75.0 → 0.76.1

data/docs/planning/fr2-gpt-context-help/AGENTS.md

@@ -0,0 +1,256 @@
+# AGENTS.md — fr2-gpt-context-help
+
+> Operational knowledge for this campaign's background agents.
+> Inherited from docs/planning/AGENTS.md (2026-03-19). Campaign-specific additions below.
+> Self-contained — you receive only this file + your work unit prompt.
+
+---
+
+## 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:** FR-2 — enhance `bin/gpt_context.rb` OptionParser with structured help system. One file. No lib/ changes.
+**Commits:** Always use `kfeat`/`kfix` — never `git 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/appydave/tools/gpt_context/       # GPT context specs only
+RUBYOPT="-W0" bundle exec rspec                          # Suppress Ruby 3.4 platform warnings
+
+# Lint
+bundle exec rubocop --format clang                       # Standard lint check (matches CI)
+
+# Manual verification
+bin/gpt_context.rb --help                                # Should show structured help
+bin/gpt_context.rb --version                             # Should show version
+bin/gpt_context.rb -v                                    # Short version flag
+bin/gpt_context.rb --help | grep -E "^(SYNOPSIS|DESCRIPTION|OPTIONS|OUTPUT FORMATS|EXAMPLES)"
+
+# Commit (never use git commit directly)
+kfeat "add AI-friendly help system to GPT Context"       # Use this exact message
+```
+
+**Baseline (2026-03-19):** 748 examples, 0 failures, 84.88% line coverage (7680/9048)
+
+---
+
+## Directory Structure
+
+```
+bin/gpt_context.rb                              ← THE ONLY FILE TO CHANGE
+lib/appydave/tools/gpt_context/
+  file_collector.rb                             Read-only reference (DO NOT MODIFY)
+  options.rb                                    Read-only reference (DO NOT MODIFY)
+  output_handler.rb                             Read-only reference (DO NOT MODIFY)
+lib/appydave/tools/version.rb                   Read-only — VERSION constant lives here
+spec/appydave/tools/gpt_context/
+  cli_spec.rb                                   ← CREATE THIS (new file)
+  file_collector_spec.rb                        Existing — do not modify
+```
+
+---
+
+## Success Criteria
+
+Every work unit must satisfy ALL before marking `[x]`:
+
+- [ ] `bundle exec rspec` — 748+ examples, 0 failures (new specs add to this count)
+- [ ] `bundle exec rubocop --format clang` — 0 offenses
+- [ ] Line coverage stays ≥ 84.88%
+- [ ] `bin/gpt_context.rb --help` output includes SYNOPSIS, DESCRIPTION, OPTIONS, OUTPUT FORMATS, EXAMPLES sections
+- [ ] `bin/gpt_context.rb --version` outputs `gpt_context version X.Y.Z`
+- [ ] `spec/appydave/tools/gpt_context/cli_spec.rb` exists with ≥ 3 passing tests
+- [ ] Banner no longer says `gather_content.rb` — it says `gpt_context`
+- [ ] `# frozen_string_literal: true` at top of new spec file
+
+---
+
+## Work Unit Spec
+
+### fr2-gpt-context-help — Implement AI-friendly help system
+
+**File to modify:** `bin/gpt_context.rb`
+
+**What to do:**
+
+1. Replace the `opts.banner` line with a heredoc banner containing Synopsis and Description sections
+2. Add `opts.separator` calls for OUTPUT FORMATS and EXAMPLES sections after the options
+3. Add `--version` / `-v` flag before the `--help` flag
+4. Enhance each option's description to include defaults and examples (multi-line array format)
+5. Fix the banner script name: currently `gather_content.rb` → should be `gpt_context`
+
+**Full implementation pattern** (from spec, Option A):
+
+```ruby
+OptionParser.new do |opts|
+  opts.banner = <<~BANNER
+    GPT Context Gatherer - Collect project files for AI context
+
+    SYNOPSIS
+        gpt_context [options]
+
+    DESCRIPTION
+        Collects and packages codebase files for AI assistant context.
+        Outputs to clipboard (default), file, or stdout.
+
+  BANNER
+
+  opts.separator "OPTIONS"
+  opts.separator ""
+
+  opts.on('-i', '--include PATTERN',
+          'Glob pattern for files to include (repeatable)',
+          'Example: -i "lib/**/*.rb" -i "bin/**/*.rb"') do |pattern|
+    options.include_patterns << pattern
+  end
+
+  opts.on('-e', '--exclude PATTERN',
+          'Glob pattern for files to exclude (repeatable)',
+          'Example: -e "spec/**/*" -e "node_modules/**/*"') do |pattern|
+    options.exclude_patterns << pattern
+  end
+
+  opts.on('-f', '--format FORMATS',
+          'Output format(s): tree, content, json, aider, files',
+          'Comma-separated. Default: content',
+          'Example: -f tree,content') do |format|
+    options.format = format
+  end
+
+  opts.on('-o', '--output TARGET',
+          'Output target: clipboard, filename, or stdout',
+          'Default: clipboard. Repeatable for multiple targets.') do |target|
+    options.output_target << target
+  end
+
+  opts.on('-d', '--debug [MODE]', 'Enable debug mode [none, info, params, debug]',
+          'none', 'info', 'params', 'debug') do |debug|
+    options.debug = debug || 'info'
+  end
+
+  opts.on('-l', '--line-limit N', Integer,
+          'Limit lines per file (default: unlimited)') do |n|
+    options.line_limit = n
+  end
+
+  opts.on('-b', '--base-dir DIRECTORY',
+          'Set the base directory to gather files from') do |directory|
+    options.working_directory = directory
+  end
+
+  opts.on('-p', '--prompt TEXT',
+          'Prompt text for aider format output') do |message|
+    options.prompt = message
+  end
+
+  opts.separator ""
+  opts.separator "OUTPUT FORMATS"
+  opts.separator "    tree     - Directory tree structure"
+  opts.separator "    content  - File contents with headers (default)"
+  opts.separator "    json     - Structured JSON output"
+  opts.separator "    aider    - Aider CLI command format (requires -p)"
+  opts.separator "    files    - File paths only"
+  opts.separator ""
+  opts.separator "EXAMPLES"
+  opts.separator "    # Gather Ruby library code for AI context"
+  opts.separator "    gpt_context -i 'lib/**/*.rb' -e 'spec/**/*' -d"
+  opts.separator ""
+  opts.separator "    # Project structure overview"
+  opts.separator "    gpt_context -i '**/*' -f tree -e 'node_modules/**/*'"
+  opts.separator ""
+  opts.separator "    # Save to file with tree and content"
+  opts.separator "    gpt_context -i 'src/**/*.ts' -f tree,content -o context.txt"
+  opts.separator ""
+  opts.separator "    # Generate aider command"
+  opts.separator "    gpt_context -i 'lib/**/*.rb' -f aider -p 'Add logging'"
+  opts.separator ""
+
+  opts.on('-v', '--version', 'Show version') do
+    puts "gpt_context version #{Appydave::Tools::VERSION}"
+    exit
+  end
+
+  opts.on_tail('-h', '--help', 'Show this help') do
+    puts opts
+    exit
+  end
+end.parse!
+```
+
+**New spec file** `spec/appydave/tools/gpt_context/cli_spec.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+RSpec.describe 'gpt_context CLI help' do
+  let(:script) { File.expand_path('../../../../bin/gpt_context.rb', __dir__) }
+
+  describe '--help' do
+    subject(:output) { `ruby #{script} --help 2>&1` }
+
+    it 'includes SYNOPSIS section' do
+      expect(output).to include('SYNOPSIS')
+    end
+
+    it 'includes EXAMPLES section' do
+      expect(output).to include('EXAMPLES')
+    end
+
+    it 'includes OUTPUT FORMATS section' do
+      expect(output).to include('OUTPUT FORMATS')
+    end
+  end
+
+  describe '--version' do
+    it 'shows version number' do
+      output = `ruby #{script} --version 2>&1`
+      expect(output).to match(/gpt_context version \d+\.\d+\.\d+/)
+    end
+  end
+end
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+- ❌ Do NOT modify any file in `lib/` — this campaign is bin/ only
+- ❌ Do NOT use `opts.on_tail` for `--version` (use `opts.on` so it appears before `--help` in output)
+- ❌ Do NOT leave the banner saying `gather_content.rb`
+- ❌ Do NOT require spec_helper explicitly — it's auto-required via `.rspec` config
+- ❌ Do NOT use `system()` or backticks in specs to call the script with a path that includes spaces
+
+---
+
+## Quality Gates
+
+- **Tests:** `bundle exec rspec` — 748+ examples, 0 failures
+- **Lint:** `bundle exec rubocop --format clang` — 0 offenses
+- **Coverage:** ≥ 84.88% line coverage
+- **Manual:** `bin/gpt_context.rb --help` and `--version` work as expected
+- **Commit format:** `kfeat "add AI-friendly help system to GPT Context"`
+
+---
+
+## Learnings (inherited)
+
+### From Three-Lens Audit (2026-03-19)
+- `file_collector.rb` pre-conditions (B015, B019) already fixed in commit 13d5f87 — do not re-fix
+- BUG-1 already verified fixed — do not re-investigate
+
+### From DAM Enhancement Sprint (Jan 2025)
+- `Config.configure` is memoized — idempotent
+- Table format() pattern: always use same format string for headers and data rows
+
+### From Jump Location Tool (Dec 2025)
+- Dependency injection for path validators required for CI compatibility
+- Jump Commands layer is undertested — not relevant to this campaign

data/docs/planning/fr2-gpt-context-help/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,24 @@
+# IMPLEMENTATION_PLAN.md — fr2-gpt-context-help
+
+**Goal**: Enhance GPT Context CLI with AI-friendly help system (FR-2)
+**Started**: 2026-03-19
+**Target**: `--help` shows structured sections; `--version` works; specs pass; rubocop clean
+
+## Summary
+- Total: 1 | Complete: 1 | In Progress: 0 | Pending: 0 | Failed: 0
+
+## Pending
+
+## In Progress
+
+## Complete
+- [x] fr2-gpt-context-help — Implement AI-friendly help system in bin/gpt_context.rb. 754 examples, 0 failures. v0.76.0 published. Also fixed pre-existing rubocop offenses in bin/dam and split jump_test_helpers (JumpTestLocations → own file).
+
+## Failed / Needs Retry
+
+## Notes & Decisions
+- Pre-conditions already satisfied: B015 (FileUtils.cd) and B019 (debug puts) fixed in commit 13d5f87
+- Implementation is Option A from spec: enhanced OptionParser only — no changes to lib/
+- Fix banner script name while in there (currently says gather_content.rb, should say gpt_context)
+- New spec file: spec/appydave/tools/gpt_context/cli_spec.rb (3 tests minimum)
+- Commit with: kfeat "add AI-friendly help system to GPT Context"

data/docs/planning/fr2-gpt-context-help/assessment.md

@@ -0,0 +1,70 @@
+# Assessment: fr2-gpt-context-help
+
+**Campaign**: fr2-gpt-context-help
+**Date**: 2026-03-19 → 2026-03-19
+**Results**: 1 complete, 0 failed
+**Version shipped**: v0.76.0
+**Quality audit**: code-quality-audit + test-quality-audit run post-campaign
+
+---
+
+## Results Summary
+
+| Work Unit | Status | Notes |
+|-----------|--------|-------|
+| B002 — FR-2 GPT Context help system | ✅ Complete | 754 examples, 0 failures. Also fixed pre-existing rubocop offenses in bin/dam and split JumpTestLocations into own file. |
+
+---
+
+## What Worked Well
+
+- **Single-file scope held.** `bin/gpt_context.rb` only — no lib/ changes. Agent stayed in bounds.
+- **Side-fixes landed cleanly.** Rubocop offenses in bin/dam (select/reject → partition) and JumpTestLocations split were caught and fixed without scope creep.
+- **Test count and coverage improved.** 748 → 754 examples, 84.88% → 84.92% coverage.
+- **Spec approach was correct.** subprocess integration testing (running the actual script) is the right pattern for CLI help/version tests.
+- **Pre-conditions were pre-cleared.** B015 and B019 fixed in prior commit 13d5f87 meant agent could focus on FR-2 immediately.
+
+---
+
+## What Didn't Work
+
+- **cli_spec.rb is too thin (Grade: C from test audit).** 4 tests only verify help text strings are present. No functional tests: `-i`, `-e`, `-f`, `-o` flags completely untested at CLI level. Creates false sense of security.
+- **format.nil? guard is dead code.** `bin/gpt_context.rb` line 115 checks `options.format.nil?` as part of its "no options provided" guard. But `format` defaults to `'content'` in the Options class — it is never nil. The third AND condition is always false, meaning the guard can only trigger if both include_patterns AND exclude_patterns are empty AND format has somehow been set to nil (impossible via normal usage).
+- **file_collector_spec missing formats.** JSON and aider format output paths in FileCollector have zero specs. Error cases also unprotected.
+
+---
+
+## Key Learnings — Application
+
+- **OptionParser `opts.on_tail` vs `opts.on` matters for ordering.** `--version` must be `opts.on` (not `on_tail`) to appear before `--help` in output. Anti-pattern documented in AGENTS.md.
+- **format.nil? is a dead guard.** When Options class sets a default for `format`, the nil check in bin/gpt_context.rb line 115 is always false. Any "no args provided" guard must check `include_patterns.empty?` and `exclude_patterns.empty?` only.
+- **Subprocess specs work but need functional assertions.** Using `\`ruby #{script} --flag\`` is correct for CLI integration testing, but tests must verify actual output content and exit codes — not just documentation strings.
+
+---
+
+## Key Learnings — Ralph Loop
+
+- **One work unit campaigns are fast.** 1 agent, 1 wave, done. No coordination overhead.
+- **Pre-conditions from prior commits reduce campaign scope.** B015/B019 were in next-round-brief as work units but had already been fixed. Always verify pre-conditions live before writing the plan.
+- **Quality audit caught 3 new backlog items.** B021 (format.nil? dead guard), B022 (cli_spec functional tests), B023 (file_collector JSON/aider/error specs). These were invisible without the audit.
+
+---
+
+## Suggestions for Next Campaign
+
+**Recommended next campaign: `bugfix-and-security` — B016, B017, B021**
+
+Priority order:
+1. **B017** — ssl_verify_peer: false (security BLOCKER — remove before adding any S3 features)
+2. **B016** — ManifestGenerator vs SyncFromSsd range string mismatch (data integrity BLOCKER)
+3. **B021** — fix format.nil? dead guard in gpt_context (5-minute fix, prevents silent failure)
+
+Then schedule soon after:
+- **B022** — expand cli_spec.rb with functional tests (-i, -e, -f, -o, exit codes)
+- **B023** — file_collector_spec: add JSON, aider, error path coverage
+- **B018** — Jump Commands layer specs (Remove/Add/Update)
+
+**AGENTS.md updates needed for next campaign:**
+- Add: "format.nil? in gpt_context is always false — do not use as a no-args guard"
+- Add: "S3Operations ssl_verify_peer must be removed — see B017"
+- Add: "ManifestGenerator and SyncFromSsd produce incompatible range strings — see B016 before touching SSD archive paths"

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

@@ -0,0 +1,39 @@
+# Next Round Brief
+
+**Created:** 2026-03-19
+**Updated:** 2026-03-19 (after fr2-gpt-context-help assessment)
+
+---
+
+## Recommended Next Campaign: bugfix-and-security
+
+### Goal
+
+Fix two BLOCKER-level bugs (B016, B017) and one dead-code guard (B021) before building any new S3 or archive features.
+
+### Background
+
+Quality audit after fr2-gpt-context-help surfaced these as blockers:
+
+1. **B017** — `ssl_verify_peer: false` hardcoded unconditionally in `S3Operations` and `ShareOperations`. Removes MITM protection on all S3 operations including credential transmission. Must fix before any S3 feature work.
+2. **B016** — `ManifestGenerator.determine_range` returns `"b50-b99"` format; `SyncFromSsd.determine_range` returns `"60-69"` format. Incompatible SSD path construction means projects can be silently missed during archive/restore. Must fix before any archive feature work.
+3. **B021** — `bin/gpt_context.rb` line 115 guard checks `options.format.nil?` as third AND condition. `format` defaults to `'content'` in Options — never nil. Dead condition; guard can only fire on include/exclude emptiness. 5-minute fix.
+
+### Suggested Work Units
+
+1. **Fix B017** — Remove `ssl_verify_peer: false` from `S3Operations` and `ShareOperations`. No env flag needed — AWS SDK handles SSL correctly by default.
+2. **Fix B016** — Align range string format between `ManifestGenerator` and `SyncFromSsd`. Read actual SSD folder structure on disk first to determine which format matches reality; update the other to match.
+3. **Fix B021** — Remove `&& options.format.nil?` from guard at `bin/gpt_context.rb:115`. Update or add spec to verify no-args behavior.
+
+### Optional (bundle if small)
+
+- **B018** — Jump Commands layer specs (Remove/Add/Update) — no code changes, just test coverage
+- **B022** — Expand cli_spec.rb with functional tests for -i, -e, -f, -o flags
+
+### Mode Recommendation
+
+**Extend** — stack, patterns, and quality gates known. Inherit AGENTS.md.
+
+### Pre-Campaign Blockers: None
+
+All three fixes are standalone. B016 requires reading SSD disk structure before writing code (per AGENTS.md: read actual files before designing data shapes).

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

@@ -100,17 +100,9 @@ module Appydave
         end
 
         def configure_ssl_options
-          # Check for explicit SSL verification bypass (for development/testing)
-          if ENV['AWS_SDK_RUBY_SKIP_SSL_VERIFICATION'] == 'true'
-            puts '⚠️  WARNING: SSL verification is disabled (development mode)'
-            return { ssl_verify_peer: false }
-          end
+          return { ssl_verify_peer: false } if ENV['AWS_SDK_RUBY_SKIP_SSL_VERIFICATION'] == 'true'
 
-          # Disable SSL peer verification to work around OpenSSL 3.4.x CRL checking issues
-          # This is safe for AWS S3 connections as we're still using HTTPS (encrypted connection)
-          {
-            ssl_verify_peer: false
-          }
+          {}
         end
 
         public

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

@@ -111,8 +111,7 @@ module Appydave
           Aws::S3::Client.new(
             credentials: credentials,
             region: brand_info.aws.region,
-            http_wire_trace: false,
-            ssl_verify_peer: false
+            http_wire_trace: false
           )
         end
 

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

@@ -87,17 +87,9 @@ module Appydave
         end
 
         def configure_ssl_options
-          # Check for explicit SSL verification bypass (for development/testing)
-          if ENV['AWS_SDK_RUBY_SKIP_SSL_VERIFICATION'] == 'true'
-            puts '⚠️  WARNING: SSL verification is disabled (development mode)'
-            return { ssl_verify_peer: false }
-          end
+          return { ssl_verify_peer: false } if ENV['AWS_SDK_RUBY_SKIP_SSL_VERIFICATION'] == 'true'
 
-          # Disable SSL peer verification to work around OpenSSL 3.4.x CRL checking issues
-          # This is safe for AWS S3 connections as we're still using HTTPS (encrypted connection)
-          {
-            ssl_verify_peer: false
-          }
+          {}
         end
 
         public

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

@@ -181,14 +181,17 @@ module Appydave
           sync_light_files(ssd_path, local_dir, dry_run: dry_run)
         end
 
-        # Determine range folder for project (e.g., b65 → 60-69)
+        # Determine range folder for project (e.g., b65 → b50-b99)
         def determine_range(project_id)
-          # FliVideo pattern: b40, b41, ... b99
-          if project_id =~ /^b(\d+)/
-            tens = (Regexp.last_match(1).to_i / 10) * 10
-            "#{tens}-#{tens + 9}"
+          # FliVideo/Modern pattern: b40, a82, etc.
+          if project_id =~ /^([a-z])(\d+)/
+            letter = Regexp.last_match(1)
+            number = Regexp.last_match(2).to_i
+            range_start = (number / 50) * 50
+            range_end = range_start + 49
+            format("#{letter}%02d-#{letter}%02d", range_start, range_end)
           else
-            # Legacy pattern or unknown: use first 3 chars
+            # Legacy pattern or unknown
             '000-099'
           end
         end

data/lib/appydave/tools/gpt_context/file_collector.rb

@@ -12,36 +12,29 @@ module Appydave
           @exclude_patterns = options.exclude_patterns
           @format = options.format
           @working_directory = File.expand_path(options.working_directory)
-          puts @working_directory
           @line_limit = options.line_limit
         end
 
         def build
-          FileUtils.cd(@working_directory) if @working_directory && Dir.exist?(@working_directory)
+          return build_formats unless @working_directory && Dir.exist?(@working_directory)
 
-          formats = @format.split(',')
-          result = formats.map do |fmt|
+          FileUtils.cd(@working_directory) { build_formats }
+        end
+
+        private
+
+        def build_formats
+          @format.split(',').map do |fmt|
             case fmt
-            when 'tree'
-              build_tree
-            when 'content'
-              build_content
-            when 'json'
-              build_json
-            when 'aider'
-              build_aider
-            else
-              ''
+            when 'tree'    then build_tree
+            when 'content' then build_content
+            when 'json'    then build_json
+            when 'aider'   then build_aider
+            else ''
             end
           end.join("\n\n")
-
-          FileUtils.cd(Dir.home) if @working_directory
-
-          result
         end
 
-        private
-
         def build_content
           concatenated_content = []
 

data/lib/appydave/tools/version.rb

@@ -2,6 +2,6 @@
 
 module Appydave
   module Tools
-    VERSION = '0.75.0'
+    VERSION = '0.76.1'
   end
 end

data/package.json

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: appydave-tools
 version: !ruby/object:Gem::Version
-  version: 0.75.0
+  version: 0.76.1
 platform: ruby
 authors:
 - David Cruwys
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-08 00:00:00.000000000 Z
+date: 2026-03-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -295,6 +295,14 @@ files:
 - docs/guides/tools/video-file-namer.md
 - docs/guides/tools/youtube-automation.md
 - docs/guides/tools/youtube-manager.md
+- docs/planning/AGENTS.md
+- docs/planning/BACKLOG.md
+- docs/planning/bugfix-and-security/AGENTS.md
+- docs/planning/bugfix-and-security/IMPLEMENTATION_PLAN.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/specs/fr-002-gpt-context-help-system.md
 - docs/specs/fr-003-jump-location-tool.md
 - docs/specs/zsh-history-tool.md