Skip to content

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

37.2 KB
Raw Blame
//! 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`
//!
//! # Web docs generation (`--help-page`)
//!
//! Each command page flows through a small set of transforms before becoming
//! portable Markdown:
//!
//! ```text
//! cli.rs (source of truth)
//!   ├── after_long_help: markdown prose with [experimental] markers, `#` CI samples, plain URLs
//!   └── doc comments (/// lines): definition + subtitle for lead paragraph
//!         │
//!         ▼
//! combine_command_docs()         — assembles "definition. subtitle\n\n<after_long_help>"
//!         │
//!         ▼
//! post_process_for_html()        — text replacements on after_long_help markdown:
//!         │                        [experimental] → badge <span>
//!         │                        `#` green → colored <span>
//!         │                        plain URLs → markdown links
//!         ▼
//! --help-page stdout             — Markdown with small semantic HTML spans
//!         │
//!         ▼  (readme_sync.rs test captures and writes to docs/)
//!         │
//! expand_command_placeholders()        — command placeholders → snapshot console blocks
//!         │
//!         ▼
//! docs/src/content/docs/{command}.md — final Markdown consumed by Astro
//! ```
//!
//! **Manually-written pages** (faq.md, llm-commits.md) bypass this pipeline.
//! They use `<span class="badge-experimental"></span>` directly for badges.
//!
//! **Skill reference files** mirror docs content via `transform_docs_for_skill()`,
//! which strips site-only elements such as demo figures and converts badge
//! `<span>` elements back to `[experimental]`.

use std::ffi::OsString;
use std::process;

use ansi_str::AnsiStr;
use clap::error::ErrorKind;
use worktrunk::docs::{
    BADGE_EXPERIMENTAL_HTML, DEMO_MARKER_PREFIX, MARKER_CLOSE, MARKER_OPEN_PREFIX,
    SUBDOC_MARKER_PREFIX,
};
use worktrunk::styling::{ColorChoice, eprintln, print, println};

use crate::cli;

/// Output format for a `--help-page`. Web pages keep semantic HTML spans and
/// demo GIF figures for the docs site; plain pages strip those for skill
/// reference files that need portable Markdown.
#[derive(Clone, Copy)]
enum PageMode {
    Web,
    Plain,
}

impl PageMode {
    /// Transform the body (everything before subdoc placeholders). Web expands
    /// demo GIFs into `<picture>` figures and converts CLI markers into HTML
    /// spans; plain strips demo placeholders so they don't leak as comments.
    fn process_body(self, text: &str) -> String {
        match self {
            Self::Web => post_process_for_html(&expand_demo_placeholders(text)),
            Self::Plain => strip_demo_placeholders(text),
        }
    }

    /// Transform subdoc trailing content (e.g. an `Aliases` section after the
    /// last subdoc marker). Web post-processes CLI markers; plain passes
    /// through unchanged — each subdoc's body is processed during expansion.
    fn process_subdoc_trailing(self, text: &str) -> String {
        match self {
            Self::Web => post_process_for_html(text),
            Self::Plain => text.to_string(),
        }
    }

    /// Rendering for the `[experimental]` badge.
    fn experimental_marker(self) -> &'static str {
        match self {
            Self::Web => BADGE_EXPERIMENTAL_HTML,
            Self::Plain => "[experimental]",
        }
    }

    /// Opening fence for generated command references. The web marker gives
    /// the renderer explicit ownership; plain skill pages stay portable.
    fn command_reference_fence(self) -> &'static str {
        match self {
            Self::Web => "```text wt-command-reference",
            Self::Plain => "```",
        }
    }

    /// Emit the page header — an auto-generated comment for web (sync test
    /// uses it as a region marker), or an H1 title for plain skill pages.
    fn emit_header(self, subcommand: &str) {
        match self {
            Self::Web => println!(
                "{MARKER_OPEN_PREFIX}`wt {subcommand} --help-page` — edit src/cli/mod.rs to update -->"
            ),
            Self::Plain => println!("# wt {subcommand}"),
        }
        println!();
    }

    /// Emit the closing END marker (web only).
    fn emit_footer(self) {
        if matches!(self, Self::Web) {
            println!();
            println!("{MARKER_CLOSE}");
        }
    }
}

