Skip to content

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

14.4 KB
Raw Blame
//! `wt config alias` subcommands.
//!
//! Introspection and preview for aliases configured in user config
//! (`~/.config/worktrunk/config.toml`) and project config (`.config/wt.toml`).
//! `show <name>` prints the template text, source-labeled, with one gutter
//! block per alias entry and `# <name>` comment lines above named pipeline
//! steps. `show` with no name prints that block for every configured alias in
//! name order — equivalent to `wt config alias show <name>` run for each.
//! `dry-run` parses a per-invocation argument vector with the same parser
//! `wt <alias>` uses, then expands templates using the same context as
//! execution — so previews match what the real run will do. `show <name>` and
//! `dry-run` share a layout; only the header verb differs (`:` vs
//! ` would run:`).
//!
//! ## Why `dry-run` lives here rather than on the alias dispatch
//!
//! Previous versions exposed dry-run via `wt <alias> --dry-run`. That routed
//! through `AliasOptions::parse` and required every caller to handle the
//! "preview vs run" branch. Lifting it into a dedicated subcommand keeps the
//! alias-dispatch path single-purpose (always runs) and gives preview a
//! natural home alongside `show`.

use std::collections::BTreeSet;

use anyhow::Context;
use color_print::cformat;
use worktrunk::config::{
    ALIAS_ARGS_KEY, CommandConfig, ProjectConfig, UserConfig, VarScope, referenced_vars_for_config,
};
use worktrunk::git::{Repository, WorktrunkError};
use worktrunk::styling::{eprint, format_bash_with_gutter, info_message, println};

use crate::commands::alias::{
    AliasOptions, is_top_level_builtin, load_aliases, load_aliases_for_listing,
};
use crate::commands::build_invalid_subcommand_error;
use crate::commands::command_executor::{
    CommandContext, build_hook_context, render_template_preview,
};
use worktrunk::config::HookSource;
use worktrunk::utils::did_you_mean;

/// Show configured alias templates, optionally restricted to one name.
///
/// Both forms are discovery surfaces: tolerate running outside a repository,
/// suppress config migration warnings, and page long definitions. Entries are
/// ordered by name, then user before project, matching runtime execution order.
pub fn handle_alias_show(name: Option<String>) -> anyhow::Result<()> {
    worktrunk::config::suppress_warnings();
    let mut entries = load_aliases_for_listing();
    if let Some(name) = name {
        if !entries.iter().any(|(n, _, _)| n == &name) {
            return Err(unknown_alias_error(
                &name,
                "show",
                entries.into_iter().map(|(n, _, _)| n).collect(),
            ));
        }
        entries.retain(|(n, _, _)| n == &name);
    }
    if entries.is_empty() {
        println!("{}", info_message("No aliases configured"));
        return Ok(());
    }

    // Duplicate names from user and project config need only one warning.
    let mut prev_name: Option<&str> = None;
    let mut out = String::new();
    for (name, cfg, source) in &entries {
        if prev_name != Some(name.as_str()) {
            warn_if_shadowed(name);
            prev_name = Some(name);
        }
        let bodies: Vec<String> = cfg.commands().map(|c| c.template.clone()).collect();
        out.push_str(&format_entry(name, cfg, *source, &bodies, None));
        out.push('\n');
    }
    crate::help_pager::show_help_in_pager(&out, true)
}

/// Emit a warning if `name` is a top-level built-in subcommand. Aliases with
/// these names are unreachable via `wt <name>` — clap matches the built-in
/// first. Reported in `show`/`dry-run` so the user finds out at the discovery
/// surface rather than silently during an invocation that never reaches the
/// alias.
fn warn_if_shadowed(name: &str) {
    if is_top_level_builtin(name) {
        worktrunk::styling::eprintln!(
            "{}",
            worktrunk::styling::warning_message(cformat!(
                "Alias <bold>{name}</> is shadowed by built-in <bold>wt {name}</>"
            ))
        );
    }
}

