@smartergpt/lexrunner 1.0.0 → 1.3.0

package/docs/tutorials/README.md

@@ -1,201 +0,0 @@
-# Video Tutorial Scripts
-
-This directory contains scripts and resources for creating video tutorials about lexrunner.
-
-## Quick Start Tutorial
-
-**[Quick Merge Pyramid](./quick-merge-pyramid.md)** (10 minutes) - Complete hands-on tutorial
-
-- Discover → Plan → Execute → Merge workflow
-- Dependency management and merge order
-- Gate execution and verification
-- Common patterns and best practices
-- **Start here** for a practical introduction to lexrunner!
-
-## Available Scripts
-
-1. **[Getting Started](./01-getting-started.md)** (5 minutes)
-   - Installation and setup
-   - First successful merge
-   - Target audience: New users
-
-2. **[Understanding Dependencies](./02-understanding-dependencies.md)** (8 minutes)
-   - Dependency syntax
-   - Merge order computation
-   - Target audience: Developers
-
-3. **[Quality Gates](./03-quality-gates.md)** (10 minutes)
-   - Configuring gates
-   - Gate execution
-   - Target audience: DevOps/QA
-
-4. **[CI/CD Integration](./04-cicd-integration.md)** (12 minutes)
-   - GitHub Actions setup
-   - Automated workflows
-   - Target audience: Platform engineers
-
-5. **[Advanced Workflows](./05-advanced-workflows.md)** (15 minutes)
-   - PR stacks
-   - Team coordination
-   - Target audience: Tech leads
-
-## Video Production Guidelines
-
-### Recording Setup
-
-**Screen Recording:**
-
-- Resolution: 1920x1080 (1080p)
-- Frame rate: 30 fps
-- Software: OBS Studio, ScreenFlow, or Camtasia
-
-**Terminal:**
-
-- Font: Monaco or Fira Code, 14pt
-- Color scheme: Solarized Dark or Nord
-- Window size: 80x24 minimum
-
-**Audio:**
-
-- Microphone: USB condenser mic (Blue Yeti or similar)
-- Sample rate: 48kHz
-- No background music during code demos
-
-### Visual Style
-
-**Terminal Prompts:**
-
-```bash
-# Use clear, short prompts
-$ lex-pr init
-
-# Show output immediately
-✓ Workspace initialized
-
-# Highlight important output
-[✓] All gates passed
-```
-
-**Code Examples:**
-
-- Use syntax highlighting
-- Show complete, runnable examples
-- Include error cases and recovery
-
-**Annotations:**
-
-- Add text overlays for key concepts
-- Use arrows to highlight CLI output
-- Show keyboard shortcuts
-
-### Pacing
-
-- **Introduction:** 30 seconds (what you'll learn)
-- **Setup:** 1-2 minutes (prerequisites)
-- **Demonstration:** 60-70% of video (hands-on)
-- **Recap:** 30 seconds (what you learned)
-- **Next Steps:** 30 seconds (where to go next)
-
-## Recording Checklist
-
-Before recording:
-
-- [ ] Test all commands in clean environment
-- [ ] Prepare sample repository with example PRs
-- [ ] Script key talking points
-- [ ] Close unnecessary applications
-- [ ] Disable notifications
-- [ ] Test audio levels
-
-During recording:
-
-- [ ] Speak clearly and at moderate pace
-- [ ] Pause between commands to show output
-- [ ] Explain what you're doing and why
-- [ ] Show both success and error cases
-- [ ] Point out important output/results
-
-After recording:
-
-- [ ] Add captions/subtitles
-- [ ] Include chapter markers
-- [ ] Add end screen with links
-- [ ] Test playback at 1x and 1.5x speed
-
-## Sample Repository Setup
-
-Create example repository for demos:
-
-```bash
-# Create demo repo
-mkdir lex-pr-demo
-cd lex-pr-demo
-git init
-
-# Create sample PRs (use gh CLI)
-gh pr create --title "Add authentication" --body "Base feature" --label "ready"
-gh pr create --title "Add API endpoints" --body "Depends-On: #1" --label "ready"
-gh pr create --title "Add dashboard" --body "Depends-On: #2" --label "ready"
-
-# Initialize lexrunner
-lex-pr init
-```
-
-## Accompanying Resources
-
-For each video, provide:
-
-1. **Written transcript** - Full text of narration
-2. **Code snippets** - Copy-pasteable examples
-3. **Slide deck** - Key concepts and diagrams
-4. **Exercise files** - Sample configurations
-5. **Quiz** - Test understanding (optional)
-
-## Publishing
-
-### YouTube
-
-- Title format: "lexrunner: [Topic] - [Duration]"
-- Description: Link to docs, timestamps, resources
-- Tags: git, automation, pr, merge, ci-cd, devops
-- Playlist: "lexrunner Tutorials"
-
-### Documentation Site
-
-- Embed videos in relevant docs pages
-- Provide download links for offline viewing
-- Include transcript for accessibility
-
-## Maintenance
-
-Update videos when:
-
-- CLI interface changes significantly
-- New major features added
-- Best practices evolve
-
-Strategy:
-
-- Create new video for major changes
-- Add pinned comment for minor updates
-- Archive outdated videos with redirect
-
-## Feedback
-
-Collect viewer feedback via:
-
-- YouTube comments
-- GitHub Discussions
-- Video-specific survey links
-
-Track metrics:
-
-- Watch time and completion rate
-- Likes/dislikes ratio
-- Common questions in comments
-
-## Related Documentation
-
-- [Quickstart Guide](../quickstart.md) - Text version of Getting Started
-- [CLI Reference](../cli.md) - Complete command documentation
-- [Examples](../../examples/) - Working code examples

package/docs/tutorials/diffgraph-planner/01-simple-stack.md

@@ -1,460 +0,0 @@
-# Tutorial 1: Simple Stack Planning
-
-Learn how to generate a plan for a linear dependency chain using diffgraph auto-discovery.
-
-**Time to complete:** ~5 minutes
-
-**Difficulty:** Beginner
-
----
-
-## Goal
-
-Generate and execute a plan for 3 PRs that build on each other sequentially (a "stack").
-
-## Scenario
-
-You have 3 open PRs that form a linear dependency chain:
-
-1. **PR-100:** `feature/auth-api` - Add authentication API endpoints (foundation)
-2. **PR-101:** `feature/auth-ui` - Add authentication UI components (depends on API)
-3. **PR-102:** `feature/auth-tests` - Add E2E tests for authentication (depends on UI)
-
-**Dependency graph:**
-
-```
-PR-100 → PR-101 → PR-102
-```
-
-## Prerequisites
-
-- lexrunner installed (`npm install -g lexrunner`)
-- GitHub repository with 3 open PRs
-- GitHub token set: `export GITHUB_TOKEN=your_token_here`
-- Basic understanding of Git and GitHub PRs
-
----
-
-## Step 1: Prepare PR Descriptions
-
-Update the PR descriptions with explicit `Depends-on:` footers.
-
-### PR-100 (auth-api) Description
-
-```markdown
-# Add Authentication API
-
-Implement core authentication endpoints:
-
-- POST /api/auth/login
-- POST /api/auth/logout
-- GET /api/auth/session
-
-## Changes
-
-- Add auth routes
-- Add session management
-- Add password hashing
-
-(No dependencies - this is the foundation)
-```
-
-### PR-101 (auth-ui) Description
-
-```markdown
-# Add Authentication UI
-
-Implement authentication UI components:
-
-- Login form
-- Logout button
-- Session indicator
-
-## Dependencies
-
-Depends-on: #100
-
-## Changes
-
-- Add LoginForm component
-- Add LogoutButton component
-- Add SessionStatus component
-```
-
-### PR-102 (auth-tests) Description
-
-```markdown
-# Add Authentication E2E Tests
-
-Add end-to-end tests for the complete authentication flow:
-
-- Login flow test
-- Logout flow test
-- Session persistence test
-
-## Dependencies
-
-Depends-on: #101
-
-## Changes
-
-- Add E2E test suite
-- Add test fixtures
-- Add test utilities
-```
-
-**Key points:**
-
-- PR-100 has **no dependencies** (foundation)
-- PR-101 **depends on PR-100** (`Depends-on: #100`)
-- PR-102 **depends on PR-101** (`Depends-on: #101`)
-
----
-
-## Step 2: Generate Plan
-
-Run the planner to generate a plan from GitHub PRs:
-
-```bash
-lex-pr plan --from-github --output plan.json
-```
-
-**Expected output:**
-
-```
-🔍 Fetching open PRs from GitHub...
-✓ Found 3 open PRs
-
-📝 Parsing dependencies...
-✓ Parsed dependencies: 2 explicit, 0 implicit
-
-🔍 Validating plan...
-✓ No cycles detected
-✓ No orphan PRs
-✓ No invalid references
-
-📊 Plan statistics:
-  - 3 nodes
-  - 2 edges
-  - 3 layers
-
-✓ Plan generated successfully
-
-Plan written to: plan.json
-```
-
-**What happened:**
-
-1. Planner fetched 3 open PRs from GitHub
-2. Parsed `Depends-on:` footers from PR descriptions
-3. Validated the dependency graph (no cycles)
-4. Computed merge layers using topological sort
-5. Generated `plan.json`
-
----
-
-## Step 3: Review Plan Structure
-
-Inspect the generated plan file:
-
-```bash
-cat plan.json
-```
-
-**Expected content:**
-
-```json
-{
-  "schemaVersion": "1.0.0",
-  "target": "main",
-  "items": [
-    {
-      "id": "pr-100",
-      "name": "auth-api",
-      "branch": "feature/auth-api",
-      "sha": "abc123...",
-      "deps": [],
-      "strategy": "merge-weave",
-      "gates": []
-    },
-    {
-      "id": "pr-101",
-      "name": "auth-ui",
-      "branch": "feature/auth-ui",
-      "sha": "def456...",
-      "deps": ["auth-api"],
-      "strategy": "merge-weave",
-      "gates": []
-    },
-    {
-      "id": "pr-102",
-      "name": "auth-tests",
-      "branch": "feature/auth-tests",
-      "sha": "ghi789...",
-      "deps": ["auth-ui"],
-      "strategy": "merge-weave",
-      "gates": []
-    }
-  ]
-}
-```
-
-**Key observations:**
-
-- `pr-100` has `deps: []` (no dependencies, Layer 0)
-- `pr-101` depends on `["auth-api"]` (Layer 1)
-- `pr-102` depends on `["auth-ui"]` (Layer 2)
-- All items are sorted deterministically
-
----
-
-## Step 4: Review Merge Order
-
-Visualize the computed merge order:
-
-```bash
-lex-pr merge-order plan.json
-```
-
-**Expected output:**
-
-```
-📊 Merge order for 3 items:
-
-Layer 0 (ready to merge):
-  → PR-100 (auth-api)
-
-Layer 1 (after PR-100):
-  → PR-101 (auth-ui)
-
-Layer 2 (after PR-101):
-  → PR-102 (auth-tests)
-```
-
-**Understanding layers:**
-
-- **Layer 0:** PRs with no dependencies, can merge immediately
-- **Layer 1:** PRs that depend on Layer 0, merge after Layer 0 completes
-- **Layer 2:** PRs that depend on Layer 1, merge after Layer 1 completes
-
-**Merge order:**
-
-1. Merge PR-100 first
-2. After PR-100 succeeds, merge PR-101
-3. After PR-101 succeeds, merge PR-102
-
----
-
-## Step 5: Execute Gates
-
-Run quality gates for all items in the plan:
-
-```bash
-lex-pr execute --plan plan.json
-```
-
-**Expected output:**
-
-```
-📦 Executing plan: 3 items, 3 layers
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Layer 0: 1 item
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Running gates for PR-100 (auth-api)...
-  ✓ lint: passed (1.2s)
-  ✓ typecheck: passed (2.5s)
-  ✓ test: passed (8.3s)
-
-All gates passed for PR-100 ✓
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Layer 1: 1 item
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Running gates for PR-101 (auth-ui)...
-  ✓ lint: passed (1.1s)
-  ✓ typecheck: passed (2.3s)
-  ✓ test: passed (9.7s)
-
-All gates passed for PR-101 ✓
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Layer 2: 1 item
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Running gates for PR-102 (auth-tests)...
-  ✓ lint: passed (1.0s)
-  ✓ typecheck: passed (2.1s)
-  ✓ test: passed (15.8s)
-
-All gates passed for PR-102 ✓
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-✨ All gates passed! Ready to merge.
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-**What happened:**
-
-1. Gates run in **dependency order** (Layer 0 → Layer 1 → Layer 2)
-2. Each item's gates must **pass** before proceeding to the next layer
-3. Results are saved to `.smartergpt/runner/gate-results/`
-4. Exit code 0 indicates all gates passed
-
----
-
-## Step 6: Execute Merge
-
-Merge the PRs in the computed order:
-
-```bash
-# Preview merge operations (dry-run)
-lex-pr merge --plan plan.json
-
-# Execute merge for real
-lex-pr merge --plan plan.json --execute
-```
-
-**Expected output (dry-run):**
-
-```
-🔍 Dry-run mode: Previewing merge operations
-
-Layer 0:
-  → PR-100 (auth-api): Would merge to main ✓
-
-Layer 1:
-  → PR-101 (auth-ui): Would merge to main (after PR-100) ✓
-
-Layer 2:
-  → PR-102 (auth-tests): Would merge to main (after PR-101) ✓
-
-✓ All PRs would merge successfully
-Run with --execute to perform actual merges
-```
-
-**Expected output (execute):**
-
-```
-🚀 Executing merge plan...
-
-Merging PR-100 (auth-api)...
-  ✓ Merged to main (sha: abc123)
-  ✓ Deleted branch: feature/auth-api
-  ✓ Closed PR #100
-
-Merging PR-101 (auth-ui)...
-  ✓ Merged to main (sha: def456)
-  ✓ Deleted branch: feature/auth-ui
-  ✓ Closed PR #101
-
-Merging PR-102 (auth-tests)...
-  ✓ Merged to main (sha: ghi789)
-  ✓ Deleted branch: feature/auth-tests
-  ✓ Closed PR #102
-
-✨ All PRs merged successfully!
-```
-
----
-
-## Step 7: Verify Success
-
-Confirm all PRs merged in the correct order:
-
-```bash
-# Check git log
-git log --oneline --graph -10
-```
-
-**Expected output:**
-
-```
-*   abc1234 Merge PR #102: Add authentication E2E tests
-|\
-| * def5678 Add E2E test suite
-*   ghi9012 Merge PR #101: Add authentication UI
-|\
-| * jkl3456 Add UI components
-*   mno7890 Merge PR #100: Add authentication API
-|\
-| * pqr1234 Add auth endpoints
-* stu5678 Previous commit on main
-```
-
-**Verification checklist:**
-
-- ✅ All 3 PRs merged to `main`
-- ✅ Merge order is correct (PR-100 → PR-101 → PR-102)
-- ✅ No merge conflicts occurred
-- ✅ All branches deleted (optional)
-- ✅ All PRs closed
-
----
-
-## Common Issues
-
-### Issue: "Dependency cycle detected"
-
-**Symptom:**
-
-```
-❌ Validation failed: Dependency cycle detected
-```
-
-**Cause:** Circular dependency in PR descriptions.
-
-**Solution:**
-Check PR descriptions for circular `Depends-on:` references. Remove the cycle by eliminating the weakest dependency.
-
-### Issue: "Invalid dependency reference"
-
-**Symptom:**
-
-```
-❌ Validation failed: Invalid dependency reference #100
-```
-
-**Cause:** Referenced PR doesn't exist or is not included in the plan.
-
-**Solution:**
-
-- Check that PR-100 exists: `gh pr view 100`
-- Verify it's open and matches label filters
-- Update the PR number if incorrect
-
-### Issue: Gates fail for PR-101
-
-**Symptom:**
-
-```
-❌ test: failed (exit code 1)
-```
-
-**Cause:** PR-101's tests depend on PR-100 being merged first.
-
-**Solution:**
-This is expected! The planner will:
-
-1. Merge PR-100
-2. Then re-run gates for PR-101 (which should now pass)
-3. Then merge PR-101
-
----
-
-## Next Steps
-
-Congratulations! You've successfully planned and merged a simple stack. Next tutorials:
-
-- **[Tutorial 2: Diamond Pattern](./02-diamond-pattern.md)** - Fan-out/fan-in dependencies
-- **[Tutorial 3: Large Batch](./03-large-batch.md)** - Managing 20+ PRs
-- **[Tutorial 4: Fixing Cycles](./04-fixing-cycles.md)** - Resolving circular dependencies
-- **[Tutorial 5: Hybrid Workflow](./05-hybrid-workflow.md)** - Combining explicit + implicit dependencies
-
-## Related Documentation
-
-- **[Diffgraph Planner Guide](../../diffgraph-planner.md)** - Complete feature documentation
-- **[CLI Reference](../../cli.md)** - Full command documentation
-- **[Dependency Parser](../../dependency-parser.md)** - Parser details