/// Keep the global-options section in the first command reference on a page,
/// and cut it from the rest.
///
/// Clap repeats the same ~20-line `Global Options:` list in every reference it
/// renders, so a page built from subdocs stacks one copy per reference — 12 on
/// `wt config`, 13 on `wt step`. That pads both the site page and the skill
/// mirror, and gives the site's search that many near-identical hits. `kept`
/// carries the state for one page; a reference with no such section leaves it
/// alone, so the page's first *real* reference is always the one that keeps it.
///
/// Terminal `--help` renders through clap directly and still prints the section
/// for every command.
///
/// The section is last in the block: `help_reference_inner` cuts
/// `after_long_help` off at `find_after_help_start`, which is the first
/// non-indented line after it.
fn take_global_options(reference: &str, kept: &mut bool) -> String {
    // Clap renders references with color escapes even under NO_COLOR, so match
    // on the stripped text.
    let heading = |line: &str| line.ansi_strip().trim_end() == "Global Options:";
    let Some(start) = reference
        .lines()
        .scan(0, |offset, line| {
            let at = *offset;
            *offset += line.len() + 1;
            Some((at, line))
        })
        .find_map(|(at, line)| heading(line).then_some(at))
    else {
        return reference.to_string();
    };

    if *kept {
        reference[..start].trim_end().to_string()
    } else {
        *kept = true;
        reference.to_string()
    }
}