/// Preview an alias invocation: parse the args, build the template context,
/// and print the rendered command(s) without executing.
///
/// Rendering goes through [`render_template_preview`], which mirrors
/// execution-time semantics for everything but `{{ vars.<key> }}`: each of
/// those renders as itself, because the value resolves from git config when
/// the step runs, potentially written by an earlier pipeline step.
pub fn handle_alias_dry_run(name: String, args: Vec<String>) -> anyhow::Result<()> {
    let repo = Repository::current()?;
    let user_config = repo.user_config();
    let project_config = repo.project_config()?;
    let entries = entries_for_name(&repo, user_config, project_config, &name);

    if entries.is_empty() {
        return Err(unknown_alias_error(
            &name,
            "dry-run",
            load_aliases(Some(&repo), user_config, project_config)
                .into_keys()
                .collect(),
        ));
    }

    // Reuse the real parser so previews stay aligned with runtime parsing —
    // including `--KEY=VALUE` routing and positional forwarding. When both
    // user and project configs define the alias, union the referenced vars
    // so a flag binds if any entry's template references it.
    let mut referenced: BTreeSet<String> = BTreeSet::new();
    for (cfg, _) in &entries {
        referenced.extend(referenced_vars_for_config(cfg, |_| name.clone())?);
    }
    let mut parse_args = Vec::with_capacity(1 + args.len());
    parse_args.push(name.clone());
    parse_args.extend(args);
    let (opts, warnings) = AliasOptions::parse(parse_args, &referenced)?;
    warn_if_shadowed(&name);
    for warning in &warnings {
        worktrunk::styling::eprintln!("{}", worktrunk::styling::warning_message(warning));
    }

    let wt = repo.current_worktree();
    let wt_path = wt.root().context("Failed to get worktree root")?;
    let branch = wt.branch().ok().flatten();
    let ctx = CommandContext::new(&repo, user_config, branch.as_deref(), &wt_path, false);
    let extra_refs: Vec<(&str, &str)> = opts
        .vars
        .iter()
        .map(|(k, v)| (k.as_str(), v.as_str()))
        .collect();
    let mut context_map = build_hook_context(&ctx, &extra_refs, VarScope::All)?;
    context_map.insert(
        ALIAS_ARGS_KEY,
        serde_json::to_string(&opts.positional_args)
            .expect("Vec<String> serialization should never fail"),
    );

    let routing = format_routing_summary(&opts);

    for (cfg, source) in &entries {
        let bodies: Vec<String> = cfg
            .commands()
            .map(|c| render_template_preview(&c.template, &context_map, &repo, &name))
            .collect::<anyhow::Result<_>>()?;
        println!(
            "{}",
            format_entry_with_routing(
                &name,
                cfg,
                *source,
                &bodies,
                Some("would run"),
                routing.as_deref()
            )
        );
    }
    Ok(())
}

/// Summarize how each CLI token routed, as `# ` comment lines suitable for the
/// top of a dry-run body. Returns `None` when nothing would have been bound or
/// forwarded — the common no-args case stays clean.
fn format_routing_summary(opts: &AliasOptions) -> Option<String> {
    if opts.vars.is_empty() && opts.positional_args.is_empty() {
        return None;
    }
    let mut lines = String::new();
    if !opts.vars.is_empty() {
        let bound = opts
            .vars
            .iter()
            .map(|(k, v)| format!("{k}={}", shell_escape::unix::escape(v.into())))
            .collect::<Vec<_>>()
            .join(", ");
        lines.push_str(&format!("# bound: {bound}\n"));
    }
    if !opts.positional_args.is_empty() {
        let args = opts
            .positional_args
            .iter()
            .map(|a| shell_escape::unix::escape(a.into()).into_owned())
            .collect::<Vec<_>>()
            .join(" ");
        lines.push_str(&format!("# args: {args}\n"));
    }
    Some(lines)
}

/// Resolve `name` against user + project config, preserving runtime execution
/// order (user first, then project).
fn entries_for_name(
    repo: &Repository,
    user_config: &UserConfig,
    project_config: Option<&ProjectConfig>,
    name: &str,
) -> Vec<(CommandConfig, HookSource)> {
    let project_id = repo.project_identifier().ok();
    let mut entries = Vec::new();
    if let Some(cfg) = user_config.aliases(project_id.as_ref()).get(name) {
        entries.push((cfg.clone(), HookSource::User));
    }
    if let Some(pc) = project_config
        && let Some(cfg) = pc.aliases.get(name)
    {
        entries.push((cfg.clone(), HookSource::Project));
    }
    entries
}

