Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Smart routing for alias arguments + dry-run routing display (#2304)
Maximilian Roos68229ce57199
diff --git a/docs/content/extending.md b/docs/content/extending.mdindex fe1a6ab66..a495dac9b 100644--- a/docs/content/extending.md+++ b/docs/content/extending.md@@ -108,85 +108,52 @@ See [Tips & Patterns](@/tips-patterns.md) for more recipes: dev server per workt## Aliases-Aliases are custom commands invoked as `wt <name>`. They share the same template variables and approval model as hooks.+`[aliases]` defines commands invoked as `wt <name>`. Templates and approvals behave like hooks.```toml[aliases]-deploy = "make deploy BRANCH={{ branch }} ENV={{ env }}"+deploy = "fly deploy --config=fly.{{ env }}.toml --app=myapp-{{ branch }}"open = "open http://localhost:{{ branch | hash_port }}"+since-main = "git log --oneline {{ default_branch }}..HEAD"```-{{ terminal(cmd="wt deploy|||wt deploy --env=staging") }}+{{ terminal(cmd="wt deploy --env=staging|||wt open") }}-`wt deploy` resolves `deploy` against configured aliases first, then falls through to a `wt-deploy` PATH binary if no alias matches. Built-in subcommands always take precedence — an alias named `list` or `switch` is unreachable.+`wt <name>` resolves to a built-in first, then an alias, then a [custom subcommand](#custom-subcommands).-### How arguments are routed+### Passing values-Tokens after the alias name fall into one of these buckets, decided by what the alias's template references:+`--KEY=VALUE` (or `--KEY VALUE`) binds `KEY` whenever `{{ KEY }}` appears in the template — `wt deploy --env=staging` sets `{{ env }}` to `staging`. Everything else joins `{{ args }}` (see [Forwarding](#forwarding-positional-arguments)).-| Token shape | Routes to |-|---|---|-| `--KEY=VALUE` or `--KEY VALUE` where the template references `{{ KEY }}` | Bound — `KEY` becomes the template value |-| `--KEY=VALUE` where the template doesn't reference `KEY` | Forwarded literally to `{{ args }}` |-| `--KEY` followed by another flag or end of args | Forwarded literally to `{{ args }}` |-| Bare positional (no `--` prefix) | Forwarded to `{{ args }}` |-| Anything after a literal `--` | Forwarded to `{{ args }}` regardless of shape |+Built-in variables can be overridden: `--branch=foo` sets `{{ branch }}` inside the template — the worktree's actual branch doesn't move.-Built-in template variables (`branch`, `worktree_path`, `commit`, …) can be overridden — `--branch=override` for an alias referencing `{{ branch }}` binds to the user's value, but only inside the template; the worktree's actual branch is unchanged.--Hyphens in variable names are canonicalized to underscores at parse time. `--my-var=value` binds to `{{ my_var }}` because minijinja parses `{{ my-var }}` as subtraction.--### Escaping with `--`--Use `--` to forward a flag-shaped value literally instead of letting the parser bind it. Everything after `--` goes into `{{ args }}` verbatim:--```toml-[aliases]-search = "rg {{ args }}"-```--{{ terminal(cmd="wt search -- --hidden --glob '*.rs' pattern # --hidden and --glob reach rg, not the alias parser") }}--### Inspecting and previewing--Two subcommands introspect aliases without running them:--- `wt config alias show <name>` prints the configured template text, tagged by source (`user`/`project`).-- `wt config alias dry-run <name> [-- args...]` parses the invocation with the same parser `wt <name>` uses, then prints the rendered command without executing.--{{ terminal(cmd="wt config alias show deploy|||wt config alias dry-run deploy|||wt config alias dry-run deploy -- --env=staging") }}--Arguments after `--` in `dry-run` are forwarded verbatim — `wt config alias dry-run s -- target-branch` previews exactly what `wt s target-branch` would run. Templates referencing `vars.*` are shown unexpanded, mirroring execution semantics: those values are read from git config just before each step runs.+Hyphens in keys become underscores: `--my-var=x` sets `{{ my_var }}`.### Forwarding positional arguments-Non-flag tokens after the alias name are forwarded to the template as `{{ args }}`. Bare `{{ args }}` renders as a space-joined, shell-escaped string ready to append to a command line — so `wt s some-branch` with `s = "wt switch {{ args }}"` expands to `wt switch some-branch`.+`{{ args }}` renders as a space-joined, shell-escaped string — ready to splice into a command:```toml[aliases]s = "wt switch {{ args }}"```-{{ terminal(cmd="wt s some-branch|||wt s feature/api # multiple tokens pass through in order|||wt s 'has a space' # spaces and metacharacters are escaped safely") }}+{{ terminal(cmd="wt s some-branch|||wt s feature/api|||wt s 'has a space'") }}-Access elements with `{{ args[0] }}`, iterate with `{% for a in args %}…{% endfor %}`, or count with `{{ args | length }}`. Each element is individually shell-escaped, so `wt run 'a b' 'c;d'` splices in as `'a b' 'c;d'` without shell injection.+Index with `{{ args[0] }}`, loop with `{% for a in args %}…{% endfor %}`, count with `{{ args | length }}`. Each element is escaped individually, so `wt run 'a b' 'c;d'` renders as `'a b' 'c;d'` — no shell injection.-An `up` alias that fetches all remotes and rebases each worktree onto its upstream:+Tokens after `--` forward unconditionally, bypassing any binding. `wt deploy -- --branch=foo` forwards `--branch=foo` to `{{ args }}` even though the template references `{{ branch }}`.-```toml-[aliases]-up = '''-git fetch --all --prune && wt step for-each -- '- git rev-parse --verify @{u} >/dev/null 2>&1 || exit 0- g=$(git rev-parse --git-dir)- test -d "$g/rebase-merge" -o -d "$g/rebase-apply" && exit 0- git rebase @{u} --no-autostash || git rebase --abort-''''-```+### Inspecting and previewing++- `wt config alias show <name>` prints the template.+- `wt config alias dry-run <name> [-- args...]` prints the rendered command.++{{ terminal(cmd="wt config alias show deploy|||wt config alias dry-run deploy|||wt config alias dry-run deploy -- --env=staging") }}### Multi-step pipelines-Multi-step aliases run commands in order using `[[aliases.NAME]]` blocks. Each block is one step; multiple keys within a block run concurrently.+`[[aliases.NAME]]` defines a pipeline. Each block runs serially; keys within a block run concurrently.```toml[[aliases.release]]@@ -197,16 +164,31 @@ build = "cargo build --release"package = "cargo package --no-verify"[[aliases.release]]-publish = "cargo publish"+publish = "cargo publish {{ args }}"```-`test` runs first, then `build` and `package` run together, then `publish` runs last. A step failure aborts the remaining steps.+`test` runs first, then `build` and `package` run together, then `publish` runs last. A step failure aborts the remaining steps. Every step sees the same `{{ args }}` and bound variables — `wt release -- --dry-run` forwards `--dry-run` to `publish` without affecting earlier steps.### Sources and approvalWhen both user and project config define the same alias name, both run — user first, then project. Project-config aliases require approval on first run, same as project hooks. User-config aliases are trusted.-Inside an alias body, an inner `wt switch` (or `wt switch --create`) passes its `cd` through to the parent shell, so an alias wrapping `wt switch --create` lands the shell in the new worktree just like running it directly.+An alias that calls `wt switch` (or `wt switch --create`) changes the parent shell's directory, just like running `wt switch` directly.++### Recipe: rebase every worktree onto its upstream++```toml+[aliases]+up = '''+git fetch --all --prune && wt step for-each -- '+ git rev-parse --verify @{u} >/dev/null 2>&1 || exit 0+ g=$(git rev-parse --git-dir)+ test -d "$g/rebase-merge" -o -d "$g/rebase-apply" && exit 0+ git rebase @{u} --no-autostash || git rebase --abort+''''+```++`wt up` fetches all remotes, then iterates every worktree: skip if no upstream, skip if mid-rebase, otherwise rebase and auto-abort on conflict.### Recipe: move or copy in-progress changes to a new worktreediff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.mdindex 446c4db46..37d11df61 100644--- a/skills/worktrunk/reference/extending.md+++ b/skills/worktrunk/reference/extending.md@@ -101,56 +101,53 @@ See [Tips & Patterns](https://worktrunk.dev/tips-patterns/) for more recipes: de## Aliases-Aliases are custom commands invoked as `wt <name>`. They share the same template variables and approval model as hooks.+`[aliases]` defines commands invoked as `wt <name>`. Templates and approvals behave like hooks.```toml[aliases]-deploy = "make deploy BRANCH={{ branch }} ENV={{ env }}"+deploy = "fly deploy --config=fly.{{ env }}.toml --app=myapp-{{ branch }}"open = "open http://localhost:{{ branch | hash_port }}"+since-main = "git log --oneline {{ default_branch }}..HEAD"``````bash-wt deploywt deploy --env=staging+wt open```-`wt deploy` resolves `deploy` against configured aliases first, then falls through to a `wt-deploy` PATH binary if no alias matches. Built-in subcommands always take precedence — an alias named `list` or `switch` is unreachable.+`wt <name>` resolves to a built-in first, then an alias, then a [custom subcommand](#custom-subcommands).-### How arguments are routed+### Passing values-Tokens after the alias name fall into one of these buckets, decided by what the alias's template references:+`--KEY=VALUE` (or `--KEY VALUE`) binds `KEY` whenever `{{ KEY }}` appears in the template — `wt deploy --env=staging` sets `{{ env }}` to `staging`. Everything else joins `{{ args }}` (see [Forwarding](#forwarding-positional-arguments)).-| Token shape | Routes to |-|---|---|-| `--KEY=VALUE` or `--KEY VALUE` where the template references `{{ KEY }}` | Bound — `KEY` becomes the template value |-| `--KEY=VALUE` where the template doesn't reference `KEY` | Forwarded literally to `{{ args }}` |-| `--KEY` followed by another flag or end of args | Forwarded literally to `{{ args }}` |-| Bare positional (no `--` prefix) | Forwarded to `{{ args }}` |-| Anything after a literal `--` | Forwarded to `{{ args }}` regardless of shape |+Built-in variables can be overridden: `--branch=foo` sets `{{ branch }}` inside the template — the worktree's actual branch doesn't move.-Built-in template variables (`branch`, `worktree_path`, `commit`, …) can be overridden — `--branch=override` for an alias referencing `{{ branch }}` binds to the user's value, but only inside the template; the worktree's actual branch is unchanged.+Hyphens in keys become underscores: `--my-var=x` sets `{{ my_var }}`.-Hyphens in variable names are canonicalized to underscores at parse time. `--my-var=value` binds to `{{ my_var }}` because minijinja parses `{{ my-var }}` as subtraction.--### Escaping with `--`+### Forwarding positional arguments-Use `--` to forward a flag-shaped value literally instead of letting the parser bind it. Everything after `--` goes into `{{ args }}` verbatim:+`{{ args }}` renders as a space-joined, shell-escaped string — ready to splice into a command:```toml[aliases]-search = "rg {{ args }}"+s = "wt switch {{ args }}"``````bash-wt search -- --hidden --glob '*.rs' pattern # --hidden and --glob reach rg, not the alias parser+wt s some-branch+wt s feature/api+wt s 'has a space'```-### Inspecting and previewing+Index with `{{ args[0] }}`, loop with `{% for a in args %}…{% endfor %}`, count with `{{ args | length }}`. Each element is escaped individually, so `wt run 'a b' 'c;d'` renders as `'a b' 'c;d'` — no shell injection.++Tokens after `--` forward unconditionally, bypassing any binding. `wt deploy -- --branch=foo` forwards `--branch=foo` to `{{ args }}` even though the template references `{{ branch }}`.-Two subcommands introspect aliases without running them:+### Inspecting and previewing-- `wt config alias show <name>` prints the configured template text, tagged by source (`user`/`project`).-- `wt config alias dry-run <name> [-- args...]` parses the invocation with the same parser `wt <name>` uses, then prints the rendered command without executing.+- `wt config alias show <name>` prints the template.+- `wt config alias dry-run <name> [-- args...]` prints the rendered command.```bashwt config alias show deploy@@ -158,41 +155,9 @@ wt config alias dry-run deploywt config alias dry-run deploy -- --env=staging```-Arguments after `--` in `dry-run` are forwarded verbatim — `wt config alias dry-run s -- target-branch` previews exactly what `wt s target-branch` would run. Templates referencing `vars.*` are shown unexpanded, mirroring execution semantics: those values are read from git config just before each step runs.--### Forwarding positional arguments--Non-flag tokens after the alias name are forwarded to the template as `{{ args }}`. Bare `{{ args }}` renders as a space-joined, shell-escaped string ready to append to a command line — so `wt s some-branch` with `s = "wt switch {{ args }}"` expands to `wt switch some-branch`.--```toml-[aliases]-s = "wt switch {{ args }}"-```--```bash-wt s some-branch-wt s feature/api # multiple tokens pass through in order-wt s 'has a space' # spaces and metacharacters are escaped safely-```--Access elements with `{{ args[0] }}`, iterate with `{% for a in args %}…{% endfor %}`, or count with `{{ args | length }}`. Each element is individually shell-escaped, so `wt run 'a b' 'c;d'` splices in as `'a b' 'c;d'` without shell injection.--An `up` alias that fetches all remotes and rebases each worktree onto its upstream:--```toml-[aliases]-up = '''-git fetch --all --prune && wt step for-each -- '- git rev-parse --verify @{u} >/dev/null 2>&1 || exit 0- g=$(git rev-parse --git-dir)- test -d "$g/rebase-merge" -o -d "$g/rebase-apply" && exit 0- git rebase @{u} --no-autostash || git rebase --abort-''''-```-### Multi-step pipelines-Multi-step aliases run commands in order using `[[aliases.NAME]]` blocks. Each block is one step; multiple keys within a block run concurrently.+`[[aliases.NAME]]` defines a pipeline. Each block runs serially; keys within a block run concurrently.```toml[[aliases.release]]@@ -203,16 +168,31 @@ build = "cargo build --release"package = "cargo package --no-verify"[[aliases.release]]-publish = "cargo publish"+publish = "cargo publish {{ args }}"```-`test` runs first, then `build` and `package` run together, then `publish` runs last. A step failure aborts the remaining steps.+`test` runs first, then `build` and `package` run together, then `publish` runs last. A step failure aborts the remaining steps. Every step sees the same `{{ args }}` and bound variables — `wt release -- --dry-run` forwards `--dry-run` to `publish` without affecting earlier steps.### Sources and approvalWhen both user and project config define the same alias name, both run — user first, then project. Project-config aliases require approval on first run, same as project hooks. User-config aliases are trusted.-Inside an alias body, an inner `wt switch` (or `wt switch --create`) passes its `cd` through to the parent shell, so an alias wrapping `wt switch --create` lands the shell in the new worktree just like running it directly.+An alias that calls `wt switch` (or `wt switch --create`) changes the parent shell's directory, just like running `wt switch` directly.++### Recipe: rebase every worktree onto its upstream++```toml+[aliases]+up = '''+git fetch --all --prune && wt step for-each -- '+ git rev-parse --verify @{u} >/dev/null 2>&1 || exit 0+ g=$(git rev-parse --git-dir)+ test -d "$g/rebase-merge" -o -d "$g/rebase-apply" && exit 0+ git rebase @{u} --no-autostash || git rebase --abort+''''+```++`wt up` fetches all remotes, then iterates every worktree: skip if no upstream, skip if mid-rebase, otherwise rebase and auto-abort on conflict.### Recipe: move or copy in-progress changes to a new worktreediff --git a/src/cli/config.rs b/src/cli/config.rsindex ceba5b6c6..73ebe52c4 100644--- a/src/cli/config.rs+++ b/src/cli/config.rs@@ -330,7 +330,7 @@ $ wt config alias show deploy/// Preview an alias invocation with template expansion#[command(- after_long_help = r#"Runs the same parser used at invocation time, applies template expansion (including `{{ args }}` and any `--var`/`--KEY=VALUE` assignments), and prints the resulting command without executing it. Templates referencing `vars.*` are shown unexpanded — those values resolve from git config at execution time, after earlier steps have had a chance to set them.+ after_long_help = r#"Runs the same parser used at invocation time, applies template expansion (including `{{ args }}` and any `--KEY=VALUE` assignments), and prints the resulting command without executing it. Templates referencing `vars.*` are shown unexpanded — those values resolve from git config at execution time, after earlier steps have had a chance to set them.Arguments after `--` are forwarded verbatim as if typed after `wt <name>`.diff --git a/src/cli/hook.rs b/src/cli/hook.rsindex 549ff4df1..bf75c849f 100644--- a/src/cli/hook.rs+++ b/src/cli/hook.rs@@ -37,8 +37,10 @@ const KNOWN_HOOK_LONG_FLAGS: &[&str] = &[];/// Rewrite `wt hook <type> --KEY=VALUE` into `wt hook <type> --var KEY=VALUE`-/// for unknown `--key=value` flags, matching the ergonomics of the alias-/// variable shorthand (see `AliasOptions::parse`).+/// for unknown `--key=value` flags, so hook invocations can use the same+/// `--KEY=VALUE` shorthand that `wt <alias>` supports. (Aliases route via+/// template references; hooks have no such discriminator, so the rewrite+/// here is an unconditional "unknown `--KEY=VALUE` means var".)////// Only args after a `hook <type>` prefix are touched, and only when `<type>`/// is a hook that accepts `--var`.diff --git a/src/commands/alias.rs b/src/commands/alias.rsindex ebf1f5788..e2833dafc 100644--- a/src/commands/alias.rs+++ b/src/commands/alias.rs@@ -40,7 +40,7 @@ use worktrunk::config::{referenced_vars_for_config,};use worktrunk::git::Repository;-use worktrunk::styling::{eprintln, progress_message};+use worktrunk::styling::{eprintln, println, progress_message, warning_message};use crate::commands::command_approval::approve_alias_commands;use crate::commands::command_executor::{@@ -72,19 +72,49 @@ const BUILTIN_STEP_COMMANDS: &[&str] = &[/// alias dispatch sees the name, so `wt list` always runs the built-in even/// if `[aliases] list = …` is configured. Kept in sync with `Cli` via/// `test_top_level_builtins_match_clap`.-const TOP_LEVEL_BUILTINS: &[&str] = &[+pub(crate) const TOP_LEVEL_BUILTINS: &[&str] = &["config", "hook", "list", "merge", "remove", "select", "step", "switch",];+/// Whether `--help` or `-h` appears in `args` before any `--` literal-forward+/// terminator. Aliases have no clap-style help page — the template *is* the+/// help — so dispatchers intercept help requests and redirect the user to+/// `wt config alias show / dry-run`. After `--`, all tokens forward to+/// `{{ args }}` verbatim, so `wt <alias> -- --help` bypasses the intercept.+fn help_flag_requested(args: &[String]) -> bool {+ for arg in args {+ if arg == "--" {+ return false;+ }+ if arg == "--help" || arg == "-h" {+ return true;+ }+ }+ false+}++/// Print guidance when `wt <alias> --help` is invoked. Points at the canonical+/// inspection path and documents the `--` escape for forwarding `--help` into+/// the alias body.+fn emit_alias_help_hint(name: &str) {+ println!(+ "`{name}` is an alias. Inspect with:+ wt config alias show {name}+ wt config alias dry-run {name}+Forward `--help` to the alias body with `wt {name} -- --help`."+ );+}+/// Options parsed from alias-dispatch args (`wt step <alias>` or `wt <alias>`).#[derive(Debug)]pub struct AliasOptions {pub name: String,pub vars: Vec<(String, String)>,- /// Non-flag positional tokens passed after the alias name. Forwarded into- /// the template context as `{{ args }}` (a `ShellArgs` sequence). Appear- /// in CLI order, interleaving freely with flags: `wt s foo --env=prod bar`- /// collects `["foo", "bar"]`.+ /// Tokens forwarded to the template as `{{ args }}` (a `ShellArgs`+ /// sequence). Contains plain positionals, `--KEY=VALUE` / `--KEY` tokens+ /// whose key isn't referenced by the template, and everything after `--`.+ /// Appears in CLI order: `wt s foo --env=prod bar` with no `{{ env }}`+ /// reference collects `["foo", "--env=prod", "bar"]`.pub positional_args: Vec<String>,}@@ -98,14 +128,14 @@ impl AliasOptions {////// - `--` — literal-forward escape: every later token goes straight into/// `positional_args`, no var binding.- /// - `--KEY=VALUE` — binds `KEY=VALUE` if `KEY` is in `referenced_vars`,- /// otherwise forwards the whole `--KEY=VALUE` token as a positional.- /// - `--KEY VALUE` (separated by space, `VALUE` doesn't start with `--`)- /// — binds `KEY=VALUE` if `KEY` is in `referenced_vars`, otherwise- /// forwards `--KEY` as a positional and re-examines `VALUE` at its- /// normal position.- /// - `--KEY` followed by another `--…` (or end of args) — forwards- /// `--KEY` as a positional.+ /// - `--KEY=VALUE` or `--KEY VALUE` — binds `KEY=VALUE` if `KEY` is in+ /// `referenced_vars`, otherwise forwards both parts as positionals. The+ /// space form consumes the next token as the value unconditionally —+ /// even when it starts with `--` — so `--env --other` with `env`+ /// referenced binds `env=--other`. Use the `=` form or put flags+ /// before the bound key to avoid this.+ /// - `--KEY` at end of args — forwards `--KEY` as a positional. No next+ /// token to consume./// - Anything else — forwards as a positional.////// `--yes`/`-y` is a top-level global flag (`wt -y <alias>`); the@@ -129,13 +159,20 @@ impl AliasOptions {/// `referenced_vars` is expected to contain the canonical underscore/// form. `referenced_vars_for_config` produces it directly from the/// alias's template.- pub fn parse(args: Vec<String>, referenced_vars: &BTreeSet<String>) -> anyhow::Result<Self> {+ ///+ /// Returns `(options, warnings)`. Warnings are advisory — callers emit+ /// them; the parser stays pure so tests can inspect both halves.+ pub fn parse(+ args: Vec<String>,+ referenced_vars: &BTreeSet<String>,+ ) -> anyhow::Result<(Self, Vec<String>)> {let Some(name) = args.first().cloned() else {bail!("Missing alias name");};let mut vars = Vec::new();let mut positional_args = Vec::new();+ let mut warnings = Vec::new();let mut literal_mode = false;let mut i = 1;while i < args.len() {@@ -169,17 +206,32 @@ impl AliasOptions {i += 1;continue;}+ // Bare `--KEY`: mirror the atomic `--KEY=VALUE` form. When a+ // next token exists, consume both regardless of its shape —+ // bind if KEY is referenced, else forward both as positionals.+ // At end of args, forward `--KEY` alone.let canon = rest.replace('-', "_");- if let Some(next) = args.get(i + 1)- && !next.starts_with("--")- && referenced_vars.contains(&canon)- {- vars.push((canon, next.clone()));+ if let Some(next) = args.get(i + 1) {+ if referenced_vars.contains(&canon) {+ // Warn on the footgun case: `--KEY --VALUE` with KEY+ // referenced binds VALUE as the value. Almost always+ // a typo — the user probably meant `--KEY=--VALUE`.+ // Show the user's typed form (hyphenated) throughout;+ // the template binding (underscored) is internal.+ // Mirrors the `--var` TODO in hook_commands.rs.+ if next.starts_with("--") {+ warnings.push(format!(+ "`--{rest} {next}` bound `{rest}` to `{next}` — use `--{rest}={next}` if that was intended"+ ));+ }+ vars.push((canon, next.clone()));+ } else {+ positional_args.push(arg.clone());+ positional_args.push(next.clone());+ }i += 2;continue;}- // No bindable destination: forward the flag token as positional;- // the next token is re-examined at its normal position.positional_args.push(arg.clone());i += 1;continue;@@ -188,11 +240,14 @@ impl AliasOptions {i += 1;}- Ok(Self {- name,- vars,- positional_args,- })+ Ok((+ Self {+ name,+ vars,+ positional_args,+ },+ warnings,+ ))}}@@ -316,11 +371,28 @@ pub fn try_alias(name: String, rest: Vec<String>, global_yes: bool) -> anyhow::Rreturn Ok(None);};let referenced = referenced_vars_for_config(cmd_config)?;+ // Aliases can bind a `help` variable; only intercept `--help` when the+ // template doesn't reference it. `-h` is never a binding, so it's always+ // safe to intercept. Conservatively: intercept if any help flag appears+ // and no binding is claimed on `help`.+ if !referenced.contains("help") && help_flag_requested(&rest) {+ emit_alias_help_hint(&name);+ return Ok(Some(()));+ }let mut alias_args = Vec::with_capacity(1 + rest.len());alias_args.push(name);alias_args.extend(rest);- let opts = AliasOptions::parse(alias_args, &referenced)?;- run_alias(opts, repo, user_config, project_config, aliases, global_yes).map(Some)+ let (opts, warnings) = AliasOptions::parse(alias_args, &referenced)?;+ run_alias(+ opts,+ warnings,+ repo,+ user_config,+ project_config,+ aliases,+ global_yes,+ )+ .map(Some)}/// Run a configured alias from `wt step <name>`. Errors with a clap-style@@ -333,6 +405,11 @@ pub fn try_alias(name: String, rest: Vec<String>, global_yes: bool) -> anyhow::R////// `global_yes` is the top-level `--yes`/`-y` flag, passed through to/// `run_alias`.+///+/// TODO: consider deprecating `wt step <alias>` in favor of top-level+/// `wt <alias>` (and `wt config alias show/dry-run` for inspection). The step+/// path exists today as the escape for shadowed names, but that could instead+/// be handled with a dedicated error hint.pub fn step_alias(args: Vec<String>, global_yes: bool) -> anyhow::Result<()> {let repo = Repository::current()?;let user_config = UserConfig::load()?;@@ -356,8 +433,20 @@ pub fn step_alias(args: Vec<String>, global_yes: bool) -> anyhow::Result<()> {unknown_step_command_exit(&name, &alias_names);};let referenced = referenced_vars_for_config(cmd_config)?;- let opts = AliasOptions::parse(args, &referenced)?;- run_alias(opts, repo, user_config, project_config, aliases, global_yes)+ if !referenced.contains("help") && help_flag_requested(&args[1..]) {+ emit_alias_help_hint(&name);+ return Ok(());+ }+ let (opts, warnings) = AliasOptions::parse(args, &referenced)?;+ run_alias(+ opts,+ warnings,+ repo,+ user_config,+ project_config,+ aliases,+ global_yes,+ )}/// Return alias names for use as suggestions when a top-level subcommand is@@ -388,6 +477,7 @@ pub fn alias_names_for_suggestions() -> Vec<String> {/// recognized. Use `wt -y deploy` or `wt --yes deploy` instead.fn run_alias(opts: AliasOptions,+ warnings: Vec<String>,repo: Repository,user_config: UserConfig,project_config: Option<ProjectConfig>,@@ -398,6 +488,12 @@ fn run_alias(.get(&opts.name).expect("caller verified alias is configured");+ // Surface parser advisories (e.g. `--KEY --VALUE` footgun) before+ // announcing the run so they're visible in execution output.+ for warning in &warnings {+ eprintln!("{}", warning_message(warning));+ }+// Check if this alias needs project-config approval. project_id is required// for approval — re-derive with error propagation rather than relying on// `.ok()`. `global_yes` is the sole source for skipping approval now that@@ -724,7 +820,17 @@ mod tests {/// Parse with an explicit `referenced_vars` set. Tests build the set/// directly to exercise routing without needing a full template fixture.+ /// Drops warnings — see `parse_with_warnings` to inspect them.fn parse_with(args: &[&str], referenced: &[&str]) -> anyhow::Result<AliasOptions> {+ parse_with_warnings(args, referenced).map(|(opts, _)| opts)+ }++ /// Like `parse_with` but also returns the warning vector, for tests that+ /// assert on advisory output.+ fn parse_with_warnings(+ args: &[&str],+ referenced: &[&str],+ ) -> anyhow::Result<(AliasOptions, Vec<String>)> {let refs: BTreeSet<String> = referenced.iter().map(|s| s.to_string()).collect();AliasOptions::parse(args.iter().map(|s| s.to_string()).collect(), &refs)}@@ -858,6 +964,20 @@ cmd = [positional_args: [],}"#);+ // Pathological: multiple `=` in value. `split_once('=')` only splits on+ // the first, so everything past the first `=` is the value.+ assert_debug_snapshot!(parse_with(&["deploy", "--foo=a=b=c"], &["foo"]).unwrap(), @r#"+ AliasOptions {+ name: "deploy",+ vars: [+ (+ "foo",+ "a=b=c",+ ),+ ],+ positional_args: [],+ }+ "#);// Empty value accepted on bind.assert_debug_snapshot!(parse_with(&["deploy", "--env="], &["env"]).unwrap(), @r#"AliasOptions {@@ -886,7 +1006,7 @@ cmd = [#[test]fn test_parse_space_separated_routing() {use insta::assert_debug_snapshot;- // --KEY VALUE binds when KEY is referenced and VALUE is non-flag.+ // --KEY VALUE binds when KEY is referenced.assert_debug_snapshot!(parse_with(&["deploy", "--env", "staging"], &["env"]).unwrap(), @r#"AliasOptions {name: "deploy",@@ -910,9 +1030,25 @@ cmd = [],}"#);- // --KEY followed by another --flag: --KEY forwards alone, the next- // flag is processed at its normal position.+ // --KEY --other with KEY referenced: the space form consumes the next+ // token unconditionally, so `--other` binds as the value of `env`.+ // Use `--env=VALUE` or reorder flags to avoid this.assert_debug_snapshot!(parse_with(&["deploy", "--env", "--other"], &["env"]).unwrap(), @r#"+ AliasOptions {+ name: "deploy",+ vars: [+ (+ "env",+ "--other",+ ),+ ],+ positional_args: [],+ }+ "#);+ // Same shape, unreferenced: both consumed as the pair and forwarded.+ // The next token is not re-examined, so `--other` is not processed+ // independently.+ assert_debug_snapshot!(parse_with(&["deploy", "--env", "--other"], &[]).unwrap(), @r#"AliasOptions {name: "deploy",vars: [],@@ -934,6 +1070,80 @@ cmd = ["#);}+ #[test]+ fn test_parse_warns_on_footgun_space_form() {+ // `--KEY VALUE` binds VALUE even when it's flag-shaped. The parser+ // emits an advisory pointing at `--KEY=VALUE` so the user can+ // disambiguate if the bind was unintended.+ let (_, warnings) = parse_with_warnings(&["deploy", "--env", "--other"], &["env"]).unwrap();+ insta::assert_debug_snapshot!(warnings, @r#"+ [+ "`--env --other` bound `env` to `--other` — use `--env=--other` if that was intended",+ ]+ "#);++ // Unreferenced pair: both tokens forward as positionals — not a+ // binding, so no warning.+ let (_, warnings) = parse_with_warnings(&["deploy", "--env", "--other"], &[]).unwrap();+ assert!(warnings.is_empty());++ // Ordinary bind: warning stays silent.+ let (_, warnings) = parse_with_warnings(&["deploy", "--env", "prod"], &["env"]).unwrap();+ assert!(warnings.is_empty());++ // Hyphenated key: warning shows the user's typed form throughout+ // (`my-env`), not the canonicalized template name (`my_env`).+ let (_, warnings) =+ parse_with_warnings(&["deploy", "--my-env", "--other"], &["my_env"]).unwrap();+ insta::assert_debug_snapshot!(warnings, @r#"+ [+ "`--my-env --other` bound `my-env` to `--other` — use `--my-env=--other` if that was intended",+ ]+ "#);+ }++ #[test]+ fn test_parse_duplicate_key_last_write_wins() {+ use insta::assert_debug_snapshot;+ // Duplicate `--KEY=` bindings are kept in order in the Vec;+ // `build_hook_context` inserts them into a HashMap so the last one+ // wins at expansion time. Parser preserves order so that behavior is+ // testable and deterministic.+ assert_debug_snapshot!(parse_with(&["deploy", "--env=a", "--env=b"], &["env"]).unwrap(), @r#"+ AliasOptions {+ name: "deploy",+ vars: [+ (+ "env",+ "a",+ ),+ (+ "env",+ "b",+ ),+ ],+ positional_args: [],+ }+ "#);+ // Mixed space/equals forms follow the same rule.+ assert_debug_snapshot!(parse_with(&["deploy", "--env", "a", "--env=b"], &["env"]).unwrap(), @r#"+ AliasOptions {+ name: "deploy",+ vars: [+ (+ "env",+ "a",+ ),+ (+ "env",+ "b",+ ),+ ],+ positional_args: [],+ }+ "#);+ }+#[test]fn test_parse_hyphen_canonicalization() {use insta::assert_debug_snapshot;diff --git a/src/commands/config/alias.rs b/src/commands/config/alias.rsindex 4b08721f9..a545bce2a 100644--- a/src/commands/config/alias.rs+++ b/src/commands/config/alias.rs@@ -28,7 +28,7 @@ use worktrunk::config::{use worktrunk::git::Repository;use worktrunk::styling::{format_bash_with_gutter, info_message, println};-use crate::commands::alias::{AliasOptions, AliasSource};+use crate::commands::alias::{AliasOptions, AliasSource, TOP_LEVEL_BUILTINS};use crate::commands::command_executor::{CommandContext, build_hook_context, expand_shell_template,};@@ -53,6 +53,8 @@ pub fn handle_alias_show(name: String) -> anyhow::Result<()> {));}+ warn_if_shadowed(&name);+for (i, (cfg, source)) in entries.iter().enumerate() {if i > 0 {println!();@@ -63,6 +65,22 @@ pub fn handle_alias_show(name: String) -> anyhow::Result<()> {Ok(())}+/// 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 TOP_LEVEL_BUILTINS.contains(&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.///@@ -96,7 +114,11 @@ pub fn handle_alias_dry_run(name: String, args: Vec<String>) -> anyhow::Result<(let mut parse_args = Vec::with_capacity(1 + args.len());parse_args.push(name.clone());parse_args.extend(args);- let opts = AliasOptions::parse(parse_args, &referenced)?;+ 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")?;@@ -114,6 +136,8 @@ pub fn handle_alias_dry_run(name: String, args: Vec<String>) -> anyhow::Result<(.expect("Vec<String> serialization should never fail"),);+ let routing = format_routing_summary(&opts);+for (i, (cfg, source)) in entries.iter().enumerate() {if i > 0 {println!();@@ -124,12 +148,48 @@ pub fn handle_alias_dry_run(name: String, args: Vec<String>) -> anyhow::Result<(.collect::<anyhow::Result<_>>()?;println!("{}",- format_entry(&name, cfg, *source, &bodies, Some("would run"))+ 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)+}+/// Render a single command template for preview. Mirrors execution-time lazy/// semantics — see the module-level docstring.fn render_preview(@@ -208,6 +268,19 @@ fn format_entry(source: AliasSource,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: AliasSource,+ bodies: &[String],+ verb: Option<&str>,+ routing: Option<&str>,) -> String {let label = source.label();let suffix = match verb {@@ -215,8 +288,11 @@ fn format_entry(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() {+ if !body.is_empty() && !body.ends_with('\n') {body.push('\n');}if let Some(step_name) = &cmd.name {diff --git a/src/config/expansion.rs b/src/config/expansion.rsindex c86129bff..574262d6c 100644--- a/src/config/expansion.rs+++ b/src/config/expansion.rs@@ -498,25 +498,32 @@ fn setup_template_env(repo: &Repository) -> Environment<'static> {env}-/// Check if a template references a specific top-level variable.+/// Top-level variables referenced by a single template.////// Uses minijinja's AST analysis rather than string matching, avoiding false-/// positives from literal text like `template_vars.txt`.+/// positives from literal text like `template_vars.txt`. Templates that fail+/// to parse contribute nothing — a syntax error surfaces later at expansion+/// time with a richer message.+fn referenced_vars(template: &str) -> std::collections::HashSet<String> {+ minijinja::Environment::new()+ .template_from_str(template)+ .map(|tmpl| tmpl.undeclared_variables(false))+ .unwrap_or_default()+}++/// Check if a template references a specific top-level variable.pub fn template_references_var(template: &str, var: &str) -> bool {- let env = minijinja::Environment::new();- let Ok(tmpl) = env.template_from_str(template) else {- return false;- };- tmpl.undeclared_variables(false).contains(var)+ referenced_vars(template).contains(var)}-/// Union of top-level variables referenced by every command in a `CommandConfig`.+/// Union of top-level variables referenced across every command in `cfg`.////// Drives alias-arg routing in `AliasOptions::parse`: a `--KEY=VALUE` token/// binds to `{{ KEY }}` only when KEY appears in this set; otherwise it-/// forwards as a positional. A syntax error in any template fails here so the-/// user sees it before flags are routed — a silent skip could mask a typo and-/// silently change how subsequent CLI args bind.+/// forwards as a positional. A var referenced in any step of a pipeline is+/// a binding candidate for the whole invocation. A syntax error in any+/// template fails here so the user sees it before flags are routed — a+/// silent skip could mask a typo and change how subsequent CLI args bind.pub fn referenced_vars_for_config(cfg: &super::CommandConfig) -> anyhow::Result<BTreeSet<String>> {let env = minijinja::Environment::new();let mut out = BTreeSet::new();diff --git a/tests/integration_tests/output_system_guard.rs b/tests/integration_tests/output_system_guard.rsindex 59b65d45e..ba9b1442f 100644--- a/tests/integration_tests/output_system_guard.rs+++ b/tests/integration_tests/output_system_guard.rs@@ -38,6 +38,8 @@ const STDOUT_ALLOWED_PATHS: &[&str] = &["config/hints.rs",// Alias introspection output (show / dry-run), intended to be pipeable"config/alias.rs",+ // Alias --help hint output (conventional `--help` destination)+ "alias.rs",// Template evaluation output for scripting"eval.rs",// LLM prompt output for wt step commit --show-promptdiff --git a/tests/integration_tests/step_alias.rs b/tests/integration_tests/step_alias.rsindex 97a138cc6..f6228ed47 100644--- a/tests/integration_tests/step_alias.rs+++ b/tests/integration_tests/step_alias.rs@@ -1242,6 +1242,79 @@ deploy = "echo hi"));}+/// Retired `--dry-run` bail also fires through `wt step <alias>` — the parser+/// is shared, but this pins the `step_alias` dispatch route specifically.+#[rstest]+fn test_retired_dry_run_flag_via_step(mut repo: TestRepo) {+ repo.write_project_config(+ r#"+[aliases]+deploy = "echo hi"+"#,+ );+ repo.commit("Add alias config");+ let feature_path = repo.add_worktree("feature");++ let settings = setup_snapshot_settings(&repo);+ let _guard = settings.bind_to_scope();++ assert_cmd_snapshot!(make_snapshot_cmd(+ &repo,+ "step",+ &["deploy", "--dry-run"],+ Some(&feature_path),+ ));+}++/// `wt <alias> --help` prints guidance rather than forwarding `--help` into+/// `{{ args }}`. Aliases have no clap-style help page; the canonical+/// inspection path is `wt config alias show / dry-run`.+#[rstest]+fn test_alias_help_flag_prints_hint(mut repo: TestRepo) {+ repo.write_project_config(+ r#"+[aliases]+deploy = "echo hi {{ args }}"+"#,+ );+ repo.commit("Add alias config");+ let feature_path = repo.add_worktree("feature");++ let settings = setup_snapshot_settings(&repo);+ let _guard = settings.bind_to_scope();++ assert_cmd_snapshot!(make_snapshot_cmd(+ &repo,+ "deploy",+ &["--help"],+ Some(&feature_path),+ ));+}++/// `wt <alias> -- --help` bypasses the intercept and forwards `--help` into+/// the alias body — the documented escape.+#[rstest]+fn test_alias_help_flag_after_double_dash_forwards(mut repo: TestRepo) {+ repo.write_project_config(+ r#"+[aliases]+deploy = "echo {{ args }}"+"#,+ );+ repo.commit("Add alias config");+ let feature_path = repo.add_worktree("feature");++ let settings = setup_snapshot_settings(&repo);+ let _guard = settings.bind_to_scope();++ assert_cmd_snapshot!(make_snapshot_cmd(+ &repo,+ "deploy",+ &["--", "--help"],+ Some(&feature_path),+ ));+}+/// `wt config alias show <name>` prints the configured template text, source-labeled.#[rstest]fn test_config_alias_show_single(mut repo: TestRepo) {@@ -1395,6 +1468,56 @@ deploy = "echo hi"));}+/// `wt config alias show <name>` on an alias whose name is also a top-level+/// built-in subcommand warns that the alias is unreachable via `wt <name>`.+/// The alias is still configured, so the show output itself is shown — the+/// warning is an advisory on stderr.+#[rstest]+fn test_config_alias_show_warns_on_shadowed_name(mut repo: TestRepo) {+ repo.write_project_config(+ r#"+[aliases]+list = "echo custom list"+"#,+ );+ repo.commit("Add alias config");+ let feature_path = repo.add_worktree("feature");++ let settings = setup_snapshot_settings(&repo);+ let _guard = settings.bind_to_scope();++ assert_cmd_snapshot!(make_snapshot_cmd(+ &repo,+ "config",+ &["alias", "show", "list"],+ Some(&feature_path),+ ));+}++/// `wt config alias dry-run` on a shadowed name emits the same advisory as+/// `show` — both are discovery surfaces, so both point out the shadowing.+#[rstest]+fn test_config_alias_dry_run_warns_on_shadowed_name(mut repo: TestRepo) {+ repo.write_project_config(+ r#"+[aliases]+list = "echo custom list"+"#,+ );+ repo.commit("Add alias config");+ let feature_path = repo.add_worktree("feature");++ let settings = setup_snapshot_settings(&repo);+ let _guard = settings.bind_to_scope();++ assert_cmd_snapshot!(make_snapshot_cmd(+ &repo,+ "config",+ &["alias", "dry-run", "list"],+ Some(&feature_path),+ ));+}+/// `wt step` with no subcommand lists built-in steps plus configured aliases.////// Skipped on Windows: clap renders `[experimental]` subcommand tagsdiff --git a/tests/snapshots/integration__integration_tests__step_alias__alias_help_flag_after_double_dash_forwards.snap b/tests/snapshots/integration__integration_tests__step_alias__alias_help_flag_after_double_dash_forwards.snapnew file mode 100644index 000000000..fef9bfd3c--- /dev/null+++ b/tests/snapshots/integration__integration_tests__step_alias__alias_help_flag_after_double_dash_forwards.snap@@ -0,0 +1,52 @@+---+source: tests/integration_tests/step_alias.rs+info:+ program: wt+ args:+ - deploy+ - "--"+ - "--help"+ env:+ APPDATA: "[TEST_CONFIG_HOME]"+ CLICOLOR_FORCE: "1"+ COLUMNS: "500"+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"+ GIT_CONFIG_SYSTEM: /dev/null+ GIT_EDITOR: ""+ GIT_TERMINAL_PROMPT: "0"+ HOME: "[TEST_HOME]"+ LANG: C+ LC_ALL: C+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"+ NO_COLOR: ""+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"+ PATH: "[PATH]"+ PSModulePath: ""+ RUST_LOG: warn+ SHELL: ""+ TERM: alacritty+ USERPROFILE: "[TEST_HOME]"+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"+ WORKTRUNK_TEST_EPOCH: "1735776000"+ WORKTRUNK_TEST_NUSHELL_ENV: "0"+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"+---+success: false+exit_code: 1+----- stdout -----++----- stderr -----+[33m▲[39m [33m[1morigin[22m needs approval to execute [1m1[22m command:[39m+[2m○[22m alias [1mdeploy[22m:+[107m [0m [2m[0m[2m[34mecho[0m[2m [0m[2m[32m{{[0m[2m args [0m[2m[32m}}[0m[2m+[31m✗[39m [31mCannot prompt for approval in non-interactive environment[39m+[2m↳[22m [2mTo skip prompts in CI/CD, add [4m--yes[24m; to pre-approve commands, run [4mwt config approvals add[24m[22mdiff --git a/tests/snapshots/integration__integration_tests__step_alias__alias_help_flag_prints_hint.snap b/tests/snapshots/integration__integration_tests__step_alias__alias_help_flag_prints_hint.snapnew file mode 100644index 000000000..f4fe7d27b--- /dev/null+++ b/tests/snapshots/integration__integration_tests__step_alias__alias_help_flag_prints_hint.snap@@ -0,0 +1,50 @@+---+source: tests/integration_tests/step_alias.rs+info:+ program: wt+ args:+ - deploy+ - "--help"+ env:+ APPDATA: "[TEST_CONFIG_HOME]"+ CLICOLOR_FORCE: "1"+ COLUMNS: "500"+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"+ GIT_CONFIG_SYSTEM: /dev/null+ GIT_EDITOR: ""+ GIT_TERMINAL_PROMPT: "0"+ HOME: "[TEST_HOME]"+ LANG: C+ LC_ALL: C+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"+ NO_COLOR: ""+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"+ PATH: "[PATH]"+ PSModulePath: ""+ RUST_LOG: warn+ SHELL: ""+ TERM: alacritty+ USERPROFILE: "[TEST_HOME]"+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"+ WORKTRUNK_TEST_EPOCH: "1735776000"+ WORKTRUNK_TEST_NUSHELL_ENV: "0"+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"+---+success: true+exit_code: 0+----- stdout -----+`deploy` is an alias. Inspect with:+ wt config alias show deploy+ wt config alias dry-run deploy+Forward `--help` to the alias body with `wt deploy -- --help`.++----- stderr -----diff --git a/tests/snapshots/integration__integration_tests__step_alias__config_alias_dry_run_positional_args.snap b/tests/snapshots/integration__integration_tests__step_alias__config_alias_dry_run_positional_args.snapindex 03f52e6c3..02502d65b 100644--- a/tests/snapshots/integration__integration_tests__step_alias__config_alias_dry_run_positional_args.snap+++ b/tests/snapshots/integration__integration_tests__step_alias__config_alias_dry_run_positional_args.snap@@ -47,6 +47,7 @@ success: trueexit_code: 0----- stdout -----[2m○[22m Alias [1ms[22m (project) would run:+[107m [0m [2m# args: target-branch[0m[2m[107m [0m [2m[0m[2m[34mwt[0m[2m switch target-branch----- stderr -----diff --git a/tests/snapshots/integration__integration_tests__step_alias__config_alias_dry_run_warns_on_shadowed_name.snap b/tests/snapshots/integration__integration_tests__step_alias__config_alias_dry_run_warns_on_shadowed_name.snapnew file mode 100644index 000000000..106da89e3--- /dev/null+++ b/tests/snapshots/integration__integration_tests__step_alias__config_alias_dry_run_warns_on_shadowed_name.snap@@ -0,0 +1,51 @@+---+source: tests/integration_tests/step_alias.rs+info:+ program: wt+ args:+ - config+ - alias+ - dry-run+ - list+ env:+ APPDATA: "[TEST_CONFIG_HOME]"+ CLICOLOR_FORCE: "1"+ COLUMNS: "500"+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"+ GIT_CONFIG_SYSTEM: /dev/null+ GIT_EDITOR: ""+ GIT_TERMINAL_PROMPT: "0"+ HOME: "[TEST_HOME]"+ LANG: C+ LC_ALL: C+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"+ NO_COLOR: ""+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"+ PATH: "[PATH]"+ PSModulePath: ""+ RUST_LOG: warn+ SHELL: ""+ TERM: alacritty+ USERPROFILE: "[TEST_HOME]"+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"+ WORKTRUNK_TEST_EPOCH: "1735776000"+ WORKTRUNK_TEST_NUSHELL_ENV: "0"+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"+---+success: true+exit_code: 0+----- stdout -----+[2m○[22m Alias [1mlist[22m (project) would run:+[107m [0m [2m[0m[2m[34mecho[0m[2m custom list++----- stderr -----+[33m▲[39m [33mAlias [1mlist[22m is shadowed by built-in [1mwt list[22m[39mdiff --git a/tests/snapshots/integration__integration_tests__step_alias__config_alias_show_warns_on_shadowed_name.snap b/tests/snapshots/integration__integration_tests__step_alias__config_alias_show_warns_on_shadowed_name.snapnew file mode 100644index 000000000..c7053013f--- /dev/null+++ b/tests/snapshots/integration__integration_tests__step_alias__config_alias_show_warns_on_shadowed_name.snap@@ -0,0 +1,51 @@+---+source: tests/integration_tests/step_alias.rs+info:+ program: wt+ args:+ - config+ - alias+ - show+ - list+ env:+ APPDATA: "[TEST_CONFIG_HOME]"+ CLICOLOR_FORCE: "1"+ COLUMNS: "500"+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"+ GIT_CONFIG_SYSTEM: /dev/null+ GIT_EDITOR: ""+ GIT_TERMINAL_PROMPT: "0"+ HOME: "[TEST_HOME]"+ LANG: C+ LC_ALL: C+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"+ NO_COLOR: ""+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"+ PATH: "[PATH]"+ PSModulePath: ""+ RUST_LOG: warn+ SHELL: ""+ TERM: alacritty+ USERPROFILE: "[TEST_HOME]"+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"+ WORKTRUNK_TEST_EPOCH: "1735776000"+ WORKTRUNK_TEST_NUSHELL_ENV: "0"+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"+---+success: true+exit_code: 0+----- stdout -----+[2m○[22m Alias [1mlist[22m (project):+[107m [0m [2m[0m[2m[34mecho[0m[2m custom list++----- stderr -----+[33m▲[39m [33mAlias [1mlist[22m is shadowed by built-in [1mwt list[22m[39mdiff --git a/tests/snapshots/integration__integration_tests__step_alias__retired_dry_run_flag_via_step.snap b/tests/snapshots/integration__integration_tests__step_alias__retired_dry_run_flag_via_step.snapnew file mode 100644index 000000000..328f301e3--- /dev/null+++ b/tests/snapshots/integration__integration_tests__step_alias__retired_dry_run_flag_via_step.snap@@ -0,0 +1,48 @@+---+source: tests/integration_tests/step_alias.rs+info:+ program: wt+ args:+ - step+ - deploy+ - "--dry-run"+ env:+ APPDATA: "[TEST_CONFIG_HOME]"+ CLICOLOR_FORCE: "1"+ COLUMNS: "500"+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"+ GIT_CONFIG_SYSTEM: /dev/null+ GIT_EDITOR: ""+ GIT_TERMINAL_PROMPT: "0"+ HOME: "[TEST_HOME]"+ LANG: C+ LC_ALL: C+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"+ NO_COLOR: ""+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"+ PATH: "[PATH]"+ PSModulePath: ""+ RUST_LOG: warn+ SHELL: ""+ TERM: alacritty+ USERPROFILE: "[TEST_HOME]"+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"+ WORKTRUNK_TEST_EPOCH: "1735776000"+ WORKTRUNK_TEST_NUSHELL_ENV: "0"+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"+---+success: false+exit_code: 1+----- stdout -----++----- stderr -----+[31m✗[39m [31m--dry-run is no longer supported; use `wt config alias dry-run deploy` instead[39mdiff --git a/tests/snapshots/integration__integration_tests__step_alias__step_alias_binds_referenced_var.snap b/tests/snapshots/integration__integration_tests__step_alias__step_alias_binds_referenced_var.snapindex a38698b01..9e3d4b50e 100644--- a/tests/snapshots/integration__integration_tests__step_alias__step_alias_binds_referenced_var.snap+++ b/tests/snapshots/integration__integration_tests__step_alias__step_alias_binds_referenced_var.snap@@ -47,6 +47,7 @@ success: trueexit_code: 0----- stdout -----[2m○[22m Alias [1mgreet[22m (project) would run:+[107m [0m [2m# bound: name=World[0m[2m[107m [0m [2m[0m[2m[34mecho[0m[2m Hello World from feature----- stderr -----diff --git a/tests/snapshots/integration__integration_tests__step_alias__step_alias_binds_space_separated_var.snap b/tests/snapshots/integration__integration_tests__step_alias__step_alias_binds_space_separated_var.snapindex 33a4c34fa..90131e6a1 100644--- a/tests/snapshots/integration__integration_tests__step_alias__step_alias_binds_space_separated_var.snap+++ b/tests/snapshots/integration__integration_tests__step_alias__step_alias_binds_space_separated_var.snap@@ -48,6 +48,7 @@ success: trueexit_code: 0----- stdout -----[2m○[22m Alias [1mgreet[22m (project) would run:+[107m [0m [2m# bound: name=World[0m[2m[107m [0m [2m[0m[2m[34mecho[0m[2m Hello World from feature----- stderr -----diff --git a/tests/snapshots/integration__integration_tests__step_alias__top_level_alias_positional_expands_in_dry_run.snap b/tests/snapshots/integration__integration_tests__step_alias__top_level_alias_positional_expands_in_dry_run.snapindex 03f52e6c3..02502d65b 100644--- a/tests/snapshots/integration__integration_tests__step_alias__top_level_alias_positional_expands_in_dry_run.snap+++ b/tests/snapshots/integration__integration_tests__step_alias__top_level_alias_positional_expands_in_dry_run.snap@@ -47,6 +47,7 @@ success: trueexit_code: 0----- stdout -----[2m○[22m Alias [1ms[22m (project) would run:+[107m [0m [2m# args: target-branch[0m[2m[107m [0m [2m[0m[2m[34mwt[0m[2m switch target-branch----- stderr -----