1 line
No EOL
10 KiB
Markdown
1 line
No EOL
10 KiB
Markdown
# 🚀 Run Scripts Guide - Presentation Launcher\n\nConvenient Nushell scripts to launch Provisioning Platform presentations.\n\n## Quick Start\n\n### Option 1: Interactive Menu (Recommended)\n\n```bash\n# Standard version (more features)\nnu run.nu\n\n# Simple version (more compatible)\nnu run-simple.nu\n```\n\nShows a menu to select presentation:\n\n```plaintext\n╔═══════════════════════════════════════════════════════════════╗\n║ Provisioning Platform - Presentation Launcher ║\n╚═══════════════════════════════════════════════════════════════╝\n\n [1] pitch.md │ Executives │ 10 min\n [2] demo-intro.md │ Developers │ 15 min\n [3] talk.md │ Technical │ 30-45 min\n [4] workshop.md │ Learners │ 1-2 hours\n [5] slides.md │ All │ Custom\n\n [Q] Quit\n\nSelect presentation number (1-5):\n```\n\n### Option 2: Direct Launch\n\n```bash\n# Specify presentation as argument\nnu run.nu pitch # Launches pitch.md\nnu run.nu demo-intro # Launches demo-intro.md\nnu run.nu talk.md # Launches talk.md (with .md)\nnu run.nu workshop # Launches workshop.md\n```\n\n### Option 3: NPM Direct (No Script)\n\n```bash\npnpm run dev pitch.md\nnpm run dev talk.md\n```\n\n## Scripts Comparison\n\n| Feature | run.nu | run-simple.nu | run-ultra-simple.nu | pnpm direct |\n|---------|--------|---------------|---------------------|-------------|\n| **Interactive menu** | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No |\n| **Format validation** | ✅ Smart | ✅ Smart | ✅ Smart | ❌ Manual |\n| **File validation** | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No |\n| **Beautiful output** | ✅ Yes | ✅ Basic | ✅ Basic | ❌ No |\n| **Nushell 0.107.1+** | ✅ Required | ✅ 0.95+ | ✅ 0.90+ | N/A |\n| **Information display** | ✅ Detailed | ✅ Basic | ✅ Minimal | ❌ None |\n| **Most compatible** | ❌ | ❌ | ✅ | N/A |\n\n## `run.nu` - Full Version\n\n**Features:**\n\n- Beautiful formatted menu with descriptions\n- Audience and duration information\n- Slide count display\n- Interactive selection with error handling\n- Detailed launch information\n- Requires: Nushell 0.107.1+\n\n**Usage:**\n\n```bash\n# Interactive menu\nnu run.nu\n\n# Direct launch (auto-adds .md if needed)\nnu run.nu pitch\nnu run.nu talk\nnu run.nu demo-intro.md\n```\n\n**Output Example:**\n\n```plaintext\n🚀 Launching presentation: talk.md\n 📺 View at: http://localhost:3030\n ⌨️ Controls: Arrow keys to navigate, S for speaker view, F for fullscreen, ESC for overview\n```\n\n## `run-simple.nu` - Simplified Version\n\n**Features:**\n\n- Compatible with Nushell 0.95+\n- Simple text menu\n- Quick option selection\n- Basic error handling\n- Modern `where` syntax\n\n**Usage:**\n\n```bash\n# Interactive menu\nnu run-simple.nu\n\n# Direct launch\nnu run-simple.nu talk\n```\n\n**Menu Example:**\n\n```plaintext\n[1] pitch.md │ Executives │ 10 min\n[2] demo-intro.md │ Developers │ 15 min\n[3] talk.md │ Technical │ 30-45 min\n[4] workshop.md │ Learners │ 1-2 hours\n[5] slides.md │ All │ Custom\n\nSelect presentation (1-5):\n```\n\n## `run-ultra-simple.nu` - Ultra-Compatible Version\n\n**Features:**\n\n- Maximum compatibility (Nushell 0.90+)\n- No fancy features, just works\n- Traditional loop-based implementation\n- Zero dependencies\n- Requires: Nushell 0.90+\n\n**Usage:**\n\n```bash\n# Interactive menu\nnu run-ultra-simple.nu\n\n# Direct launch\nnu run-ultra-simple.nu talk\n```\n\n**Best For:**\n\n- Older Nushell installations\n- Compatibility-first environments\n- Systems with limited Nushell features\n\n**Note**: If you're getting deprecation warnings with `run.nu` or `run-simple.nu`, use this version instead.\n\n## Troubleshooting\n\n### "Command not found: pnpm"\n\nMake sure npm/pnpm is installed:\n\n```bash\n# Check if installed\nwhich pnpm\nwhich npm\n\n# Install pnpm if needed\nnpm install -g pnpm\n\n# Or install locally\nnpm install\n```\n\n### Script won't run\n\n```bash\n# Make sure script is executable\nls -la run.nu\n\n# If not executable, fix permissions\nchmod +x run.nu run-simple.nu\n\n# Run explicitly with nu\nnu run.nu\n```\n\n### File not found error\n\nMake sure you're in the correct directory:\n\n```bash\n# Navigate to presentation directory\ncd pres-prvng\n\n# Check files exist\nls *.md\n\n# Then run script\nnu run.nu\n```\n\n### Deprecation Warnings ("filter was deprecated in 0.105.0")\n\nIf you see warnings like:\n\n```plaintext\n⚠ filter was deprecated in 0.105.0 and will be removed in a future release.\nhelp: `where` command can be used instead\n```\n\n**Solution**: Use the appropriate script for your Nushell version:\n\n```bash\n# For Nushell 0.107.1+\nnu run.nu\n\n# For Nushell 0.95 - 0.107.0\nnu run-simple.nu\n\n# For Nushell 0.90 - 0.95 (most compatible)\nnu run-ultra-simple.nu\n```\n\n**Why**: Nushell removed the `filter` command and replaced it with `where`. Different scripts use the appropriate syntax for their version.\n\n### Nushell not installed\n\n```bash\n# Install Nushell\nbrew install nushell # macOS\nchoco install nushell # Windows\napt install nushell # Linux\n\n# Or download from https://www.nushell.sh\n\n# Check version\nnushell --version\n```\n\n## Advanced Usage\n\n### Create Alias for Easy Access\n\nAdd to your Nushell config (`~/.config/nushell/env.nu`):\n\n```nushell\n# Navigate to presentation and launch\nalias pres = { cd ~/path/to/project-provisioning/pres-prvng && nu run.nu }\n\n# Use it anywhere\npres\n```\n\n### Batch Launch Multiple Presentations\n\n```nushell\n# In Nushell REPL\nfor file in [pitch.md talk.md workshop.md] {\n print $"Opening ($file)..."\n # (Run in separate terminal or with &)\n}\n```\n\n### Custom Script\n\nCreate your own launcher:\n\n```nushell\n#!/usr/bin/env nu\n\n# Custom launcher with additional features\ndef launch-with-config [file: string] {\n print "Setting up presentation environment..."\n\n # Set environment variables\n env PRESENTATION = $file\n env START_TIME = (date now)\n\n # Launch\n pnpm run dev $file\n}\n\nlaunch-with-config "talk.md"\n```\n\n## Features Explained\n\n### Smart Extension Handling\n\n```bash\n# All these work the same way:\nnu run.nu pitch\nnu run.nu pitch.md\n\n# Script auto-detects and adds .md if needed\n```\n\n### File Validation\n\n```bash\n# Script checks if file exists before launching\nnu run.nu nonexistent.md\n# ❌ Presentation not found: nonexistent.md\n# Available:\n# • pitch.md\n# • talk.md\n# ...\n```\n\n### Interactive Selection\n\n```bash\n# If file doesn't exist, shows menu to choose\nnu run.nu invalid\n# Shows menu → you select option → launches\n\n# If no argument, shows menu immediately\nnu run.nu\n# Shows menu → you select option → launches\n```\n\n### Information Display\n\nThe script shows helpful information before launching:\n\n```plaintext\n🚀 Launching presentation: talk.md\n 📺 View at: http://localhost:3030\n ⌨️ Controls: Arrow keys to navigate, S for speaker view, F for fullscreen, ESC for overview\n```\n\n## Keyboard Controls in Presentation\n\nOnce presentation launches:\n\n| Key | Action |\n|-----|--------|\n| `→` or `Space` | Next slide |\n| `←` | Previous slide |\n| `F` | Fullscreen |\n| `S` | Speaker notes view |\n| `B` | Blank screen |\n| `ESC` | Overview/navigation |\n| `G` | Go to slide number |\n| `D` | Dark mode toggle |\n\n## Integration with Other Tools\n\n### Use in CI/CD\n\n```yaml\n# GitLab CI\nbuild-presentation:\n stage: build\n script:\n - cd pres-prvng\n - nu run.nu pitch # Validate and launch\n```\n\n### Scheduled Reload\n\n```nushell\n# Reload presentation every hour\nloop {\n nu run.nu talk\n sleep 1h\n}\n```\n\n### Combined with Demos\n\n```bash\n# Launch presentation then run demos\nnu run.nu demo-intro.md &\nsleep 5\nbash demos/01-server-creation-demo.sh\n```\n\n## Performance Notes\n\n- **First launch**: ~2-3 seconds (Nushell + pnpm startup)\n- **Hot reload**: <100ms (browser reloads on file change)\n- **Switching presentations**: <1 second\n\n## Customization\n\n### Modify Available Presentations\n\nEdit `run.nu` or `run-simple.nu`:\n\n```nushell\nlet presentations = [\n { idx: 1, name: "custom.md", audience: "My Team", duration: "20 min", slides: 15 }\n # ... add your custom presentations\n]\n```\n\n### Add Custom Menu Items\n\n```nushell\n# Add a custom option\n{ idx: 6, name: "my-presentation.md", audience: "Custom", duration: "25 min", slides: 20 }\n```\n\n### Modify Launch Message\n\nEdit the launch section:\n\n```nushell\nprint "🚀 Launching: ($selected.name)"\nprint " Your custom message here"\n```\n\n## Tips & Tricks\n\n### Quick Switch Between Presentations\n\n```bash\n# Terminal 1: Launch presentation\nnu run.nu talk\n\n# Terminal 2: Make changes to slides.md\n# Browser auto-reloads on file change\n```\n\n### Present on Second Screen\n\n```bash\n# While presenting, use:\n# - Main screen: Full presentation (F key)\n# - Second screen: Speaker notes (S key)\n# - Third window: Live demos\n```\n\n### Record Session\n\n```bash\n# Start recording\nobs &\n\n# Launch presentation\nnu run.nu workshop\n\n# Stop recording when done\n# Use recorded video for training or sharing\n```\n\n### Share Live Presentation\n\n```bash\n# Option 1: Share screen in Zoom/Teams\n# Option 2: Use ngrok to share localhost\nngrok http 3030\n# Share: https://xxxxxxxx.ngrok.io\n\n# Option 3: Export to PDF\nnpm run export-pdf pitch.md\n```\n\n## FAQ\n\n**Q: Can I run multiple presentations at once?**\nA: Yes, each instance opens a separate Vite server on different ports. Run in separate terminals.\n\n**Q: Which script should I use?**\nA: Use `run.nu` if you have Nushell 0.107.1+. Use `run-simple.nu` for older versions. Both work fine.\n\n**Q: Can I use this with npm instead of pnpm?**\nA: Yes, modify the script to use `npm run dev` instead of `pnpm run dev`.\n\n**Q: How do I autostart with a specific presentation?**\nA: Add to your shell config: `nu ~/path/to/pres-prvng/run.nu pitch`\n\n## Version Information\n\n- **Created**: 2025-11-14\n- **Nushell Version**: 0.95+ (run-simple.nu), 0.107.1+ (run.nu)\n- **Tested On**: macOS, Linux\n- **Status**: Production ready\n\n---\n\n**Happy presenting! 🎉**\n\nFor more information, see:\n\n- `QUICKSTART.md` - Quick setup\n- `PRESENTATION_GUIDE.md` - Complete guide\n- `README.md` - Main information |