/// Print an "unrecognized alias 'X'" error matching clap's `InvalidSubcommand`
/// layout — same `error:` / `tip:` / `Usage:` block and exit code 2 as
/// `wt <typo>` and `wt step <typo>`. `sub` is `"show"` or `"dry-run"`,
/// anchoring the error on the real clap subcommand so the Usage line reads
/// `Usage: wt config alias <sub> <NAME>`.
///
/// Built as a real `clap::Error` with `ErrorKind::InvalidSubcommand`, rendered
/// by clap, then string-substituted to say "alias" instead of "subcommand" —
/// the positional is an alias name, not a subcommand, so the tighter wording
/// reads more honestly at this surface. Going through clap's rendering gets
/// NO_COLOR / TTY detection, singular-vs-plural "similar" phrasing, and
/// styling correct automatically; modifying the final string is cheaper than
/// reimplementing those.
///
/// Substitutions are scoped to clap's fixed phrases, never the bare word
/// "subcommand" — otherwise an alias or typo containing the literal string
/// `subcommand` (e.g. `my-subcommand`) would be mangled when echoed into
/// the error. Plural `subcommands` is rewritten before singular `subcommand`
/// because `"similar subcommand"` is a prefix of `"similar subcommands"`.
///
/// Returns `AlreadyDisplayed { exit_code: 2 }` rather than calling
/// `process::exit`, so `main`'s `finish_command` still runs `terminate_output`
/// (ANSI reset for shell integration) and `diagnostic::write_if_verbose`.
fn unknown_alias_error(name: &str, sub: &str, aliases: BTreeSet<String>) -> anyhow::Error {
    let suggestions = did_you_mean(name, aliases);

    let mut top = crate::cli::build_command();
    let sub_cmd = top
        .find_subcommand_mut("config")
        .expect("`config` subcommand is defined in the CLI")
        .find_subcommand_mut("alias")
        .expect("`config alias` subcommand is defined in the CLI")
        .find_subcommand_mut(sub)
        .unwrap_or_else(|| panic!("`config alias {sub}` subcommand is defined in the CLI"));
    // `render_usage` needs `bin_name`; clap only sets it on match, so when we
    // synthesize the error ahead of that, set it to the display_name
    // `apply_help_template_recursive` would apply.
    sub_cmd.set_bin_name(format!("wt config alias {sub}"));
    let err = build_invalid_subcommand_error(sub_cmd, name, suggestions);

    let rewritten = err
        .render()
        .ansi()
        .to_string()
        .replace("unrecognized subcommand", "unrecognized alias")
        .replace("similar subcommands", "similar aliases")
        .replace("similar subcommand", "similar alias");

    eprint!("{rewritten}");
    WorktrunkError::AlreadyDisplayed { exit_code: 2 }.into()
}

/// Format one alias entry: `○ Alias <name> (<source>)[ <verb>]:` header
/// followed by a single gutter block of the command bodies. Each named step
/// gets a `# <name>` comment line above its body; anonymous steps render the
/// body alone. Joining into one block matches the old `--dry-run` layout and
/// keeps `show`/`dry-run` visually aligned — the only difference is the verb.
fn format_entry(
    name: &str,
    cfg: &CommandConfig,
    source: HookSource,
    bodies: &[String],
    verb: Option<&str>,
) -> String {
    format_entry_with_routing(name, cfg, source, bodies, verb, None)
}

/// As `format_entry`, with optional routing comment lines prepended to the
/// body. Used by `dry-run` to surface `--KEY` bindings and forwarded args.
fn format_entry_with_routing(
    name: &str,
    cfg: &CommandConfig,
    source: HookSource,
    bodies: &[String],
    verb: Option<&str>,
    routing: Option<&str>,
) -> String {
    let suffix = match verb {
        Some(v) => format!(" {v}:"),
        None => ":".to_string(),
    };
    let mut body = String::new();
    if let Some(routing) = routing {
        body.push_str(routing);
    }
    for (cmd, rendered) in cfg.commands().zip(bodies) {
        if !body.is_empty() && !body.ends_with('\n') {
            body.push('\n');
        }
        if let Some(step_name) = &cmd.name {
            body.push_str(&format!("# {step_name}\n"));
        }
        body.push_str(rendered);
    }
    info_message(cformat!(
        "Alias <bold>{name}</> ({source}){suffix}\n{}",
        format_bash_with_gutter(&body)
    ))
    .to_string()
}

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

    fn cfg_from_toml(toml_str: &str) -> CommandConfig {
        #[derive(serde::Deserialize)]
        struct Wrap {
            cmd: CommandConfig,
        }
        toml::from_str::<Wrap>(toml_str).unwrap().cmd
    }

    #[test]
    fn test_format_entry_show_single() {
        let cfg = cfg_from_toml(r#"cmd = "echo {{ branch }}""#);
        let bodies: Vec<String> = cfg.commands().map(|c| c.template.clone()).collect();
        let out = format_entry("greet", &cfg, HookSource::User, &bodies, None);
        insta::assert_snapshot!(out.ansi_strip());
    }

    #[test]
    fn test_format_entry_show_pipeline() {
        let cfg = cfg_from_toml(
            r#"
cmd = [
    { install = "npm install" },
    { build = "npm run build", lint = "npm run lint" },
]
"#,
        );
        let bodies: Vec<String> = cfg.commands().map(|c| c.template.clone()).collect();
        let out = format_entry("deploy", &cfg, HookSource::Project, &bodies, None);
        insta::assert_snapshot!(out.ansi_strip());
    }

    #[test]
    fn test_format_entry_dry_run_pipeline() {
        // The verb only changes the header suffix — body layout is identical.
        let cfg = cfg_from_toml(
            r#"
cmd = [
    { install = "npm install" },
    { build = "npm run build", lint = "npm run lint" },
]
"#,
        );
        let bodies: Vec<String> = cfg.commands().map(|c| c.template.clone()).collect();
        let out = format_entry(
            "deploy",
            &cfg,
            HookSource::Project,
            &bodies,
            Some("would run"),
        );
        insta::assert_snapshot!(out.ansi_strip());
    }
}