Skip to main content

sprite/commands/
help.rs

1//! Help command - Comprehensive help system for Sprite
2
3use crate::cli::HelpCategory;
4use crate::utils::help::{
5    get_help_system, search_help, show_accessible_help, show_help, show_usage_patterns,
6    UsageCategory,
7};
8use anyhow::Result;
9
10/// Command-line arguments for the help command.
11#[derive(Debug)]
12pub struct HelpArgs {
13    /// Command to get help for
14    pub command: Option<String>,
15
16    /// Search help content
17    pub search: Option<String>,
18
19    /// Show usage patterns
20    pub patterns: bool,
21
22    /// Show troubleshooting guides
23    pub troubleshooting: bool,
24
25    /// Show quick reference
26    pub quick: bool,
27
28    /// Show accessible help (screen reader friendly)
29    pub accessible: bool,
30
31    /// Show usage patterns for specific category
32    pub category: Option<HelpCategory>,
33}
34
35impl From<HelpCategory> for UsageCategory {
36    fn from(category: HelpCategory) -> Self {
37        match category {
38            HelpCategory::GettingStarted => UsageCategory::GettingStarted,
39            HelpCategory::DailyWorkflow => UsageCategory::DailyWorkflow,
40            HelpCategory::Troubleshooting => UsageCategory::Troubleshooting,
41            HelpCategory::Advanced => UsageCategory::Advanced,
42            HelpCategory::Collaboration => UsageCategory::Collaboration,
43        }
44    }
45}
46
47/// Execute the help command with the given arguments.
48pub fn execute(args: HelpArgs) -> Result<()> {
49    // Handle accessible help request
50    if args.accessible {
51        return show_accessible_help(args.command.as_deref());
52    }
53
54    // Handle search request
55    if let Some(query) = args.search {
56        return search_help(&query);
57    }
58
59    // Handle usage patterns request
60    if args.patterns {
61        let category = args.category.map(|c| c.into());
62        return show_usage_patterns(category);
63    }
64
65    // Handle troubleshooting request
66    if args.troubleshooting {
67        return show_troubleshooting();
68    }
69
70    // Handle quick reference request
71    if args.quick {
72        return show_quick_reference();
73    }
74
75    // Default help for specific command or general help
76    show_help(args.command.as_deref())
77}
78
79/// Show troubleshooting guides.
80fn show_troubleshooting() -> Result<()> {
81    let help_system = get_help_system();
82    let guides = help_system.get_troubleshooting();
83
84    if guides.is_empty() {
85        println!("🔧 No troubleshooting guides available.");
86        return Ok(());
87    }
88
89    println!("🔧 Troubleshooting Guides\n");
90    for guide in guides {
91        println!("❓ Problem: {}", guide.problem);
92
93        if !guide.symptoms.is_empty() {
94            println!("🔍 Symptoms:");
95            for symptom in &guide.symptoms {
96                println!("  • {}", symptom);
97            }
98        }
99
100        if !guide.causes.is_empty() {
101            println!("🤔 Possible Causes:");
102            for cause in &guide.causes {
103                println!("  • {}", cause);
104            }
105        }
106
107        if !guide.solutions.is_empty() {
108            println!("💡 Solutions:");
109            for solution in &guide.solutions {
110                println!("  → {}", solution);
111            }
112        }
113
114        if !guide.prevention.is_empty() {
115            println!("🛡️  Prevention:");
116            for prevention in &guide.prevention {
117                println!("  • {}", prevention);
118            }
119        }
120
121        if !guide.related_commands.is_empty() {
122            println!("🔗 Related Commands: {}", guide.related_commands.join(", "));
123        }
124
125        println!();
126    }
127
128    Ok(())
129}
130
131/// Show quick reference.
132fn show_quick_reference() -> Result<()> {
133    let help_system = get_help_system();
134    let quick_ref = help_system.get_quick_reference();
135
136    println!("⚡ Quick Reference\n");
137
138    // Common commands
139    println!("🔥 Most Common Commands:");
140    for (i, cmd) in quick_ref.common_commands.iter().enumerate() {
141        println!("  {}. {}", i + 1, cmd);
142    }
143
144    println!();
145
146    // Keyboard shortcuts
147    if !quick_ref.shortcuts.is_empty() {
148        println!("⌨️  Keyboard Shortcuts:");
149        for shortcut in &quick_ref.shortcuts {
150            println!("  {} - {}", shortcut.keys, shortcut.description);
151            println!("     Context: {}", shortcut.context);
152        }
153        println!();
154    }
155
156    // FAQ
157    if !quick_ref.faq.is_empty() {
158        println!("❓ Frequently Asked Questions:");
159        for faq in &quick_ref.faq {
160            println!("  Q: {}", faq.question);
161            println!("  A: {}", faq.answer);
162            if !faq.related_commands.is_empty() {
163                println!("  Related: {}", faq.related_commands.join(", "));
164            }
165            println!();
166        }
167    }
168
169    println!("💡 For detailed help: sprite help <command>");
170    println!("🔍 For search: sprite help --search <query>");
171
172    Ok(())
173}
174
175/// Show comprehensive help overview.
176#[allow(dead_code)]
177pub fn show_help_overview() -> Result<()> {
178    println!("🚀 Sprite - Multi-Agent Workflow Toolkit\n");
179    println!("Sprite helps you manage multiple AI coding agents in isolated tmux sessions\n");
180    println!("with comprehensive workspace management and health monitoring.\n");
181
182    println!("📋 Quick Start Guide:");
183    println!("  1️⃣  Initialize your project");
184    println!("     sprite init --agents 3");
185    println!();
186    println!("  2️⃣  Start your first session");
187    println!("     sprite start");
188    println!();
189    println!("  3️⃣  Work with agents");
190    println!("     sprite hey 1 'npm install'");
191    println!("     sprite hey 2 'cargo build'");
192    println!();
193    println!("  4️⃣  Navigate workspaces");
194    println!("     cd $(sprite warp --print 1)");
195    println!();
196    println!("  5️⃣  Check status");
197    println!("     sprite status");
198    println!();
199
200    println!("🔧 Core Commands Overview:\n");
201
202    let help_system = get_help_system();
203    let core_commands = [
204        "init", "start", "agents", "warp", "hey", "send", "sync", "status",
205    ];
206
207    for cmd in &core_commands {
208        if let Some(help) = help_system.get_command_help(cmd) {
209            println!("  {} - {}", cmd, help.description);
210        }
211    }
212
213    println!();
214    println!("📚 Getting More Help:");
215    println!("  sprite help <command>           # Detailed command help");
216    println!("  sprite help --search <query>    # Search help content");
217    println!("  sprite help --patterns          # Show usage patterns");
218    println!("  sprite help --troubleshooting   # Troubleshooting guides");
219    println!("  sprite help --quick             # Quick reference");
220    println!("  sprite help --accessible       # Screen reader friendly");
221
222    println!();
223    println!("🎯 Common Workflows:");
224    println!("  First Time Setup → sprite help --patterns --category getting-started");
225    println!("  Daily Workflow → sprite help --patterns --category daily-workflow");
226    println!("  Team Collaboration → sprite help --patterns --category collaboration");
227
228    println!();
229    println!("🔗 Resources:");
230    println!("  Documentation: https://docs.rs/sprite");
231    println!("  Repository: https://github.com/hotaq/Sprit-mutil");
232    println!("  Issues: https://github.com/hotaq/Sprit-mutil/issues");
233
234    Ok(())
235}
236
237/// Show command examples in a structured way.
238#[allow(dead_code)]
239pub fn show_examples(command: Option<&str>) -> Result<()> {
240    let help_system = get_help_system();
241
242    if let Some(cmd) = command {
243        if let Some(help) = help_system.get_command_help(cmd) {
244            println!("💡 Examples for '{}'\n", cmd);
245
246            if help.examples.is_empty() {
247                println!("No examples available for this command.");
248                return Ok(());
249            }
250
251            for (i, example) in help.examples.iter().enumerate() {
252                println!("  {}. {}", i + 1, example);
253            }
254
255            println!();
256            println!("💡 Tips:");
257            for tip in &help.tips {
258                println!("  • {}", tip);
259            }
260        } else {
261            println!("❌ Command '{}' not found.", cmd);
262            println!(
263                "Available commands: {}",
264                help_system.list_commands().join(", ")
265            );
266        }
267    } else {
268        println!("💡 Common Examples\n");
269
270        let common_examples = [
271            ("Initialize Project", "sprite init --agents 3"),
272            ("Start Session", "sprite start --session-name dev"),
273            ("List Agents", "sprite agents list"),
274            ("Send Command to Agent", "sprite hey 1 'npm test'"),
275            ("Broadcast to All", "sprite send 'git pull'"),
276            ("Navigate Workspace", "cd $(sprite warp --print 1)"),
277            ("Check Status", "sprite status --detailed"),
278            ("Sync Workspaces", "sprite sync --agent 2"),
279            ("Focus Agent", "sprite zoom 1"),
280            ("End Session", "sprite kill --all"),
281        ];
282
283        for (description, command) in &common_examples {
284            println!("  {} → {}", description, command);
285        }
286
287        println!();
288        println!("For command-specific examples: sprite help --examples <command>");
289    }
290
291    Ok(())
292}
293
294/// Show command aliases and shortcuts.
295#[allow(dead_code)]
296pub fn show_aliases() -> Result<()> {
297    println!("🔗 Command Aliases & Shortcuts\n");
298
299    println!("Common Aliases (add to your shell configuration):");
300    println!("  alias si='sprite init'");
301    println!("  alias ss='sprite start'");
302    println!("  alias sk='sprite kill'");
303    println!("  alias sa='sprite agents'");
304    println!("  alias sw='cd $(sprite warp --print \"$1\")'");
305    println!("  alias sh='sprite hey'");
306    println!();
307
308    println!("Shell Functions:");
309    println!("  # Function to quickly switch agent workspaces");
310    println!("  sw() {{");
311    println!("    if [ $# -eq 0 ]; then");
312    println!("      sprite warp --list");
313    println!("    else");
314    println!("      cd \"$(sprite warp --print \"$1\")\"");
315    println!("    fi");
316    println!("  }}");
317    println!();
318
319    println!("Tmux Shortcuts (when in a sprite session):");
320    println!("  Ctrl+B, d    → Detach from session");
321    println!("  Ctrl+B, %    → Split pane horizontally");
322    println!("  Ctrl+B, \"    → Split pane vertically");
323    println!("  Ctrl+B, ←→↑↓ → Navigate panes");
324    println!("  Ctrl+B, z    → Zoom current pane");
325    println!();
326
327    println!("🔧 Integration:");
328    println!("  sprite help --generate-shell-integration  # Generate full integration script");
329
330    Ok(())
331}
332
333/// Generate shell integration script.
334#[allow(dead_code)]
335pub fn generate_shell_integration() -> Result<()> {
336    let script = r#"#!/bin/bash
337# Sprite workspace integration script
338# Add this to your ~/.bashrc or ~/.zshrc
339
340# Tab completion for sprite commands
341_sprite_completion() {
342  local cur prev words
343  cur="${COMP_WORDS[COMP_CWORD]}"
344  prev="${COMP_WORDS[COMP_CWORD-1]}"
345  words=("${COMP_WORDS[@]}")
346
347  case "$prev" in
348    sprite)
349      COMPREPLY=($(compgen -W "init start agents attach kill send hey sync remove warp zoom status config help" -- "$cur"))
350      ;;
351    warp)
352      COMPREPLY=($(compgen -W "$(sprite warp --list 2>/dev/null | grep '📁' | awk '{print $3}' | sed 's/://')" -- "$cur"))
353      ;;
354    hey|send)
355      COMPREPLY=($(compgen -W "$(sprite agents list 2>/dev/null | grep -E '^[0-9]+' | awk '{print $1}')" -- "$cur"))
356      ;;
357  esac
358}
359
360complete -F _sprite_completion sprite
361
362# Quick workspace navigation
363sw() {
364  if [ $# -eq 0 ]; then
365    sprite warp --list
366  else
367    cd "$(sprite warp --print "$1")"
368  fi
369}
370
371# Quick agent commands
372sh() {
373  local agent="$1"
374  shift
375  sprite hey "$agent" "$@"
376}
377
378# Sprite session management
379ss() { sprite start "$@"; }
380sk() { sprite kill "$@"; }
381sa() { sprite attach "$@"; }
382"#;
383
384    println!("🔧 Shell Integration Script\n");
385    println!("{}", script);
386
387    println!("💡 Save this as ~/.sprite_completion.sh and add:");
388    println!("   source ~/.sprite_completion.sh");
389    println!("   to your shell configuration file.");
390
391    Ok(())
392}
393
394#[cfg(test)]
395mod tests {
396    use super::*;
397
398    #[test]
399    fn test_help_args_parsing() {
400        // Test basic parsing
401        let args = HelpArgs {
402            command: Some("init".to_string()),
403            search: None,
404            patterns: false,
405            troubleshooting: false,
406            quick: false,
407            accessible: false,
408            category: None,
409        };
410
411        assert_eq!(args.command, Some("init".to_string()));
412        assert!(!args.patterns);
413    }
414
415    #[test]
416    fn test_category_conversion() {
417        let help_cat = HelpCategory::GettingStarted;
418        let usage_cat: UsageCategory = help_cat.into();
419        assert_eq!(usage_cat, UsageCategory::GettingStarted);
420    }
421}