appydave-tools 0.69.0 → 0.71.0

data/docs/guides/tools/video-file-namer.md

@@ -0,0 +1,400 @@
+# VideoFileNamer - Filename Generation Tool
+
+> **Web-based utility for generating structured video segment filenames** following the FliVideo naming convention.
+
+---
+
+## 📋 Overview
+
+**App Name**: VideoFileNamer
+**Type**: Web Application (Replit)
+**Purpose**: Generate structured filenames for video recording segments with clipboard management
+**Target Users**: Content creators, video producers, YouTubers
+**Database**: ReplDB
+
+### Important Clarification
+
+⚠️ **This application does NOT rename or modify actual files on your system.** It is purely a filename generator that:
+- Creates structured filenames following conventions
+- Copies filenames to your clipboard
+- You manually rename files in your file manager
+
+---
+
+## 🎯 Core Features
+
+### 1. Automatic Filename Generation
+
+Generates filenames using a standardized format compatible with **FliVideo naming conventions**:
+
+```
+[chapter]-[part]-[label]-[metadata?].mov
+```
+
+**Format Components:**
+- **Chapter**: Sequential number (1, 2, 3, etc.) - auto-incremented
+- **Part**: Part number within chapter (1, 2, 3, etc.) - resets on new chapter
+- **Label**: Chapter name/description (intro, content, outro, etc.)
+- **Metadata** (Optional): Additional tags (cta, endcards, etc.)
+
+### 2. Real-Time Filename Preview
+
+- Read-only column shows generated filename as you type
+- Updates instantly when you modify chapter, part, label, or metadata
+- Visual feedback for filename generation
+
+### 3. Clipboard Integration
+
+- Copy individual filenames to clipboard with one click
+- Auto-clipboard option: Automatically copy filenames to clipboard after you finish typing
+- Clipboard actions are logged for debugging
+
+### 4. Smart Row Management
+
+- **Next Chapter**: Adds new row with chapter incremented, part reset to 1
+- **Next Part**: Adds new row with same chapter, part incremented
+- Preserves labels when adding new parts in same chapter
+- Prevents manual data entry redundancy
+
+### 5. Data Persistence
+
+- Stores generated filenames and metadata in ReplDB
+- Retrieve history of previously generated names
+- Track transcript text alongside filenames
+
+---
+
+## 🎬 Filename Format & Examples
+
+### Default Structure
+
+```
+[chapter number]-[part number]-[label].mov
+```
+
+### With Metadata
+
+```
+[chapter number]-[part number]-[label]-[metadata].mov
+```
+
+### Examples
+
+| Input | Output |
+|-------|--------|
+| Chapter: 1, Part: 1, Label: intro | `1-1-intro.mov` |
+| Chapter: 1, Part: 2, Label: intro | `1-2-intro.mov` |
+| Chapter: 2, Part: 1, Label: content | `2-1-content.mov` |
+| Chapter: 2, Part: 1, Label: content, Metadata: cta | `2-1-content-cta.mov` |
+| Chapter: 3, Part: 2, Label: outro, Metadata: endcards | `3-2-outro-endcards.mov` |
+
+---
+
+## 🖥️ User Interface & Workflow
+
+### Initial Load
+
+- Empty table displayed on startup
+- One pre-filled row created automatically:
+  - Chapter: 1
+  - Part: 1
+  - Label: (empty - user fills in)
+
+### Typical Workflow
+
+1. **View default row**: Table shows one empty row (1-1)
+2. **Enter label**: Type label name (e.g., "intro")
+3. **See filename update**: Read-only column shows `1-1-intro.mov`
+4. **Copy filename**: Click copy button or enable auto-clipboard
+5. **Add more segments**: Use "Next Part" to add 1-2, "Next Chapter" to add 2-1
+6. **Continue workflow**: Repeat for each segment
+
+### UI Elements
+
+#### Input Fields (Per Row)
+- **Chapter**: Numeric input (auto-incremented via buttons)
+- **Part**: Numeric input (auto-incremented via buttons)
+- **Label**: Text input (chapter name/description)
+- **Metadata**: Text input (optional tags)
+
+#### Output Column
+- **Filename**: Read-only display of generated name
+- **Copy Button**: One-click clipboard copy
+
+#### Control Buttons
+- **Next Chapter**: Increment chapter, reset part to 1, add new row
+- **Next Part**: Increment part, keep chapter, add new row
+- **Auto-Clipboard Checkbox**: Toggle auto-copy functionality
+
+#### Additional Controls
+- **Delete Row**: Remove row from table
+- **Clear All**: Start fresh
+
+---
+
+## ⚙️ Technical Specifications
+
+### Filename Generation Algorithm
+
+```
+1. Validate inputs (chapter, part, label not empty)
+2. Format chapter as integer (1, 2, 3... not 01, 02, 03)
+3. Format part as integer (1, 2, 3... not 01, 02, 03)
+4. Combine: "{chapter}-{part}-{label}"
+5. Append metadata if provided: "{chapter}-{part}-{label}-{metadata}"
+6. Append extension: "{chapter}-{part}-{label}-{metadata}.mov"
+```
+
+### Auto-Increment Logic
+
+**Next Chapter Button:**
+- Chapter: current_chapter + 1
+- Part: reset to 1
+- Label: prompt user for new chapter name
+- Create new row with these values
+
+**Next Part Button:**
+- Chapter: keep same
+- Part: current_part + 1
+- Label: preserve from previous row
+- Create new row with these values
+
+### Debouncing
+
+- API calls debounced to 1 second after user stops typing
+- Prevents excessive database operations
+- Smooth typing experience without lag
+
+### Auto-Clipboard
+
+- Triggered 1 second after user finishes editing
+- Only copies when auto-clipboard is enabled
+- Shows toast notification: "Filename copied to clipboard"
+- Logged for debugging
+
+---
+
+## 📊 Data Structure
+
+### File Entry
+
+```json
+{
+  "id": "unique-identifier",
+  "chapter": 1,
+  "part": 1,
+  "label": "intro",
+  "metadata": ["cta"],
+  "filename": "1-1-intro-cta.mov",
+  "transcript": "Optional transcript text...",
+  "createdAt": "2024-11-25T10:30:00Z",
+  "updatedAt": "2024-11-25T10:30:00Z"
+}
+```
+
+### Database Storage (ReplDB)
+
+- **Filenames Table**: Stores all generated filename entries
+- **Metadata Table**: Optional - stores transcript and additional context
+- **History**: Full edit history maintained for reference
+
+---
+
+## 🔍 Input Validation
+
+### Required Fields
+- ✅ **Chapter**: Must be numeric, > 0
+- ✅ **Part**: Must be numeric, > 0
+- ✅ **Label**: Must not be empty
+
+### Optional Fields
+- ⭕ **Metadata**: Optional, can contain multiple comma-separated tags
+
+### Error Handling
+
+**Display descriptive errors:**
+- "Chapter must be a number greater than 0"
+- "Label cannot be empty"
+- "Database connection error - please try again"
+- "Clipboard copy failed - try again manually"
+
+---
+
+## 📝 Logging & Debugging
+
+### Logged Events
+
+**Input Changes:**
+```
+[LOG] Chapter changed: 1 → 2
+[LOG] Part changed: 1 → 2
+[LOG] Label changed: "" → "intro"
+[LOG] Metadata changed: "" → "cta"
+```
+
+**Filename Generation:**
+```
+[LOG] Filename generated: 1-1-intro.mov
+[LOG] Filename updated: 1-1-intro.mov → 1-1-intro-cta.mov
+```
+
+**Clipboard Actions:**
+```
+[LOG] Filename copied to clipboard: 1-1-intro.mov
+[LOG] Auto-clipboard enabled: true
+[LOG] Auto-clipboard disabled: false
+```
+
+**Database Operations:**
+```
+[LOG] Saving filename to database: 1-1-intro.mov
+[LOG] Retrieved 12 filenames from history
+[LOG] Database error: Connection timeout
+```
+
+### Browser Console
+
+- All events logged to browser console (F12 → Console tab)
+- Timestamps included for debugging
+- Debug information easily searchable for troubleshooting
+
+---
+
+## 🎬 Integration with FliVideo
+
+VideoFileNamer is a companion tool to **FliVideo** that generates segment filenames following FliVideo naming conventions:
+
+### FliVideo Naming Standards
+
+| Element | Format | Example |
+|---------|--------|---------|
+| Project Folder | `[sequence]-[project-name]` | `a27-my-video-project` |
+| Episode Folder | `[sequence]-[episode-name]` | `01-introduction` |
+| **Video Segment** | **`[chapter]-[part]-[label].mov`** | **`1-1-intro.mov`** ✅ |
+| Project Structure | `/project/recordings/` | `/a27-my-video/recordings/` |
+
+### Workflow Integration
+
+```
+Ecamm Live Recording
+      ↓
+[automatic save with date/time name]
+      ↓
+VideoFileNamer
+[generate: 1-1-intro.mov]
+      ↓
+Manual Rename
+[1-1-intro.mov on file system]
+      ↓
+FliVideo Project
+[organized in recordings/ folder]
+      ↓
+Transcription & Processing
+[FliVideo handles this automatically]
+```
+
+---
+
+## 🚀 Quick Start
+
+### Access the App
+
+1. Open Replit project: **VideoFileNamer (4)**
+2. Start development server: `npm run dev`
+3. Navigate to: `http://localhost:5000`
+
+### Basic Usage
+
+1. **First segment**:
+   - Label field shows empty, type "intro"
+   - Filename generates: `1-1-intro.mov`
+   - Click copy or enable auto-clipboard
+
+2. **Second attempt at intro**:
+   - Click "Next Part"
+   - Filename generates: `1-2-intro.mov`
+   - Label preserved automatically
+
+3. **Move to next chapter**:
+   - Click "Next Chapter"
+   - System prompts for new chapter name: "content"
+   - Filename generates: `2-1-content.mov`
+
+### Common Actions
+
+| Action | Steps |
+|--------|-------|
+| Copy filename | Click copy button OR enable auto-clipboard |
+| Add video segment | Click "Next Part" (same chapter) |
+| Start new chapter | Click "Next Chapter" (reset part) |
+| Undo/Delete row | Click delete button on row |
+| Clear everything | Click "Clear All" button |
+
+---
+
+## 🔧 Troubleshooting
+
+### Application Won't Start
+
+```bash
+# Check if port is in use
+lsof -i :5000
+
+# Kill existing process
+pkill -f "node|tsx"
+
+# Start fresh
+npm run dev
+```
+
+### Typing Lag
+
+- Debouncing is set to 1 second
+- Short delay is normal while API processes
+- Should feel responsive after debouncing implementation
+- Check browser console (F12) for errors
+
+### Filenames Not Saving
+
+- Check ReplDB connection status
+- Verify metadata fields are not empty
+- Check browser console for database errors
+- Try refreshing page and re-entering data
+
+### Clipboard Copy Failed
+
+- Some browsers restrict clipboard access
+- Try using the copy button instead of auto-clipboard
+- Or manually select and copy the filename text
+- Check browser console for permission errors
+
+---
+
+## 📦 Feature Checklist
+
+- ✅ Automatic filename generation
+- ✅ Real-time filename preview
+- ✅ Chapter/part smart increment buttons
+- ✅ Label preservation on next part
+- ✅ Optional metadata support
+- ✅ Clipboard copy (manual)
+- ✅ Auto-clipboard option with debouncing
+- ✅ ReplDB persistence
+- ✅ Comprehensive logging
+- ✅ Error handling and validation
+- ✅ User-friendly UI with table layout
+- ✅ Responsive design
+
+---
+
+## 📖 Related Documentation
+
+- **[FliVideo Naming Conventions](../../../architecture/dam/dam-vision.md)** - Project/episode/segment naming standards
+- **[FliVideo Overview](../../../../../../flivideo/docs/fli-video.md)** - Complete VAM system
+- **[DAM (Digital Asset Management)](./dam/)** - Video project organization
+
+---
+
+**Last Updated**: 2025-11-25
+**Status**: Active
+**Platform**: Replit (Web-based)

