Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

refactor: extract help system and invocation utilities from main.rs (#612)

Maximilian Roos7d52c2a2daf1
diff --git a/src/diagnostic.rs b/src/diagnostic.rs
index 2603b4718..b0ba1b758 100644
--- a/src/diagnostic.rs
+++ b/src/diagnostic.rs
@@ -44,11 +44,14 @@
//!
use std::path::PathBuf;
+use ansi_str::AnsiStr;
use anyhow::Context;
use color_print::cformat;
use minijinja::{Environment, context};
use worktrunk::git::Repository;
+use worktrunk::path::format_path_for_display;
use worktrunk::shell_exec::Cmd;
+use worktrunk::styling::{hint_message, info_message, warning_message};
use crate::cli::version_str;
use crate::output;
@@ -180,7 +183,7 @@ impl DiagnosticReport {
/// Write the diagnostic report to a file (for -vv flag).
///
- /// Called from `write_vv_diagnostic()` in main.rs when verbose >= 2.
+ /// Called from `write_if_verbose()` when verbose >= 2.
/// Returns the path if successful, None if write failed.
pub fn write_diagnostic_file(&self, repo: &Repository) -> Option<PathBuf> {
self.write_file(repo)
@@ -199,14 +202,75 @@ pub(crate) fn issue_hint() -> String {
cformat!("To create a diagnostic file, run with <bright-black>-vv</>")
}
+/// Write diagnostic file when -vv is used.
+///
+/// Called at the end of command execution. If verbose level is >= 2, writes
+/// a diagnostic report to `.git/wt-logs/diagnostic.md` for issue filing.
+///
+/// Silently returns if:
+/// - verbose < 2
+/// - Not in a git repository
+///
+/// Warns if diagnostic file write fails.
+pub(crate) fn write_if_verbose(verbose: u8, command_line: &str, error_msg: Option<&str>) {
+ if verbose < 2 {
+ return;
+ }
+
+ // Use Repository::current() which honors the -C flag
+ let Ok(repo) = Repository::current() else {
+ return;
+ };
+
+ // Check if we're actually in a git repo
+ if repo.current_worktree().git_dir().is_err() {
+ return;
+ }
+
+ // Build context based on success/error
+ let context = match error_msg {
+ Some(msg) => format!("Command failed: {msg}"),
+ None => "Command completed successfully".to_string(),
+ };
+
+ // Collect and write diagnostic
+ let report = DiagnosticReport::collect(&repo, command_line, context);
+ match report.write_diagnostic_file(&repo) {
+ Some(path) => {
+ let path_display = format_path_for_display(&path);
+ let _ = output::print(info_message(format!("Diagnostic saved: {path_display}")));
+
+ // Only show gh command if gh is installed
+ if is_gh_installed() {
+ // Escape single quotes for shell: 'it'\''s' -> it's
+ let path_str = path.to_string_lossy().replace('\'', "'\\''");
+ // URL with prefilled body: ## Gist\n\n[Paste URL]\n\n## Description\n\n[Describe the issue]
+ let issue_url = "https://github.com/max-sixty/worktrunk/issues/new?body=%23%23%20Gist%0A%0A%5BPaste%20gist%20URL%5D%0A%0A%23%23%20Description%0A%0A%5BDescribe%20the%20issue%5D";
+ let _ = output::print(hint_message(cformat!(
+ "To report a bug, create a secret gist with <bright-black>gh gist create --web '{path_str}'</> and reference it from an issue at <bright-black>{issue_url}</>"
+ )));
+ }
+ }
+ None => {
+ let _ = output::print(warning_message("Failed to write diagnostic file"));
+ }
+ }
+}
+
+/// Check if the GitHub CLI (gh) is installed.
+fn is_gh_installed() -> bool {
+ Cmd::new("gh")
+ .arg("--version")
+ .run()
+ .map(|o| o.status.success())
+ .unwrap_or(false)
+}
+
/// Strip ANSI escape codes from a string.
///
/// Used to clean terminal-formatted text for markdown output.
fn strip_ansi_codes(s: &str) -> String {
- // Match SGR (Select Graphic Rendition) sequences: ESC [ <params> m
- // This covers colors, bold, dim, etc.
- let re = regex::Regex::new(r"\x1b\[[0-9;]*m").unwrap();
- re.replace_all(s, "").into_owned()
+ s.ansi_strip().into_owned()
}
/// Truncate verbose log to ~50KB if it's too large.
diff --git a/src/help.rs b/src/help.rs
new file mode 100644
index 000000000..aabdea5b9
--- /dev/null
+++ b/src/help.rs
@@ -0,0 +1,528 @@
+//! Help system with pager support and web documentation generation.
+//!
+//! This module provides:
+//! - Pager support for `--help` output (git-style)
+//! - Markdown rendering for help text
+//! - Web documentation generation via `--help-page` and `--help-md`
+
+use std::process;
+
+use ansi_str::AnsiStr;
+
+use crate::cli;
+
+/// Custom help handling for pager support and markdown rendering.
+///
+/// We intercept help requests to provide:
+/// 1. **Pager support**: Help is shown through the detected pager (git-style precedence)
+/// 2. **Markdown rendering**: `## Headers` become green, code blocks are dimmed
+///
+/// Uses `Error::render()` to get clap's pre-formatted help, which already
+/// respects `-h` (short) vs `--help` (long) distinction.
+///
+/// Returns `true` if help was handled (caller should exit), `false` to continue normal parsing.
+pub fn maybe_handle_help_with_pager() -> bool {
+ use clap::ColorChoice;
+ use clap::error::ErrorKind;
+
+ let args: Vec<String> = std::env::args().collect();
+
+ // Check for --help-page flag (output full doc page with frontmatter)
+ if args.iter().any(|a| a == "--help-page") {
+ handle_help_page(&args);
+ process::exit(0);
+ }
+
+ // Check for --help-md flag (output raw markdown without ANSI rendering)
+ if args.iter().any(|a| a == "--help-md") {
+ let mut cmd = cli::build_command();
+ cmd = cmd.color(ColorChoice::Never); // No ANSI codes for raw markdown
+
+ // Replace --help-md with --help for clap
+ let filtered_args: Vec<String> = args
+ .iter()
+ .map(|a| {
+ if a == "--help-md" {
+ "--help".to_string()
+ } else {
+ a.clone()
+ }
+ })
+ .collect();
+
+ if let Err(err) = cmd.try_get_matches_from_mut(filtered_args)
+ && matches!(
+ err.kind(),
+ ErrorKind::DisplayHelp | ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand
+ )
+ {
+ // Transform code block languages for Zola compatibility:
+ // - ```text (clap's default for usage) -> ``` (no highlighting)
+ // - ```console (our examples) -> ```bash
+ let output = err
+ .render()
+ .to_string()
+ .replace("```text\n", "```\n")
+ .replace("```console\n", "```bash\n");
+ println!("{output}");
+ process::exit(0);
+ }
+ // Fall through if not a help request
+ }
+
+ let mut cmd = cli::build_command();
+ cmd = cmd.color(clap::ColorChoice::Always); // Force clap to emit ANSI codes
+
+ match cmd.try_get_matches_from_mut(args) {
+ Ok(_) => false, // Normal args, not help
+ Err(err) => {
+ match err.kind() {
+ ErrorKind::DisplayHelp | ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand => {
+ // err.render() returns a StyledStr containing ANSI codes.
+ // Use .ansi() to preserve them; .to_string() strips ANSI codes.
+ let clap_output = err.render().ansi().to_string();
+
+ // Render markdown sections (tables, code blocks, prose) with proper wrapping.
+ // Since we disabled clap's wrapping above, our renderer controls all line breaks.
+ let width = worktrunk::styling::get_terminal_width();
+ let help = crate::md_help::render_markdown_in_help_with_width(
+ &clap_output,
+ Some(width),
+ );
+
+ // show_help_in_pager checks if stdout or stderr is a TTY.
+ // If neither is a TTY (e.g., `wt --help &>file`), it skips the pager.
+ if let Err(e) = crate::help_pager::show_help_in_pager(&help) {
+ log::debug!("Pager invocation failed: {}", e);
+ eprintln!("{}", help);
+ }
+ process::exit(0);
+ }
+ ErrorKind::DisplayVersion => {
+ // Print to stderr - stdout is reserved for data/scripts
+ // Use eprint! because clap's Error Display already includes a trailing newline
+ eprint!("{}", err);
+ process::exit(0);
+ }
+ _ => {
+ // Not help or version - will be re-parsed by Cli::parse()
+ false
+ }
+ }
+ }
+ }
+}
+
+/// Get the help reference block for a command by invoking clap's help system.
+///
+/// Returns the usage/options/subcommands section without the after_long_help content.
+/// If `width` is provided, wraps text at that width (for web docs); otherwise uses default.
+/// Always preserves ANSI color codes for HTML conversion.
+fn get_help_reference(command_path: &[&str], width: Option<usize>) -> String {
+ use clap::ColorChoice;
+ use clap::error::ErrorKind;
+
+ // Build args: ["wt", "config", "create", "--help"]
+ let mut args: Vec<String> = vec!["wt".to_string()];
+ args.extend(command_path.iter().map(|s| s.to_string()));
+ args.push("--help".to_string());
+
+ let mut cmd = cli::build_command();
+ cmd = cmd.color(ColorChoice::Always);
+ if let Some(w) = width {
+ cmd = cmd.term_width(w);
+ }
+
+ let help_block = if let Err(err) = cmd.try_get_matches_from_mut(args)
+ && matches!(
+ err.kind(),
+ ErrorKind::DisplayHelp | ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand
+ ) {
+ let rendered = err.render();
+ let text = rendered.ansi().to_string();
+ text.replace("```text\n", "```\n")
+ .replace("```console\n", "```bash\n")
+ } else {
+ return String::new();
+ };
+
+ // Strip after_long_help if present (it appears at the end)
+ // Find it by looking for the first ## heading after Options/Arguments
+ if let Some(after_help_start) = find_after_help_start(&help_block) {
+ help_block[..after_help_start].trim_end().to_string()
+ } else {
+ help_block
+ }
+}
+
+/// Find where after_long_help starts in help output.
+///
+/// Clap outputs: usage, description, commands/options, Global Options, then after_long_help.
+/// The after_long_help can start with a heading or plain text.
+fn find_after_help_start(help: &str) -> Option<usize> {
+ // After Global Options section, a blank line followed by non-indented text is after_long_help
+ let mut past_global_options = false;
+ let mut saw_blank_after_options = false;
+ let mut blank_offset = None;
+ let mut offset = 0;
+
+ for line in help.lines() {
+ // Strip ANSI codes for pattern matching
+ let plain_line = strip_ansi_codes(line);
+
+ if plain_line.starts_with("Global Options:") {
+ past_global_options = true;
+ offset += line.len() + 1;
+ continue;
+ }
+
+ if past_global_options {
+ if plain_line.is_empty() {
+ saw_blank_after_options = true;
+ blank_offset = Some(offset);
+ } else if saw_blank_after_options && !plain_line.starts_with(' ') {
+ // Non-indented line after blank = start of after_long_help
+ return blank_offset;
+ } else if plain_line.starts_with(' ') {
+ // Still in indented options, reset blank tracking
+ saw_blank_after_options = false;
+ }
+ }
+ offset += line.len() + 1;
+ }
+ None
+}
+
+/// Strip ANSI escape codes from a string for pattern matching.
+fn strip_ansi_codes(s: &str) -> String {
+ s.ansi_strip().into_owned()
+}
+
+/// Generate a full documentation page for a command.
+///
+/// Output format:
+/// ```markdown
+/// +++
+/// title = "Merging"
+/// weight = 5
+/// +++
+///
+/// [after_long_help content - the conceptual docs]
+///
+/// ---
+///
+/// ## Command reference
+///
+/// ```bash
+/// wt merge — ...
+/// Usage: ...
+/// ```
+/// ```
+///
+/// This is used to generate docs/content/merge.md etc from the source.
+fn handle_help_page(args: &[String]) {
+ use clap::ColorChoice;
+
+ let mut cmd = cli::build_command();
+ cmd = cmd.color(ColorChoice::Never);
+
+ // Find the subcommand name (the arg before --help-page, or after wt)
+ let subcommand = args
+ .iter()
+ .filter(|a| *a != "--help-page" && !a.starts_with('-') && !a.ends_with("/wt"))
+ .find(|a| {
+ // Skip the binary name
+ !a.contains("target/") && *a != "wt"
+ });
+
+ let Some(subcommand) = subcommand else {
+ eprintln!("Usage: wt <command> --help-page");
+ eprintln!("Commands with pages: merge, switch, remove, list");
+ return;
+ };
+
+ // Navigate to the subcommand
+ let sub = cmd.find_subcommand(subcommand);
+ let Some(sub) = sub else {
+ eprintln!("Unknown command: {subcommand}");
+ return;
+ };
+
+ // Get the after_long_help content
+ // Transform for web docs: console→bash, status colors, demo images
+ // Subdocs are expanded separately so main Command reference comes first
+ let parent_name = format!("wt {}", subcommand);
+ let raw_help = sub
+ .get_after_long_help()
+ .map(|s| s.to_string())
+ .unwrap_or_default();
+
+ // Split content at first subdoc placeholder
+ let subdoc_marker = "<!-- subdoc:";
+ let (main_content, subdoc_content) = if let Some(pos) = raw_help.find(subdoc_marker) {
+ (&raw_help[..pos], Some(&raw_help[pos..]))
+ } else {
+ (raw_help.as_str(), None)
+ };
+
+ // Process main content (before subdocs)
+ let main_help = {
+ let text = main_content.replace("```console\n", "```bash\n");
+ let text = expand_demo_placeholders(&text);
+ colorize_ci_status_for_html(&text)
+ };
+
+ // Get the help reference block (wrap at 80 chars for web docs, with colors for HTML)
+ let reference_block = get_help_reference(&[subcommand], Some(80));
+
+ // Output the generated content (frontmatter is in skeleton files)
+ // Uses region markers so sync can replace just this content
+ // END tag mirrors the ID for unambiguous matching with nested markers
+ // Use std::println! to preserve ANSI codes in output (the styling::println strips them)
+ std::println!(
+ "<!-- ⚠️ AUTO-GENERATED from `wt {subcommand} --help-page` — edit cli.rs to update -->"
+ );
+ std::println!();
+ std::println!("{}", main_help.trim());
+ std::println!();
+
+ // Main command reference immediately after its content
+ std::println!("## Command reference");
+ std::println!();
+ std::println!("```");
+ std::print!("{}", reference_block.trim());
+ std::println!();
+ std::println!("```");
+
+ // Subdocs follow, each with their own command reference at the end
+ if let Some(subdocs) = subdoc_content {
+ let subdocs_expanded = expand_subdoc_placeholders(subdocs, sub, &parent_name);
+ let subdocs_processed = colorize_ci_status_for_html(&subdocs_expanded);
+ std::println!();
+ std::println!("{}", subdocs_processed.trim());
+ }
+
+ std::println!();
+ std::println!("<!-- END AUTO-GENERATED from `wt {subcommand} --help-page` -->");
+}
+
+/// Add HTML color spans for CI status dots in help page output.
+///
+/// Transforms plain text like "`●` green" into colored HTML spans for web rendering.
+/// This is the web-docs counterpart to md_help::colorize_status_symbols() which
+/// produces ANSI codes for terminal output.
+///
+/// Also converts plain URL references to markdown links for web docs.
+fn colorize_ci_status_for_html(text: &str) -> String {
+ text
+ // CI status colors (in table cells)
+ .replace("`●` green", "<span style='color:#0a0'>●</span> green")
+ .replace("`●` blue", "<span style='color:#00a'>●</span> blue")
+ .replace("`●` red", "<span style='color:#a00'>●</span> red")
+ .replace("`●` yellow", "<span style='color:#a60'>●</span> yellow")
+ .replace("`⚠` yellow", "<span style='color:#a60'>⚠</span> yellow")
+ .replace("`●` gray", "<span style='color:#888'>●</span> gray")
+ // Convert plain URL references to markdown links for web docs
+ // CLI shows: "Open an issue at https://github.com/max-sixty/worktrunk."
+ // Web shows: "[Open an issue](https://github.com/max-sixty/worktrunk/issues)."
+ .replace(
+ "Open an issue at https://github.com/max-sixty/worktrunk.",
+ "[Open an issue](https://github.com/max-sixty/worktrunk/issues).",
+ )
+}
+
+/// Increase markdown heading levels by one (## -> ###, ### -> ####, etc.)
+///
+/// This makes subdoc headings children of the subdoc's main heading.
+/// Only transforms actual markdown headings, not code block content.
+fn increase_heading_levels(content: &str) -> String {
+ let mut result = Vec::new();
+ let mut in_code_block = false;
+
+ for line in content.lines() {
+ // Track code block boundaries (``` or ````+)
+ if line.trim_start().starts_with("```") {
+ in_code_block = !in_code_block;
+ result.push(line.to_string());
+ continue;
+ }
+
+ // Only transform headings outside code blocks
+ if !in_code_block && line.starts_with('#') {
+ result.push(format!("#{}", line));
+ } else {
+ result.push(line.to_string());
+ }
+ }
+
+ let mut output = result.join("\n");
+ // Preserve trailing newline if present (.lines() strips it)
+ if content.ends_with('\n') {
+ output.push('\n');
+ }
+ output
+}
+
+/// Expand subdoc placeholders for web docs.
+///
+/// Transforms `<!-- subdoc: subcommand -->` into an H2 section with the subcommand's help output.
+/// For example, `<!-- subdoc: create -->` in `wt config` expands to:
+///
+/// ```markdown
+/// ## wt config create
+///
+/// [help output for `wt config create`]
+/// ```
+///
+/// This allows including subcommand documentation inline in the parent command's docs page.
+fn expand_subdoc_placeholders(text: &str, parent_cmd: &clap::Command, parent_name: &str) -> String {
+ const PREFIX: &str = "<!-- subdoc: ";
+ const SUFFIX: &str = " -->";
+
+ let mut result = text.to_string();
+ while let Some(start) = result.find(PREFIX) {
+ let after_prefix = start + PREFIX.len();
+ if let Some(end_offset) = result[after_prefix..].find(SUFFIX) {
+ let subcommand_name = result[after_prefix..after_prefix + end_offset].trim();
+ let end = after_prefix + end_offset + SUFFIX.len();
+
+ // Find the subcommand in the parent
+ let replacement = if let Some(sub) = parent_cmd
+ .get_subcommands()
+ .find(|s| s.get_name() == subcommand_name)
+ {
+ format_subcommand_section(sub, parent_name, subcommand_name)
+ } else {
+ format!(
+ "<!-- subdoc error: subcommand '{}' not found -->",
+ subcommand_name
+ )
+ };
+
+ result.replace_range(start..end, &replacement);
+ } else {
+ break;
+ }
+ }
+ result
+}
+
+/// Format a subcommand as an H2 section for docs.
+///
+/// Includes the subcommand's `after_long_help` (conceptual docs) followed by
+/// the command reference (usage, options). If the subdoc has nested subdocs,
+/// the command reference comes before them.
+fn format_subcommand_section(
+ sub: &clap::Command,
+ parent_name: &str,
+ subcommand_name: &str,
+) -> String {
+ // parent_name is "wt config", subcommand_name is "create"
+ // full_command is "wt config create"
+ let full_command = format!("{} {}", parent_name, subcommand_name);
+
+ // Get the raw after_long_help content
+ let raw_help = sub
+ .get_after_long_help()
+ .map(|s| s.to_string())
+ .unwrap_or_default();
+
+ // Split content at first subdoc placeholder so command reference comes before nested subdocs
+ let subdoc_marker = "<!-- subdoc:";
+ let (main_content, subdoc_content) = if let Some(pos) = raw_help.find(subdoc_marker) {
+ (&raw_help[..pos], Some(&raw_help[pos..]))
+ } else {
+ (raw_help.as_str(), None)
+ };
+
+ // Process main content (before any nested subdocs)
+ let main_help = {
+ let text = main_content.replace("```console\n", "```bash\n");
+ let text = increase_heading_levels(&text);
+ colorize_ci_status_for_html(&text)
+ };
+
+ // Build command path from parent_name: "wt config" -> ["config", "create"]
+ let command_path: Vec<&str> = parent_name
+ .strip_prefix("wt ")
+ .unwrap_or(parent_name)
+ .split_whitespace()
+ .chain(std::iter::once(subcommand_name))
+ .collect();
+
+ // Get help reference (wrap at 80 chars for web docs, with colors for HTML)
+ let reference_block = get_help_reference(&command_path, Some(80));
+
+ // Format the section: heading, main content, command reference, then nested subdocs
+ let mut section = format!("## {}\n\n", full_command);
+
+ if !main_help.is_empty() {
+ section.push_str(main_help.trim());
+ section.push_str("\n\n");
+ }
+
+ // Command reference comes after main content but before nested subdocs
+ section.push_str("### Command reference\n\n```\n");
+ section.push_str(reference_block.trim());
+ section.push_str("\n```\n");
+
+ // Expand nested subdocs after the command reference
+ if let Some(subdocs) = subdoc_content {
+ let subdocs_expanded = expand_subdoc_placeholders(subdocs, sub, &full_command);
+ let subdocs_processed = colorize_ci_status_for_html(&subdocs_expanded);
+ section.push('\n');
+ section.push_str(subdocs_processed.trim());
+ section.push('\n');
+ }
+
+ section
+}
+
+/// Expand demo GIF placeholders for web docs.
+///
+/// Transforms `<!-- demo: filename.gif -->` into an HTML figure with the `demo` class.
+/// The HTML comment is invisible in terminal --help output, but expands to a styled figure
+/// for web docs generated via --help-page.
+///
+/// The placeholder should be on its own line without surrounding blank lines in the source.
+/// This function adds blank lines around the figure for proper markdown paragraph separation.
+///
+/// Supports optional dimensions: `<!-- demo: filename.gif 1600x900 -->`
+fn expand_demo_placeholders(text: &str) -> String {
+ const PREFIX: &str = "<!-- demo: ";
+ const SUFFIX: &str = " -->";
+
+ let mut result = text.to_string();
+ while let Some(start) = result.find(PREFIX) {
+ let after_prefix = start + PREFIX.len();
+ if let Some(end_offset) = result[after_prefix..].find(SUFFIX) {
+ let content = &result[after_prefix..after_prefix + end_offset];
+ // Parse "filename.gif" or "filename.gif 1600x900"
+ let mut parts = content.split_whitespace();
+ let filename = parts.next().unwrap_or("");
+ let dimensions = parts.next(); // Optional "WIDTHxHEIGHT"
+
+ // Extract command name from filename (e.g., "wt-select.gif" -> "wt select")
+ let alt_text = filename.trim_end_matches(".gif").replace('-', " ");
+
+ // Build dimension attributes if provided
+ let dim_attrs = dimensions
+ .and_then(|d| d.split_once('x'))
+ .map(|(w, h)| format!(" width=\"{w}\" height=\"{h}\""))
+ .unwrap_or_default();
+
+ // Use figure.demo class for proper mobile styling (no shrink, horizontal scroll)
+ // Generate <picture> element for light/dark theme switching
+ // Assets are organized as: /assets/docs/{light,dark}/filename.gif
+ // Add blank line before the figure; blank line after is already in source
+ let replacement = format!(
+ "\n<figure class=\"demo\">\n<picture>\n <source srcset=\"/assets/docs/dark/{filename}\" media=\"(prefers-color-scheme: dark)\">\n <img src=\"/assets/docs/light/{filename}\" alt=\"{alt_text} demo\"{dim_attrs}>\n</picture>\n</figure>"
+ );
+ let end = after_prefix + end_offset + SUFFIX.len();
+ result.replace_range(start..end, &replacement);
+ } else {
+ break;
+ }
+ }
+ result
+}
diff --git a/src/invocation.rs b/src/invocation.rs
new file mode 100644
index 000000000..82ebef115
--- /dev/null
+++ b/src/invocation.rs
@@ -0,0 +1,108 @@
+//! Utilities for understanding how the binary was invoked.
+//!
+//! These functions examine `argv[0]` and environment variables to determine:
+//! - What name the binary was invoked as (`binary_name`)
+//! - Whether we're running as a git subcommand (`is_git_subcommand`)
+//! - Whether shell integration can work (`was_invoked_with_explicit_path`)
+
+/// Get the binary name from `argv[0]`, falling back to "wt".
+///
+/// Used as the default for `--cmd` in shell integration commands.
+/// When invoked as `git-wt`, returns "git-wt"; when invoked as `wt`, returns "wt".
+/// On Windows, strips `.exe` extension — users should use `wt` not `wt.exe` in aliases.
+pub fn binary_name() -> String {
+ std::env::args()
+ .next()
+ .and_then(|arg0| {
+ std::path::Path::new(&arg0)
+ .file_stem()
+ .and_then(|name| name.to_str())
+ .map(String::from)
+ })
+ .unwrap_or_else(|| "wt".to_string())
+}
+
+/// Check if we're running as a git subcommand (e.g., `git wt` instead of `git-wt`).
+///
+/// When git runs a subcommand like `git wt`, it sets `GIT_EXEC_PATH` in the environment.
+/// This is NOT set when running `git-wt` directly or via a shell function.
+///
+/// This distinction matters for shell integration: `git wt` runs as a subprocess of git,
+/// so even with shell integration configured, the `cd` directive cannot propagate to
+/// the parent shell. Users must use `git-wt` directly (via shell function) for automatic cd.
+pub fn is_git_subcommand() -> bool {
+ std::env::var_os("GIT_EXEC_PATH").is_some()
+}
+
+/// Get the raw `argv[0]` value (how we were invoked).
+///
+/// Used in error messages to show what command was actually run.
+/// Returns the full invocation path (e.g., `target/debug/wt`, `./wt`, `wt`).
+pub fn invocation_path() -> String {
+ std::env::args().next().unwrap_or_else(|| "wt".to_string())
+}
+
+/// Check if we were invoked via an explicit path rather than PATH lookup.
+///
+/// # Purpose
+///
+/// When shell integration is configured (e.g., `eval "$(wt config shell init)"`),
+/// the shell wrapper function intercepts calls to `wt` and handles directory
+/// changes. However, this only works when the shell finds `wt` via PATH lookup.
+///
+/// If the user runs a specific binary path (like `cargo run` or `./target/debug/wt`),
+/// the shell wrapper won't intercept it, and shell integration won't work.
+///
+/// # Heuristic
+///
+/// Returns `true` if argv\[0\] contains a path separator (`/` or `\`).
+///
+/// - PATH lookup: shell sets argv\[0\] to just the command name (`wt`)
+/// - Explicit path: argv\[0\] contains the path (`./wt`, `target/debug/wt`, `/usr/bin/wt`)
+///
+/// # Examples
+///
+/// | Invocation | argv\[0\] | Returns | Reason |
+/// |-----------------------------|----------------------|---------|---------------------------|
+/// | `wt switch foo` | `wt` | `false` | PATH lookup, wrapper works|
+/// | `cargo run -- switch foo` | `target/debug/wt` | `true` | Explicit path, no wrapper |
+/// | `./target/debug/wt switch` | `./target/debug/wt` | `true` | Explicit path, no wrapper |
+/// | `/usr/local/bin/wt switch` | `/usr/local/bin/wt` | `true` | Explicit path, no wrapper |
+///
+/// # Edge Cases
+///
+/// - **False positive**: User types full path to installed binary (`/usr/local/bin/wt`).
+/// Harmless — if they're typing the full path, shell wrapper wouldn't intercept anyway.
+///
+/// - **Aliases**: `alias wt='...'` — shell expands alias before setting argv\[0\], so:
+/// - `alias wt='wt'` → argv\[0\] = `wt` → `false` (correct)
+/// - `alias wt='./target/debug/wt'` → argv\[0\] = `./target/debug/wt` → `true` (correct)
+///
+/// - **Symlinks**: If `~/bin/wt` is a symlink to `target/debug/wt`, argv\[0\] = `~/bin/wt`
+/// (contains `/`) → `true`. This is correct — the shell wrapper wraps PATH's `wt`,
+/// not the symlink.
+///
+/// - **`git wt` subcommand**: When invoked as `git wt`, git dispatches to `git-wt` binary
+/// and sets argv\[0\] = `git-wt` (no path separator) → returns `false`. However, shell
+/// integration configured for `wt` won't intercept `git wt` — they're different commands.
+/// This is handled separately by `is_integration_configured()` which checks for the
+/// actual binary name (`git-wt`), not `wt`.
+///
+/// # Why Not Other Approaches?
+///
+/// - **`current_exe()` + check for `/target/debug/`**: Only catches cargo builds,
+/// misses other "ran specific path" scenarios.
+///
+/// - **Compare with `which wt`**: More accurate but requires subprocess overhead
+/// and `which` behavior varies across shells.
+///
+/// - **Check if `current_exe()` is in PATH**: Complex PATH parsing, platform differences.
+///
+/// The argv\[0\] heuristic is simple, fast, and catches all cases where shell
+/// integration won't work because the shell wrapper wasn't invoked.
+pub fn was_invoked_with_explicit_path() -> bool {
+ std::env::args()
+ .next()
+ .map(|arg0| arg0.contains('/') || arg0.contains('\\'))
+ .unwrap_or(false)
+}
diff --git a/src/main.rs b/src/main.rs
index 861f84f8c..c01837974 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -7,8 +7,7 @@ use worktrunk::git::{Repository, exit_code, set_base_path};
use worktrunk::path::format_path_for_display;
use worktrunk::shell::extract_filename_from_path;
use worktrunk::styling::{
- error_message, format_with_gutter, hint_message, info_message, println, success_message,
- warning_message,
+ error_message, format_with_gutter, hint_message, info_message, success_message, warning_message,
};
mod cli;
@@ -16,13 +15,20 @@ mod commands;
mod completion;
mod diagnostic;
mod display;
+mod help;
pub(crate) mod help_pager;
+mod invocation;
mod llm;
mod md_help;
mod output;
mod pager;
mod verbose_log;
+// Re-export invocation utilities at crate level for use by other modules
+pub(crate) use invocation::{
+ binary_name, invocation_path, is_git_subcommand, was_invoked_with_explicit_path,
+};
+
pub(crate) use crate::cli::OutputFormat;
use commands::command_executor::{CommandContext, build_hook_context};
@@ -47,640 +53,6 @@ use cli::{
};
use worktrunk::HookType;
-/// Get the binary name from `argv[0]`, falling back to "wt".
-///
-/// Used as the default for `--cmd` in shell integration commands.
-/// When invoked as `git-wt`, returns "git-wt"; when invoked as `wt`, returns "wt".
-/// On Windows, strips `.exe` extension — users should use `wt` not `wt.exe` in aliases.
-fn binary_name() -> String {
- std::env::args()
- .next()
- .and_then(|arg0| {
- std::path::Path::new(&arg0)
- .file_stem()
- .and_then(|name| name.to_str())
- .map(String::from)
- })
- .unwrap_or_else(|| "wt".to_string())
-}
-
-/// Check if we're running as a git subcommand (e.g., `git wt` instead of `git-wt`).
-///
-/// When git runs a subcommand like `git wt`, it sets `GIT_EXEC_PATH` in the environment.
-/// This is NOT set when running `git-wt` directly or via a shell function.
-///
-/// This distinction matters for shell integration: `git wt` runs as a subprocess of git,
-/// so even with shell integration configured, the `cd` directive cannot propagate to
-/// the parent shell. Users must use `git-wt` directly (via shell function) for automatic cd.
-fn is_git_subcommand() -> bool {
- std::env::var_os("GIT_EXEC_PATH").is_some()
-}
-
-/// Get the raw `argv[0]` value (how we were invoked).
-///
-/// Used in error messages to show what command was actually run.
-/// Returns the full invocation path (e.g., `target/debug/wt`, `./wt`, `wt`).
-pub(crate) fn invocation_path() -> String {
- std::env::args().next().unwrap_or_else(|| "wt".to_string())
-}
-
-/// Check if we were invoked via an explicit path rather than PATH lookup.
-///
-/// # Purpose
-///
-/// When shell integration is configured (e.g., `eval "$(wt config shell init)"`),
-/// the shell wrapper function intercepts calls to `wt` and handles directory
-/// changes. However, this only works when the shell finds `wt` via PATH lookup.
-///
-/// If the user runs a specific binary path (like `cargo run` or `./target/debug/wt`),
-/// the shell wrapper won't intercept it, and shell integration won't work.
-///
-/// # Heuristic
-///
-/// Returns `true` if argv\[0\] contains a path separator (`/` or `\`).
-///
-/// - PATH lookup: shell sets argv\[0\] to just the command name (`wt`)
-/// - Explicit path: argv\[0\] contains the path (`./wt`, `target/debug/wt`, `/usr/bin/wt`)
-///
-/// # Examples
-///
-/// | Invocation | argv\[0\] | Returns | Reason |
-/// |-----------------------------|----------------------|---------|---------------------------|
-/// | `wt switch foo` | `wt` | `false` | PATH lookup, wrapper works|
-/// | `cargo run -- switch foo` | `target/debug/wt` | `true` | Explicit path, no wrapper |
-/// | `./target/debug/wt switch` | `./target/debug/wt` | `true` | Explicit path, no wrapper |
-/// | `/usr/local/bin/wt switch` | `/usr/local/bin/wt` | `true` | Explicit path, no wrapper |
-///
-/// # Edge Cases
-///
-/// - **False positive**: User types full path to installed binary (`/usr/local/bin/wt`).
-/// Harmless — if they're typing the full path, shell wrapper wouldn't intercept anyway.
-///
-/// - **Aliases**: `alias wt='...'` — shell expands alias before setting argv\[0\], so:
-/// - `alias wt='wt'` → argv\[0\] = `wt` → `false` (correct)
-/// - `alias wt='./target/debug/wt'` → argv\[0\] = `./target/debug/wt` → `true` (correct)
-///
-/// - **Symlinks**: If `~/bin/wt` is a symlink to `target/debug/wt`, argv\[0\] = `~/bin/wt`
-/// (contains `/`) → `true`. This is correct — the shell wrapper wraps PATH's `wt`,
-/// not the symlink.
-///
-/// - **`git wt` subcommand**: When invoked as `git wt`, git dispatches to `git-wt` binary
-/// and sets argv\[0\] = `git-wt` (no path separator) → returns `false`. However, shell
-/// integration configured for `wt` won't intercept `git wt` — they're different commands.
-/// This is handled separately by `is_integration_configured()` which checks for the
-/// actual binary name (`git-wt`), not `wt`.
-///
-/// # Why Not Other Approaches?
-///
-/// - **`current_exe()` + check for `/target/debug/`**: Only catches cargo builds,
-/// misses other "ran specific path" scenarios.
-///
-/// - **Compare with `which wt`**: More accurate but requires subprocess overhead
-/// and `which` behavior varies across shells.
-///
-/// - **Check if `current_exe()` is in PATH**: Complex PATH parsing, platform differences.
-///
-/// The argv\[0\] heuristic is simple, fast, and catches all cases where shell
-/// integration won't work because the shell wrapper wasn't invoked.
-pub(crate) fn was_invoked_with_explicit_path() -> bool {
- std::env::args()
- .next()
- .map(|arg0| arg0.contains('/') || arg0.contains('\\'))
- .unwrap_or(false)
-}
-
-/// Custom help handling for pager support and markdown rendering.
-///
-/// We intercept help requests to provide:
-/// 1. **Pager support**: Help is shown through the detected pager (git-style precedence)
-/// 2. **Markdown rendering**: `## Headers` become green, code blocks are dimmed
-///
-/// Uses `Error::render()` to get clap's pre-formatted help, which already
-/// respects `-h` (short) vs `--help` (long) distinction.
-fn maybe_handle_help_with_pager() -> bool {
- use clap::ColorChoice;
- use clap::error::ErrorKind;
-
- let args: Vec<String> = std::env::args().collect();
-
- // Check for --help-page flag (output full doc page with frontmatter)
- if args.iter().any(|a| a == "--help-page") {
- handle_help_page(&args);
- process::exit(0);
- }
-
- // Check for --help-md flag (output raw markdown without ANSI rendering)
- if args.iter().any(|a| a == "--help-md") {
- let mut cmd = cli::build_command();
- cmd = cmd.color(ColorChoice::Never); // No ANSI codes for raw markdown
-
- // Replace --help-md with --help for clap
- let filtered_args: Vec<String> = args
- .iter()
- .map(|a| {
- if a == "--help-md" {
- "--help".to_string()
- } else {
- a.clone()
- }
- })
- .collect();
-
- if let Err(err) = cmd.try_get_matches_from_mut(filtered_args)
- && matches!(
- err.kind(),
- ErrorKind::DisplayHelp | ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand
- )
- {
- // Transform code block languages for Zola compatibility:
- // - ```text (clap's default for usage) -> ``` (no highlighting)
- // - ```console (our examples) -> ```bash
- let output = err
- .render()
- .to_string()
- .replace("```text\n", "```\n")
- .replace("```console\n", "```bash\n");
- println!("{output}");
- process::exit(0);
- }
- // Fall through if not a help request
- }
-
- let mut cmd = cli::build_command();
- cmd = cmd.color(ColorChoice::Always); // Force clap to emit ANSI codes
-
- match cmd.try_get_matches_from_mut(args) {
- Ok(_) => false, // Normal args, not help
- Err(err) => {
- match err.kind() {
- ErrorKind::DisplayHelp | ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand => {
- // err.render() returns a StyledStr containing ANSI codes.
- // Use .ansi() to preserve them; .to_string() strips ANSI codes.
- let clap_output = err.render().ansi().to_string();
-
- // Render markdown sections (tables, code blocks, prose) with proper wrapping.
- // Since we disabled clap's wrapping above, our renderer controls all line breaks.
- let width = worktrunk::styling::get_terminal_width();
- let help =
- md_help::render_markdown_in_help_with_width(&clap_output, Some(width));
-
- // show_help_in_pager checks if stdout or stderr is a TTY.
- // If neither is a TTY (e.g., `wt --help &>file`), it skips the pager.
- if let Err(e) = help_pager::show_help_in_pager(&help) {
- log::debug!("Pager invocation failed: {}", e);
- eprintln!("{}", help);
- }
- process::exit(0);
- }
- ErrorKind::DisplayVersion => {
- // Print to stderr - stdout is reserved for data/scripts
- // Use eprint! because clap's Error Display already includes a trailing newline
- eprint!("{}", err);
- process::exit(0);
- }
- _ => {
- // Not help or version - will be re-parsed by Cli::parse()
- false
- }
- }
- }
- }
-}
-
-/// Get the help reference block for a command by invoking clap's help system.
-///
-/// Returns the usage/options/subcommands section without the after_long_help content.
-/// If `width` is provided, wraps text at that width (for web docs); otherwise uses default.
-/// Always preserves ANSI color codes for HTML conversion.
-fn get_help_reference(command_path: &[&str], width: Option<usize>) -> String {
- use clap::ColorChoice;
- use clap::error::ErrorKind;
-
- // Build args: ["wt", "config", "create", "--help"]
- let mut args: Vec<String> = vec!["wt".to_string()];
- args.extend(command_path.iter().map(|s| s.to_string()));
- args.push("--help".to_string());
-
- let mut cmd = cli::build_command();
- cmd = cmd.color(ColorChoice::Always);
- if let Some(w) = width {
- cmd = cmd.term_width(w);
- }
-
- let help_block = if let Err(err) = cmd.try_get_matches_from_mut(args)
- && matches!(
- err.kind(),
- ErrorKind::DisplayHelp | ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand
- ) {
- let rendered = err.render();
- let text = rendered.ansi().to_string();
- text.replace("```text\n", "```\n")
- .replace("```console\n", "```bash\n")
- } else {
- return String::new();
- };
-
- // Strip after_long_help if present (it appears at the end)
- // Find it by looking for the first ## heading after Options/Arguments
- if let Some(after_help_start) = find_after_help_start(&help_block) {
- help_block[..after_help_start].trim_end().to_string()
- } else {
- help_block
- }
-}
-
-/// Find where after_long_help starts in help output.
-///
-/// Clap outputs: usage, description, commands/options, Global Options, then after_long_help.
-/// The after_long_help can start with a heading or plain text.
-fn find_after_help_start(help: &str) -> Option<usize> {
- // After Global Options section, a blank line followed by non-indented text is after_long_help
- let mut past_global_options = false;
- let mut saw_blank_after_options = false;
- let mut blank_offset = None;
- let mut offset = 0;
-
- for line in help.lines() {
- // Strip ANSI codes for pattern matching
- let plain_line = strip_ansi_codes(line);
-
- if plain_line.starts_with("Global Options:") {
- past_global_options = true;
- offset += line.len() + 1;
- continue;
- }
-
- if past_global_options {
- if plain_line.is_empty() {
- saw_blank_after_options = true;
- blank_offset = Some(offset);
- } else if saw_blank_after_options && !plain_line.starts_with(' ') {
- // Non-indented line after blank = start of after_long_help
- return blank_offset;
- } else if plain_line.starts_with(' ') {
- // Still in indented options, reset blank tracking
- saw_blank_after_options = false;
- }
- }
- offset += line.len() + 1;
- }
- None
-}
-
-/// Strip ANSI escape codes from a string for pattern matching.
-fn strip_ansi_codes(s: &str) -> String {
- let mut result = String::with_capacity(s.len());
- let mut chars = s.chars().peekable();
-
- while let Some(c) = chars.next() {
- if c == '\x1b' {
- // Skip escape sequence: ESC [ ... m (SGR) or ESC [ ... other
- if chars.peek() == Some(&'[') {
- chars.next(); // consume '['
- // Consume until we hit a letter (the command character)
- while let Some(&next) = chars.peek() {
- chars.next();
- if next.is_ascii_alphabetic() {
- break;
- }
- }
- }
- } else {
- result.push(c);
- }
- }
- result
-}
-
-/// Generate a full documentation page for a command.
-///
-/// Output format:
-/// ```markdown
-/// +++
-/// title = "Merging"
-/// weight = 5
-/// +++
-///
-/// [after_long_help content - the conceptual docs]
-///
-/// ---
-///
-/// ## Command reference
-///
-/// ```bash
-/// wt merge — ...
-/// Usage: ...
-/// ```
-/// ```
-///
-/// This is used to generate docs/content/merge.md etc from the source.
-fn handle_help_page(args: &[String]) {
- use clap::ColorChoice;
-
- let mut cmd = cli::build_command();
- cmd = cmd.color(ColorChoice::Never);
-
- // Find the subcommand name (the arg before --help-page, or after wt)
- let subcommand = args
- .iter()
- .filter(|a| *a != "--help-page" && !a.starts_with('-') && !a.ends_with("/wt"))
- .find(|a| {
- // Skip the binary name
- !a.contains("target/") && *a != "wt"
- });
-
- let Some(subcommand) = subcommand else {
- eprintln!("Usage: wt <command> --help-page");
- eprintln!("Commands with pages: merge, switch, remove, list");
- return;
- };
-
- // Navigate to the subcommand
- let sub = cmd.find_subcommand(subcommand);
- let Some(sub) = sub else {
- eprintln!("Unknown command: {subcommand}");
- return;
- };
-
- // Get the after_long_help content
- // Transform for web docs: console→bash, status colors, demo images
- // Subdocs are expanded separately so main Command reference comes first
- let parent_name = format!("wt {}", subcommand);
- let raw_help = sub
- .get_after_long_help()
- .map(|s| s.to_string())
- .unwrap_or_default();
-
- // Split content at first subdoc placeholder
- let subdoc_marker = "<!-- subdoc:";
- let (main_content, subdoc_content) = if let Some(pos) = raw_help.find(subdoc_marker) {
- (&raw_help[..pos], Some(&raw_help[pos..]))
- } else {
- (raw_help.as_str(), None)
- };
-
- // Process main content (before subdocs)
- let main_help = {
- let text = main_content.replace("```console\n", "```bash\n");
- let text = expand_demo_placeholders(&text);
- colorize_ci_status_for_html(&text)
- };
-
- // Get the help reference block (wrap at 80 chars for web docs, with colors for HTML)
- let reference_block = get_help_reference(&[subcommand], Some(80));
-
- // Output the generated content (frontmatter is in skeleton files)
- // Uses region markers so sync can replace just this content
- // END tag mirrors the ID for unambiguous matching with nested markers
- // Use std::println! to preserve ANSI codes in output (the styling::println strips them)
- std::println!(
- "<!-- ⚠️ AUTO-GENERATED from `wt {subcommand} --help-page` — edit cli.rs to update -->"
- );
- std::println!();
- std::println!("{}", main_help.trim());
- std::println!();
-
- // Main command reference immediately after its content
- std::println!("## Command reference");
- std::println!();
- std::println!("```");
- std::print!("{}", reference_block.trim());
- std::println!();
- std::println!("```");
-
- // Subdocs follow, each with their own command reference at the end
- if let Some(subdocs) = subdoc_content {
- let subdocs_expanded = expand_subdoc_placeholders(subdocs, sub, &parent_name);
- let subdocs_processed = colorize_ci_status_for_html(&subdocs_expanded);
- std::println!();
- std::println!("{}", subdocs_processed.trim());
- }
-
- std::println!();
- std::println!("<!-- END AUTO-GENERATED from `wt {subcommand} --help-page` -->");
-}
-
-/// Add HTML color spans for CI status dots in help page output.
-///
-/// Transforms plain text like "`●` green" into colored HTML spans for web rendering.
-/// This is the web-docs counterpart to md_help::colorize_status_symbols() which
-/// produces ANSI codes for terminal output.
-///
-/// Also converts plain URL references to markdown links for web docs.
-fn colorize_ci_status_for_html(text: &str) -> String {
- text
- // CI status colors (in table cells)
- .replace("`●` green", "<span style='color:#0a0'>●</span> green")
- .replace("`●` blue", "<span style='color:#00a'>●</span> blue")
- .replace("`●` red", "<span style='color:#a00'>●</span> red")
- .replace("`●` yellow", "<span style='color:#a60'>●</span> yellow")
- .replace("`⚠` yellow", "<span style='color:#a60'>⚠</span> yellow")
- .replace("`●` gray", "<span style='color:#888'>●</span> gray")
- // Convert plain URL references to markdown links for web docs
- // CLI shows: "Open an issue at https://github.com/max-sixty/worktrunk."
- // Web shows: "[Open an issue](https://github.com/max-sixty/worktrunk/issues)."
- .replace(
- "Open an issue at https://github.com/max-sixty/worktrunk.",
- "[Open an issue](https://github.com/max-sixty/worktrunk/issues).",
- )
-}
-
-/// Increase markdown heading levels by one (## -> ###, ### -> ####, etc.)
-///
-/// This makes subdoc headings children of the subdoc's main heading.
-/// Only transforms actual markdown headings, not code block content.
-fn increase_heading_levels(content: &str) -> String {
- let mut result = Vec::new();
- let mut in_code_block = false;
-
- for line in content.lines() {
- // Track code block boundaries (``` or ````+)
- if line.trim_start().starts_with("```") {
- in_code_block = !in_code_block;
- result.push(line.to_string());
- continue;
- }
-
- // Only transform headings outside code blocks
- if !in_code_block && line.starts_with('#') {
- result.push(format!("#{}", line));
- } else {
- result.push(line.to_string());
- }
- }
-
- let mut output = result.join("\n");
- // Preserve trailing newline if present (.lines() strips it)
- if content.ends_with('\n') {
- output.push('\n');
- }
- output
-}
-
-/// Expand subdoc placeholders for web docs.
-///
-/// Transforms `<!-- subdoc: subcommand -->` into an H2 section with the subcommand's help output.
-/// For example, `<!-- subdoc: create -->` in `wt config` expands to:
-///
-/// ```markdown
-/// ## wt config create
-///
-/// [help output for `wt config create`]
-/// ```
-///
-/// This allows including subcommand documentation inline in the parent command's docs page.
-fn expand_subdoc_placeholders(text: &str, parent_cmd: &clap::Command, parent_name: &str) -> String {
- const PREFIX: &str = "<!-- subdoc: ";
- const SUFFIX: &str = " -->";
-
- let mut result = text.to_string();
- while let Some(start) = result.find(PREFIX) {
- let after_prefix = start + PREFIX.len();
- if let Some(end_offset) = result[after_prefix..].find(SUFFIX) {
- let subcommand_name = result[after_prefix..after_prefix + end_offset].trim();
- let end = after_prefix + end_offset + SUFFIX.len();
-
- // Find the subcommand in the parent
- let replacement = if let Some(sub) = parent_cmd
- .get_subcommands()
- .find(|s| s.get_name() == subcommand_name)
- {
- format_subcommand_section(sub, parent_name, subcommand_name)
- } else {
- format!(
- "<!-- subdoc error: subcommand '{}' not found -->",
- subcommand_name
- )
- };
-
- result.replace_range(start..end, &replacement);
- } else {
- break;
- }
- }
- result
-}
-
-/// Format a subcommand as an H2 section for docs.
-///
-/// Includes the subcommand's `after_long_help` (conceptual docs) followed by
-/// the command reference (usage, options). If the subdoc has nested subdocs,
-/// the command reference comes before them.
-fn format_subcommand_section(
- sub: &clap::Command,
- parent_name: &str,
- subcommand_name: &str,
-) -> String {
- // parent_name is "wt config", subcommand_name is "create"
- // full_command is "wt config create"
- let full_command = format!("{} {}", parent_name, subcommand_name);
-
- // Get the raw after_long_help content
- let raw_help = sub
- .get_after_long_help()
- .map(|s| s.to_string())
- .unwrap_or_default();
-
- // Split content at first subdoc placeholder so command reference comes before nested subdocs
- let subdoc_marker = "<!-- subdoc:";
- let (main_content, subdoc_content) = if let Some(pos) = raw_help.find(subdoc_marker) {
- (&raw_help[..pos], Some(&raw_help[pos..]))
- } else {
- (raw_help.as_str(), None)
- };
-
- // Process main content (before any nested subdocs)
- let main_help = {
- let text = main_content.replace("```console\n", "```bash\n");
- let text = increase_heading_levels(&text);
- colorize_ci_status_for_html(&text)
- };
-
- // Build command path from parent_name: "wt config" -> ["config", "create"]
- let command_path: Vec<&str> = parent_name
- .strip_prefix("wt ")
- .unwrap_or(parent_name)
- .split_whitespace()
- .chain(std::iter::once(subcommand_name))
- .collect();
-
- // Get help reference (wrap at 80 chars for web docs, with colors for HTML)
- let reference_block = get_help_reference(&command_path, Some(80));
-
- // Format the section: heading, main content, command reference, then nested subdocs
- let mut section = format!("## {}\n\n", full_command);
-
- if !main_help.is_empty() {
- section.push_str(main_help.trim());
- section.push_str("\n\n");
- }
-
- // Command reference comes after main content but before nested subdocs
- section.push_str("### Command reference\n\n```\n");
- section.push_str(reference_block.trim());
- section.push_str("\n```\n");
-
- // Expand nested subdocs after the command reference
- if let Some(subdocs) = subdoc_content {
- let subdocs_expanded = expand_subdoc_placeholders(subdocs, sub, &full_command);
- let subdocs_processed = colorize_ci_status_for_html(&subdocs_expanded);
- section.push('\n');
- section.push_str(subdocs_processed.trim());
- section.push('\n');
- }
-
- section
-}
-
-/// Expand demo GIF placeholders for web docs.
-///
-/// Transforms `<!-- demo: filename.gif -->` into an HTML figure with the `demo` class.
-/// The HTML comment is invisible in terminal --help output, but expands to a styled figure
-/// for web docs generated via --help-page.
-///
-/// The placeholder should be on its own line without surrounding blank lines in the source.
-/// This function adds blank lines around the figure for proper markdown paragraph separation.
-///
-/// Supports optional dimensions: `<!-- demo: filename.gif 1600x900 -->`
-fn expand_demo_placeholders(text: &str) -> String {
- const PREFIX: &str = "<!-- demo: ";
- const SUFFIX: &str = " -->";
-
- let mut result = text.to_string();
- while let Some(start) = result.find(PREFIX) {
- let after_prefix = start + PREFIX.len();
- if let Some(end_offset) = result[after_prefix..].find(SUFFIX) {
- let content = &result[after_prefix..after_prefix + end_offset];
- // Parse "filename.gif" or "filename.gif 1600x900"
- let mut parts = content.split_whitespace();
- let filename = parts.next().unwrap_or("");
- let dimensions = parts.next(); // Optional "WIDTHxHEIGHT"
-
- // Extract command name from filename (e.g., "wt-select.gif" -> "wt select")
- let alt_text = filename.trim_end_matches(".gif").replace('-', " ");
-
- // Build dimension attributes if provided
- let dim_attrs = dimensions
- .and_then(|d| d.split_once('x'))
- .map(|(w, h)| format!(" width=\"{w}\" height=\"{h}\""))
- .unwrap_or_default();
-
- // Use figure.demo class for proper mobile styling (no shrink, horizontal scroll)
- // Generate <picture> element for light/dark theme switching
- // Assets are organized as: /assets/docs/{light,dark}/filename.gif
- // Add blank line before the figure; blank line after is already in source
- let replacement = format!(
- "\n<figure class=\"demo\">\n<picture>\n <source srcset=\"/assets/docs/dark/{filename}\" media=\"(prefers-color-scheme: dark)\">\n <img src=\"/assets/docs/light/{filename}\" alt=\"{alt_text} demo\"{dim_attrs}>\n</picture>\n</figure>"
- );
- let end = after_prefix + end_offset + SUFFIX.len();
- result.replace_range(start..end, &replacement);
- } else {
- break;
- }
- }
- result
-}
-
/// Enhance clap errors with command-specific hints, then exit.
///
/// For `wt switch` missing the branch argument, adds hints about shortcuts.
@@ -748,7 +120,7 @@ fn main() {
}
// Handle --help with pager before clap processes it
- if maybe_handle_help_with_pager() {
+ if help::maybe_handle_help_with_pager() {
return;
}
@@ -1789,7 +1161,7 @@ fn main() {
let code = exit_code(&e).unwrap_or(1);
// Write diagnostic if -vv was used (error case)
- write_vv_diagnostic(verbose_level, &command_line, Some(&e.to_string()));
+ diagnostic::write_if_verbose(verbose_level, &command_line, Some(&e.to_string()));
// Reset ANSI state before exiting
let _ = output::terminate_output();
@@ -1797,74 +1169,8 @@ fn main() {
}
// Write diagnostic if -vv was used (success case)
- write_vv_diagnostic(verbose_level, &command_line, None);
+ diagnostic::write_if_verbose(verbose_level, &command_line, None);
// Reset ANSI state before returning to shell (success case)
let _ = output::terminate_output();
}
-
-/// Write diagnostic file when -vv is used.
-///
-/// Called at the end of command execution. If verbose level is >= 2, writes
-/// a diagnostic report to `.git/wt-logs/diagnostic.md` for issue filing.
-///
-/// Silently returns if:
-/// - verbose < 2
-/// - Not in a git repository
-///
-/// Warns if diagnostic file write fails.
-fn write_vv_diagnostic(verbose: u8, command_line: &str, error_msg: Option<&str>) {
- if verbose < 2 {
- return;
- }
-
- // Use Repository::current() which honors the -C flag
- let Ok(repo) = worktrunk::git::Repository::current() else {
- return;
- };
-
- // Check if we're actually in a git repo
- if repo.current_worktree().git_dir().is_err() {
- return;
- }
-
- // Build context based on success/error
- let context = match error_msg {
- Some(msg) => format!("Command failed: {msg}"),
- None => "Command completed successfully".to_string(),
- };
-
- // Collect and write diagnostic
- let report = diagnostic::DiagnosticReport::collect(&repo, command_line, context);
- match report.write_diagnostic_file(&repo) {
- Some(path) => {
- let path_display = format_path_for_display(&path);
- let _ = output::print(info_message(format!("Diagnostic saved: {path_display}")));
-
- // Only show gh command if gh is installed
- if is_gh_installed() {
- // Escape single quotes for shell: 'it'\''s' -> it's
- let path_str = path.to_string_lossy().replace('\'', "'\\''");
- // URL with prefilled body: ## Gist\n\n[Paste URL]\n\n## Description\n\n[Describe the issue]
- let issue_url = "https://github.com/max-sixty/worktrunk/issues/new?body=%23%23%20Gist%0A%0A%5BPaste%20gist%20URL%5D%0A%0A%23%23%20Description%0A%0A%5BDescribe%20the%20issue%5D";
- let _ = output::print(hint_message(cformat!(
- "To report a bug, create a secret gist with <bright-black>gh gist create --web '{path_str}'</> and reference it from an issue at <bright-black>{issue_url}</>"
- )));
- }
- }
- None => {
- let _ = output::print(warning_message("Failed to write diagnostic file"));
- }
- }
-}
-
-/// Check if the GitHub CLI (gh) is installed.
-fn is_gh_installed() -> bool {
- use worktrunk::shell_exec::Cmd;
-
- Cmd::new("gh")
- .arg("--version")
- .run()
- .map(|o| o.status.success())
- .unwrap_or(false)
-}