Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
feat: lazy template expansion for pipeline vars (#1840)
Maximilian Roos79fa6a8b73ca
diff --git a/docs/content/hook.md b/docs/content/hook.mdindex 71497ea5c..a90ebc2b9 100644--- a/docs/content/hook.md+++ b/docs/content/hook.md@@ -333,27 +333,33 @@ server = "npm run dev -- --host {{ branch | sanitize }}.localhost --port {{ bran## Databases-Each worktree can have its own database. Docker containers get unique names and ports, and the connection string is stored in `vars` for use outside hooks:+Each worktree can have its own database. A pipeline sets up the container name and connection string as vars, then later steps and hooks reference them:```toml-[post-start]-db = """-docker run -d --rm \- --name {{ repo }}-{{ branch | sanitize }}-postgres \- -p {{ ('db-' ~ branch) | hash_port }}:5432 \- -e POSTGRES_DB={{ branch | sanitize_db }} \- -e POSTGRES_PASSWORD=dev \- postgres:16-"""-db-url = "wt config state vars set db-url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'"+post-start = [+ """+ wt config state vars set \+ container='{{ repo }}-{{ branch | sanitize }}-postgres' \+ port='{{ ('db-' ~ branch) | hash_port }}' \+ db-url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'+ """,+ { db = """+ docker run -d --rm \+ --name {{ vars.container }} \+ -p {{ vars.port }}:5432 \+ -e POSTGRES_DB={{ branch | sanitize_db }} \+ -e POSTGRES_PASSWORD=dev \+ postgres:16+ """},+][post-remove]-db-stop = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"+db-stop = "docker stop {{ vars.container }} 2>/dev/null || true"```-The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide.+The first pipeline step derives names and ports from the branch name and stores them as vars. The second step uses `{{ vars.container }}` and `{{ vars.port }}` — expanded at execution time, after the vars are set. The `post-remove` hook reads the same vars.-The connection string is now accessible anywhere — not just in hooks:+The connection string is accessible anywhere — not just in hooks:{{ terminal(cmd="DATABASE_URL=$(wt config state vars get db-url) npm start") }}diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.mdindex fc4ca04f6..9d8307d32 100644--- a/docs/content/tips-patterns.md+++ b/docs/content/tips-patterns.md@@ -65,27 +65,35 @@ Ports are deterministic — `fix-auth` always gets port 16460, regardless of whi## Database per worktree-Each worktree can have its own isolated database. Docker containers get unique names and ports, and the connection string is stored in `vars` for use outside hooks:+Each worktree can have its own isolated database. A pipeline sets up names and ports as vars, then later steps and hooks reference them:```toml-[post-start]-db = """-docker run -d --rm \- --name {{ repo }}-{{ branch | sanitize }}-postgres \- -p {{ ('db-' ~ branch) | hash_port }}:5432 \- -e POSTGRES_DB={{ branch | sanitize_db }} \- -e POSTGRES_PASSWORD=dev \- postgres:16-"""-db-url = "wt config state vars set db-url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'"+post-start = [+ """+ wt config state vars set \+ container='{{ repo }}-{{ branch | sanitize }}-postgres' \+ port='{{ ('db-' ~ branch) | hash_port }}' \+ db-url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'+ """,+ { db = """+ docker run -d --rm \+ --name {{ vars.container }} \+ -p {{ vars.port }}:5432 \+ -e POSTGRES_DB={{ branch | sanitize_db }} \+ -e POSTGRES_PASSWORD=dev \+ postgres:16+ """},+][pre-remove]-db-stop = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"+db-stop = "docker stop {{ vars.container }} 2>/dev/null || true"```-The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide. The `sanitize_db` filter produces database-safe identifiers (lowercase, underscores, no leading digits, with a short hash suffix to avoid collisions and SQL reserved words).+The first pipeline step derives values from the branch and stores them as vars. The second step references `{{ vars.container }}` and `{{ vars.port }}` — expanded at execution time, after the vars are set. `post-remove` reads the same vars to stop the container.++The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide. The `sanitize_db` filter produces database-safe identifiers (lowercase, underscores, no leading digits, with a short hash suffix).-The connection string is now accessible anywhere — not just in hooks:+The connection string is accessible anywhere — not just in hooks:{{ terminal(cmd="DATABASE_URL=$(wt config state vars get db-url) npm start") }}diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.mdindex 056ca7216..980983e9e 100644--- a/skills/worktrunk/reference/hook.md+++ b/skills/worktrunk/reference/hook.md@@ -331,27 +331,33 @@ server = "npm run dev -- --host {{ branch | sanitize }}.localhost --port {{ bran## Databases-Each worktree can have its own database. Docker containers get unique names and ports, and the connection string is stored in `vars` for use outside hooks:+Each worktree can have its own database. A pipeline sets up the container name and connection string as vars, then later steps and hooks reference them:```toml-[post-start]-db = """-docker run -d --rm \- --name {{ repo }}-{{ branch | sanitize }}-postgres \- -p {{ ('db-' ~ branch) | hash_port }}:5432 \- -e POSTGRES_DB={{ branch | sanitize_db }} \- -e POSTGRES_PASSWORD=dev \- postgres:16-"""-db-url = "wt config state vars set db-url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'"+post-start = [+ """+ wt config state vars set \+ container='{{ repo }}-{{ branch | sanitize }}-postgres' \+ port='{{ ('db-' ~ branch) | hash_port }}' \+ db-url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'+ """,+ { db = """+ docker run -d --rm \+ --name {{ vars.container }} \+ -p {{ vars.port }}:5432 \+ -e POSTGRES_DB={{ branch | sanitize_db }} \+ -e POSTGRES_PASSWORD=dev \+ postgres:16+ """},+][post-remove]-db-stop = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"+db-stop = "docker stop {{ vars.container }} 2>/dev/null || true"```-The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide.+The first pipeline step derives names and ports from the branch name and stores them as vars. The second step uses `{{ vars.container }}` and `{{ vars.port }}` — expanded at execution time, after the vars are set. The `post-remove` hook reads the same vars.-The connection string is now accessible anywhere — not just in hooks:+The connection string is accessible anywhere — not just in hooks:```bash$ DATABASE_URL=$(wt config state vars get db-url) npm startdiff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.mdindex 9b94d2b0c..e6b1e0e12 100644--- a/skills/worktrunk/reference/tips-patterns.md+++ b/skills/worktrunk/reference/tips-patterns.md@@ -58,27 +58,35 @@ Ports are deterministic — `fix-auth` always gets port 16460, regardless of whi## Database per worktree-Each worktree can have its own isolated database. Docker containers get unique names and ports, and the connection string is stored in `vars` for use outside hooks:+Each worktree can have its own isolated database. A pipeline sets up names and ports as vars, then later steps and hooks reference them:```toml-[post-start]-db = """-docker run -d --rm \- --name {{ repo }}-{{ branch | sanitize }}-postgres \- -p {{ ('db-' ~ branch) | hash_port }}:5432 \- -e POSTGRES_DB={{ branch | sanitize_db }} \- -e POSTGRES_PASSWORD=dev \- postgres:16-"""-db-url = "wt config state vars set db-url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'"+post-start = [+ """+ wt config state vars set \+ container='{{ repo }}-{{ branch | sanitize }}-postgres' \+ port='{{ ('db-' ~ branch) | hash_port }}' \+ db-url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'+ """,+ { db = """+ docker run -d --rm \+ --name {{ vars.container }} \+ -p {{ vars.port }}:5432 \+ -e POSTGRES_DB={{ branch | sanitize_db }} \+ -e POSTGRES_PASSWORD=dev \+ postgres:16+ """},+][pre-remove]-db-stop = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"+db-stop = "docker stop {{ vars.container }} 2>/dev/null || true"```-The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide. The `sanitize_db` filter produces database-safe identifiers (lowercase, underscores, no leading digits, with a short hash suffix to avoid collisions and SQL reserved words).+The first pipeline step derives values from the branch and stores them as vars. The second step references `{{ vars.container }}` and `{{ vars.port }}` — expanded at execution time, after the vars are set. `post-remove` reads the same vars to stop the container.++The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide. The `sanitize_db` filter produces database-safe identifiers (lowercase, underscores, no leading digits, with a short hash suffix).-The connection string is now accessible anywhere — not just in hooks:+The connection string is accessible anywhere — not just in hooks:```bash$ DATABASE_URL=$(wt config state vars get db-url) npm startdiff --git a/src/cli/mod.rs b/src/cli/mod.rsindex c8ead811b..5f7ec20e5 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -1444,27 +1444,33 @@ server = "npm run dev -- --host {{ branch | sanitize }}.localhost --port {{ bran## Databases-Each worktree can have its own database. Docker containers get unique names and ports, and the connection string is stored in `vars` for use outside hooks:+Each worktree can have its own database. A pipeline sets up the container name and connection string as vars, then later steps and hooks reference them:```toml-[post-start]-db = """-docker run -d --rm \- --name {{ repo }}-{{ branch | sanitize }}-postgres \- -p {{ ('db-' ~ branch) | hash_port }}:5432 \- -e POSTGRES_DB={{ branch | sanitize_db }} \- -e POSTGRES_PASSWORD=dev \- postgres:16-"""-db-url = "wt config state vars set db-url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'"+post-start = [+ """+ wt config state vars set \+ container='{{ repo }}-{{ branch | sanitize }}-postgres' \+ port='{{ ('db-' ~ branch) | hash_port }}' \+ db-url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'+ """,+ { db = """+ docker run -d --rm \+ --name {{ vars.container }} \+ -p {{ vars.port }}:5432 \+ -e POSTGRES_DB={{ branch | sanitize_db }} \+ -e POSTGRES_PASSWORD=dev \+ postgres:16+ """},+][post-remove]-db-stop = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"+db-stop = "docker stop {{ vars.container }} 2>/dev/null || true"```-The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide.+The first pipeline step derives names and ports from the branch name and stores them as vars. The second step uses `{{ vars.container }}` and `{{ vars.port }}` — expanded at execution time, after the vars are set. The `post-remove` hook reads the same vars.-The connection string is now accessible anywhere — not just in hooks:+The connection string is accessible anywhere — not just in hooks:```console$ DATABASE_URL=$(wt config state vars get db-url) npm startdiff --git a/src/cli/step.rs b/src/cli/step.rsindex 39f965f0d..6a39831b4 100644--- a/src/cli/step.rs+++ b/src/cli/step.rs@@ -393,6 +393,10 @@ Note: This command is experimental and may change in future versions./// Template expression to evaluatetemplate: String,+ /// Shell-escape substituted values (used internally by pipeline lazy expansion)+ #[arg(long, hide = true)]+ shell_escape: bool,+/// Show template variables and expanded result#[arg(long)]dry_run: bool,diff --git a/src/commands/command_executor.rs b/src/commands/command_executor.rsindex ccb76b319..dcfa65c14 100644--- a/src/commands/command_executor.rs+++ b/src/commands/command_executor.rs@@ -2,7 +2,9 @@ use anyhow::Result;use std::collections::HashMap;use std::path::Path;use worktrunk::HookType;-use worktrunk::config::{Command, CommandConfig, HookStep, UserConfig, expand_template};+use worktrunk::config::{+ Command, CommandConfig, HookStep, UserConfig, expand_template, template_references_var,+};use worktrunk::git::Repository;use worktrunk::path::to_posix_path;@@ -13,6 +15,9 @@ pub struct PreparedCommand {pub name: Option<String>,pub expanded: String,pub context_json: String,+ /// Raw template for lazy expansion at execution time (when template references `vars.`).+ /// When `Some`, the `expanded` field is a placeholder — use `lazy_template` instead.+ pub lazy_template: Option<String>,}/// A step in a prepared pipeline, mirroring `HookStep`.@@ -160,17 +165,19 @@ pub fn build_hook_context(Ok(map)}-/// Expand commands from a CommandConfig without approval+/// Expand commands from a CommandConfig without approval.///-/// This is the canonical command expansion implementation.-/// Returns cloned commands with their expanded forms filled in, each with per-command JSON context.+/// When `lazy_enabled` is true, commands referencing `vars.` are validated but not+/// expanded — they carry a `lazy_template` for deferred expansion at execution time.+/// Only enable for pipeline steps where ordering guarantees vars are set by prior steps.fn expand_commands(commands: &[Command],ctx: &CommandContext<'_>,extra_vars: &[(&str, &str)],hook_type: HookType,source: HookSource,-) -> anyhow::Result<Vec<(Command, String)>> {+ lazy_enabled: bool,+) -> anyhow::Result<Vec<(Command, String, Option<String>)>> {if commands.is_empty() {return Ok(Vec::new());}@@ -189,16 +196,32 @@ fn expand_commands(cmd_context.insert("hook_name".into(), name.clone());}- let vars: HashMap<&str, &str> = cmd_context- .iter()- .map(|(k, v)| (k.as_str(), v.as_str()))- .collect();-let template_name = match &cmd.name {Some(name) => format!("{}:{}", source, name),None => format!("{} {} hook", source, hook_type),};- let expanded_str = expand_template(&cmd.template, &vars, true, ctx.repo, &template_name)?;++ let lazy = lazy_enabled && template_references_var(&cmd.template, "vars");++ let (expanded_str, lazy_template) = if lazy {+ // Parse-only validation: catch syntax errors upfront without rendering.+ // Full rendering (validate_template) would fail on {{ vars.X }} because+ // vars aren't set yet — that's the whole point of lazy expansion.+ let env = minijinja::Environment::new();+ env.template_from_named_str(&template_name, &cmd.template)+ .map_err(|e| anyhow::anyhow!("syntax error in {template_name}: {e}"))?;+ let tpl = cmd.template.clone();+ (tpl.clone(), Some(tpl))+ } else {+ let vars: HashMap<&str, &str> = cmd_context+ .iter()+ .map(|(k, v)| (k.as_str(), v.as_str()))+ .collect();+ (+ expand_template(&cmd.template, &vars, true, ctx.repo, &template_name)?,+ None,+ )+ };let context_json = serde_json::to_string(&cmd_context).expect("HashMap<String, String> serialization should never fail");@@ -206,6 +229,7 @@ fn expand_commands(result.push((Command::with_expansion(cmd.name.clone(), cmd.template.clone(), expanded_str),context_json,+ lazy_template,));}@@ -232,14 +256,18 @@ pub fn prepare_commands(return Ok(Vec::new());}- let expanded_with_json = expand_commands(&commands, ctx, extra_vars, hook_type, source)?;+ // Lazy expansion for pipeline configs (sequential ordering guarantees vars are+ // set by prior steps). Flat configs (concurrent table) expand eagerly.+ let lazy = command_config.is_pipeline();+ let expanded_with_json = expand_commands(&commands, ctx, extra_vars, hook_type, source, lazy)?;Ok(expanded_with_json.into_iter()- .map(|(cmd, context_json)| PreparedCommand {+ .map(|(cmd, context_json, lazy_template)| PreparedCommand {name: cmd.name,expanded: cmd.expanded,context_json,+ lazy_template,}).collect())}@@ -272,7 +300,7 @@ pub fn prepare_steps(.collect();let all_commands: Vec<Command> = command_config.commands().cloned().collect();- let all_expanded = expand_commands(&all_commands, ctx, extra_vars, hook_type, source)?;+ let all_expanded = expand_commands(&all_commands, ctx, extra_vars, hook_type, source, true)?;let mut expanded_iter = all_expanded.into_iter();let mut result = Vec::new();@@ -280,20 +308,22 @@ pub fn prepare_steps(let chunk: Vec<_> = expanded_iter.by_ref().take(size).collect();match step {HookStep::Single(_) => {- let (cmd, json) = chunk.into_iter().next().unwrap();+ let (cmd, json, lazy) = chunk.into_iter().next().unwrap();result.push(PreparedStep::Single(PreparedCommand {name: cmd.name,expanded: cmd.expanded,context_json: json,+ lazy_template: lazy,}));}HookStep::Concurrent(_) => {let prepared = chunk.into_iter()- .map(|(cmd, json)| PreparedCommand {+ .map(|(cmd, json, lazy)| PreparedCommand {name: cmd.name,expanded: cmd.expanded,context_json: json,+ lazy_template: lazy,}).collect();result.push(PreparedStep::Concurrent(prepared));@@ -303,3 +333,30 @@ pub fn prepare_steps(Ok(result)}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn test_template_references_var_for_vars() {+ // Real vars references+ assert!(template_references_var("{{ vars.container }}", "vars"));+ assert!(template_references_var("{{vars.container}}", "vars"));+ assert!(template_references_var(+ "docker run --name {{ vars.name }}",+ "vars"+ ));+ assert!(template_references_var(+ "{% if vars.key %}yes{% endif %}",+ "vars"+ ));++ // Literal text — not a template reference+ assert!(!template_references_var(+ "echo hello > template_vars.txt",+ "vars"+ ));+ assert!(!template_references_var("no vars references here", "vars"));+ }+}diff --git a/src/commands/eval.rs b/src/commands/eval.rsindex 6908926bb..2ad4bb7ba 100644--- a/src/commands/eval.rs+++ b/src/commands/eval.rs@@ -1,8 +1,8 @@//! Eval command implementation//!//! Evaluates a template expression in the current worktree context and prints-//! the result to stdout. Designed for scripting — output is raw (no shell-//! escaping, no decoration).+//! the result to stdout. Output is raw by default; `--shell-escape` enables+//! shell escaping for safe use with `eval`.use std::collections::HashMap;@@ -18,7 +18,7 @@ use crate::commands::command_executor::{CommandContext, build_hook_context};////// With `dry_run`, prints the template variables and the expanded result/// to stderr — useful for debugging templates.-pub fn step_eval(template: &str, dry_run: bool) -> anyhow::Result<()> {+pub fn step_eval(template: &str, shell_escape: bool, dry_run: bool) -> anyhow::Result<()> {let repo = Repository::current()?;let config = UserConfig::load()?;@@ -34,8 +34,7 @@ pub fn step_eval(template: &str, dry_run: bool) -> anyhow::Result<()> {.map(|(k, v)| (k.as_str(), v.as_str())).collect();- // No shell escaping — output is literal for scripting- let result = expand_template(template, &vars, false, &repo, "eval")?;+ let result = expand_template(template, &vars, shell_escape, &repo, "eval")?;if dry_run {let mut keys: Vec<&str> = context_map.keys().map(|k| k.as_str()).collect();diff --git a/src/commands/hooks.rs b/src/commands/hooks.rsindex 47eb21a95..daac79a9b 100644--- a/src/commands/hooks.rs+++ b/src/commands/hooks.rs@@ -244,6 +244,7 @@ pub fn spawn_background_hooks(ctx.branch_or_head(),&hook_log,Some(&cmd.prepared.context_json),+ &[],) {let err_msg = err.to_string();let message = match &cmd.prepared.name {@@ -276,33 +277,58 @@ pub struct SourcedStep {pub display_path: Option<PathBuf>,}-/// Build a compound shell command from pipeline steps.+/// Build a compound shell command from pipeline steps, collecting env vars for+/// lazy template expansion.////// Serial steps are chained with `&&`. Concurrent groups use background-/// processes with `wait`. The entire result is one shell command string-/// suitable for `spawn_detached`.+/// processes with `wait`. Commands referencing `vars.` are wrapped in+/// `eval "$(wt step eval --shell-escape ...)"` and their raw templates are+/// returned as env vars for the spawned process.///-/// Example output: `cmd1 && cmd2 && { cmd3 & cmd4 & wait; }`-fn build_pipeline_command(steps: &[SourcedStep]) -> String {+/// Returns `(shell_command, env_vars)`.+fn build_pipeline_command(steps: &[SourcedStep]) -> (String, Vec<(String, String)>) {+ let wt_bin = std::env::current_exe()+ .ok()+ .map(|p| shell_escape::escape(p.to_string_lossy()).into_owned())+ .unwrap_or_else(|| "wt".to_string());+let mut parts = Vec::new();+ let mut env_vars: Vec<(String, String)> = Vec::new();+for step in steps {match &step.step {PreparedStep::Single(cmd) => {// Wrap in braces to prevent operator interaction between steps.// Without this, `false || echo fallback && echo next` would// parse as `false || (echo fallback && echo next)`.- parts.push(format!("{{ {}; }}", cmd.expanded));+ parts.push(format!(+ "{{ {}; }}",+ format_cmd(cmd, &wt_bin, &mut env_vars)+ ));}PreparedStep::Concurrent(cmds) => {let bg: Vec<String> = cmds.iter()- .map(|c| format!("{{ {}; }} &", c.expanded))+ .map(|c| format!("{{ {}; }} &", format_cmd(c, &wt_bin, &mut env_vars))).collect();parts.push(format!("{{ {} wait; }}", bg.join(" ")));}}}- parts.join(" && ")+ (parts.join(" && "), env_vars)+}++/// Format a single command for the pipeline, using lazy eval wrapping for commands+/// with `lazy_template`.+fn format_cmd(cmd: &PreparedCommand, wt_bin: &str, env_vars: &mut Vec<(String, String)>) -> String {+ match &cmd.lazy_template {+ Some(template) => {+ let var_name = format!("__WT_TPL_{}", env_vars.len());+ env_vars.push((var_name.clone(), template.clone()));+ format!(r#"eval "$({wt_bin} step eval --shell-escape "${var_name}")"#)+ }+ None => cmd.expanded.clone(),+ }}/// Format a summary description of a pipeline for display.@@ -371,7 +397,7 @@ pub fn spawn_hook_pipeline(ctx: &CommandContext, steps: Vec<SourcedStep>) -> any};eprintln!("{}", progress_message(message));- let pipeline_cmd = build_pipeline_command(&steps);+ let (pipeline_cmd, lazy_env) = build_pipeline_command(&steps);let hook_log = HookLog::hook(source, hook_type, "pipeline");let log_label = format!("{hook_type} {source} pipeline");@@ -382,6 +408,11 @@ pub fn spawn_hook_pipeline(ctx: &CommandContext, steps: Vec<SourcedStep>) -> anyPreparedStep::Concurrent(cmds) => cmds.first().map(|c| c.context_json.as_str()),});+ let extra_env: Vec<(&str, &str)> = lazy_env+ .iter()+ .map(|(k, v)| (k.as_str(), v.as_str()))+ .collect();+if let Err(err) = spawn_detached(ctx.repo,ctx.worktree_path,@@ -389,6 +420,7 @@ pub fn spawn_hook_pipeline(ctx: &CommandContext, steps: Vec<SourcedStep>) -> anyctx.branch_or_head(),&hook_log,context_json,+ &extra_env,) {eprintln!("{}",@@ -525,10 +557,26 @@ pub fn run_hook_with_filter(for cmd in commands {cmd.announce()?;+ // Lazy commands (referencing vars.) are expanded just before execution+ // so that vars set by earlier commands in the pipeline are available.+ let expanded = if let Some(ref template) = cmd.prepared.lazy_template {+ let context_map: std::collections::HashMap<String, String> =+ serde_json::from_str(&cmd.prepared.context_json)+ .expect("context_json round-trip should never fail");+ let vars: std::collections::HashMap<&str, &str> = context_map+ .iter()+ .map(|(k, v)| (k.as_str(), v.as_str()))+ .collect();+ let name = cmd.summary_name();+ worktrunk::config::expand_template(template, &vars, true, ctx.repo, &name)?+ } else {+ cmd.prepared.expanded.clone()+ };+let log_label = format!("{} {}", cmd.hook_type, cmd.summary_name());if let Err(err) = execute_command_in_worktree(ctx.worktree_path,- &cmd.prepared.expanded,+ &expanded,Some(&cmd.prepared.context_json),Some(&log_label),) {@@ -745,6 +793,7 @@ mod tests {name: name.map(String::from),expanded: expanded.to_string(),context_json: "{}".to_string(),+ lazy_template: None,}}@@ -757,8 +806,9 @@ mod tests {"npm run build",))),];- let cmd = build_pipeline_command(&steps);+ let (cmd, env) = build_pipeline_command(&steps);assert_eq!(cmd, "{ npm install; } && { npm run build; }");+ assert!(env.is_empty());}#[test]@@ -770,11 +820,12 @@ mod tests {make_cmd(Some("lint"), "npm run lint"),])),];- let cmd = build_pipeline_command(&steps);+ let (cmd, env) = build_pipeline_command(&steps);assert_eq!(cmd,"{ npm install; } && { { npm run build; } & { npm run lint; } & wait; }");+ assert!(env.is_empty());}#[test]@@ -783,8 +834,9 @@ mod tests {Some("only"),"echo hi",)]))];- let cmd = build_pipeline_command(&steps);+ let (cmd, env) = build_pipeline_command(&steps);assert_eq!(cmd, "{ { echo hi; } & wait; }");+ assert!(env.is_empty());}#[test]@@ -825,4 +877,88 @@ mod tests {let single = CommandConfig::single("npm install");assert!(!single.is_pipeline());}++ fn make_lazy_cmd(name: Option<&str>, template: &str) -> PreparedCommand {+ PreparedCommand {+ name: name.map(String::from),+ expanded: template.to_string(),+ context_json: "{}".to_string(),+ lazy_template: Some(template.to_string()),+ }+ }++ #[test]+ fn test_build_pipeline_command_lazy_step() {+ let steps = vec![+ make_sourced_step(PreparedStep::Single(make_cmd(None, "echo setup"))),+ make_sourced_step(PreparedStep::Single(make_lazy_cmd(+ Some("db"),+ "docker run --name {{ vars.container }}",+ ))),+ ];+ let (cmd, env) = build_pipeline_command(&steps);++ // Lazy step uses eval wrapping with env var reference+ assert!(+ cmd.contains("eval \"$("),+ "should contain eval wrapping: {cmd}"+ );+ assert!(+ cmd.contains("step eval --shell-escape"),+ "should reference step eval: {cmd}"+ );+ assert!(+ cmd.contains("$__WT_TPL_0"),+ "should reference env var: {cmd}"+ );++ // Env var contains the raw template+ assert_eq!(env.len(), 1);+ assert_eq!(env[0].0, "__WT_TPL_0");+ assert_eq!(env[0].1, "docker run --name {{ vars.container }}");+ }++ #[test]+ fn test_build_pipeline_command_mixed_lazy_and_eager() {+ let steps = vec![+ make_sourced_step(PreparedStep::Single(make_cmd(None, "echo setup"))),+ make_sourced_step(PreparedStep::Concurrent(vec![+ make_lazy_cmd(Some("db"), "docker run {{ vars.name }}"),+ make_cmd(Some("lint"), "npm run lint"),+ ])),+ ];+ let (cmd, env) = build_pipeline_command(&steps);++ // First step is eager (no eval wrapping)+ assert!(cmd.starts_with("{ echo setup; }"), "eager step: {cmd}");++ // Concurrent group has one lazy and one eager+ assert!(cmd.contains("npm run lint"), "eager concurrent cmd: {cmd}");+ assert!(cmd.contains("$__WT_TPL_0"), "lazy concurrent cmd: {cmd}");++ // Only one env var (for the lazy command)+ assert_eq!(env.len(), 1);+ assert_eq!(env[0].1, "docker run {{ vars.name }}");+ }++ #[test]+ fn test_build_pipeline_command_multiple_lazy_steps() {+ let steps = vec![+ make_sourced_step(PreparedStep::Single(make_cmd(None, "echo setup"))),+ make_sourced_step(PreparedStep::Single(make_lazy_cmd(+ None,+ "echo {{ vars.a }}",+ ))),+ make_sourced_step(PreparedStep::Single(make_lazy_cmd(+ None,+ "echo {{ vars.b }}",+ ))),+ ];+ let (_, env) = build_pipeline_command(&steps);++ // Each lazy step gets its own numbered env var+ assert_eq!(env.len(), 2);+ assert_eq!(env[0].0, "__WT_TPL_0");+ assert_eq!(env[1].0, "__WT_TPL_1");+ }}diff --git a/src/commands/process.rs b/src/commands/process.rsindex 7e82bdff8..fd4106cc6 100644--- a/src/commands/process.rs+++ b/src/commands/process.rs@@ -194,6 +194,7 @@ fn posix_command_separator(command: &str) -> &'static str {/// * `branch` - Branch name for log organization/// * `hook_log` - Log specification (determines the log filename)/// * `context_json` - Optional JSON context to pipe to command's stdin+/// * `extra_env` - Additional environment variables for the spawned process////// # Returns/// Path to the log file where output is being written@@ -204,6 +205,7 @@ pub fn spawn_detached(branch: &str,hook_log: &HookLog,context_json: Option<&str>,+ extra_env: &[(&str, &str)],) -> anyhow::Result<std::path::PathBuf> {// Create log directory in the common git directorylet log_dir = repo.wt_logs_dir();@@ -233,12 +235,12 @@ pub fn spawn_detached(#[cfg(unix)]{- spawn_detached_unix(worktree_path, command, log_file, context_json)?;+ spawn_detached_unix(worktree_path, command, log_file, context_json, extra_env)?;}#[cfg(windows)]{- spawn_detached_windows(worktree_path, command, log_file, context_json)?;+ spawn_detached_windows(worktree_path, command, log_file, context_json, extra_env)?;}Ok(log_path)@@ -250,6 +252,7 @@ fn spawn_detached_unix(command: &str,log_file: fs::File,context_json: Option<&str>,+ extra_env: &[(&str, &str)],) -> anyhow::Result<()> {use std::os::unix::process::CommandExt;@@ -287,6 +290,7 @@ fn spawn_detached_unix(.stderr(Stdio::from(log_file))// Prevent hooks from writing to the directive file.env_remove(worktrunk::shell_exec::DIRECTIVE_FILE_ENV_VAR)+ .envs(extra_env.iter().map(|(k, v)| (k, v))).process_group(0) // New process group, not in PTY's foreground group.spawn().context("Failed to spawn detached process")?;@@ -305,6 +309,7 @@ fn spawn_detached_windows(command: &str,log_file: fs::File,context_json: Option<&str>,+ extra_env: &[(&str, &str)],) -> anyhow::Result<()> {use std::os::windows::process::CommandExt;use worktrunk::shell_exec::ShellConfig;@@ -360,6 +365,7 @@ fn spawn_detached_windows(.stderr(Stdio::from(log_file))// Prevent hooks from writing to the directive file.env_remove(worktrunk::shell_exec::DIRECTIVE_FILE_ENV_VAR)+ .envs(extra_env.iter().map(|(k, v)| (k, v))).creation_flags(CREATE_NEW_PROCESS_GROUP | DETACHED_PROCESS).spawn().context("Failed to spawn detached process")?;diff --git a/src/commands/worktree/resolve.rs b/src/commands/worktree/resolve.rsindex 23993fa41..d2d66b343 100644--- a/src/commands/worktree/resolve.rs+++ b/src/commands/worktree/resolve.rs@@ -334,12 +334,8 @@ const BARE_REPO_WORKTREE_PATH: &str = "{{ repo_path }}/../{{ branch | sanitize }/// Check whether a template string references `{{ repo }}` or `{{ main_worktree }}`.fn template_references_repo_name(template: &str) -> bool {- let env = minijinja::Environment::new();- let Ok(tmpl) = env.template_from_str(template) else {- return false;- };- let vars = tmpl.undeclared_variables(false);- vars.contains("repo") || vars.contains("main_worktree")+ worktrunk::config::template_references_var(template, "repo")+ || worktrunk::config::template_references_var(template, "main_worktree")}/// Offer to set a project-level `worktree-path` for bare repos with hidden directory names.diff --git a/src/config/expansion.rs b/src/config/expansion.rsindex 41291ceb5..2228d2a23 100644--- a/src/config/expansion.rs+++ b/src/config/expansion.rs@@ -350,6 +350,19 @@ fn setup_template_env(repo: &Repository) -> Environment<'static> {/// would be fragile and context-dependent.////// No verbose logging is performed — this is a pre-flight check, not the real expansion.+///+/// Check if a template references a specific top-level variable.+///+/// Uses minijinja's AST analysis rather than string matching, avoiding false+/// positives from literal text like `template_vars.txt`.+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)+}+pub fn validate_template(template: &str,repo: &Repository,diff --git a/src/config/mod.rs b/src/config/mod.rsindex a9b6ac6c0..6dcb27283 100644--- a/src/config/mod.rs+++ b/src/config/mod.rs@@ -86,7 +86,8 @@ pub use deprecation::write_migration_file;pub use deprecation::{DEPRECATED_SECTION_KEYS, key_belongs_in, warn_unknown_fields};pub use expansion::{DEPRECATED_TEMPLATE_VARS, TEMPLATE_VARS, TemplateExpandError, expand_template,- redact_credentials, sanitize_branch_name, sanitize_db, short_hash, validate_template,+ redact_credentials, sanitize_branch_name, sanitize_db, short_hash, template_references_var,+ validate_template,};pub use hooks::HooksConfig;pub use project::{diff --git a/src/main.rs b/src/main.rsindex 9725a5cb9..1533d216f 100644--- a/src/main.rs+++ b/src/main.rs@@ -321,7 +321,11 @@ fn handle_step_command(action: StepCommand) -> anyhow::Result<()> {dry_run,force,} => step_copy_ignored(from.as_deref(), to.as_deref(), dry_run, force),- StepCommand::Eval { template, dry_run } => step_eval(&template, dry_run),+ StepCommand::Eval {+ template,+ shell_escape,+ dry_run,+ } => step_eval(&template, shell_escape, dry_run),StepCommand::ForEach { args } => step_for_each(args),StepCommand::Promote { branch } => {handle_promote(branch.as_deref()).map(|result| match result {diff --git a/src/output/handlers.rs b/src/output/handlers.rsindex 6f31f9e09..60f244259 100644--- a/src/output/handlers.rs+++ b/src/output/handlers.rs@@ -72,6 +72,7 @@ fn spawn_background_removal(log_label,&HookLog::internal(InternalOp::Remove),None,+ &[],)?;Ok(())}diff --git a/tests/integration_tests/eval.rs b/tests/integration_tests/eval.rsindex 37c131732..191329a28 100644--- a/tests/integration_tests/eval.rs+++ b/tests/integration_tests/eval.rs@@ -79,3 +79,30 @@ fn test_eval_conditional(repo: TestRepo) {None,));}++#[rstest]+fn test_eval_shell_escape(repo: TestRepo) {+ // --shell-escape quotes values containing shell metacharacters+ assert_cmd_snapshot!(make_snapshot_cmd(+ &repo,+ "step",+ &["eval", "--shell-escape", "echo {{ branch }}"],+ None,+ ));+}++#[rstest]+fn test_eval_shell_escape_with_vars(repo: TestRepo) {+ // Set a var with spaces, then expand with shell escaping+ repo.run_git(&["config", "worktrunk.state.main.vars.name", "my container"]);+ assert_cmd_snapshot!(make_snapshot_cmd(+ &repo,+ "step",+ &[+ "eval",+ "--shell-escape",+ "docker run --name {{ vars.name }}"+ ],+ None,+ ));+}diff --git a/tests/integration_tests/user_hooks.rs b/tests/integration_tests/user_hooks.rsindex b84259d9d..a6452c385 100644--- a/tests/integration_tests/user_hooks.rs+++ b/tests/integration_tests/user_hooks.rs@@ -2364,3 +2364,46 @@ fn test_user_post_start_pipeline_failure_skips_later_steps(repo: TestRepo) {"Later pipeline steps should NOT run after serial step failure");}++#[rstest]+fn test_user_post_start_pipeline_lazy_vars_foreground(repo: TestRepo) {+ // Pipeline step 1 sets a var, step 2 uses it via {{ vars.name }}.+ // Foreground mode exercises the in-process lazy re-expansion path+ // in run_hook_with_filter.+ repo.write_test_config(+ r#"post-start = [+ "git config worktrunk.state.main.vars.name '{{ branch | sanitize }}-postgres'",+ { db = "echo {{ vars.name }} > lazy_expanded.txt" }+]+"#,+ );++ // Run the hook in foreground on the main worktree.+ // Step 1 uses `git config` directly (avoids needing `wt` on PATH in CI).+ let mut cmd = crate::common::wt_command();+ cmd.current_dir(repo.root_path());+ cmd.env("WORKTRUNK_CONFIG_PATH", repo.test_config_path());+ cmd.args(["hook", "post-start", "--yes", "--foreground"]);++ let output = cmd.output().expect("Failed to run foreground hook");++ let stderr = String::from_utf8_lossy(&output.stderr);+ assert!(+ output.status.success(),+ "Foreground hook should succeed.\nstdout: {}\nstderr: {stderr}",+ String::from_utf8_lossy(&output.stdout),+ );++ // With foreground, marker file should exist immediately+ let marker_file = repo.root_path().join("lazy_expanded.txt");+ assert!(+ marker_file.exists(),+ "Foreground lazy expansion should create marker file"+ );++ let content = fs::read_to_string(&marker_file).unwrap().trim().to_string();+ assert_eq!(+ content, "main-postgres",+ "Lazy step should see var set by prior step"+ );+}diff --git a/tests/snapshots/integration__integration_tests__eval__eval_shell_escape.snap b/tests/snapshots/integration__integration_tests__eval__eval_shell_escape.snapnew file mode 100644index 000000000..b05c1f54d--- /dev/null+++ b/tests/snapshots/integration__integration_tests__eval__eval_shell_escape.snap@@ -0,0 +1,47 @@+---+source: tests/integration_tests/eval.rs+info:+ program: wt+ args:+ - step+ - eval+ - "--shell-escape"+ - "echo {{ branch }}"+ 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: ""+ 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_POWERSHELL_ENV: "0"+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"+---+success: true+exit_code: 0+----- stdout -----+echo main++----- stderr -----diff --git a/tests/snapshots/integration__integration_tests__eval__eval_shell_escape_with_vars.snap b/tests/snapshots/integration__integration_tests__eval__eval_shell_escape_with_vars.snapnew file mode 100644index 000000000..c35c62195--- /dev/null+++ b/tests/snapshots/integration__integration_tests__eval__eval_shell_escape_with_vars.snap@@ -0,0 +1,47 @@+---+source: tests/integration_tests/eval.rs+info:+ program: wt+ args:+ - step+ - eval+ - "--shell-escape"+ - "docker run --name {{ vars.name }}"+ 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: ""+ 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_POWERSHELL_ENV: "0"+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"+---+success: true+exit_code: 0+----- stdout -----+docker run --name 'my container'++----- stderr -----diff --git a/tests/snapshots/integration__integration_tests__switch__switch_create_with_progress.snap b/tests/snapshots/integration__integration_tests__switch__switch_create_with_progress.snapindex adfdc0d10..8a5e5986e 100644--- a/tests/snapshots/integration__integration_tests__switch__switch_create_with_progress.snap+++ b/tests/snapshots/integration__integration_tests__switch__switch_create_with_progress.snap@@ -1,5 +1,6 @@---source: tests/integration_tests/switch.rs+assertion_line: 74info:program: wtargs: