Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
//! Template expansion utilities for worktrunk
//!
//! Uses minijinja for template rendering. A single generic function takes a
//! [`ShellEscapeMode`] selecting how interpolated values are escaped:
//! - `Posix` — POSIX single-quoting, for command lines fed to `Cmd::shell`
//! (`sh`/Git Bash): hooks, aliases.
//! - `Literal` — values substituted verbatim, for filesystem paths.
//!
//! All templates support Jinja2 syntax including filters, conditionals, and loops.
//! Undefined-variable diagnostics use MiniJinja's source spans and shared syntax
//! analysis; preflight checks use its undeclared-variable analysis.
//!
//! See `wt hook --help` for available filters and functions.
use std::collections::{BTreeSet, HashMap};
use std::fmt;
use std::hash::{Hash, Hasher};
use std::sync::Arc;
use color_print::cformat;
use minijinja::value::{Enumerator, Kwargs, Object, ObjectRepr, Serde, StringInput};
use minijinja::{AutoEscape, Environment, ErrorKind, State, UndefinedBehavior, Value};
use regex::Regex;
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use super::template_analysis::TemplateVars;
use crate::git::{Diagnostic, HookType, Repository};
use crate::path::to_posix_path;
use crate::shell_exec::{ShellEscapeMode, shell_escape_for};
use crate::styling::{
eprintln, error_message, format_bash_with_gutter, format_with_gutter, hint_message,
info_message, verbosity,
};
use crate::utils::did_you_mean;
/// Active-context vars: point at the branch the operation acts on.
///
/// `upstream` is conditional on branch tracking configuration but is listed
/// here so templates may reference it in any context (guarded by
/// `{% if upstream %}`).
pub const ACTIVE_VARS: &[&str] = &[
"branch",
"worktree_path",
"worktree_name",
"commit",
"short_commit",
"upstream",
];
/// Repo/remote-metadata vars: describe the repository hosting the operation.
pub const REPO_VARS: &[&str] = &[
"repo",
"repo_path",
"owner",
"remote_repo",
"primary_worktree_path",
"default_branch",
"remote",
"remote_url",
];
/// Exec-context vars always available outside hook infrastructure.
///
/// `cwd` is populated for every template expansion; `hook_type`/`hook_name`
/// are added by the hook runner itself (`HOOK_INFRASTRUCTURE_VARS`).
pub const EXEC_BASE_VARS: &[&str] = &["cwd"];
/// Template variables available in every context: the concatenation of
/// [`ACTIVE_VARS`], [`REPO_VARS`], and [`EXEC_BASE_VARS`].
///
/// Populated by `build_hook_context()` in `command_executor.rs`. Operation-
/// context vars (`base`, `target`, `pr_*`) and infrastructure vars
/// (`hook_type`, `hook_name`) are not in the base set — they're added per-
/// scope by `hook_extras` and the hook runner itself.
pub fn base_vars() -> Vec<&'static str> {
let mut v = Vec::with_capacity(ACTIVE_VARS.len() + REPO_VARS.len() + EXEC_BASE_VARS.len());
v.extend_from_slice(ACTIVE_VARS);
v.extend_from_slice(REPO_VARS);
v.extend_from_slice(EXEC_BASE_VARS);
v
}
/// Reserved context key carrying a JSON-encoded `Vec<String>` of positional
/// CLI args forwarded to an alias. The key flows through
/// [`TemplateContext`]'s flat string map — stable for JSON round-trips — and
/// [`expand_template`] rehydrates it as a `ShellArgs` object so bare
/// `{{ args }}` renders as a space-joined, shell-escaped string while
/// indexing, iteration, and `length` behave like a sequence.
pub const ALIAS_ARGS_KEY: &str = "args";
/// Whether a `--KEY=VALUE` token on an alias or `wt hook` command line binds
/// to `{{ KEY }}` rather than forwarding into `{{ args }}`.
///
/// `key` is the canonical (underscored) name and `referenced` the template's
/// top-level variables. `args` and `vars` are never bindable even when
/// referenced: the runtime always sets both (the positional list, the
/// per-branch vars object) after CLI bindings, so a bound value would be
/// overwritten and the token lost. Forwarding keeps it in `{{ args }}`.
pub fn binds_cli_var(key: &str, referenced: &BTreeSet<String>) -> bool {
key != ALIAS_ARGS_KEY && key != "vars" && referenced.contains(key)
}
/// Variables available in `wt list` custom-column templates (plus `vars.*`).
///
/// Deliberately narrower than [`base_vars`]: column values are computed per
/// row before the table skeleton renders, so only row-identity data that is
/// already in memory at that point is offered.
pub const LIST_COLUMN_VARS: &[&str] = &["branch", "worktree_path", "worktree_name"];
/// The resolved template variables for one command invocation.
///
/// Wraps the map `build_hook_context` produces and owns every operation on
/// it: expansion, the JSON a `wt step for-each` child reads on stdin, and the
/// `-v` variables table. Callers hold this rather than a bare map so the borrow
/// [`expand_template`] needs, the `serde_json` call, and the `(unset)` /
/// `(unused)` rendering each have one home.
///
/// Serializes transparently, so the JSON a for-each child reads and the
/// pipeline spec a background runner deserializes are both the flat
/// `{"branch": "…", …}` object the [`ALIAS_ARGS_KEY`] contract describes.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(transparent)]
pub struct TemplateContext(HashMap<String, String>);
impl TemplateContext {
/// Wrap a resolved variable map. `build_hook_context` is the producer;
/// nothing else assembles a context from scratch.
pub fn from_vars(vars: HashMap<String, String>) -> Self {
Self(vars)
}
/// Bind `key`, replacing any existing value.
pub fn insert(&mut self, key: impl Into<String>, value: impl Into<String>) {
self.0.insert(key.into(), value.into());
}
/// The value bound to `key`.
pub fn get(&self, key: &str) -> Option<&str> {
self.0.get(key).map(String::as_str)
}
/// Unbind `key`, so it renders as `(unset)` and is absent from the JSON.
pub fn remove(&mut self, key: &str) {
self.0.remove(key);
}
/// Expand `template` against these variables, escaping interpolated values
/// per `escape_mode`. `name` labels the template in errors.
pub fn expand(
&self,
template: &str,
escape_mode: ShellEscapeMode,
repo: &Repository,
name: &str,
) -> Result<String, TemplateExpandError> {
self.expand_with(template, escape_mode, repo, name, VarsMode::Resolve)
}
/// [`Self::expand`], with control over how `{{ vars.<key> }}` resolves.
pub fn expand_with(
&self,
template: &str,
escape_mode: ShellEscapeMode,
repo: &Repository,
name: &str,
vars_mode: VarsMode,
) -> Result<String, TemplateExpandError> {
let vars: HashMap<&str, &str> = self
.0
.iter()
.map(|(k, v)| (k.as_str(), v.as_str()))
.collect();
expand_template_with(template, &vars, escape_mode, repo, name, vars_mode)
}
/// The JSON form piped to a `wt step for-each` child's stdin.
pub fn to_json(&self) -> String {
serde_json::to_string(&self.0)
.expect("HashMap<String, String> serialization should never fail")
}
}
/// Which template variables a context build has to resolve.
///
/// The choice follows from who reads the finished [`TemplateContext`], not
/// from what kind of command is running — see `build_hook_context`.
#[derive(Debug, Clone, Copy)]
pub enum VarScope<'a> {
/// Only the templates read the map, so a var they don't name is never
/// looked up. The set comes from `referenced_vars_for_config` or
/// [`referenced_vars_for_templates`].
Referenced(&'a BTreeSet<String>),
/// Something reads keys the templates never mention: a `wt step for-each`
/// child consuming the JSON on stdin, or a command whose output is the
/// variable listing.
All,
}
impl VarScope<'_> {
/// Whether `key` has to be resolved.
pub fn wants(&self, key: &str) -> bool {
match self {
VarScope::All => true,
VarScope::Referenced(referenced) => referenced.contains(key),
}
}
}
/// The context in which a template will be expanded.
///
/// Validation uses this to answer "which variables are available here?" —
/// the single source of truth for hook-type-specific vars, alias-only vars,
/// and the `--execute` context. Each hook type gets the base set plus its
/// own extras (e.g., `target` for merge/remove, `base` for create/switch).
#[derive(Debug, Clone, Copy)]
pub enum ValidationScope {
/// A hook of the given type. Adds hook infrastructure vars (`hook_type`,
/// `hook_name`), hook-specific vars (`base`, `target`, etc.), and `args`.
Hook(HookType),
/// The `--execute` template or trailing args for `wt switch --create`.
/// Adds `base` / `base_worktree_path` for the source worktree.
SwitchExecute,
/// An alias body. Adds `args` for positional CLI forwarding.
Alias,
}
/// Hook-type-specific extras that sit on top of [`base_vars`].
///
/// These are the vars injected by callers via `extra_vars` when running a
/// hook. Keeping the mapping in one place means "which vars work in a
/// `post-merge` hook?" is answerable without chasing inline comments.
///
/// Each arm's order must be a prefix-ordered subset of the operation-context
/// block in the user-facing help table (`src/cli/mod.rs`, `## Template
/// variables`): `base, base_worktree_path, target, target_worktree_path,
/// pr_number, pr_url`.
fn hook_extras(hook_type: HookType) -> &'static [&'static str] {
use HookType::*;
match hook_type {
// Switch: source branch (`base`) and destination (`target`).
// `pr_number`/`pr_url` are populated whenever the switch was named by
// `pr:N` / `mr:N` — the forge answers before `pre-switch` runs, so
// both hooks see the same values.
PreSwitch | PostSwitch => &[
"base",
"base_worktree_path",
"target",
"target_worktree_path",
"pr_number",
"pr_url",
],
// Create: source worktree (`base`) and newly-created destination
// (`target`). On create, the destination branch equals the bare `branch`
// var — `target` is accepted for template portability with switch hooks.
// `pr_number`/`pr_url` are populated when creating via `pr:N` / `mr:N`
// (GitLab MRs reuse the same `pr_*` names).
PreCreate | PostCreate => &[
"base",
"base_worktree_path",
"target",
"target_worktree_path",
"pr_number",
"pr_url",
],
// Commit: integration target for the pre-commit squash.
PreCommit | PostCommit => &["target"],
// Merge: where the feature is being merged into.
PreMerge | PostMerge => &["target", "target_worktree_path"],
// Remove: where the user ends up after removal.
PreRemove | PostRemove => &["target", "target_worktree_path"],
}
}
/// Vars added by the hook execution infrastructure itself (`prepare_steps`),
/// regardless of hook type.
const HOOK_INFRASTRUCTURE_VARS: &[&str] = &["hook_type", "hook_name"];
/// All template variables available in a given scope.
///
/// The returned list is [`base_vars`] + scope-specific extras. Used by
/// [`validate_template`] to build the placeholder context and by error
/// messages to list what the user could have typed. Retired names
/// (`repo_root`, `worktree`, …) are absent: the deprecation layer renames them
/// before serde parses the config, so a template reaching here carries only
/// current names, and one typed on the command line gets the undefined-variable
/// error with this list attached.
pub fn vars_available_in(scope: ValidationScope) -> Vec<&'static str> {
let mut vars: Vec<&'static str> = base_vars();
match scope {
ValidationScope::Hook(hook_type) => {
vars.extend(HOOK_INFRASTRUCTURE_VARS);
vars.extend(hook_extras(hook_type));
vars.push(ALIAS_ARGS_KEY);
}
ValidationScope::SwitchExecute => {
vars.extend(["base", "base_worktree_path"]);
}
ValidationScope::Alias => {
vars.push(ALIAS_ARGS_KEY);
}
}
vars
}
/// Whether `name` is a variable Worktrunk supplies in some scope.
fn is_worktrunk_var(name: &str) -> bool {
use strum::IntoEnumIterator;
HookType::iter().any(|hook| vars_available_in(ValidationScope::Hook(hook)).contains(&name))
}
/// Cheap vars `build_hook_context` computes regardless of [`VarScope`] but
/// which can still come out absent, so their absence is `(unset)` — a fact
/// about the worktree — rather than `(unused)`, which claims the scope gate
/// skipped the work. `branch` is absent in a detached worktree.
const ALWAYS_COMPUTED_VARS: &[&str] = &["branch"];
/// Shared formatter for [`format_hook_variables`] and [`format_alias_variables`].
///
/// Renders `vars` as an aligned `name = value` block — no heading, no indent,
/// caller wraps. Values come from `ctx`; vars absent from `ctx` render as
/// `(unset)`, surfacing operation-specific gaps (e.g., `target_worktree_path`
/// during `wt switch -`, `upstream` when the branch doesn't track a remote).
///
/// When `referenced` is `Some`, vars absent from `ctx` *and* not in the set
/// render as dim `(unused)` — `build_hook_context` only skips computation for
/// expensive vars, so this fires precisely when the gate saved real work.
/// Cheap vars are populated unconditionally, so they show their value even
/// when the body doesn't reference them — though a cheap var can still come
/// out absent. `(unset)` is reserved for the distinct case of a var the
/// operation couldn't supply — including [`ALWAYS_COMPUTED_VARS`], the cheap
/// vars that are computed whatever the scope but can still be genuinely
/// absent.
///
/// `(unset)` relies on an invariant in `build_hook_context` that the
/// `extra_vars` layered on top must hold too (see
/// `PostRemoveContext::extra_vars`): optional vars are omitted from the map
/// rather than inserted as empty strings. If a future caller starts inserting
/// `""`, revisit the empty-vs-absent distinction here.
fn format_variables_table(
vars: &[&'static str],
ctx: &TemplateContext,
scope: VarScope<'_>,
) -> String {
let max_name = vars.iter().map(|v| v.len()).max().unwrap_or(0);
vars.iter()
.map(|var| match ctx.get(var) {
Some(value) => format!("{var:<max_name$} = {value}"),
None if !scope.wants(var) && !ALWAYS_COMPUTED_VARS.contains(var) => {
cformat!("<dim>{var:<max_name$} = (unused)</>")
}
None => format!("{var:<max_name$} = (unset)"),
})
.collect::<Vec<_>>()
.join("\n")
}
/// Format the resolved template variables for a hook invocation.
///
/// Ordered per the `## Template variables` help table in `src/cli/mod.rs`:
/// active, operation, repo, exec, infrastructure.
///
/// Deprecated aliases and `vars.*` (user state) are intentionally omitted.
pub fn format_hook_variables(hook_type: HookType, ctx: &TemplateContext) -> String {
let vars: Vec<&'static str> = ACTIVE_VARS
.iter()
.chain(hook_extras(hook_type))
.chain(REPO_VARS)
.chain(EXEC_BASE_VARS)
.chain(HOOK_INFRASTRUCTURE_VARS)
.copied()
.collect();
format_variables_table(&vars, ctx, VarScope::All)
}
/// Format the resolved template variables for an alias invocation.
///
/// Ordering mirrors [`format_hook_variables`]; alias scope has no operation
/// or infrastructure vars, and `args` lives in the exec group per the help
/// table in `src/cli/mod.rs` (alongside `cwd`).
///
/// `args` is stored as a JSON-encoded `Vec<String>` per the [`ALIAS_ARGS_KEY`]
/// contract; the table displays it space-joined and shell-escaped so it
/// matches what `{{ args }}` substitutes in templates.
///
/// `scope` is the one the context was built with, so vars it skipped render as
/// dim `(unused)` — the reader sees what's reachable without paying for values
/// the body won't substitute.
pub fn format_alias_variables(ctx: &TemplateContext, scope: VarScope<'_>) -> String {
let vars: Vec<&'static str> = ACTIVE_VARS
.iter()
.copied()
.chain(REPO_VARS.iter().copied())
.chain(EXEC_BASE_VARS.iter().copied())
.chain(std::iter::once(ALIAS_ARGS_KEY))
.collect();
let mut display_ctx = ctx.clone();
if let Some(json) = ctx.get(ALIAS_ARGS_KEY) {
let args: Vec<String> = serde_json::from_str(json)
.expect("ALIAS_ARGS_KEY is always serialized from a Vec<String>");
display_ctx.insert(ALIAS_ARGS_KEY, shell_join(&args));
}
format_variables_table(&vars, &display_ctx, scope)
}
/// Format the resolved template variables for a bare template expansion
/// (`wt step eval`), whose scope is exactly [`base_vars`] — no hook operation
/// or infrastructure vars, no alias `args`.
///
/// Same curated ordering and `(unset)` treatment as [`format_hook_variables`],
/// so the four `-v` variable listings (hook foreground, hook background, alias,
/// eval) render one family.
pub fn format_base_variables(ctx: &TemplateContext) -> String {
format_variables_table(&base_vars(), ctx, VarScope::All)
}
/// Extend `referenced` with the implicit context-map keys an alias dispatch
/// needs:
///
/// - [`ALIAS_ARGS_KEY`] (`args`) — always present in alias scope (`run_alias`
/// inserts it after `build_hook_context`), so include it so the verbose
/// table renders the row.
/// - `branch` when the body references `vars` — `expand_template` reads
/// `branch` out of the context map to look up `{{ vars.X }}` from git
/// config at execution time. Bare `{{ vars }}`, `{{ vars.X }}`, and
/// `{{ vars["X"] }}` all surface `vars` in `undeclared_variables`.
///
/// New implicit dependencies (template-level reads from the context map that
/// `undeclared_variables` doesn't see) belong here, not at each call site.
pub fn alias_context_filter(mut referenced: BTreeSet<String>) -> BTreeSet<String> {
let needs_branch = referenced.contains("vars");
referenced.insert(ALIAS_ARGS_KEY.to_string());
if needs_branch {
referenced.insert("branch".to_string());
}
referenced
}
/// Positional CLI args forwarded from `wt <alias> a b c` into the alias's
/// template context. Bare `{{ args }}` renders as a space-joined,
/// shell-escaped string ready to append to a command line; `{{ args[0] }}`
/// and `{% for a in args %}…{% endfor %}` and `{{ args | length }}` all
/// behave as expected because the object reports as an
/// [`ObjectRepr::Seq`].
///
/// Shell escaping happens at render time via POSIX [`shell_escape_for`]
/// rather than through the template environment's formatter — the formatter
/// would otherwise quote the already-escaped joined string as a whole. The
/// formatter installed by `expand_template` detects `ShellArgs` and writes
/// it through unmodified.
///
/// `args` exists only in alias scope, whose bodies always run through
/// `Cmd::shell` (POSIX) — so this rendering is unconditionally POSIX,
/// independent of the user's interactive shell.
#[derive(Debug)]
struct ShellArgs(Vec<String>);
impl ShellArgs {
fn new(args: Vec<String>) -> Self {
Self(args)
}
}
impl Object for ShellArgs {
fn repr(self: &Arc<Self>) -> ObjectRepr {
ObjectRepr::Seq
}
fn get_value(self: &Arc<Self>, key: &Value) -> Option<Value> {
let idx = key.as_usize()?;
self.0.get(idx).cloned().map(Value::from)
}
fn enumerate(self: &Arc<Self>) -> Enumerator {
Enumerator::Seq(self.0.len())
}
fn render(self: &Arc<Self>, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(&shell_join(&self.0))
}
}
/// Stands in for the `vars` map in a preview, rendering each reference back as
/// the `{{ vars.<path> }}` that produced it.
///
/// A preview shows what a command *will* run, and `vars.*` values are read from
/// git config when the step runs — after any earlier step in the pipeline has
/// written them. Resolving one at preview time would show a value the run may
/// not use, so the reference stands for itself while everything around it
/// expands normally.
///
/// Each key access returns another `LiteralVars` carrying the path so far, so
/// nested access (`{{ vars.config.port }}`) round-trips too. The formatter
/// installed by `expand_template` writes it through unescaped, as it does
/// `ShellArgs`.
#[derive(Debug)]
struct LiteralVars(String);
impl Object for LiteralVars {
fn get_value(self: &Arc<Self>, key: &Value) -> Option<Value> {
Some(Value::from_object(LiteralVars(format!("{}.{key}", self.0))))
}
fn render(self: &Arc<Self>, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{{{{ {} }}}}", self.0)
}
}
/// How template expansion resolves `{{ vars.<key> }}`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum VarsMode {
/// Read values from git config — what a command runs with.
Resolve,
/// Render each reference back as `{{ vars.<key> }}`, for a preview.
Literal,
}
/// Space-join POSIX-shell-escaped args — the canonical rendering of
/// `{{ args }}` used by both `ShellArgs::render` (template expansion) and the
/// alias `-v` variable table. Always POSIX: see [`ShellArgs`].
fn shell_join(args: &[String]) -> String {
args.iter()
.map(|a| shell_escape_for(ShellEscapeMode::Posix, a))
.collect::<Vec<_>>()
.join(" ")
}
/// Hash a string to a port in range 10000-19999.
fn string_to_port(s: &str) -> u16 {
let mut h = std::collections::hash_map::DefaultHasher::new();
s.hash(&mut h);
10000 + (h.finish() % 10000) as u16
}
const CODENAME_MAX_WORDS: usize = 8;
/// Wordlists used by [`codename`].
///
/// Sourced from `petname::Petnames::medium()` (1198 adjectives, 1052 nouns —
/// ~1.26M `codename(2)` combinations, ~1.5B for `codename(3)`). The pin in
/// `Cargo.toml` is `=3.0.0`; bumping it may change, add, or remove words and
/// would silently shift every existing user's `worktree-path` output. Treat
/// any upgrade as a breaking change — see `test_codename_outputs_are_stable`.
///
/// `petname::Petnames::medium()` is effectively free — its `Cow::Borrowed`
/// fields point at static slices embedded by the `petnames!` macro — so
/// re-constructing per call is cheaper than reaching for a `OnceLock`.
fn codename_words() -> petname::Petnames<'static> {
petname::Petnames::medium()
}
/// Sanitize a branch name for use in filesystem paths.
///
/// Replaces path separators (`/` and `\`) with dashes to prevent directory traversal
/// and ensure the branch name is a single path component.
///
/// # Examples
/// ```
/// use worktrunk::config::sanitize_branch_name;
///
/// assert_eq!(sanitize_branch_name("feature/foo"), "feature-foo");
/// assert_eq!(sanitize_branch_name("user\\task"), "user-task");
/// assert_eq!(sanitize_branch_name("simple-branch"), "simple-branch");
/// ```
pub fn sanitize_branch_name(branch: &str) -> String {
branch.replace(['/', '\\'], "-")
}
/// Sanitize a string for use as a database identifier.
///
/// Transforms input into an identifier compatible with most SQL databases
/// (PostgreSQL, MySQL, SQL Server). The transformation is more aggressive than
/// `sanitize_branch_name` to ensure compatibility with database identifier rules.
///
/// # Transformation Rules (applied in order)
/// 1. Convert to lowercase (ensures portability across case-sensitive systems)
/// 2. Replace non-alphanumeric characters with `_` (only `[a-z0-9_]` are safe)
/// 3. Collapse consecutive underscores into single underscore
/// 4. Add `_` prefix if identifier starts with a digit (SQL prohibits leading digits)
/// 5. Append 3-character hash suffix for uniqueness (avoids reserved words and collisions)
/// 6. Truncate to 48 characters total (well within PostgreSQL's 63-char identifier
/// limit, leaving room for prefixes/suffixes when composing paths or identifiers)
///
/// The hash suffix ensures that:
/// - SQL reserved words are avoided (e.g., `user` → `user_abc`, not a reserved word)
/// - Different inputs don't collide (e.g., `a-b` and `a_b` get different suffixes)
///
/// # Limitations
/// - Empty input produces empty output (not a valid identifier in most DBs)
///
/// # Examples
/// ```
/// use worktrunk::config::sanitize_db;
///
/// // Hash suffix ensures uniqueness
/// assert!(sanitize_db("feature/auth").starts_with("feature_auth_"));
/// assert!(sanitize_db("123-bug-fix").starts_with("_123_bug_fix_"));
/// assert!(sanitize_db("UPPERCASE.Branch").starts_with("uppercase_branch_"));
///
/// // Different inputs get different suffixes even if base transforms are identical
/// assert_ne!(sanitize_db("a-b"), sanitize_db("a_b"));
/// ```
pub fn sanitize_db(s: &str) -> String {
if s.is_empty() {
return String::new();
}
// Single pass: lowercase, replace non-alphanumeric with underscore, collapse consecutive
let mut result = String::with_capacity(s.len() + 4); // +4 for _xxx suffix
let mut prev_underscore = false;
for c in s.chars() {
if c.is_ascii_alphanumeric() {
result.push(c.to_ascii_lowercase());
prev_underscore = false;
} else if !prev_underscore {
result.push('_');
prev_underscore = true;
}
}
// Prefix with underscore if starts with digit
if result.starts_with(|c: char| c.is_ascii_digit()) {
result.insert(0, '_');
}
// Truncate base to leave room for hash suffix (4 chars: _ + 3 hash chars).
// Total cap is 48 chars (well within PostgreSQL's 63-char identifier limit),
// so max base is 44.
if result.len() > 44 {
result.truncate(44);
}
// Append 3-character hash suffix for collision avoidance and reserved word safety
// Hash is computed from original input, ensuring unique suffixes for colliding transforms
if !result.ends_with('_') {
result.push('_');
}
result.push_str(&short_hash(s));
result
}
/// Generate a 3-character hash suffix from a string.
///
/// Uses base36 (0-9, a-z) for a compact representation with 46,656 unique values.
/// Used by `sanitize_db` and `sanitize_for_filename` to avoid collisions.
pub fn short_hash(s: &str) -> String {
let mut h = std::collections::hash_map::DefaultHasher::new();
s.hash(&mut h);
let hash = h.finish();
// Convert to base36 and take 3 characters
const CHARS: &[u8] = b"0123456789abcdefghijklmnopqrstuvwxyz";
let c0 = CHARS[(hash % 36) as usize];
let c1 = CHARS[((hash / 36) % 36) as usize];
let c2 = CHARS[((hash / 1296) % 36) as usize];
String::from_utf8(vec![c0, c1, c2]).unwrap()
}
fn codename_index(input: &str, position: usize, salt: usize, pool: &str, len: usize) -> usize {
// Cast to a fixed-width type so the hash is identical across 32-bit and
// 64-bit builds. `usize::to_le_bytes` is architecture-dependent and would
// change the on-disk codename for the same branch when users move between
// architectures.
let mut hasher = Sha256::new();
hasher.update(input.as_bytes());
hasher.update([0]);
hasher.update((position as u64).to_le_bytes());
hasher.update((salt as u64).to_le_bytes());
hasher.update(pool.as_bytes());
let digest = hasher.finalize();
let mut bytes = [0_u8; 8];
bytes.copy_from_slice(&digest[..8]);
// Take the modulo in u64 before narrowing — `as usize` on a 32-bit
// build truncates the upper 32 bits and would pick a different word
// than 64-bit for the same branch, defeating the whole point of
// hashing through a fixed-width type above.
(u64::from_le_bytes(bytes) % len as u64) as usize
}
fn codename(input: &str, words: usize) -> String {
let lists = codename_words();
let adjectives: &[&str] = lists.adjectives.as_ref();
let nouns: &[&str] = lists.nouns.as_ref();
let mut parts = Vec::with_capacity(words);
let adjective_count = words.saturating_sub(1);
for position in 0..adjective_count {
let mut salt = 0;
loop {
let index = codename_index(input, position, salt, "adjective", adjectives.len());
let word = adjectives[index];
if !parts.contains(&word) || salt >= adjectives.len() {
parts.push(word);
break;
}
salt += 1;
}
}
let index = codename_index(input, adjective_count, 0, "noun", nouns.len());
parts.push(nouns[index]);
parts.join("-")
}
fn invalid_filter_arg(message: impl Into<String>) -> minijinja::Error {
minijinja::Error::new(ErrorKind::InvalidOperation, message.into())
}
fn codename_filter(
state: &State,
value: Value,
words: Option<usize>,
) -> Result<String, minijinja::Error> {
let words = words.unwrap_or(2);
if words == 0 || words > CODENAME_MAX_WORDS {
return Err(invalid_filter_arg(format!(
"codename word count must be between 1 and {CODENAME_MAX_WORDS}"
)));
}
Ok(codename(filter_string(state, &value)?, words))
}
/// Redact credentials from URLs for safe logging.
///
/// URLs with embedded credentials (e.g., `https://[email protected]/...`) have
/// the credential portion replaced with `[REDACTED]`.
///
/// # Examples
/// ```
/// use worktrunk::config::redact_credentials;
///
/// // URLs with credentials are redacted
/// assert_eq!(
/// redact_credentials("https://[email protected]/owner/repo"),
/// "https://[REDACTED]@github.com/owner/repo"
/// );
///
/// // URLs without credentials are unchanged
/// assert_eq!(
/// redact_credentials("https://github.com/owner/repo"),
/// "https://github.com/owner/repo"
/// );
///
/// // Non-URL values pass through unchanged
/// assert_eq!(redact_credentials("main"), "main");
/// ```
pub fn redact_credentials(s: &str) -> String {
// Pattern: scheme://credentials@host where credentials don't contain @
// This matches URLs like https://[email protected] or https://user:[email protected]
thread_local! {
static CREDENTIAL_URL: Regex = Regex::new(r"^([a-z][a-z0-9+.-]*://)([^@/]+)@").unwrap();
}
CREDENTIAL_URL.with(|re| re.replace(s, "${1}[REDACTED]@").into_owned())
}
/// Error from template expansion with rich context for diagnostics.
///
/// Produced by [`expand_template`] when a template fails to parse or render.
/// Contains structured data for styled display in `main.rs` (via downcast)
/// and a `message` field for callers that embed errors in other output.
#[derive(Debug)]
pub struct TemplateExpandError {
/// Plain-text error summary for callers that embed errors in styled messages.
pub message: String,
/// The failing template line, when identifiable.
pub source_line: Option<String>,
/// Variable names available in this template context.
pub available_vars: Vec<String>,
/// Closest available variable, when a missing name is identifiable.
pub suggestion: Option<String>,
}
impl std::fmt::Display for TemplateExpandError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(&self.message)
}
}
impl Diagnostic for TemplateExpandError {
fn render(&self) -> String {
let mut parts = vec![error_message(&self.message).to_string()];
if let Some(ref line) = self.source_line {
parts.push(format_with_gutter(line, None));
}
if let Some(ref suggestion) = self.suggestion {
parts.push(
hint_message(cformat!("Did you mean <underline>{suggestion}</>?")).to_string(),
);
}
if !self.available_vars.is_empty() {
let underlined_vars: Vec<String> = self
.available_vars
.iter()
.map(|v| cformat!("<underline>{}</>", v))
.collect();
parts.push(
hint_message(cformat!(
"Available variables: {}",
underlined_vars.join(", ")
))
.to_string(),
);
}
parts.join("\n")
}
}
impl std::error::Error for TemplateExpandError {}
/// Keep MiniJinja's error detail and failing source line in the CLI diagnostic.
fn build_template_error(
e: &minijinja::Error,
template: &str,
name: &str,
available_vars: Vec<String>,
) -> TemplateExpandError {
let lines: Vec<&str> = template.lines().collect();
let line_num = e.line();
let source_line =
line_num.and_then(|n| lines.get(n.saturating_sub(1)).copied().map(String::from));
let is_undefined = e.kind() == ErrorKind::UndefinedError;
let detail = match e.detail() {
Some(detail) => format!("{}: {detail}", e.kind()),
None => e.kind().to_string(),
};
// minijinja always provides a line number for syntax and render errors
let message = match line_num {
Some(n) => format!("Failed to expand {name}: {detail} @ line {n}"),
None => format!("Failed to expand {name}: {detail}"),
};
TemplateExpandError {
message,
source_line,
// Only show available vars for undefined errors (actionable hint)
available_vars: if is_undefined {
available_vars
} else {
Vec::new()
},
suggestion: None,
}
}
fn sorted_available_vars(vars: &[&str]) -> Vec<String> {
let mut keys: Vec<String> = vars.iter().map(|k| k.to_string()).collect();
keys.sort();
keys.dedup();
keys
}
fn build_undefined_vars_error(
name: &str,
undefined_vars: &[String],
available_vars: Vec<String>,
template: &str,
line_num: Option<usize>,
) -> TemplateExpandError {
let names = undefined_vars.join(", ");
let noun = if undefined_vars.len() == 1 {
"variable"
} else {
"variables"
};
// A name Worktrunk defines somewhere is unset here, not misspelled, so a
// similar name (`target_worktree_path` for `target`) would mislead.
let suggestion = match undefined_vars {
[var] if !is_worktrunk_var(var) => did_you_mean(var, available_vars.iter().cloned())
.into_iter()
.next(),
_ => None,
};
let location = line_num
.map(|line| format!(" @ line {line}"))
.unwrap_or_default();
TemplateExpandError {
message: format!("Failed to expand {name}: undefined {noun} {names}{location}"),
source_line: match line_num {
Some(line) => template
.lines()
.nth(line.saturating_sub(1))
.map(String::from),
None => (!template.contains('\n')).then(|| template.to_string()),
},
available_vars,
suggestion,
}
}
/// Apply the engine's undefined-input policy while preserving the filters'
/// existing treatment of defined non-string values as empty strings.
fn filter_string<'a>(state: &State, value: &'a Value) -> Result<&'a str, minijinja::Error> {
StringInput::new(state, value)?;
Ok(value.as_str().unwrap_or_default())
}
/// Set up a minijinja environment with worktrunk's custom filters and functions.
///
/// Shared by [`expand_template`], [`validate_template`], and the `wt list`
/// custom-column renderer (which holds one environment across all rows) so
/// every template user gets the same filters, functions, and
/// undefined-behavior settings.
pub fn template_environment(repo: &Repository) -> Environment<'static> {
let mut env = Environment::new();
// SemiStrict: errors on undefined variable use (printing, iteration) but allows
// truthiness checks ({% if var %}). This catches typos while supporting optional vars.
env.set_undefined_behavior(UndefinedBehavior::SemiStrict);
// MiniJinja picks HTML or JSON escaping from the template name's extension,
// and our names are config keys (a custom column named `json` or `html`),
// not file names.
env.set_auto_escape_callback(|_| AutoEscape::None);
// Register custom filters
env.add_filter("sanitize", |state: &State, value: Value| {
Ok::<_, minijinja::Error>(sanitize_branch_name(filter_string(state, &value)?))
});
env.add_filter("sanitize_db", |state: &State, value: Value| {
Ok::<_, minijinja::Error>(sanitize_db(filter_string(state, &value)?))
});
env.add_filter("sanitize_hash", |state: &State, value: Value| {
Ok::<_, minijinja::Error>(crate::path::sanitize_for_filename(filter_string(
state, &value,
)?))
});
env.add_filter("hash", |state: &State, value: Value| {
Ok::<_, minijinja::Error>(short_hash(filter_string(state, &value)?))
});
env.add_filter("hash_port", |value: String| string_to_port(&value));
env.add_filter("dirname", |state: &State, value: Value| {
Ok::<_, minijinja::Error>(
std::path::Path::new(filter_string(state, &value)?)
.parent()
.map(|p| to_posix_path(&p.to_string_lossy()))
.unwrap_or_default(),
)
});
env.add_filter("basename", |state: &State, value: Value| {
Ok::<_, minijinja::Error>(
std::path::Path::new(filter_string(state, &value)?)
.file_name()
.map(|n| n.to_string_lossy().into_owned())
.unwrap_or_default(),
)
});
env.add_filter("codename", codename_filter);
// MiniJinja's `tojson` writes an undefined value as `null`. Fail on it as
// printing does, so a missing `vars` key errors instead of sending `null`.
env.add_filter(
"tojson",
|state: &State, value: Value, indent: Option<Value>, kwargs: Kwargs| {
if value.is_undefined() {
StringInput::new(state, &value)?;
}
minijinja::filters::tojson(&value, indent, kwargs)
},
);
// Register worktree_path_of_branch function for looking up branch worktree paths.
// Returns raw paths — shell escaping is applied by the formatter at output time.
let repo_clone = repo.clone();
env.add_function("worktree_path_of_branch", move |branch: String| -> String {
repo_clone
.worktree_for_branch(&branch)
.ok()
.flatten()
.map(|p| to_posix_path(&p.to_string_lossy()))
.unwrap_or_default()
});
// Register expected_worktree_path_of_branch: where `wt switch --create` would put a
// branch's worktree, whether or not one exists there. Rendering the
// `worktree-path` template re-enters this environment, so a template
// that calls the function errors rather than recursing.
let repo_clone = repo.clone();
env.add_function(
"expected_worktree_path_of_branch",
move |branch: String| -> Result<String, minijinja::Error> {
thread_local! {
static IN_EXPECTED_WORKTREE_PATH_OF_BRANCH: std::cell::Cell<bool> =
const { std::cell::Cell::new(false) };
}
if IN_EXPECTED_WORKTREE_PATH_OF_BRANCH.replace(true) {
return Err(minijinja::Error::new(
ErrorKind::InvalidOperation,
"expected_worktree_path_of_branch cannot be used in the worktree-path template",
));
}
let result = repo_clone
.user_config()
.expected_worktree_path(&repo_clone, &branch);
IN_EXPECTED_WORKTREE_PATH_OF_BRANCH.set(false);
result
.map(|p| to_posix_path(&p.to_string_lossy()))
.map_err(|e| minijinja::Error::new(ErrorKind::InvalidOperation, format!("{e:#}")))
},
);
env
}
/// 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`. Templates that fail
/// to parse contribute nothing — a syntax error surfaces later at expansion
/// time with a richer message.
fn referenced_vars(template: &str) -> BTreeSet<String> {
minijinja::Environment::new()
.template_from_str(template)
.map(|tmpl| tmpl.undeclared_variables(false).into_iter().collect())
.unwrap_or_default()
}
/// Check if a template references a specific top-level variable.
pub fn template_references_var(template: &str, var: &str) -> bool {
referenced_vars(template).contains(var)
}
/// Union of top-level variables referenced across `templates`.
///
/// Builds the `referenced` filter for `build_hook_context` at sites that expand
/// bare template strings rather than a
/// [`CommandConfig`](super::CommandConfig) — currently `wt switch --execute`,
/// whose command and trailing args are two separate expansion positions over
/// one shared context map.
///
/// Non-erroring, unlike `referenced_vars_for_config`: an unparsable template
/// contributes nothing, and its syntax error surfaces from the caller's own
/// validation, which names the position at fault. Under-collecting is
/// therefore harmless — the vars a broken template named are ones it never
/// gets to read.
pub fn referenced_vars_for_templates<'a>(
templates: impl IntoIterator<Item = &'a str>,
) -> BTreeSet<String> {
templates.into_iter().flat_map(referenced_vars).collect()
}
/// 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 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.
/// `label` identifies the failing command in the error, so hooks can retain
/// their source, type and optional command name while aliases keep their alias
/// name. The error matches [`expand_template`]'s parse-failure shape.
pub fn referenced_vars_for_config(
cfg: &super::CommandConfig,
label: impl Fn(Option<&str>) -> String,
) -> anyhow::Result<BTreeSet<String>> {
let env = minijinja::Environment::new();
let mut out = BTreeSet::new();
for cmd in cfg.commands() {
let tmpl = env.template_from_str(&cmd.template).map_err(|e| {
build_template_error(&e, &cmd.template, &label(cmd.name.as_deref()), Vec::new())
})?;
out.extend(tmpl.undeclared_variables(false));
}
Ok(out)
}
/// Parse-only syntax check for a template.
///
/// Every path that runs hooks calls this on each template, via
/// `PreparedPipeline::validated`, so syntax errors (e.g. `{{ vars..foo }}`) abort
/// before the first pipeline step runs; rendering — and with it semantic errors
/// like undefined variables — is deferred to execution time. Alias dispatch has
/// already parsed each template for argument routing by then, so it skips the
/// check. The error matches [`expand_template`]'s
/// parse-failure shape so syntax errors render identically wherever they
/// surface.
pub fn validate_template_syntax(template: &str, name: &str) -> Result<(), TemplateExpandError> {
minijinja::Environment::new()
.template_from_named_str(name, template)
.map(|_| ())
.map_err(|e| build_template_error(&e, template, name, Vec::new()))
}
/// Validate that a template can be expanded without errors in the given scope.
///
/// Checks syntax and top-level variable references against [`vars_available_in`]
/// and environment globals, then trial-renders with placeholder context values.
///
/// This is deliberately more permissive than real expansion: conditional vars
/// like `upstream` are provided even when they may be absent at runtime. A
/// template like `{{ upstream }}` passes validation but could fail later if
/// tracking isn't configured — the alternative (predicting which optional
/// variables will be available) would be fragile and context-dependent.
///
/// No verbose logging is performed — this is a pre-flight check, not the real expansion.
pub fn validate_template(
template: &str,
scope: ValidationScope,
repo: &Repository,
name: &str,
) -> Result<(), TemplateExpandError> {
let available = vars_available_in(scope);
let mut context: HashMap<String, minijinja::Value> = available
.iter()
.filter(|&&k| k != ALIAS_ARGS_KEY)
.map(|&k| (k.to_string(), minijinja::Value::from("PLACEHOLDER")))
.collect();
// Inject vars as empty map so {{ vars.key | default(...) }} doesn't error
context.insert(
"vars".to_string(),
minijinja::Value::from(std::collections::BTreeMap::<String, String>::new()),
);
// In alias and hook scopes, inject `args` as an empty sequence so
// `{{ args }}`, `{{ args[0] | default(...) }}`, `{{ args | length }}`,
// and `{% for a in args %}…{% endfor %}` all validate.
if matches!(scope, ValidationScope::Alias | ValidationScope::Hook(_)) {
context.insert(
ALIAS_ARGS_KEY.to_string(),
Value::from_object(ShellArgs::new(Vec::new())),
);
}
let env = template_environment(repo);
let tmpl = env
.template_from_named_str(name, template)
.map_err(|e| build_template_error(&e, template, name, Vec::new()))?;
let mut allowed: BTreeSet<String> = available.iter().map(|k| k.to_string()).collect();
allowed.insert("vars".to_string());
let mut undefined: Vec<String> = tmpl
.undeclared_variables(false)
.into_iter()
.filter(|var| !allowed.contains(var) && env.globals().all(|(key, _)| key != var))
.collect();
undefined.sort();
if !undefined.is_empty() {
return Err(build_undefined_vars_error(
name,
&undefined,
sorted_available_vars(&available),
template,
None,
));
}
tmpl.render(minijinja::Value::from_object(context))
.map_err(|e| build_template_error(&e, template, name, sorted_available_vars(&available)))?;
Ok(())
}
/// Expand a template with variable substitution.
///
/// # Arguments
/// * `template` - Template string using Jinja2 syntax (e.g., `{{ branch }}`)
/// * `vars` - Variables to substitute
/// * `escape_mode` - How to escape interpolated values:
/// - [`ShellEscapeMode::Posix`] — escape for safe splicing into a command
/// line passed to `Cmd::shell` (hooks and aliases).
/// - [`ShellEscapeMode::Literal`] — substitute values verbatim (filesystem
/// paths and `--execute` argv elements).
/// * `repo` - Repository for looking up worktree paths
///
/// # Filters
/// - `sanitize` — Replace `/` and `\` with `-` for filesystem-safe paths
/// - `sanitize_db` — Transform to database-safe identifier (`[a-z0-9_]`, max 48 chars)
/// - `sanitize_hash` — Filesystem-safe name with hash suffix so distinct inputs never collide
/// - `hash` — 3-character base36 hash digest of the input
/// - `hash_port` — Hash to deterministic port number (10000-19999)
/// - `dirname` — Strip the last path component (e.g., `/a/b/c` → `/a/b`)
/// - `basename` — Keep only the last path component (e.g., `/a/b/c` → `c`)
/// - `codename(n)` — deterministic friendly words, e.g. `malleable-opah`
///
/// # Functions
/// - `worktree_path_of_branch(branch)` — Look up the filesystem path of a branch's worktree
/// Returns empty string if branch has no worktree.
/// - `expected_worktree_path_of_branch(branch)` — Where `wt switch` expects the branch's worktree,
/// from the `worktree-path` template. Returns the path whether or not it exists.
///
/// The `name` parameter appears in error messages to help identify which template failed.
pub fn expand_template(
template: &str,
vars: &HashMap<&str, &str>,
escape_mode: ShellEscapeMode,
repo: &Repository,
name: &str,
) -> Result<String, TemplateExpandError> {
expand_template_with(template, vars, escape_mode, repo, name, VarsMode::Resolve)
}
/// [`expand_template`], with control over how `{{ vars.<key> }}` resolves.
///
/// Previews pass [`VarsMode::Literal`] so a `vars.*` reference renders back as
/// itself while every other variable expands; execution passes
/// [`VarsMode::Resolve`].
pub fn expand_template_with(
template: &str,
vars: &HashMap<&str, &str>,
escape_mode: ShellEscapeMode,
repo: &Repository,
name: &str,
vars_mode: VarsMode,
) -> Result<String, TemplateExpandError> {
// Build context map with raw values (shell escaping is applied at output time via formatter).
// The `args` key is reserved: run_alias encodes positional CLI args as a JSON list string,
// and we rehydrate it here as a `ShellArgs` object so `{{ args }}` behaves sequence-like.
let mut context = HashMap::new();
for (key, value) in vars {
if *key == ALIAS_ARGS_KEY {
let parsed: Vec<String> = serde_json::from_str(value).unwrap_or_default();
context.insert(key.to_string(), Value::from_object(ShellArgs::new(parsed)));
} else {
context.insert(
key.to_string(),
minijinja::Value::from((*value).to_string()),
);
}
}
let mut env = template_environment(repo);
if escape_mode != ShellEscapeMode::Literal {
// Preserve trailing newlines in templates (important for multiline shell commands)
let syntax = env
.syntax()
.to_builder()
.keep_trailing_newline(true)
.build()
.map_err(|e| build_template_error(&e, template, name, Vec::new()))?;
env.set_syntax(syntax);
// Shell-escape values at output time, not before template rendering.
// This ensures filters (sanitize, sanitize_db, etc.) operate on raw values
// and the escaping is applied to the final output, preventing corruption
// when filters modify already-escaped strings.
env.set_formatter(move |out, _state, value| {
if value.is_none() {
return Ok(());
}
// ShellArgs renders each element pre-escaped and space-joined
// (see [`ShellArgs::render`]); passing through its Display
// output avoids re-escaping the whole joined string as one
// opaque token. Iteration and indexing yield plain string
// values that still flow through the generic escape branch.
// `LiteralVars` renders the `{{ vars.<key> }}` reference itself,
// which must reach the preview unquoted.
if value.downcast_object_ref::<ShellArgs>().is_some()
|| value.downcast_object_ref::<LiteralVars>().is_some()
{
write!(out, "{value}")?;
return Ok(());
}
let escaped = shell_escape_for(escape_mode, &value.to_string());
write!(out, "{escaped}")?;
Ok(())
});
}
// Cache verbosity level for consistent behavior within this call
let verbose = verbosity();
// -vv: Full debug logging with vars
// Redact credentials from values to prevent leaking tokens in logs
if verbose >= 2 {
tracing::debug!(name = %name, template = ?template, "[template:{name}] template={template:?}");
// Sort keys for deterministic output in tests
let mut sorted_vars: Vec<_> = vars.iter().collect();
sorted_vars.sort_by_key(|(k, _)| *k);
tracing::debug!(
name = %name,
"[template:{name}] vars={{{}}}",
sorted_vars
.iter()
.map(|(k, v)| format!("{k}={:?}", redact_credentials(v)))
.collect::<Vec<_>>()
.join(", ")
);
}
// Parse errors are always SyntaxError, never UndefinedError — no need for available_vars
let tmpl = env
.template_from_named_str(name, template)
.map_err(|e| build_template_error(&e, template, name, Vec::new()))?;
// Inject vars data as a nested object: {{ vars.env }}, {{ vars["env"] }},
// {{ vars.config.port }}. Always inject (even as an empty map) so
// {{ vars.key | default(...) }} works in SemiStrict mode.
// Only look up vars data if the parsed template references the top-level
// `vars` object (avoids a git process spawn per expansion while supporting
// every MiniJinja access form without false positives from literal text).
// A preview injects `LiteralVars` instead, which needs no branch and no
// git config read.
if tmpl.undeclared_variables(false).contains("vars") {
match vars_mode {
VarsMode::Literal => {
context.insert(
"vars".to_string(),
Value::from_object(LiteralVars("vars".to_string())),
);
}
VarsMode::Resolve => {
// A detached worktree leaves `branch` unset, and per-branch
// vars are keyed by branch — so there are none. Insert the
// empty map rather than nothing, so `{{ vars.key |
// default(…) }}` still renders under SemiStrict instead of
// erroring on an undefined `vars` (same reason
// `list::custom_columns` injects an empty map for a
// branchless row).
let entries = vars
.get("branch")
.map(|branch| repo.vars_entries(branch))
.unwrap_or_default();
context.insert("vars".to_string(), vars_map_to_value(&entries));
}
}
}
let result = tmpl.render(Value::from_object(context)).map_err(|e| {
let mut keys = vars.keys().map(|key| key.to_string()).collect::<Vec<_>>();
keys.sort();
if e.kind() == ErrorKind::UndefinedError
&& let Some(range) = e.range()
&& let Some(analysis) = TemplateVars::of(template)
&& let Some(var) = analysis.output_at(range)
&& !vars.contains_key(var)
&& var != "vars"
&& env.globals().all(|(key, _)| key != var)
{
return build_undefined_vars_error(name, &[var.to_string()], keys, template, e.line());
}
build_template_error(&e, template, name, keys)
})?;
// -vv: Full debug logging with result
// Redact credentials from result to prevent leaking tokens in logs
if verbose >= 2 {
tracing::debug!(name = %name, "[template:{name}] result={:?}", redact_credentials(&result));
}
// -v: Nice styled output showing template expansion. The source template
// and the rendered result each get a labeled info header above a bash gutter
// block, so the eye separates input from output. Callers that emit several
// expansions in a row (or a single standalone one, like `wt step eval`) add
// a trailing blank to separate them; in a command pipeline the executor
// already provides that separation.
// Single atomic write to avoid interleaving in multi-threaded execution
if verbose == 1 {
let source_header = info_message(cformat!("<bold>{name}</> source"));
let source_gutter = format_bash_with_gutter(template);
let result_header = info_message(cformat!("<bold>{name}</> result"));
let result_gutter = format_bash_with_gutter(&result);
eprintln!("{source_header}\n{source_gutter}\n{result_header}\n{result_gutter}");
}
Ok(result)
}
/// Convert raw vars entries into a minijinja object value.
///
/// JSON objects/arrays are parsed so nested access (`{{ vars.config.port }}`)
/// works; plain strings and numbers stay as-is.
pub fn vars_map_to_value(entries: &std::collections::BTreeMap<String, String>) -> Value {
let vars_map: std::collections::BTreeMap<&str, Value> = entries
.iter()
.map(|(k, v)| {
let value = serde_json::from_str::<serde_json::Value>(v)
.ok()
.filter(|j| j.is_object() || j.is_array())
.map(|j| Value::from(Serde(j)))
.unwrap_or_else(|| Value::from(v.clone()));
(k.as_str(), value)
})
.collect();
Value::from(vars_map)
}
/// A stand-in for the `vars` / `git.branch` maps that answers every key
/// with a placeholder string.
///
/// Used only by [`validate_list_column_template`]'s trial render: list
/// columns lean on `{{ vars.key }}` / `{{ git.branch.key }}` for keys that
/// only some branches set, so validating against an empty map (as
/// [`validate_template`] does) would wrongly reject the dominant pattern.
/// Answering every key keeps the trial render exercising filters without
/// constraining which keys exist.
#[derive(Debug)]
struct AnyKeyVars;
impl Object for AnyKeyVars {
fn get_value(self: &Arc<Self>, _key: &Value) -> Option<Value> {
Some(Value::from("PLACEHOLDER"))
}
}
/// Validate a `wt list` custom-column template.
///
/// Checks syntax, restricts top-level variables to `LIST_COLUMN_VARS` ∪
/// `{vars, git}` plus environment globals, and trial-renders with placeholder
/// values so filter errors (e.g. a misspelled filter name) surface at config
/// resolution rather than as silently empty cells. `vars.*` and `git.branch.*`
/// access is unconstrained — any key validates, since which keys exist is
/// per-branch runtime state.
pub fn validate_list_column_template(
template: &str,
repo: &Repository,
name: &str,
) -> Result<(), TemplateExpandError> {
let env = template_environment(repo);
let tmpl = env
.template_from_named_str(name, template)
.map_err(|e| build_template_error(&e, template, name, Vec::new()))?;
let mut undefined: Vec<String> = tmpl
.undeclared_variables(false)
.into_iter()
.filter(|var| {
var != "vars"
&& var != "git"
&& !LIST_COLUMN_VARS.contains(&var.as_str())
&& env.globals().all(|(key, _)| key != var)
})
.collect();
undefined.sort();
if !undefined.is_empty() {
let mut available = LIST_COLUMN_VARS.to_vec();
available.push("vars.<key>");
available.push("git.branch.<key>");
return Err(build_undefined_vars_error(
name,
&undefined,
sorted_available_vars(&available),
template,
None,
));
}
let mut context: HashMap<String, Value> = LIST_COLUMN_VARS
.iter()
.map(|&k| (k.to_string(), Value::from("PLACEHOLDER")))
.collect();
context.insert("vars".to_string(), Value::from_object(AnyKeyVars));
// git.branch.<key> resolves to a placeholder; nesting AnyKeyVars under
// `branch` lets the trial render exercise `{{ git.branch.* }}` filters.
let git = HashMap::from([("branch".to_string(), Value::from_object(AnyKeyVars))]);
context.insert("git".to_string(), Value::from_object(git));
match tmpl.render(Value::from_object(context)) {
Ok(_) => Ok(()),
// At runtime an undefined value renders as an empty cell by design
// (e.g. nested access like `{{ vars.config.port }}` against the flat
// placeholder), so it is never a config error here. Everything else —
// unknown filters, type errors — is a real config problem.
Err(e) if e.kind() == ErrorKind::UndefinedError => Ok(()),
Err(e) => Err(build_template_error(
&e,
template,
name,
sorted_available_vars(LIST_COLUMN_VARS),
)),
}
}
#[cfg(test)]
mod tests {
use insta::assert_snapshot;
use super::*;
use crate::shell_exec::Cmd;
use crate::testing::TestRepo;
fn test_repo() -> TestRepo {
TestRepo::new()
}
#[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"));
}
#[test]
fn test_sanitize_branch_name() {
let cases = [
("feature/foo", "feature-foo"),
(r"user\task", "user-task"),
("feature/user/task", "feature-user-task"),
(r"feature/user\task", "feature-user-task"),
("simple-branch", "simple-branch"),
("", ""),
("///", "---"),
("/feature", "-feature"),
("feature/", "feature-"),
];
for (input, expected) in cases {
assert_eq!(sanitize_branch_name(input), expected, "input: {input}");
}
}
#[test]
fn test_sanitize_db() {
// Test that base transformations are correct (ignore hash suffix)
let cases = [
// Examples from spec
("feature/auth-oauth2", "feature_auth_oauth2_"),
("123-bug-fix", "_123_bug_fix_"),
("UPPERCASE.Branch", "uppercase_branch_"),
// Lowercase conversion
("MyBranch", "mybranch_"),
("ALLCAPS", "allcaps_"),
// Non-alphanumeric replacement
("feature/foo", "feature_foo_"),
("feature-bar", "feature_bar_"),
("feature.baz", "feature_baz_"),
("feature@qux", "feature_qux_"),
// Consecutive underscore collapse
("a--b", "a_b_"),
("a///b", "a_b_"),
("a...b", "a_b_"),
("a-/-b", "a_b_"),
// Leading digit prefix
("1branch", "_1branch_"),
("123", "_123_"),
("0test", "_0test_"),
// No prefix needed
("branch1", "branch1_"),
("_already", "_already_"),
// Edge cases (non-empty)
("a", "a_"),
// Mixed cases
("Feature/Auth-OAuth2", "feature_auth_oauth2_"),
("user/TASK/123", "user_task_123_"),
// Non-ASCII characters become underscores
("naïve-impl", "na_ve_impl_"),
("über-feature", "_ber_feature_"),
];
for (input, expected_prefix) in cases {
let result = sanitize_db(input);
assert!(
result.starts_with(expected_prefix),
"input: {input}, expected prefix: {expected_prefix}, got: {result}"
);
// Result should be prefix + 3-char hash
assert_eq!(
result.len(),
expected_prefix.len() + 3,
"input: {input}, result: {result}"
);
}
// Empty input stays empty (no hash suffix)
assert_eq!(sanitize_db(""), "");
// Special cases that collapse to just underscore + hash
for input in ["_", "-", "---", "日本語"] {
let result = sanitize_db(input);
assert!(result.starts_with('_'), "input: {input}, got: {result}");
assert_eq!(result.len(), 4, "input: {input}, got: {result}"); // _xxx
}
}
#[test]
fn test_sanitize_db_collision_avoidance() {
// Different inputs that would collide without hash suffix now differ
assert_ne!(sanitize_db("a-b"), sanitize_db("a_b"));
assert_ne!(sanitize_db("feature/auth"), sanitize_db("feature-auth"));
assert_ne!(sanitize_db("UPPERCASE"), sanitize_db("uppercase"));
// Same input always produces same output (deterministic)
assert_eq!(sanitize_db("test"), sanitize_db("test"));
assert_eq!(sanitize_db("feature/foo"), sanitize_db("feature/foo"));
}
#[test]
fn test_sanitize_db_reserved_words() {
// Reserved words get hash suffix, making them safe
let user = sanitize_db("user");
assert!(user.starts_with("user_"), "got: {user}");
assert_ne!(user, "user"); // Not a bare reserved word
let select = sanitize_db("select");
assert!(select.starts_with("select_"), "got: {select}");
assert_ne!(select, "select");
}
#[test]
fn test_sanitize_db_truncation() {
// Total output is always max 48 characters
// Base is truncated to 44 chars, then _xxx suffix (4 chars) is added
// Very long input: base truncated to 44, + 4 = 48
let long_input = "a".repeat(100);
let result = sanitize_db(&long_input);
assert_eq!(result.len(), 48, "result: {result}");
assert!(result.starts_with(&"a".repeat(43)), "result: {result}");
assert!(!result.ends_with('_'), "should end with hash chars");
// Short input: base + _ + hash
let short = "test";
let result = sanitize_db(short);
assert!(result.starts_with("test_"), "result: {result}");
assert_eq!(result.len(), 8, "result: {result}"); // test_ + 3 hash chars
// Truncation happens after prefix is added for digit-starting inputs
let digit_start = format!("1{}", "x".repeat(100));
let result = sanitize_db(&digit_start);
assert_eq!(result.len(), 48, "result: {result}");
assert!(result.starts_with("_1"), "result: {result}");
}
#[test]
fn test_expand_template_basic() {
let test = test_repo();
// Single variable
let mut vars = HashMap::new();
vars.insert("name", "world");
assert_eq!(
expand_template(
"Hello {{ name }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"Hello world"
);
// Multiple variables
vars.insert("repo", "myrepo");
assert_eq!(
expand_template(
"{{ repo }}/{{ name }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"myrepo/world"
);
// Empty/static cases
let empty: HashMap<&str, &str> = HashMap::new();
assert_eq!(
expand_template("", &empty, ShellEscapeMode::Literal, &test.repo, "test").unwrap(),
""
);
assert_eq!(
expand_template(
"static text",
&empty,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"static text"
);
// Undefined variables now error in SemiStrict mode
let err = expand_template(
"no {{ variables }} here",
&empty,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap_err();
assert!(err.message.contains("undefined"), "got: {}", err.message);
}
#[test]
fn test_expand_template_shell_escape() {
let test = test_repo();
let mut vars = HashMap::new();
vars.insert("path", "my path");
let expanded = expand_template(
"cd {{ path }}",
&vars,
ShellEscapeMode::Posix,
&test.repo,
"test",
)
.unwrap();
assert!(expanded.contains("'my path'") || expanded.contains(r"my\ path"));
// Command injection prevention
vars.insert("arg", "test;rm -rf");
let expanded = expand_template(
"echo {{ arg }}",
&vars,
ShellEscapeMode::Posix,
&test.repo,
"test",
)
.unwrap();
assert!(!expanded.contains(";rm") || expanded.contains("'"));
// No escape for literal mode
vars.insert("branch", "feature/foo");
assert_eq!(
expand_template(
"{{ branch }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"feature/foo"
);
}
#[test]
fn test_expand_template_errors() {
let test = test_repo();
let vars = HashMap::new();
let err = expand_template(
"{{ unclosed",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap_err();
assert!(err.message.contains("syntax error"), "got: {}", err.message);
assert!(
expand_template(
"{{ 1 + }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.is_err()
);
// Diagnostic::render produces source line but no available vars hint for syntax errors
assert_snapshot!(crate::git::Diagnostic::render(&err), @"
[31m✗[39m [31mFailed to expand test: syntax error: unexpected end of input, expected end of variable block @ line 1[39m
[107m [0m {{ unclosed
");
}
#[test]
fn test_expand_template_undefined_var_details() {
let test = test_repo();
let mut vars = HashMap::new();
vars.insert("branch", "main");
vars.insert("remote", "origin");
let err = expand_template(
"echo {{ target }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap_err();
assert!(
err.message.contains("undefined"),
"should mention undefined variable: {}",
err.message
);
assert!(err.available_vars.contains(&"branch".to_string()));
assert!(err.available_vars.contains(&"remote".to_string()));
assert_eq!(err.source_line.as_deref(), Some("echo {{ target }}"));
// Diagnostic::render produces source line and available vars hint
assert_snapshot!(crate::git::Diagnostic::render(&err), @"
[31m✗[39m [31mFailed to expand test: undefined variable target @ line 1[39m
[107m [0m echo {{ target }}
[2m↳[22m [2mAvailable variables: [4mbranch[24m, [4mremote[24m[22m
");
}
#[test]
fn test_expand_template_names_reached_typo() {
let test = test_repo();
let vars = HashMap::from([("branch", "main")]);
for template in [
"{% if branch %}{{ brnch }}{% endif %}",
"{% for item in [1] %}{{ brnch }}{% endfor %}",
"{% if upstream %}{{ unvisited }}{% endif %}\necho {{ brnch | upper }}",
"{% set captured %}{{ brnch }}{% endset %}",
"{% autoescape true %}{{ brnch }}{% endautoescape %}",
"{% filter upper %}{{ brnch }}{% endfilter %}",
"{% with local = branch %}{{ brnch }}{% endwith %}",
"{% set ns = namespace() %}{% set ns.brnch = branch %}{{ brnch }}",
] {
let err = expand_template(
template,
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap_err();
assert_eq!(
err.message,
format!(
"Failed to expand test: undefined variable brnch @ line {}",
template.lines().count()
)
);
assert_eq!(err.suggestion.as_deref(), Some("branch"));
assert_eq!(err.source_line.as_deref(), template.lines().last());
}
}
/// A Worktrunk variable the operation left unset (`target` in a
/// `post-switch` hook to a detached worktree) is not a typo: suggesting a
/// similarly named variable would steer the user to the wrong value.
#[test]
fn test_unset_worktrunk_variable_gets_no_suggestion() {
let test = test_repo();
let vars = HashMap::from([("branch", "main"), ("target_worktree_path", "/tmp/wt")]);
let err = expand_template(
"echo {{ target }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap_err();
assert_eq!(
err.message,
"Failed to expand test: undefined variable target @ line 1"
);
assert_eq!(err.suggestion, None);
}
#[test]
fn test_undefined_namespace_values_do_not_name_unreached_typos() {
let test = test_repo();
let vars = HashMap::from([("branch", "main"), ("args", "[]")]);
for (template, undefined) in [
("{{ args[0] }}{{ brnch }}", "args[0]"),
("{{ vars.missing }}{{ brnch }}", "vars.missing"),
(
"{% if optional %}{{ brnch }}{% endif %}{{ vars.missing }}",
"vars.missing",
),
("{% set local = brnch %}{{ local }}", "brnch"),
("{{ brnch if branch else other_missing }}", "brnch"),
("{{ branch | replace(brnch, '-') }}", "brnch"),
(
"{% if false %}{{ brnch }}{% endif %}{% set brnch = vars.missing %}{{ brnch }}",
"vars.missing",
),
(
"{% if false %}{{ brnch }}{% endif %}{% with brnch = vars.missing %}{{ brnch }}{% endwith %}",
"vars.missing",
),
(
"{% if false %}{{ brnch }}{% endif %}{% for brnch in [vars.missing] %}{{ brnch }}{% endfor %}",
"vars.missing",
),
(
"{% if false %}{{ brnch }}{% endif %}{% for brnch, other in [[vars.missing, 1]] %}{{ brnch }}{% endfor %}",
"vars.missing",
),
(
"{% if false %}{{ brnch }}{% endif %}{% set captured %}{% set brnch = vars.missing %}{{ brnch }}{% endset %}",
"vars.missing",
),
] {
let err = expand_template(
template,
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap_err();
// MiniJinja names the undefined expression only when the
// environment's debug flag is on, which defaults to
// `debug_assertions`; accept either exact form.
let named = format!(
"Failed to expand test: undefined value: `{undefined}` is undefined @ line 1"
);
let unnamed = "Failed to expand test: undefined value @ line 1";
assert!(
err.message == named || err.message == unnamed,
"{template}: {}",
err.message
);
assert_eq!(err.suggestion, None);
}
}
/// Custom filters must let MiniJinja reject undefined input rather than
/// silently turn a misspelled branch into an empty path or hash.
#[test]
fn test_custom_filters_reject_undefined_input() {
let test = test_repo();
for filter in [
"sanitize",
"sanitize_db",
"sanitize_hash",
"hash",
"hash_port",
"dirname",
"basename",
"codename",
] {
let template = format!("{{{{ brnch | {filter} }}}}");
let err = expand_template(
&template,
&HashMap::new(),
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap_err();
assert_eq!(
err.message,
"Failed to expand test: undefined variable brnch @ line 1"
);
}
}
#[test]
fn test_template_validation_uses_environment_globals() {
let test = test_repo();
let template = "{% for item in range(2) %}{{ item }}{% endfor %}";
validate_template(template, ValidationScope::Alias, &test.repo, "test").unwrap();
validate_list_column_template(template, &test.repo, "test").unwrap();
assert_eq!(
expand_template(
template,
&HashMap::new(),
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap(),
"01"
);
}
#[test]
fn test_expand_template_jinja_features() {
let test = test_repo();
let mut vars = HashMap::new();
vars.insert("debug", "true");
assert_eq!(
expand_template(
"{% if debug %}DEBUG{% endif %}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"DEBUG"
);
vars.insert("debug", "");
assert_eq!(
expand_template(
"{% if debug %}DEBUG{% endif %}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
""
);
let empty: HashMap<&str, &str> = HashMap::new();
assert_eq!(
expand_template(
"{{ missing | default('fallback') }}",
&empty,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap(),
"fallback"
);
vars.insert("name", "hello");
assert_eq!(
expand_template(
"{{ name | upper }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"HELLO"
);
}
#[test]
fn test_expand_template_strip_prefix() {
let test = test_repo();
let mut vars = HashMap::new();
// Built-in replace filter strips prefix (replaces all occurrences)
vars.insert("branch", "feature/foo");
assert_eq!(
expand_template(
"{{ branch | replace('feature/', '') }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"foo"
);
// Replace + sanitize for worktree paths
assert_eq!(
expand_template(
"{{ branch | replace('feature/', '') | sanitize }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"foo"
);
// Branch without prefix passes through unchanged
vars.insert("branch", "main");
assert_eq!(
expand_template(
"{{ branch | replace('feature/', '') }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"main"
);
// Slicing for prefix-only removal (avoids replacing mid-string)
vars.insert("branch", "feature/nested/feature/deep");
assert_eq!(
expand_template(
"{{ branch[8:] }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"nested/feature/deep"
);
// Conditional slicing for safe prefix removal
assert_eq!(
expand_template(
"{% if branch[:8] == 'feature/' %}{{ branch[8:] }}{% else %}{{ branch }}{% endif %}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"nested/feature/deep"
);
// Conditional passes through non-matching branches
vars.insert("branch", "bugfix/bar");
assert_eq!(
expand_template(
"{% if branch[:8] == 'feature/' %}{{ branch[8:] }}{% else %}{{ branch }}{% endif %}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"bugfix/bar"
);
}
#[test]
fn test_expand_template_sanitize_filter() {
let test = test_repo();
let mut vars = HashMap::new();
vars.insert("branch", "feature/foo");
assert_eq!(
expand_template(
"{{ branch | sanitize }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"feature-foo"
);
// Backslashes are also sanitized
vars.insert("branch", r"feature\bar");
assert_eq!(
expand_template(
"{{ branch | sanitize }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"feature-bar"
);
// Multiple slashes
vars.insert("branch", "user/feature/task");
assert_eq!(
expand_template(
"{{ branch | sanitize }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"user-feature-task"
);
// Raw branch is unchanged
vars.insert("branch", "feature/foo");
assert_eq!(
expand_template(
"{{ branch }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"feature/foo"
);
// Shell escaping + sanitize: filters operate on raw values, escaping applied at output.
// Previously, shell escaping was applied BEFORE filters, corrupting the result
// when values contained shell-special characters (quotes, backslashes).
vars.insert("branch", "user's/feature");
let result = expand_template(
"{{ branch | sanitize }}",
&vars,
ShellEscapeMode::Posix,
&test.repo,
"test",
)
.unwrap();
// sanitize replaces / with -, producing "user's-feature"
// shell_escape wraps it: 'user'\''s-feature' (valid shell for user's-feature)
assert_eq!(result, r"'user'\''s-feature'", "sanitize + shell escape");
// Without the fix, pre-escaping would produce corrupted output because
// sanitize would replace the / and \ in the already-escaped value.
// Shell escaping without filter: raw value with special chars
let result = expand_template(
"{{ branch }}",
&vars,
ShellEscapeMode::Posix,
&test.repo,
"test",
)
.unwrap();
// shell_escape wraps: 'user'\''s/feature' (valid shell for user's/feature)
assert_eq!(
result, r"'user'\''s/feature'",
"shell escape without filter"
);
// Shell-escape formatter handles none values (renders as empty string)
let result = expand_template(
"prefix-{{ none }}-suffix",
&vars,
ShellEscapeMode::Posix,
&test.repo,
"test",
)
.unwrap();
assert_eq!(result, "prefix--suffix", "none renders as empty");
}
#[test]
fn test_expand_template_sanitize_db_filter() {
let test = test_repo();
let mut vars = HashMap::new();
// Basic transformation (with hash suffix)
vars.insert("branch", "feature/auth-oauth2");
let result = expand_template(
"{{ branch | sanitize_db }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
assert!(result.starts_with("feature_auth_oauth2_"), "got: {result}");
// Leading digit gets underscore prefix
vars.insert("branch", "123-bug-fix");
let result = expand_template(
"{{ branch | sanitize_db }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
assert!(result.starts_with("_123_bug_fix_"), "got: {result}");
// Uppercase conversion
vars.insert("branch", "UPPERCASE.Branch");
let result = expand_template(
"{{ branch | sanitize_db }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
assert!(result.starts_with("uppercase_branch_"), "got: {result}");
// Raw branch is unchanged
vars.insert("branch", "feature/foo");
assert_eq!(
expand_template(
"{{ branch }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"feature/foo"
);
}
#[test]
fn test_expand_template_trailing_newline() {
let test = test_repo();
let mut vars = HashMap::new();
vars.insert("cmd", "echo hello");
assert!(
expand_template(
"{{ cmd }}\n",
&vars,
ShellEscapeMode::Posix,
&test.repo,
"test"
)
.unwrap()
.ends_with('\n')
);
}
#[test]
fn test_string_to_port_deterministic_and_in_range() {
for input in ["main", "feature-foo", "", "a", "long-branch-name-123"] {
let p1 = string_to_port(input);
let p2 = string_to_port(input);
assert_eq!(p1, p2, "same input should produce same port");
assert!((10000..20000).contains(&p1), "port {} out of range", p1);
}
}
#[test]
fn test_hash_filter() {
let test = test_repo();
let mut vars = HashMap::new();
vars.insert("branch", "feature/very-long-branch-name");
// Filter produces a 3-char base36 digest
let result = expand_template(
"{{ branch | hash }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
assert_eq!(result.len(), 3);
assert!(
result
.chars()
.all(|c| c.is_ascii_digit() || c.is_ascii_lowercase()),
"got: {result}"
);
// Deterministic: same input produces same hash across calls
let r1 = expand_template(
"{{ branch | hash }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
let r2 = expand_template(
"{{ branch | hash }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
assert_eq!(r1, r2);
// Composable: hash reflects the upstream filter's output
vars.insert("branch", "feature/auth");
let raw = expand_template(
"{{ branch | hash }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
let sanitized = expand_template(
"{{ branch | sanitize | hash }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
// `sanitize` rewrites `/` to `-`, so the hashed input differs and the digest does too.
assert_ne!(raw, sanitized);
// User-composed truncation + hash recipe (from extending docs)
let truncated = expand_template(
"{{ (branch | sanitize)[:8] }}_{{ branch | sanitize | hash }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
assert!(truncated.starts_with("feature-"), "got: {truncated}");
assert_eq!(truncated.len(), 8 + 1 + 3);
// Empty input: still produces a 3-char digest (empty-string hash is stable)
vars.insert("branch", "");
let empty = expand_template(
"{{ branch | hash }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
assert_eq!(empty.len(), 3);
}
#[test]
fn test_codename_filter() {
let test = test_repo();
let mut vars = HashMap::new();
vars.insert("branch", "feature/very-long-branch-name");
let default = expand_template(
"{{ branch | codename }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
let explicit_default = expand_template(
"{{ branch | codename(2) }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
assert_eq!(default, explicit_default);
assert_eq!(default.split('-').count(), 2, "got: {default}");
let one_word = expand_template(
"{{ branch | codename(1) }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
assert!(!one_word.contains('-'), "got: {one_word}");
let lists = codename_words();
let nouns: &[&str] = lists.nouns.as_ref();
assert!(nouns.contains(&one_word.as_str()));
let three_words = expand_template(
"{{ branch | codename(3) }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
assert_eq!(three_words.split('-').count(), 3, "got: {three_words}");
let repeat = expand_template(
"{{ branch | codename }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
assert_eq!(default, repeat);
vars.insert("branch", "feature/different-name");
let other = expand_template(
"{{ branch | codename }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
assert_eq!(other.split('-').count(), 2, "got: {other}");
vars.insert("branch", "feature/73");
let ticket_73 = expand_template(
"{{ branch | codename(3) }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
vars.insert("branch", "feature/149");
let ticket_149 = expand_template(
"{{ branch | codename(3) }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
assert_ne!(ticket_73, ticket_149);
}
#[test]
fn test_codename_filter_rejects_invalid_counts() {
let test = test_repo();
let mut vars = HashMap::new();
vars.insert("branch", "feature");
let zero = expand_template(
"{{ branch | codename(0) }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap_err()
.to_string();
assert!(
zero.contains("codename word count must be between 1 and 8"),
"got: {zero}"
);
let too_many = expand_template(
"{{ branch | codename(9) }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap_err()
.to_string();
assert!(
too_many.contains("codename word count must be between 1 and 8"),
"got: {too_many}"
);
}
#[test]
fn test_codename_word_lists_are_path_safe() {
fn assert_word_list(name: &str, words: &[&str]) {
assert!(words.len() >= 160, "{name} should have enough entries");
let mut seen = std::collections::HashSet::new();
for &word in words {
assert!(seen.insert(word), "duplicate {name} word: {word}");
assert!(!word.is_empty(), "empty {name} word");
assert!(
word.chars().all(|c| c.is_ascii_lowercase()),
"{name} word is not lowercase ASCII: {word}"
);
assert!(
!word.contains('-') && !word.contains(' '),
"{name} word is not a single path component fragment: {word}"
);
}
}
let lists = codename_words();
let adjectives: &[&str] = lists.adjectives.as_ref();
let nouns: &[&str] = lists.nouns.as_ref();
assert_word_list("adjective", adjectives);
assert_word_list("noun", nouns);
// codename(2) cardinality — petname::medium() gives ~1.26M combinations,
// so a single adjective+noun pair is enough on its own for typical
// worktree counts.
assert!(adjectives.len() * nouns.len() >= 1_000_000);
}
/// Pins specific `codename(input, n)` outputs so the on-disk contract
/// is impossible to break by accident. Once a user adopts this filter in
/// their `worktree-path` template, the petname wordlists (and the
/// hash-input layout in `codename_index`) become an on-disk identity for
/// every worktree they own. Anything that shifts the wordlists (a
/// `petname` version bump that adds, removes, or reorders a word) or
/// changes how the hash is computed produces a different name for the
/// same branch on the next `wt switch`, orphaning the existing worktree.
///
/// If this test fails:
///
/// 1. Stop. Do not update the expected values to silence it.
/// 2. Confirm whether you actually intended to change the wordlists
/// (e.g. via a `petname` version bump) or the hash layout. If it was
/// unintentional (a refactor, a Cargo update), revert.
/// 3. If the change is intentional, accept that you are breaking every
/// existing user's worktree paths. Coordinate the rollout, document
/// it as a breaking change, and only then update the expected values.
#[test]
fn test_codename_outputs_are_stable() {
let cases: &[(&str, usize, &str)] = &[
("main", 1, "gorilla"),
("feature/auth", 2, "malleable-opah"),
("feature/73", 2, "prodigious-shoveler"),
("feature/149", 2, "tuneful-vendace"),
("release/1.0", 3, "intent-equipped-treefrog"),
(
"hotfix/some-very-long-thing",
4,
"noteworthy-musical-durable-silkworm",
),
];
for (input, n, expected) in cases {
let actual = codename(input, *n);
assert_eq!(
&actual, expected,
"\n\
codename({input:?}, {n}) returned {actual:?}, expected {expected:?}.\n\
\n\
Changing the petname version, or the codename algorithm,\n\
BREAKS every existing user's worktree paths derived from\n\
`{{{{ branch | codename(...) }}}}`. See the comment above\n\
this test before updating these expectations.\n"
);
}
}
#[test]
fn test_validate_template_accepts_codename_filter() {
let test = test_repo();
assert!(
validate_template(
"{{ branch | codename(2) }}",
ValidationScope::SwitchExecute,
&test.repo,
"test"
)
.is_ok()
);
}
#[test]
fn test_hash_port_filter() {
let test = test_repo();
let mut vars = HashMap::new();
vars.insert("branch", "feature-foo");
vars.insert("repo", "myrepo");
// Filter produces a number in range
let result = expand_template(
"{{ branch | hash_port }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
let port: u16 = result.parse().expect("should be a number");
assert!((10000..20000).contains(&port));
// Concatenation produces different (but deterministic) result
let r1 = expand_template(
"{{ (repo ~ '-' ~ branch) | hash_port }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
let r1_port: u16 = r1.parse().expect("should be a number");
let r2 = expand_template(
"{{ (repo ~ '-' ~ branch) | hash_port }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
let r2_port: u16 = r2.parse().expect("should be a number");
assert!((10000..20000).contains(&r1_port));
assert!((10000..20000).contains(&r2_port));
assert_eq!(r1, r2);
}
#[test]
fn test_dirname_and_basename_filters() {
let test = test_repo();
let mut vars = HashMap::new();
// Bare repo wrapped in a hidden dir: `dirname | basename` recovers the wrapper name
// (the case from #1279 — `{{ repo }}` resolves to `.git`, but the user wants `myrepo`)
vars.insert("repo_path", "/projects/myrepo/.git");
let result = expand_template(
"{{ repo_path | dirname | basename }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
assert_eq!(result, "myrepo");
// Composing into a worktree-path template
vars.insert("branch", "feature-auth");
let result = expand_template(
"{{ repo_path }}/../{{ repo_path | dirname | basename }}.{{ branch | sanitize }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
assert_eq!(result, "/projects/myrepo/.git/../myrepo.feature-auth");
// `dirname` strips the last component
vars.insert("repo_path", "/a/b/c");
let dirname = expand_template(
"{{ repo_path | dirname }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
assert_eq!(dirname, "/a/b");
// `basename` keeps only the last component
let basename = expand_template(
"{{ repo_path | basename }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap();
assert_eq!(basename, "c");
// No separator: dirname is empty, basename is the whole input
vars.insert("repo_path", "myrepo");
assert_eq!(
expand_template(
"{{ repo_path | dirname }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
""
);
assert_eq!(
expand_template(
"{{ repo_path | basename }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"myrepo"
);
}
#[test]
fn test_redact_credentials() {
let cases = [
(
"GitHub personal access token",
"https://[email protected]/owner/repo",
"https://[REDACTED]@github.com/owner/repo",
),
(
"GitLab personal access token",
"https://[email protected]/owner/repo.git",
"https://[REDACTED]@gitlab.com/owner/repo.git",
),
(
"HTTPS username and password",
"https://user:[email protected]/owner/repo",
"https://[REDACTED]@github.com/owner/repo",
),
(
"HTTPS without credentials",
"https://github.com/owner/repo",
"https://github.com/owner/repo",
),
(
"SSH URL",
"[email protected]:owner/repo.git",
"[email protected]:owner/repo.git",
),
("branch name", "main", "main"),
("branch name with slash", "feature/auth", "feature/auth"),
("filesystem path", "/path/to/worktree", "/path/to/worktree"),
("empty value", "", ""),
(
"git protocol token",
"git://[email protected]/owner/repo.git",
"git://[REDACTED]@github.com/owner/repo.git",
),
(
"path and query after credentials",
"https://[email protected]/owner/repo.git?ref=main",
"https://[REDACTED]@github.com/owner/repo.git?ref=main",
),
];
for (name, input, expected) in cases {
assert_eq!(redact_credentials(input), expected, "{name}: {input}");
}
}
#[test]
fn test_expand_template_vars_data() {
let test = test_repo();
// Set vars data via git config
Cmd::new("git")
.args(["config", "worktrunk.state.main.vars.env", "staging"])
.current_dir(test.path())
.run()
.unwrap();
Cmd::new("git")
.args(["config", "worktrunk.state.main.vars.port", "3000"])
.current_dir(test.path())
.run()
.unwrap();
let mut vars = HashMap::new();
vars.insert("branch", "main");
// Access vars via dot notation
assert_eq!(
expand_template(
"{{ vars.env }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"staging"
);
assert_eq!(
expand_template(
r#"{{ vars["env"] }}"#,
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"staging"
);
assert_eq!(
expand_template(
"{% if vars %}vars loaded{% endif %}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"vars loaded"
);
assert_eq!(
expand_template(
"{{ vars.port }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"3000"
);
// Default filter for missing vars keys
assert_eq!(
expand_template(
"{{ vars.missing | default('fallback') }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"fallback"
);
// Conditional on vars
assert_eq!(
expand_template(
"{% if vars.env %}env={{ vars.env }}{% endif %}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"env=staging"
);
}
#[test]
fn test_expand_template_vars_json_dot_access() {
let test = test_repo();
// Store a JSON object as a vars value
Cmd::new("git")
.args([
"config",
"worktrunk.state.main.vars.config",
r#"{"port": 3000, "debug": true, "note": null}"#,
])
.current_dir(test.path())
.run()
.unwrap();
// Store a JSON array
Cmd::new("git")
.args([
"config",
"worktrunk.state.main.vars.tags",
r#"["alpha", "beta"]"#,
])
.current_dir(test.path())
.run()
.unwrap();
// Store a plain string (not JSON)
Cmd::new("git")
.args(["config", "worktrunk.state.main.vars.env", "staging"])
.current_dir(test.path())
.run()
.unwrap();
let mut vars = HashMap::new();
vars.insert("branch", "main");
// Dot access into JSON object
assert_eq!(
expand_template(
"{{ vars.config.port }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"3000"
);
// A JSON bool or null reaches minijinja as a real bool/none, so each
// renders the way minijinja renders it: `True`/`False`/`None` since
// 2.22, which adopted Jinja2's spelling for all three together.
assert_eq!(
expand_template(
"{{ vars.config.debug }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"True"
);
assert_eq!(
expand_template(
"{{ vars.config.note }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"None"
);
// Array index access
assert_eq!(
expand_template(
"{{ vars.tags[0] }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"alpha"
);
// Plain string still works
assert_eq!(
expand_template(
"{{ vars.env }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"staging"
);
// Default filter on missing nested key
assert_eq!(
expand_template(
"{{ vars.config.missing | default('fallback') }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"fallback"
);
// `tojson` errors on a missing key, as printing it does, rather than
// writing `null`
let err = expand_template(
"{{ vars.config.missing | tojson }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test",
)
.unwrap_err();
// MiniJinja names the undefined expression only in debug builds (see
// the undefined-diagnostics test); accept either form.
assert!(
[
"Failed to expand test: undefined value: `vars.config.missing` is undefined @ line 1",
"Failed to expand test: undefined value @ line 1",
]
.contains(&err.message.as_str()),
"got: {}",
err.message
);
}
#[test]
fn test_expand_template_vars_json_shell_escape() {
let test = test_repo();
Cmd::new("git")
.args([
"config",
"worktrunk.state.main.vars.config",
r#"{"name": "my project", "cmd": "echo hello"}"#,
])
.current_dir(test.path())
.run()
.unwrap();
let mut vars = HashMap::new();
vars.insert("branch", "main");
// Shell escaping should work on JSON-parsed nested values
let result = expand_template(
"{{ vars.config.name }}",
&vars,
ShellEscapeMode::Posix,
&test.repo,
"test",
)
.unwrap();
assert_eq!(result, "'my project'");
let result = expand_template(
"{{ vars.config.cmd }}",
&vars,
ShellEscapeMode::Posix,
&test.repo,
"test",
)
.unwrap();
assert_eq!(result, "'echo hello'");
}
#[test]
fn test_expand_template_vars_empty_when_no_branch() {
let test = test_repo();
let vars = HashMap::new(); // No branch var
// A detached worktree leaves `branch` unset, and per-branch vars are
// keyed by branch — so there are none. `vars` is still the empty map
// rather than undefined, so `default` fires on the missing key instead
// of erroring on the missing object under SemiStrict.
assert_eq!(
expand_template(
"{{ vars.env | default('dev') }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"dev"
);
}
#[test]
fn test_expand_template_vars_empty_when_no_data() {
let test = test_repo();
let mut vars = HashMap::new();
vars.insert("branch", "main");
// vars injected as empty map when no entries exist — use default filter for missing keys
assert_eq!(
expand_template(
"{{ vars.env | default('dev') }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"dev"
);
}
#[test]
fn test_expand_template_args_sequence() {
let test = test_repo();
let args_json = serde_json::to_string(&["foo", "bar baz", "qux"]).unwrap();
let mut vars = HashMap::new();
vars.insert("args", args_json.as_str());
// Bare {{ args }} with shell escaping: space-joined, per-element escaped,
// NOT wrapped in outer quotes as a single token.
assert_eq!(
expand_template(
"wt switch {{ args }}",
&vars,
ShellEscapeMode::Posix,
&test.repo,
"test"
)
.unwrap(),
"wt switch foo 'bar baz' qux"
);
// Indexing returns a plain string — flows through the shell-escape formatter.
assert_eq!(
expand_template(
"{{ args[0] }}",
&vars,
ShellEscapeMode::Posix,
&test.repo,
"test"
)
.unwrap(),
"foo"
);
assert_eq!(
expand_template(
"{{ args[1] }}",
&vars,
ShellEscapeMode::Posix,
&test.repo,
"test"
)
.unwrap(),
"'bar baz'"
);
// Length works like any sequence.
assert_eq!(
expand_template(
"{{ args | length }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"3"
);
// Iteration yields per-element string values; each escaped by the formatter.
assert_eq!(
expand_template(
"{% for a in args %}[{{ a }}]{% endfor %}",
&vars,
ShellEscapeMode::Posix,
&test.repo,
"test"
)
.unwrap(),
"[foo]['bar baz'][qux]"
);
}
#[test]
fn test_expand_template_args_empty() {
let test = test_repo();
let args_json = serde_json::to_string(&Vec::<String>::new()).unwrap();
let mut vars = HashMap::new();
vars.insert("args", args_json.as_str());
// Empty args renders empty. No stray whitespace, no error.
assert_eq!(
expand_template(
"wt switch{{ args }}",
&vars,
ShellEscapeMode::Posix,
&test.repo,
"test"
)
.unwrap(),
"wt switch"
);
// Length still defined for empty.
assert_eq!(
expand_template(
"{{ args | length }}",
&vars,
ShellEscapeMode::Literal,
&test.repo,
"test"
)
.unwrap(),
"0"
);
// Iteration yields nothing.
assert_eq!(
expand_template(
"{% for a in args %}X{% endfor %}",
&vars,
ShellEscapeMode::Posix,
&test.repo,
"test"
)
.unwrap(),
""
);
}
#[test]
fn test_expand_template_args_shell_metachar_safety() {
// The point of ShellArgs is that bare {{ args }} is safe to splice into
// a command line even when args contain shell metacharacters — each
// element is individually POSIX single-quoted by `shell_join`, and the
// outer formatter doesn't re-quote the joined result.
let test = test_repo();
let args_json = serde_json::to_string(&["; rm -rf /", "$(whoami)", "a'b"]).unwrap();
let mut vars = HashMap::new();
vars.insert("args", args_json.as_str());
let rendered = expand_template(
"echo {{ args }}",
&vars,
ShellEscapeMode::Posix,
&test.repo,
"test",
)
.unwrap();
assert_eq!(rendered, r#"echo '; rm -rf /' '$(whoami)' 'a'\''b'"#);
}
#[test]
fn test_validate_template_valid() {
let test = test_repo();
let hook = ValidationScope::Hook(HookType::PostCreate);
// Static text
assert!(validate_template("echo hello", hook, &test.repo, "test").is_ok());
// Base variables are available in every scope
assert!(validate_template("{{ branch }}", hook, &test.repo, "test").is_ok());
assert!(validate_template("{{ repo }}/{{ branch }}", hook, &test.repo, "test").is_ok());
// Filters
assert!(validate_template("{{ branch | sanitize }}", hook, &test.repo, "test").is_ok());
assert!(validate_template("{{ branch | sanitize_db }}", hook, &test.repo, "test").is_ok());
assert!(
validate_template("{{ branch | sanitize_hash }}", hook, &test.repo, "test").is_ok()
);
assert!(validate_template("{{ branch | hash }}", hook, &test.repo, "test").is_ok());
assert!(validate_template("{{ branch | hash_port }}", hook, &test.repo, "test").is_ok());
// Conditionals with optional vars
assert!(
validate_template(
"{% if upstream %}{{ upstream }}{% endif %}",
hook,
&test.repo,
"test"
)
.is_ok()
);
// Remote-derived repo vars validate in every scope
assert!(
validate_template("{{ owner }}/{{ remote_repo }}", hook, &test.repo, "test").is_ok()
);
assert!(
validate_template(
"{{ remote_repo }}",
ValidationScope::Alias,
&test.repo,
"test"
)
.is_ok()
);
// Retired names resolve nowhere: the deprecation layer renames them
// before serde parses, so one reaching validation was typed on the
// command line and gets the undefined-variable error.
assert!(validate_template("{{ main_worktree }}", hook, &test.repo, "test").is_err());
// `args` validates in both Hook and Alias scopes.
assert!(validate_template("echo {{ args }}", hook, &test.repo, "test").is_ok());
let alias = ValidationScope::Alias;
assert!(validate_template("wt switch {{ args }}", alias, &test.repo, "test").is_ok());
assert!(validate_template("{{ args | length }}", alias, &test.repo, "test").is_ok());
assert!(
validate_template(
"{% for a in args %}{{ a }}{% endfor %}",
alias,
&test.repo,
"test"
)
.is_ok()
);
}
#[test]
fn test_validate_template_scope_rejects_out_of_scope_vars() {
let test = test_repo();
// `base` is unavailable in pre-merge — catch the typo at validation time.
let err = validate_template(
"{{ base }}",
ValidationScope::Hook(HookType::PreMerge),
&test.repo,
"test",
)
.unwrap_err();
assert!(err.message.contains("undefined"), "got: {}", err.message);
// `base` is available in pre-start.
assert!(
validate_template(
"{{ base }}",
ValidationScope::Hook(HookType::PreCreate),
&test.repo,
"test"
)
.is_ok()
);
// `target` is available in pre-merge.
assert!(
validate_template(
"{{ target }}",
ValidationScope::Hook(HookType::PreMerge),
&test.repo,
"test"
)
.is_ok()
);
// Typos in conditional predicates must not be hidden by SemiStrict truthiness.
let err = validate_template(
"{% if targte %}echo {{ target }}{% endif %}",
ValidationScope::Hook(HookType::PreMerge),
&test.repo,
"test",
)
.unwrap_err();
assert!(err.message.contains("undefined"), "got: {}", err.message);
assert!(err.message.contains("targte"), "got: {}", err.message);
// `pr_number`/`pr_url` are available in pre-start (populated when
// creating via `pr:N` / `mr:N`).
for var in ["pr_number", "pr_url"] {
assert!(
validate_template(
&format!("{{{{ {var} }}}}"),
ValidationScope::Hook(HookType::PreCreate),
&test.repo,
"test"
)
.is_ok(),
"{var} should validate in pre-start scope"
);
}
// `pr_number` is not available in pre-merge (different hook type).
let err = validate_template(
"{{ pr_number }}",
ValidationScope::Hook(HookType::PreMerge),
&test.repo,
"test",
)
.unwrap_err();
assert!(err.message.contains("undefined"), "got: {}", err.message);
// `args` is available in hook scope (forwarded via smart routing).
assert!(
validate_template(
"{{ args }}",
ValidationScope::Hook(HookType::PreCreate),
&test.repo,
"test",
)
.is_ok()
);
// `args` is not available in SwitchExecute.
let err = validate_template(
"{{ args }}",
ValidationScope::SwitchExecute,
&test.repo,
"test",
)
.unwrap_err();
assert!(err.message.contains("undefined"), "got: {}", err.message);
}
#[test]
fn test_validate_template_syntax_error() {
let test = test_repo();
let err = validate_template("{{ unclosed", ValidationScope::Alias, &test.repo, "test")
.unwrap_err();
assert!(err.message.contains("syntax error"), "got: {}", err.message);
}
/// The `--execute` filter unions across the command and its trailing args,
/// which are separate expansion positions over one context map — a var
/// named only in an arg still has to be computed.
#[test]
fn test_referenced_vars_for_templates_unions_positions() {
let refs = referenced_vars_for_templates(["echo {{ commit }}", "--onto={{ branch }}"]);
assert_eq!(
refs.iter().map(String::as_str).collect::<Vec<_>>(),
["branch", "commit"]
);
}
/// Unparsable templates contribute nothing rather than erroring — the
/// caller's own validation reports the syntax error, naming which position
/// was at fault.
#[test]
fn test_referenced_vars_for_templates_skips_unparsable() {
let refs = referenced_vars_for_templates(["{{ unclosed", "echo {{ commit }}"]);
assert_eq!(
refs.iter().map(String::as_str).collect::<Vec<_>>(),
["commit"]
);
}
#[test]
fn test_referenced_vars_for_config_syntax_error_propagates() {
let cfg = super::super::CommandConfig::single("echo {{ unclosed");
let err = referenced_vars_for_config(&cfg, |_| "deploy".to_owned()).unwrap_err();
let msg = format!("{err:#}");
assert!(msg.contains("Failed to expand deploy"), "got: {msg}");
assert!(msg.contains("syntax error"), "got: {msg}");
}
#[test]
fn test_validate_template_undefined_var() {
let test = test_repo();
let err = validate_template(
"{{ nonexistent_var }}",
ValidationScope::Hook(HookType::PostCreate),
&test.repo,
"test",
)
.unwrap_err();
assert!(err.message.contains("undefined"), "got: {}", err.message);
// Should list available vars in hint
assert!(!err.available_vars.is_empty(), "should list available vars");
assert!(err.available_vars.contains(&"branch".to_string()));
let err = validate_template(
"echo {{ brnch }}",
ValidationScope::Hook(HookType::PreMerge),
&test.repo,
"test",
)
.unwrap_err();
assert_eq!(
err.message,
"Failed to expand test: undefined variable brnch"
);
assert_eq!(err.source_line.as_deref(), Some("echo {{ brnch }}"));
assert_eq!(err.suggestion.as_deref(), Some("branch"));
let err = validate_template(
"{{ brnch }}{{ other_missing }}",
ValidationScope::Alias,
&test.repo,
"test",
)
.unwrap_err();
assert_eq!(
err.message,
"Failed to expand test: undefined variables brnch, other_missing"
);
assert_eq!(err.suggestion, None);
}
#[test]
fn test_format_hook_variables_groups_and_unset() {
let mut ctx = TemplateContext::default();
ctx.insert("branch", "feature");
ctx.insert("worktree_path", "/tmp/feature");
ctx.insert("worktree_name", "feature");
ctx.insert("base", "main");
ctx.insert("base_worktree_path", "/tmp/main");
ctx.insert("target", "-");
// target_worktree_path deliberately absent — mimics `wt switch -`
ctx.insert("repo", "demo");
ctx.insert("repo_path", "/tmp/demo");
ctx.insert("cwd", "/tmp/feature");
ctx.insert("hook_type", "pre-switch");
ctx.insert("hook_name", "show-variables");
assert_snapshot!(format_hook_variables(HookType::PreSwitch, &ctx), @r"
branch = feature
worktree_path = /tmp/feature
worktree_name = feature
commit = (unset)
short_commit = (unset)
upstream = (unset)
base = main
base_worktree_path = /tmp/main
target = -
target_worktree_path = (unset)
pr_number = (unset)
pr_url = (unset)
repo = demo
repo_path = /tmp/demo
owner = (unset)
remote_repo = (unset)
primary_worktree_path = (unset)
default_branch = (unset)
remote = (unset)
remote_url = (unset)
cwd = /tmp/feature
hook_type = pre-switch
hook_name = show-variables
");
}
#[test]
fn test_format_hook_variables_filters_operation() {
// pre-commit only has `target` in operation scope — no base*, pr_*, etc.
let mut ctx = TemplateContext::default();
ctx.insert("target", "main");
let out = format_hook_variables(HookType::PreCommit, &ctx);
assert!(out.contains("target = main"), "got: {out}");
assert!(
!out.contains("base "),
"pre-commit has no `base`; got: {out}"
);
assert!(
!out.contains("pr_number"),
"pre-commit has no `pr_number`; got: {out}"
);
}
#[test]
fn test_format_alias_variables_includes_args_no_hook_keys() {
let mut ctx = TemplateContext::default();
ctx.insert("branch", "feature");
ctx.insert("worktree_path", "/tmp/feature");
ctx.insert("worktree_name", "feature");
ctx.insert("repo", "demo");
ctx.insert("repo_path", "/tmp/demo");
ctx.insert("cwd", "/tmp/feature");
// args is JSON-encoded per `ALIAS_ARGS_KEY` contract; the table
// decodes and shell-renders it to match `{{ args }}` substitution.
ctx.insert(ALIAS_ARGS_KEY, r#"["a","b c"]"#);
let out = format_alias_variables(&ctx, VarScope::All);
assert!(
out.contains("args = a 'b c'"),
"got: {out}"
);
// No hook-only keys appear in alias scope.
assert!(!out.contains("hook_type"), "got: {out}");
assert!(!out.contains("target"), "got: {out}");
assert!(!out.contains("base "), "got: {out}");
}
#[test]
fn test_format_alias_variables_args_empty() {
let mut ctx = TemplateContext::default();
ctx.insert(ALIAS_ARGS_KEY, "[]");
let out = format_alias_variables(&ctx, VarScope::All);
// Empty args render as an empty string after the `=` — distinct from
// `(unset)`, which means the key was absent entirely. `args` sits last
// in alias ordering, so the output ends with it.
assert!(out.ends_with("args = "), "got: {out:?}");
}
#[test]
fn test_vars_map_to_value_parses_json() {
let mut entries = std::collections::BTreeMap::new();
entries.insert("ticket".to_string(), "JIRA-1".to_string());
entries.insert("config".to_string(), r#"{"port": 8080}"#.to_string());
let value = vars_map_to_value(&entries);
// Plain strings stay as-is; JSON objects support nested access
assert_eq!(
value.get_attr("ticket").unwrap(),
Value::from("JIRA-1".to_string())
);
assert_eq!(
value.get_attr("config").unwrap().get_attr("port").unwrap(),
Value::from(8080)
);
}
#[test]
fn test_validate_list_column_template() {
let test = test_repo();
// Row-identity vars, unconstrained vars.* keys, and filters validate
validate_list_column_template("{{ branch }} {{ worktree_name }}", &test.repo, "t").unwrap();
validate_list_column_template("{{ vars.any_key_at_all }}", &test.repo, "t").unwrap();
validate_list_column_template("{{ branch | sanitize }}", &test.repo, "t").unwrap();
// Nested vars access (JSON values at runtime) must not be rejected
// even though the trial render's placeholder vars are flat strings
validate_list_column_template("{{ vars.config.port }}", &test.repo, "t").unwrap();
// git.branch.* mirrors vars.*: any key validates, filters apply
validate_list_column_template("{{ git.branch.jira }}", &test.repo, "t").unwrap();
validate_list_column_template(
"{{ git.branch.description | lines | first }}",
&test.repo,
"t",
)
.unwrap();
// Unknown top-level variables list the available set, both namespaces included
let err = validate_list_column_template("{{ branhc }}", &test.repo, "t").unwrap_err();
assert!(err.message.contains("branhc"), "got: {}", err.message);
assert_eq!(
err.available_vars,
vec![
"branch",
"git.branch.<key>",
"vars.<key>",
"worktree_name",
"worktree_path"
]
);
// Syntax errors fail
validate_list_column_template("{{ branch", &test.repo, "t").unwrap_err();
// Misspelled filters surface via the trial render rather than as
// silently empty cells at runtime
let err =
validate_list_column_template("{{ branch | nosuch }}", &test.repo, "t").unwrap_err();
assert!(err.message.contains("nosuch"), "got: {}", err.message);
}
}