/// Custom help handling for pager support and markdown rendering.
///
/// We intercept help requests to provide:
/// 1. **Pager support**: Long help (`--help`) shown through pager, short (`-h`) prints directly
/// 2. **Markdown rendering**: `## Headers` become green, code blocks are dimmed
///
/// This follows git's convention:
/// - `-h` never opens a pager (short help, muscle-memory safe)
/// - `--help` opens a pager when content doesn't fit (via less -F flag)
///
/// Uses `Error::render()` to get clap's pre-formatted help, which already
/// respects `-h` (short) vs `--help` (long) distinction.
///
/// On a help/version/doc-generation request, prints output and calls
/// `process::exit(0)`. Otherwise returns so the caller can continue normal parsing.
///
/// `alias_help_context` and `subcommand` both come from the caller's
/// early-parse pass over the real argv, the same one that extracts global
/// options. When `alias_help_context` is `Some`, the configured aliases are
/// spliced into the rendered output — at the top level for `wt --help`, or
/// under the Aliases section for `wt step --help`. `subcommand` is the command
/// the doc-generation entry points below render, taken from clap rather than
/// re-scanned here, so `wt.exe`, a renamed binary, or `wt -C <path> list
/// --print-schema` all name the same thing.
pub fn maybe_handle_help_with_pager(
    alias_help_context: Option<crate::commands::HelpContext>,
    subcommand: Option<&str>,
) {
    let args_os: Vec<OsString> = std::env::args_os().collect();
    let args: Vec<String> = args_os
        .iter()
        .map(|arg| arg.to_string_lossy().into_owned())
        .collect();

    // --help uses pager, -h prints directly (git convention)
    let use_pager = args.iter().any(|a| a == "--help");

    // Check for --help-page flag (output full doc page with frontmatter)
    if args.iter().any(|a| a == "--help-page") {
        let mode = if args.iter().any(|a| a == "--plain") {
            PageMode::Plain
        } else {
            PageMode::Web
        };
        handle_help_page(subcommand, mode);
        process::exit(0);
    }

    // Check for --print-schema flag (output the JSON Schema for a command's
    // --format=json payload)
    if args.iter().any(|a| a == "--print-schema") {
        handle_print_schema(subcommand);
        process::exit(0);
    }

    // Check for --help-description flag (output meta description for docs)
    if args.iter().any(|a| a == "--help-description") {
        handle_help_description(subcommand);
        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 = crate::completion::inject_hook_subcommands(cmd);

        // 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
            )
        {
            // Escape-free markdown on stdout is this entry point's contract,
            // tty or not, so the choice is declared rather than left to the
            // stream's tty check.
            ColorChoice::Never.write_global();
            let output = normalize_clap_help_fences(&err.render().ansi().to_string());
            print!("{output}");
            process::exit(0);
        }
        // Fall through if not a help request
    }

    let mut cmd = cli::build_command();
    cmd = crate::completion::inject_hook_subcommands(cmd);

    if let Err(err) = cmd.try_get_matches_from_mut(args_os) {
        match err.kind() {
            ErrorKind::DisplayHelp | ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand => {
                // .ansi() renders the StyledStr's styles as escapes; its
                // Display renders the text without them.
                let clap_output = err.render().ansi().to_string();

                // Splice configured aliases into `wt --help` and
                // `wt step --help` (and their `-h` / bare-subcommand
                // equivalents) so the help surfaces both the built-ins and
                // the user's aliases. Other help pages pass through.
                let clap_output = match alias_help_context {
                    Some(ctx) => crate::commands::augment_help(&clap_output, ctx),
                    None => clap_output,
                };

                // Render markdown sections (tables, code blocks, prose) with proper wrapping.
                // Since we disabled clap's wrapping above, our renderer controls all line breaks.
                let help = crate::md_help::render_markdown_in_help_with_width(
                    &clap_output,
                    worktrunk::styling::terminal_width(),
                );

                // Page only when stdout is a TTY; redirected help stays on stdout.
                // use_pager=false for -h (short help), true for --help (long help)
                if let Err(error) = crate::help_pager::show_help_in_pager(&help, use_pager) {
                    crate::handle_command_failure(error, 0, &args.join(" "));
                }
                process::exit(0);
            }
            ErrorKind::DisplayVersion => {
                // Print to stdout — POSIX convention, and scripts rely on
                // `version=$(wt --version)` working without redirection (#2072).
                // Use print! because clap's Error Display already includes a trailing newline.
                print!("{}", err);
                process::exit(0);
            }
            _ => {
                // Not help or version - will be re-parsed by Cli::parse()
            }
        }
    }
}

/// The help reference block, normalized for portable Markdown output.
fn help_reference(command_path: &[&str], width: Option<usize>) -> String {
    let output = help_reference_inner(command_path, width);
    // Clap turns Markdown links into OSC 8 hyperlinks even when color is disabled.
    // Escape sequences are not valid portable Markdown, so retain their visible
    // labels and discard the terminal-only control bytes.
    worktrunk::styling::strip_osc8_hyperlinks(&output)
}

/// Normalize fences in clap-rendered help output for downstream Markdown
/// consumers. `--help-md` and `help_reference_inner` both run this.
fn normalize_clap_help_fences(text: &str) -> String {
    text
        // clap's default for usage blocks — strip the language for plain markdown
        .replace("```text\n", "```\n")
        // our authored examples — relabel for syntax highlighting in docs/skills
        .replace("```console\n", "```bash\n")
}

fn help_reference_inner(command_path: &[&str], width: Option<usize>) -> String {
    // 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 = crate::completion::inject_hook_subcommands(cmd);
    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
        ) {
        normalize_clap_help_fences(&err.render().ansi().to_string())
    } 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 = line.ansi_strip();

        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
}