data/docs/specs/fr-002-gpt-context-help-system.md

@@ -0,0 +1,265 @@
+# FR-002: GPT Context AI-Friendly Help System
+
+**Status**: Ready for Development
+**Priority**: High
+**Created**: 2025-12-07
+
+---
+
+## Summary
+
+Enhance GPT Context's help system to provide structured, comprehensive documentation suitable for AI agent consumption. Model after DAM's multi-level help architecture.
+
+---
+
+## User Story
+
+As an AI agent using GPT Context via skills, I want structured, comprehensive help output so I can understand all options and use the tool correctly without guessing.
+
+---
+
+## Current State
+
+**GPT Context help** (`gpt_context --help`):
+- Basic OptionParser output
+- Lists flags with brief descriptions
+- No examples, no detailed explanations
+- No `--version` flag
+
+**DAM help** (`dam help`):
+- Multi-level: `dam help`, `dam help [topic]`
+- Structured sections with examples
+- Topic-specific deep dives
+- Machine-parseable format
+
+---
+
+## Requirements
+
+### Must Have
+
+1. **Enhanced `--help` output** with structured sections:
+   - Synopsis (command signature)
+   - Description (what the tool does)
+   - Options (all flags with details)
+   - Output Formats (tree, content, json, aider, files)
+   - Examples (real-world usage)
+
+2. **Each option must include**:
+   - Flag(s): `-i, --include`
+   - Description: What it does
+   - Default: Default value if any
+   - Valid values: For constrained options like `-f`
+
+3. **Add `--version` flag**
+   - Output: `gpt_context version X.Y.Z`
+
+4. **Real-world examples** in help output:
+   ```
+   Examples:
+     # Gather Ruby library code
+     gpt_context -i 'lib/**/*.rb' -e 'spec/**/*' -d
+
+     # Project structure overview
+     gpt_context -i '**/*' -f tree -e 'node_modules/**/*'
+
+     # Generate aider command
+     gpt_context -i 'lib/**/*.rb' -f aider -p "Add logging"
+   ```
+
+### Nice to Have
+
+- `gpt_context help formats` - detailed format documentation
+- `gpt_context help examples` - extended examples collection
+- Markdown-formatted output option (`--help --format md`)
+
+---
+
+## Technical Implementation
+
+### File Locations
+
+- **CLI**: `bin/gpt_context.rb`
+- **Options**: `lib/appydave/tools/gpt_context/options.rb`
+- **Version**: `lib/appydave/tools/version.rb` (already exists)
+
+### Approach
+
+**Option A: Enhanced OptionParser** (Recommended)
+- Keep single `--help` flag
+- Add custom `banner` and `separator` calls for structure
+- Add `--version` flag
+- Simpler, maintains current architecture
+
+**Option B: Subcommand Pattern** (Like DAM)
+- Add `help` subcommand with topics
+- More complex, requires CLI restructure
+- Overkill for single-purpose tool
+
+### Recommended: Option A
+
+Enhance the existing OptionParser in `bin/gpt_context.rb`:
+
+```ruby
+# Current structure (simplified)
+OptionParser.new do |opts|
+  opts.banner = "Usage: gpt_context [options]"
+  opts.on('-i', '--include PATTERN', 'Include pattern') { ... }
+  # etc
+end
+
+# Enhanced structure
+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 ""
+  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|
+    # ...
+  end
+
+  opts.on('-e', '--exclude PATTERN',
+          'Glob pattern for files to exclude (repeatable)',
+          'Example: -e "spec/**/*" -e "node_modules/**/*"') do |pattern|
+    # ...
+  end
+
+  opts.on('-f', '--format FORMATS',
+          'Output format(s): tree, content, json, aider, files',
+          'Comma-separated. Default: content',
+          'Example: -f tree,content') do |formats|
+    # ...
+  end
+
+  opts.on('-o', '--output TARGET',
+          'Output target: clipboard, filename, or stdout',
+          'Default: clipboard') do |target|
+    # ...
+  end
+
+  opts.on('-d', '--debug', 'Enable debug output') do
+    # ...
+  end
+
+  opts.on('-l', '--line-limit N', Integer,
+          'Limit lines per file (default: unlimited)') do |n|
+    # ...
+  end
+
+  opts.on('-p', '--prompt TEXT',
+          'Prompt text for aider format') do |text|
+    # ...
+  end
+
+  opts.separator ""
+  opts.separator "OUTPUT FORMATS"
+  opts.separator "    tree     - Directory tree structure"
+  opts.separator "    content  - File contents with headers"
+  opts.separator "    json     - Structured JSON output"
+  opts.separator "    aider    - Aider CLI command format"
+  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('-h', '--help', 'Show this help') do
+    puts opts
+    exit
+  end
+end
+```
+
+---
+
+## Acceptance Criteria
+
+- [ ] `gpt_context --help` shows structured output with sections
+- [ ] All options include description, default (if any), and examples
+- [ ] Examples section shows 3-4 real-world use cases
+- [ ] Output formats section explains each format
+- [ ] `gpt_context --version` outputs version number
+- [ ] Help output is easily parseable by AI agents (clear sections, consistent formatting)
+
+---
+
+## Testing
+
+```bash
+# Manual verification
+gpt_context --help        # Should show enhanced help
+gpt_context --version     # Should show version
+gpt_context -v            # Short version flag
+
+# Verify help includes all required sections
+gpt_context --help | grep -E "^(SYNOPSIS|DESCRIPTION|OPTIONS|OUTPUT FORMATS|EXAMPLES)"
+```
+
+Add spec:
+```ruby
+# spec/appydave/tools/gpt_context/cli_spec.rb
+describe 'CLI help' do
+  it 'includes synopsis section' do
+    output = `bin/gpt_context.rb --help`
+    expect(output).to include('SYNOPSIS')
+  end
+
+  it 'includes examples section' do
+    output = `bin/gpt_context.rb --help`
+    expect(output).to include('EXAMPLES')
+  end
+
+  it 'shows version' do
+    output = `bin/gpt_context.rb --version`
+    expect(output).to match(/gpt_context version \d+\.\d+\.\d+/)
+  end
+end
+```
+
+---
+
+## Definition of Done
+
+1. Enhanced `--help` output with all sections
+2. `--version` flag working
+3. Specs pass
+4. Manual verification complete
+5. Commit with `kfeat "add AI-friendly help system to GPT Context"`
+
+---
+
+## Reference
+
+- **DAM help implementation**: `bin/dam` lines 1-200 (help system)
+- **Current GPT Context CLI**: `bin/gpt_context.rb`
+- **GPT Context architecture**: `docs/architecture/gpt-context/`