appydave-tools 0.69.0 → 0.71.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. checksums.yaml +4 -4
  2. data/.claude/commands/brainstorming-agent.md +227 -0
  3. data/.claude/commands/cli-test.md +251 -0
  4. data/.claude/commands/dev.md +234 -0
  5. data/.claude/commands/po.md +227 -0
  6. data/.claude/commands/progress.md +51 -0
  7. data/.claude/commands/uat.md +321 -0
  8. data/.rubocop.yml +11 -0
  9. data/AGENTS.md +43 -0
  10. data/CHANGELOG.md +24 -0
  11. data/CLAUDE.md +96 -3
  12. data/README.md +15 -0
  13. data/bin/dam +39 -7
  14. data/bin/jump.rb +29 -0
  15. data/bin/subtitle_processor.rb +54 -1
  16. data/bin/zsh_history.rb +846 -0
  17. data/docs/README.md +162 -68
  18. data/docs/architecture/cli/exe-bin-convention.md +434 -0
  19. data/docs/architecture/cli-patterns.md +631 -0
  20. data/docs/architecture/gpt-context/gpt-context-architecture.md +325 -0
  21. data/docs/architecture/gpt-context/gpt-context-implementation-guide.md +419 -0
  22. data/docs/architecture/gpt-context/gpt-context-vision.md +179 -0
  23. data/docs/architecture/testing/testing-patterns.md +762 -0
  24. data/docs/backlog.md +120 -0
  25. data/docs/cli-tests/FR-3-jump-location-tool.md +515 -0
  26. data/docs/dam/batch-s3-listing-requirements.md +780 -0
  27. data/docs/guides/tools/video-file-namer.md +400 -0
  28. data/docs/specs/fr-002-gpt-context-help-system.md +265 -0
  29. data/docs/specs/fr-003-jump-location-tool.md +779 -0
  30. data/docs/specs/zsh-history-tool.md +820 -0
  31. data/docs/uat/FR-3-jump-location-tool.md +741 -0
  32. data/exe/jump +11 -0
  33. data/exe/{subtitle_manager → subtitle_processor} +1 -1
  34. data/exe/zsh_history +11 -0
  35. data/lib/appydave/tools/configuration/openai.rb +1 -1
  36. data/lib/appydave/tools/dam/file_helper.rb +28 -0
  37. data/lib/appydave/tools/dam/project_listing.rb +220 -138
  38. data/lib/appydave/tools/dam/s3_operations.rb +112 -60
  39. data/lib/appydave/tools/dam/ssd_status.rb +226 -0
  40. data/lib/appydave/tools/dam/status.rb +3 -51
  41. data/lib/appydave/tools/jump/cli.rb +561 -0
  42. data/lib/appydave/tools/jump/commands/add.rb +52 -0
  43. data/lib/appydave/tools/jump/commands/base.rb +43 -0
  44. data/lib/appydave/tools/jump/commands/generate.rb +153 -0
  45. data/lib/appydave/tools/jump/commands/remove.rb +58 -0
  46. data/lib/appydave/tools/jump/commands/report.rb +214 -0
  47. data/lib/appydave/tools/jump/commands/update.rb +42 -0
  48. data/lib/appydave/tools/jump/commands/validate.rb +54 -0
  49. data/lib/appydave/tools/jump/config.rb +233 -0
  50. data/lib/appydave/tools/jump/formatters/base.rb +48 -0
  51. data/lib/appydave/tools/jump/formatters/json_formatter.rb +19 -0
  52. data/lib/appydave/tools/jump/formatters/paths_formatter.rb +21 -0
  53. data/lib/appydave/tools/jump/formatters/table_formatter.rb +183 -0
  54. data/lib/appydave/tools/jump/location.rb +134 -0
  55. data/lib/appydave/tools/jump/path_validator.rb +47 -0
  56. data/lib/appydave/tools/jump/search.rb +230 -0
  57. data/lib/appydave/tools/subtitle_processor/transcript.rb +51 -0
  58. data/lib/appydave/tools/version.rb +1 -1
  59. data/lib/appydave/tools/zsh_history/command.rb +37 -0
  60. data/lib/appydave/tools/zsh_history/config.rb +235 -0
  61. data/lib/appydave/tools/zsh_history/filter.rb +184 -0
  62. data/lib/appydave/tools/zsh_history/formatter.rb +75 -0
  63. data/lib/appydave/tools/zsh_history/parser.rb +101 -0
  64. data/lib/appydave/tools.rb +25 -0
  65. data/package.json +1 -1
  66. metadata +53 -4