/// Extract the `about` (definition) and subtitle from a command's metadata.
///
/// The subtitle is the part of `long_about` beyond the short `about`.
/// For `/// Short\n///\n/// Long description`, about = "Short", subtitle = "Long description".
fn extract_about_and_subtitle(cmd: &clap::Command) -> (Option<String>, Option<String>) {
    let about = cmd.get_about().map(|s| s.to_string());
    let long_about = cmd.get_long_about().map(|s| s.to_string());
    let subtitle = match (&about, &long_about) {
        (Some(short), Some(long)) if long.starts_with(short) => {
            let rest = long[short.len()..].trim_start();
            if rest.is_empty() {
                None
            } else {
                Some(rest.to_string())
            }
        }
        _ => None,
    };
    (about, subtitle)
}

/// Output the meta description for a command's docs page.
///
/// Combines the command's `about` (definition) and `long_about` subtitle into
/// a single description suitable for `<meta name="description">`. This is used
/// by the docs sync test to auto-populate the `description` field in frontmatter.
fn handle_help_description(subcommand: Option<&str>) {
    let mut cmd = cli::build_command();
    cmd = crate::completion::inject_hook_subcommands(cmd);

    let Some(subcommand) = subcommand else {
        eprintln!("Usage: wt <command> --help-description");
        return;
    };

    let Some(sub) = cmd.find_subcommand(subcommand) else {
        eprintln!("Unknown command: {subcommand}");
        return;
    };

    let (about, subtitle) = extract_about_and_subtitle(sub);

    let description = match (&about, &subtitle) {
        (Some(def), Some(sub)) => format!("{def}. {sub}"),
        (Some(def), None) => format!("{def}."),
        _ => String::new(),
    };

    print!("{description}");
}

/// Print the JSON Schema for a command's `--format=json` payload.
///
/// A developer entry point in the same family as `--help-page`: it exists so
/// the docs sync (`test_docs_are_in_sync`) can regenerate a committed schema
/// file by running the binary, which is the only way a `tests/` integration
/// test can reach a type in the bin-only `crate::commands` tree.
///
/// One command has a schema today, because one payload is versioned. The
/// subcommand is the axis a second would arrive on.
fn handle_print_schema(subcommand: Option<&str>) {
    let Some(subcommand) = subcommand else {
        eprintln!(
            "Usage: wt <command> --print-schema
Commands with schemas: list"
        );
        process::exit(2);
    };

    if subcommand != "list" {
        eprintln!("No JSON schema for '{subcommand}'; commands with schemas: list");
        process::exit(2);
    }

    let schema = crate::commands::list::json_v2::schema_document();
    crate::output::print_json(&schema).expect("schema serializes");
}

/// Generate a full documentation page for a command.
///
/// Output format:
/// ```markdown
/// +++
/// title = "Merging"
/// weight = 5
/// +++
///
/// [after_long_help content - the conceptual docs]
///
/// ---
///
/// ## Command reference
///
/// ```text wt-command-reference
/// wt merge — ...
/// Usage: ...
/// ```
/// ```
///
/// This is used to generate docs/src/content/docs/merge.md etc from the source.
fn handle_help_page(subcommand: Option<&str>, mode: PageMode) {
    // Help pages are portable Markdown, so terminal color escapes never enter
    // the generated source. The website adds syntax and prompt styling when
    // it renders fenced blocks.
    ColorChoice::Never.write_global();

    let mut cmd = cli::build_command();
    cmd = crate::completion::inject_hook_subcommands(cmd);

    let Some(subcommand) = subcommand else {
        eprintln!(
            "Usage: wt <command> --help-page
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;
    };

    let parent_name = format!("wt {}", subcommand);
    let raw_help = combine_command_docs(sub);

    // Subdocs are expanded separately so the main command reference comes first.
    let (main_content, subdoc_content) = match raw_help.find(SUBDOC_MARKER_PREFIX) {
        Some(pos) => (&raw_help[..pos], Some(&raw_help[pos..])),
        None => (raw_help.as_str(), None),
    };

    let main_help = mode.process_body(main_content);
    // One flag for the whole page: the first reference below keeps its global
    // options and every later one drops them.
    let mut kept_global_options = false;
    let reference_block = help_reference(&[subcommand], Some(100));
    let reference_block = take_global_options(&reference_block, &mut kept_global_options);

    mode.emit_header(subcommand);
    println!("{}", main_help.trim());
    println!();

    // Main command reference immediately after its content
    println!("## Command reference");
    println!();
    println!("{}", mode.command_reference_fence());
    println!("{}", reference_block.trim());
    println!("```");

    // Subdocs follow, each with their own command reference at the end.
    if let Some(subdocs) = subdoc_content {
        // Process trailing text (e.g., an Aliases section after the last subdoc
        // marker) before expansion — each subdoc's own body is post-processed
        // inside format_subcommand_section, so re-running would double-convert.
        let subdocs = mode.process_subdoc_trailing(subdocs);
        let subdocs_expanded =
            expand_subdoc_placeholders(&subdocs, sub, &parent_name, mode, &mut kept_global_options);
        println!();
        println!("# Subcommands");
        println!();
        println!("{}", subdocs_expanded.trim());
    }

    mode.emit_footer();
}

/// Post-process CLI help content for web docs rendering.
///
/// Applies text replacements to `after_long_help` content before it becomes markdown
/// in the docs site. Each replacement converts a CLI-friendly marker into styled HTML:
///
/// | CLI source | Web docs |
/// |------------|----------|
/// | `` `#` green `` | `<span style='color:#0a0'>#</span> green` |
/// | `[experimental]` | `<span class="badge-experimental"></span>` (text via CSS) |
/// | plain URL | markdown link |
/// | approval prompt code block | unchanged portable Markdown |
///
/// Only runs on `after_long_help` Markdown, not on terminal reference blocks.
///
/// The terminal counterpart is `md_help::colorize_status_symbols()`.
fn post_process_for_html(text: &str) -> String {
    // First pass: move [experimental] from heading lines to a separate line after
    // the heading. This keeps the badge out of the generated anchor slug.
    // Terminal help keeps [experimental] on the heading line (different render path).
    let text = move_experimental_from_headings(text);

    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("`#` magenta", "<span style='color:#a0a'>#</span> magenta")
        .replace("`#` cyan", "<span style='color:#0aa'>#</span> cyan")
        .replace("`#` yellow", "<span style='color:#a60'>#</span> yellow")
        .replace("`⚠` yellow", "<span style='color:#a60'>⚠</span> yellow")
        .replace("`#` gray", "<span style='color:#888'>#</span> gray")
        .replace("[experimental]", BADGE_EXPERIMENTAL_HTML)
        // 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).",
        )
}

/// Move `[experimental]` from heading lines to a separate line after the heading.
///
/// Transforms `## Foo [experimental]` into:
/// ```text
/// ## Foo
///
/// [experimental]
/// ```
///
/// This keeps the badge out of the heading text and therefore out of its slug.
/// The `[experimental]` is then replaced with the badge `<span>` by the
/// caller's `.replace()` chain.
fn move_experimental_from_headings(text: &str) -> String {
    if !text.contains(" [experimental]") {
        return text.to_string();
    }

    let mut result = String::with_capacity(text.len());
    let mut in_code_block = false;

    for line in text.lines() {
        if line.trim_start().starts_with("```") {
            in_code_block = !in_code_block;
        }

        if !in_code_block
            && line.starts_with('#')
            && let Some(heading) = line.strip_suffix(" [experimental]")
        {
            result.push_str(heading);
            result.push_str("\n\n[experimental]");
        } else {
            result.push_str(line);
        }
        result.push('\n');
    }
    // .lines() strips the trailing newline; restore original behavior
    if !text.ends_with('\n') {
        result.pop();
    }
    result
}

/// 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,
    mode: PageMode,
    kept_global_options: &mut bool,
) -> String {
    const SUFFIX: &str = " -->";

    let mut result = text.to_string();
    while let Some(start) = result.find(SUBDOC_MARKER_PREFIX) {
        let after_prefix = start + SUBDOC_MARKER_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,
                    mode,
                    kept_global_options,
                )
            } else {
                format!(
                    "<!-- subdoc error: subcommand '{}' not found -->",
                    subcommand_name
                )
            };

            result.replace_range(start..end, &replacement);
        } else {
            break;
        }
    }
    result
}

/// Combine a command's about, long_about, and after_long_help into documentation content.
///
/// The pattern is: `"definition. subtitle\n\n<after_long_help>"`
/// - `about` is the one-liner definition
/// - `subtitle` is the extra content in `long_about` beyond the `about`
/// - If `long_about` doesn't extend `about`, subtitle is empty
fn combine_command_docs(cmd: &clap::Command) -> String {
    let (about, subtitle) = extract_about_and_subtitle(cmd);
    let after_long_help = cmd
        .get_after_long_help()
        .map(|s| s.to_string())
        .unwrap_or_default();

    // Combine: definition + subtitle as single lead paragraph, then after_long_help
    // Definition doesn't have trailing period, subtitle does, so join with ". "
    match (&about, &subtitle) {
        (Some(def), Some(sub)) => format!("{def}. {sub}\n\n{after_long_help}"),
        (Some(def), None) => format!("{def}.\n\n{after_long_help}"),
        (None, Some(sub)) => format!("{sub}\n\n{after_long_help}"),
        (None, None) => after_long_help,
    }
}