data/docs/README.md CHANGED
@@ -4,40 +4,140 @@
4
4
 
5
5
  ---
6
6
 
7
- ## 📖 Guides (How To Use)
8
-
9
- ### Tools
10
-
11
- - **[DAM - Digital Asset Management](./guides/tools/dam/)** - Video project storage orchestration
12
- - [Usage Guide](./guides/tools/dam/dam-usage.md) ✅
13
- - [Testing Plan](./guides/tools/dam/dam-testing-plan.md) ✅
14
- - **[GPT Context](./guides/tools/gpt-context.md)** - Gather files for AI context ✅
15
- - **[YouTube Manager](./guides/tools/youtube-manager.md)** - Manage YouTube metadata ✅
16
- - **[Subtitle Processor](./guides/tools/subtitle-processor.md)** - Clean/merge SRT files ✅
17
- - **[Configuration Tool](./guides/tools/configuration.md)** - Manage config files ✅
18
- - **[YouTube Automation](./guides/tools/youtube-automation.md)** - Automation workflows ✅
19
- - **[Prompt Tools](./guides/tools/prompt-tools.md)** - OpenAI completion wrapper ✅
20
- - **[Move Images](./guides/tools/move-images.md)** - Organize video assets ✅
21
- - **[Bank Reconciliation](./guides/tools/bank-reconciliation.md)** - DEPRECATED ✅
22
- - **[Name Manager](./guides/tools/name-manager.md)** - Naming utilities ✅
23
- - **[CLI Actions](./guides/tools/cli-actions.md)** - CLI base actions ✅
7
+ ## Two Major Systems
8
+
9
+ AppyDave Tools contains **two major systems** with comprehensive documentation, plus several smaller utilities:
10
+
11
+ | System | Purpose | Domain | Audience |
12
+ |--------|---------|--------|----------|
13
+ | **[DAM](#-dam-digital-asset-management)** | Video project storage orchestration | Video assets, S3, SSD | Video creators, editors |
14
+ | **[GPT Context](#-gpt-context-gatherer)** | AI context collection from codebases | Source code, AI assistants | Developers, AI users |
15
+
16
+ ### Quick Comparison
17
+
18
+ | Aspect | DAM | GPT Context |
19
+ |--------|-----|-------------|
20
+ | **Input** | Video files (MP4, SRT, MOV) | Source code files |
21
+ | **Output** | Cloud/SSD storage | Text (clipboard/files) |
22
+ | **State** | Stateful (sync tracking) | Stateless |
23
+ | **External services** | AWS S3 | None |
24
+ | **Configuration** | brands.json, settings.json | CLI options only |
25
+ | **Primary command** | `vat` | `gpt_context` |
26
+
27
+ ---
28
+
29
+ ## 🎬 DAM (Digital Asset Management)
30
+
31
+ **Purpose**: Multi-tenant video project storage orchestration for content creators.
32
+
33
+ ### Guides (How to Use)
34
+
35
+ - **[DAM Usage Guide](./guides/tools/dam/dam-usage.md)** ✅ - Complete command reference
36
+ - **[DAM Testing Plan](./guides/tools/dam/dam-testing-plan.md)** ✅ - Verification procedures
37
+ - **[Windows Testing](./guides/platforms/windows/dam-testing-plan-windows-powershell.md)** ✅ - Windows-specific testing
38
+
39
+ ### Architecture (How it Works)
40
+
41
+ - **[Implementation Roadmap](./architecture/dam/implementation-roadmap.md)** ⭐ START HERE
42
+ - **[DAM Vision](./architecture/dam/dam-vision.md)** ✅ - Strategic vision and roadmap
43
+ - **[Data Model](./architecture/dam/dam-data-model.md)** ✅ - Entity schema and relationships
44
+ - **[Visualization Requirements](./architecture/dam/dam-visualization-requirements.md)** ✅ - Astro dashboard spec
45
+ - **[CLI Enhancements](./architecture/dam/dam-cli-enhancements.md)** ✅ - Command requirements
46
+ - **[CLI Implementation Guide](./architecture/dam/dam-cli-implementation-guide.md)** ✅ - Code-level details
47
+ - **[Jan Collaboration Guide](./architecture/dam/jan-collaboration-guide.md)** ✅ - Team workflow
48
+
49
+ ### Design Decisions
50
+
51
+ - **[002 - Client Sharing](./architecture/dam/design-decisions/002-client-sharing.md)** 🔄 IN PROGRESS
52
+ - **[003 - Git Integration](./architecture/dam/design-decisions/003-git-integration.md)** 📋 PLANNED
53
+
54
+ ### Quick Start
55
+
56
+ ```bash
57
+ # List all brands
58
+ vat list
59
+
60
+ # List projects for a brand
61
+ vat list appydave
62
+
63
+ # Upload to S3 for collaboration
64
+ vat s3-up appydave b65
65
+
66
+ # Download from S3
67
+ vat s3-down appydave b65
68
+
69
+ # Check sync status
70
+ vat s3-status appydave b65
71
+
72
+ # Archive to SSD
73
+ vat archive appydave b63
74
+ ```
75
+
76
+ ---
77
+
78
+ ## 🤖 GPT Context Gatherer
79
+
80
+ **Purpose**: Collect and package codebase files for AI assistant context.
81
+
82
+ ### Guides (How to Use)
83
+
84
+ - **[GPT Context Usage Guide](./guides/tools/gpt-context.md)** ✅ - Complete command reference with examples
85
+
86
+ ### Architecture (How it Works)
87
+
88
+ - **[GPT Context Vision](./architecture/gpt-context/gpt-context-vision.md)** ✅ - Strategic vision and philosophy
89
+ - **[GPT Context Architecture](./architecture/gpt-context/gpt-context-architecture.md)** ✅ - Data flow and components
90
+ - **[GPT Context Implementation Guide](./architecture/gpt-context/gpt-context-implementation-guide.md)** ✅ - Code-level details
91
+
92
+ ### Quick Start
93
+
94
+ ```bash
95
+ # Gather Ruby files for AI context (copies to clipboard)
96
+ gpt_context -i '**/*.rb' -e 'spec/**/*' -d
97
+
98
+ # Save to file with tree structure
99
+ gpt_context -i 'lib/**/*.rb' -f tree,content -o context.txt
100
+
101
+ # Generate aider command
102
+ gpt_context -i 'lib/**/*.rb' -f aider -p "Add logging to all methods"
103
+
104
+ # JSON format for structured output
105
+ gpt_context -i 'src/**/*.ts' -f json -o codebase.json
106
+ ```
107
+
108
+ ---
109
+
110
+ ## 📖 Other Tools (Guides)
111
+
112
+ Smaller utilities with usage documentation:
113
+
114
+ | Tool | Purpose | Status |
115
+ |------|---------|--------|
116
+ | **[VideoFileNamer](./guides/tools/video-file-namer.md)** | Generate structured video segment filenames | ✅ |
117
+ | **[YouTube Manager](./guides/tools/youtube-manager.md)** | Manage YouTube video metadata via API | ✅ |
118
+ | **[Subtitle Processor](./guides/tools/subtitle-processor.md)** | Clean and merge SRT subtitle files | ✅ |
119
+ | **[Configuration Tool](./guides/tools/configuration.md)** | Manage JSON config files | ✅ |
120
+ | **[YouTube Automation](./guides/tools/youtube-automation.md)** | Prompt sequence automation | ✅ |
121
+ | **[Prompt Tools](./guides/tools/prompt-tools.md)** | OpenAI completion wrapper (deprecated API) | ✅ |
122
+ | **[Move Images](./guides/tools/move-images.md)** | Organize video asset images | ✅ |
123
+ | **[Name Manager](./guides/tools/name-manager.md)** | Naming utilities and conventions | ✅ |
124
+ | **[CLI Actions](./guides/tools/cli-actions.md)** | Base CLI action patterns | ✅ |
125
+ | **[Bank Reconciliation](./guides/tools/bank-reconciliation.md)** | DEPRECATED | ✅ |
24
126
 
25
127
  ### Platform-Specific
26
128
 
27
- - **[Windows Setup](./guides/platforms/windows/)** - Windows/WSL installation ✅
129
+ - **[Windows Setup](./guides/platforms/windows/)** ✅ - Windows/WSL installation
28
130
  - [Installation Guide](./guides/platforms/windows/installation.md) ✅
29
131
  - [Testing Plan](./guides/platforms/windows/dam-testing-plan-windows-powershell.md) ✅
30
132
 
31
133
  ### Configuration
32
134
 
33
- - **[Configuration Setup Guide](./guides/configuration-setup.md)** - Complete configuration reference ✅
135
+ - **[Configuration Setup Guide](./guides/configuration-setup.md)** ✅ - Complete configuration reference
34
136
  - Quick start, file locations, settings reference
35
137
  - Migration from legacy configs
36
138
  - Backup and recovery
37
139
 
38
- ### Future Configuration Guides
39
-
40
- More detailed configuration guides (not yet created):
140
+ #### Future Configuration Guides
41
141
 
42
142
  - **Settings Deep Dive** 📝 (detailed explanation of each setting)
43
143
  - **Channels System** 📝 (YouTube channel management)
@@ -46,32 +146,18 @@ More detailed configuration guides (not yet created):
46
146
 
47
147
  ---
48
148
 
49
- ## 🏗️ Architecture (Understanding How It Works)
149
+ ## 🏗️ General Architecture
50
150
 
51
- ### DAM (Digital Asset Management)
52
-
53
- **Complete documentation for DAM visualization and CLI system:**
54
-
55
- - **[Implementation Roadmap](./architecture/dam/implementation-roadmap.md)** ⭐ START HERE - Complete development guide ✅
56
- - **[DAM Vision](./architecture/dam/dam-vision.md)** - Strategic vision and roadmap ✅
57
- - **[Data Model](./architecture/dam/dam-data-model.md)** - Complete entity schema and relationships ✅
58
- - **[Visualization Requirements](./architecture/dam/dam-visualization-requirements.md)** - Astro dashboard specification ✅
59
- - **[CLI Enhancements](./architecture/dam/dam-cli-enhancements.md)** - Command requirements specification ✅
60
- - **[CLI Implementation Guide](./architecture/dam/dam-cli-implementation-guide.md)** - Code-level implementation details ✅
61
- - **[Jan Collaboration Guide](./architecture/dam/jan-collaboration-guide.md)** - Team workflow reference ✅
62
-
63
- **DAM Design Decisions:**
64
- - **[002 - Client Sharing](./architecture/dam/design-decisions/002-client-sharing.md)** 🔄 IN PROGRESS
65
- - **[003 - Git Integration](./architecture/dam/design-decisions/003-git-integration.md)** 📋 PLANNED
151
+ Cross-cutting architectural documentation:
66
152
 
67
153
  ### CLI Architecture
68
154
 
69
- - **[CLI Patterns](./architecture/cli/cli-patterns.md)** - CLI architecture patterns ✅
70
- - **[CLI Pattern Comparison](./architecture/cli/cli-pattern-comparison.md)** - Visual pattern guide ✅
155
+ - **[CLI Patterns](./architecture/cli/cli-patterns.md)** ✅ - CLI architecture patterns
156
+ - **[CLI Pattern Comparison](./architecture/cli/cli-pattern-comparison.md)** ✅ - Visual pattern guide
71
157
 
72
158
  ### Configuration Systems
73
159
 
74
- - **[Configuration Systems Analysis](./architecture/configuration/configuration-systems.md)** - How brands/channels/NameManager relate ✅
160
+ - **[Configuration Systems Analysis](./architecture/configuration/configuration-systems.md)** ✅ - How brands/channels/NameManager relate
75
161
 
76
162
  ### Design Decisions (General)
77
163
 
@@ -84,10 +170,10 @@ More detailed configuration guides (not yet created):
84
170
 
85
171
  Ready-to-use configuration templates:
86
172
 
87
- - **[settings.example.json](./templates/settings.example.json)** - Settings template ✅
88
- - **[channels.example.json](./templates/channels.example.json)** - Channels template ✅
89
- - **[.env.example](./templates/.env.example)** - Environment variables template ✅
90
- - **brands.example.json** 📝 (not yet created - should mirror brands.json structure with placeholders)
173
+ - **[settings.example.json](./templates/settings.example.json)** ✅ - Settings template
174
+ - **[channels.example.json](./templates/channels.example.json)** ✅ - Channels template
175
+ - **[.env.example](./templates/.env.example)** ✅ - Environment variables template
176
+ - **brands.example.json** 📝 (not yet created)
91
177
 
92
178
  **To use templates:**
93
179
  ```bash
@@ -108,12 +194,10 @@ ad_config -e
108
194
 
109
195
  Documentation for contributors and developers:
110
196
 
111
- - **[CODEX Recommendations](./development/codex-recommendations.md)** - AI coding guidelines ✅
197
+ - **[CODEX Recommendations](./development/codex-recommendations.md)** ✅ - AI coding guidelines
112
198
 
113
199
  ### Future Development Topics
114
200
 
115
- Planned documentation for contributors:
116
-
117
201
  - **Contributing Guide** 📝 (how to contribute, PR process, coding standards)
118
202
  - **Testing Guide** 📝 (how to run tests, write specs, coverage requirements)
119
203
  - **Release Process** 📝 (semantic versioning, CI/CD, gem publishing)
@@ -125,7 +209,7 @@ Planned documentation for contributors:
125
209
 
126
210
  Historical and deprecated documentation:
127
211
 
128
- - **[Archive](./archive/)** - Deprecated documentation ✅
212
+ - **[Archive](./archive/)** ✅ - Deprecated documentation
129
213
 
130
214
  ---
131
215
 
@@ -140,38 +224,44 @@ docs/
140
224
  │ │ ├── dam/ # DAM-specific guides
141
225
  │ │ │ ├── dam-usage.md
142
226
  │ │ │ └── dam-testing-plan.md
143
- │ │ ├── gpt-context.md
227
+ │ │ ├── gpt-context.md # GPT Context usage
144
228
  │ │ ├── youtube-manager.md
145
229
  │ │ ├── subtitle-processor.md
146
230
  │ │ ├── configuration.md
147
231
  │ │ └── ... (11 tool guides total)
148
232
  │ │
149
233
  │ └── platforms/ # Platform-specific setup
150
- │ └── windows/ # Windows/WSL guides
234
+ │ └── windows/
151
235
  │ ├── README.md
152
236
  │ ├── installation.md
153
237
  │ └── dam-testing-plan-windows-powershell.md
154
238
  │
155
239
  ├── architecture/ # WHY/HOW systems work
156
240
  │ ├── dam/ # DAM system documentation
157
- │ │ ├── implementation-roadmap.md # ⭐ START HERE - Complete dev guide
158
- │ │ ├── dam-vision.md # Strategic vision
159
- │ │ ├── dam-data-model.md # Entity schema
160
- │ │ ├── dam-visualization-requirements.md # Astro dashboard spec
161
- │ │ ├── dam-cli-enhancements.md # CLI implementation
162
- │ │ ├── jan-collaboration-guide.md # Team workflow
163
- │ │ └── design-decisions/ # DAM-specific PRDs
241
+ │ │ ├── implementation-roadmap.md # ⭐ START HERE
242
+ │ │ ├── dam-vision.md
243
+ │ │ ├── dam-data-model.md
244
+ │ │ ├── dam-visualization-requirements.md
245
+ │ │ ├── dam-cli-enhancements.md
246
+ │ │ ├── dam-cli-implementation-guide.md
247
+ │ │ ├── jan-collaboration-guide.md
248
+ │ │ └── design-decisions/
164
249
  │ │ ├── 002-client-sharing.md
165
250
  │ │ └── 003-git-integration.md
166
251
  │ │
252
+ │ ├── gpt-context/ # GPT Context documentation
253
+ │ │ ├── gpt-context-vision.md # Strategic vision
254
+ │ │ ├── gpt-context-architecture.md # Data flow & components
255
+ │ │ └── gpt-context-implementation-guide.md # Code-level details
256
+ │ │
167
257
  │ ├── cli/ # CLI architecture
168
- │ │ ├── cli-patterns.md # CLI patterns
169
- │ │ └── cli-pattern-comparison.md # Pattern guide
258
+ │ │ ├── cli-patterns.md
259
+ │ │ └── cli-pattern-comparison.md
170
260
  │ │
171
261
  │ ├── configuration/ # Configuration system
172
- │ │ └── configuration-systems.md # System overlap analysis
262
+ │ │ └── configuration-systems.md
173
263
  │ │
174
- │ └── design-decisions/ # General PRDs, ADRs, session logs
264
+ │ └── design-decisions/ # General PRDs, ADRs
175
265
  │ ├── 001-unified-brands-config.md
176
266
  │ └── session-2025-11-09.md
177
267
  │
@@ -195,12 +285,14 @@ docs/
195
285
 
196
286
  | Task | Documentation |
197
287
  |------|---------------|
198
- | **DAM development** | [Implementation Roadmap](./architecture/dam/implementation-roadmap.md) ⭐ |
288
+ | **Gather code for AI** | [GPT Context Usage](./guides/tools/gpt-context.md) |
289
+ | **Understand GPT Context design** | [GPT Context Architecture](./architecture/gpt-context/gpt-context-architecture.md) |
290
+ | **Extend GPT Context** | [GPT Context Implementation](./architecture/gpt-context/gpt-context-implementation-guide.md) |
199
291
  | **Video storage management** | [DAM Usage](./guides/tools/dam/dam-usage.md) |
200
292
  | **S3 sync for collaboration** | [DAM Usage](./guides/tools/dam/dam-usage.md) |
201
293
  | **Understand DAM architecture** | [DAM Data Model](./architecture/dam/dam-data-model.md) |
202
294
  | **Build DAM dashboard** | [Visualization Requirements](./architecture/dam/dam-visualization-requirements.md) |
203
- | **Gather AI context** | [GPT Context](./guides/tools/gpt-context.md) |
295
+ | **DAM development** | [Implementation Roadmap](./architecture/dam/implementation-roadmap.md) ⭐ |
204
296
  | **Manage YouTube videos** | [YouTube Manager](./guides/tools/youtube-manager.md) |
205
297
  | **Process subtitles** | [Subtitle Processor](./guides/tools/subtitle-processor.md) |
206
298
  | **Configure tools** | [Configuration Tool](./guides/tools/configuration.md) |
@@ -212,13 +304,15 @@ docs/
212
304
 
213
305
  | Audience | Start Here |
214
306
  |----------|------------|
307
+ | **AI-Assisted Developers** | [GPT Context Usage](./guides/tools/gpt-context.md) |
308
+ | **GPT Context Contributors** | [GPT Context Implementation](./architecture/gpt-context/gpt-context-implementation-guide.md) |
309
+ | **Video Creators** | [DAM Usage](./guides/tools/dam/dam-usage.md) |
215
310
  | **DAM Developers** | [Implementation Roadmap](./architecture/dam/implementation-roadmap.md) ⭐ |
216
- | **End Users** | [Guides](#-guides-how-to-use) - Individual tool documentation |
311
+ | **End Users** | [Guides](#-other-tools-guides) - Individual tool documentation |
217
312
  | **Windows Users** | [Windows Setup](./guides/platforms/windows/) |
218
313
  | **Team Members (Jan)** | [Jan Collaboration Guide](./architecture/dam/jan-collaboration-guide.md) |
219
- | **Developers** | [Development](#%EF%B8%8F-development-contributing) - Contributing guides |
220
314
  | **Contributors** | [CLI Patterns](./architecture/cli/cli-patterns.md) |
221
- | **Architects** | [Architecture](#%EF%B8%8F-architecture-understanding-how-it-works) - System design |
315
+ | **Architects** | [Architecture](#%EF%B8%8F-general-architecture) - System design |
222
316
 
223
317
  ---
224
318
 
@@ -263,4 +357,4 @@ When adding new documentation:
263
357
 
264
358
  ---
265
359
 
266
- **Last updated**: 2025-11-18
360
+ **Last updated**: 2025-12-06