/// 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,
    mode: PageMode,
    kept_global_options: &mut bool,
) -> String {
    // parent_name is "wt config", subcommand_name is "create"
    // full_command is "wt config create"
    let full_command = format!("{} {}", parent_name, subcommand_name);

    let raw_help = combine_command_docs(sub);

    // Extract [experimental] marker from content start → badge after heading.
    // Web mode: placed after the heading so it does not affect the anchor slug.
    // Plain mode: kept as [experimental] text.
    let (has_experimental, raw_help) = match raw_help.strip_prefix("[experimental] ") {
        Some(rest) => (true, rest.to_string()),
        None => (false, raw_help),
    };

    // Split content at first subdoc placeholder so command reference comes before nested subdocs
    let (main_content, subdoc_content) = match raw_help.find(SUBDOC_MARKER_PREFIX) {
        Some(pos) => (&raw_help[..pos], Some(&raw_help[pos..])),
        None => (raw_help.as_str(), None),
    };

    let main_help = mode.process_body(&increase_heading_levels(main_content));

    // 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();

    let reference_block = help_reference(&command_path, Some(100));
    let reference_block = take_global_options(&reference_block, kept_global_options);

    // Format the section: heading, badge (outside heading), main content, command reference
    let mut section = format!("## {full_command}\n\n");
    if has_experimental {
        section.push_str(mode.experimental_marker());
        section.push_str("\n\n");
    }

    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");
    section.push_str(mode.command_reference_fence());
    section.push('\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 = mode.process_subdoc_trailing(subdocs);
        let subdocs_expanded =
            expand_subdoc_placeholders(&subdocs, sub, &full_command, mode, kept_global_options);
        section.push('\n');
        section.push_str(subdocs_expanded.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 and a caption, in that order:
/// `<!-- demo: filename.gif 1600x900 | What the recording shows -->`. The
/// caption becomes the figure's `<figcaption>`, the same treatment the
/// hand-written homepage figures get; without one the figure has no caption.
fn expand_demo_placeholders(text: &str) -> String {
    const SUFFIX: &str = " -->";

    let mut result = text.to_string();
    while let Some(start) = result.find(DEMO_MARKER_PREFIX) {
        let after_prefix = start + DEMO_MARKER_PREFIX.len();
        if let Some(end_offset) = result[after_prefix..].find(SUFFIX) {
            let content = &result[after_prefix..after_prefix + end_offset];
            // Split "filename.gif 1600x900" from an optional "| caption"
            let (spec, caption) = match content.split_once('|') {
                Some((spec, caption)) => (spec, caption.trim()),
                None => (content, ""),
            };
            let mut parts = spec.split_whitespace();
            let filename = parts.next().unwrap_or("");
            let dimensions = parts.next(); // Optional "WIDTHxHEIGHT"

            // Extract command name from filename (e.g., "wt-switch-picker.gif" -> "wt switch picker")
            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();

            let figcaption = if caption.is_empty() {
                String::new()
            } else {
                format!("\n<figcaption>{caption}</figcaption>")
            };

            // 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 trailing newline for markdown paragraph separation after the figure
            let replacement = format!(
                "<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>{figcaption}\n</figure>\n"
            );
            let end = after_prefix + end_offset + SUFFIX.len();
            result.replace_range(start..end, &replacement);
        } else {
            break;
        }
    }
    result
}

/// Strip demo GIF placeholders from content (for plain/skill output).
///
/// Removes `<!-- demo: filename.gif -->` lines entirely. These are invisible in
/// terminal --help but would leak as HTML comments in skill reference files.
fn strip_demo_placeholders(text: &str) -> String {
    const SUFFIX: &str = " -->";

    let mut result = text.to_string();
    while let Some(start) = result.find(DEMO_MARKER_PREFIX) {
        let after_prefix = start + DEMO_MARKER_PREFIX.len();
        if let Some(end_offset) = result[after_prefix..].find(SUFFIX) {
            let end = after_prefix + end_offset + SUFFIX.len();
            // Also strip trailing newline if present
            let end = if result[end..].starts_with('\n') {
                end + 1
            } else {
                end
            };
            result.replace_range(start..end, "");
        } else {
            break;
        }
    }
    result
}

#[cfg(test)]
mod tests {
    use super::*;

    /// A reference with no `Global Options:` heading is returned whole, and
    /// leaves `kept` alone so the first reference that does carry one still
    /// keeps it. Every clap-rendered reference has the section today, so this
    /// is the path that runs if clap renames or drops the heading: the page
    /// loses nothing rather than being truncated at a heading that isn't there.
    #[test]
    fn take_global_options_passes_through_a_reference_without_the_section() {
        let reference = "Usage: wt list\n\nOptions:\n  -h, --help  Print help\n";
        let mut kept = false;

        assert_eq!(take_global_options(reference, &mut kept), reference);
        assert!(!kept, "a reference with no section must not claim the slot");
    }

    /// The first reference keeps the section; every later one ends before the
    /// heading. This is what stops a subdoc-assembled page from stacking a
    /// dozen copies of the same twenty lines.
    #[test]
    fn take_global_options_keeps_only_the_first_section() {
        let reference = "Usage: wt list\n\nGlobal Options:\n  -C <path>  Working directory\n";
        let mut kept = false;

        assert_eq!(take_global_options(reference, &mut kept), reference);
        assert!(kept);
        assert_eq!(
            take_global_options(reference, &mut kept),
            "Usage: wt list",
            "a later reference ends before the heading"
        );
    }

    /// The caption is optional: a placeholder without one renders a figure with
    /// no `<figcaption>` rather than an empty element.
    #[test]
    fn demo_placeholder_without_a_caption_renders_no_figcaption() {
        let expanded = expand_demo_placeholders("<!-- demo: wt-switch.gif 1600x900 -->");

        assert!(
            !expanded.contains("figcaption"),
            "no caption means no element: {expanded}"
        );
        assert!(expanded.contains("width=\"1600\" height=\"900\""));
    }

    /// A caption after `|` becomes the figure's `<figcaption>`.
    #[test]
    fn demo_placeholder_caption_becomes_a_figcaption() {
        let expanded =
            expand_demo_placeholders("<!-- demo: wt-switch.gif | Switching worktrees -->");

        assert!(
            expanded.contains("<figcaption>Switching worktrees</figcaption>"),
            "{expanded}"
        );
    }
}