Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
refactor(docs): fix blank-line cmd-stream corruption; share AUTO-GENERATED marker constants (#2417)
Maximilian Roos1e053d2d88c8
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.mdindex fadbfef28..43f9dedf1 100644--- a/docs/CLAUDE.md+++ b/docs/CLAUDE.md@@ -231,7 +231,7 @@ All shell commands use `$ ` prefix in `` ```console `` blocks. `convert_dollar_cAll `$ ` commands go through the `cmd` parameter path for consistent Syntect highlighting. Multiple commands are joined by `|||`; the template splits and highlights each individually. Commands are wrapped in `<span class="cmd">` (CSS `::before` adds `$ `). Comment lines (`#`) are highlighted but not wrapped (no prompt).-**Placeholders in cmd values:** Tera (Zola's template engine) would interpret `{{ }}` in the `cmd` parameter as template expressions, and `"` would close the parameter string. Since Tera has no backslash-escape mechanism for string literals, these characters are replaced with text placeholders (`__WT_OPEN2__`, `__WT_CLOSE2__`, `__WT_QUOT__`) in the Rust conversion function. The terminal shortcode template replaces them back before Syntect highlighting. The sync test also strips them when generating skill reference files.+**Placeholders in cmd values:** Tera (Zola's template engine) would interpret `{{ }}` in the `cmd` parameter as template expressions, and `"` would close the parameter string. Since Tera has no backslash-escape mechanism for string literals, these characters are replaced with text placeholders (`__WT_OPEN__`, `__WT_CLOSE__`, `__WT_QUOT__`) in the Rust conversion function. The terminal shortcode template replaces them back before Syntect highlighting. The sync test also strips them when generating skill reference files.Hand-written docs can use either `console` fences with `$ ` (auto-converted by the sync test) or shortcodes directly.diff --git a/docs/content/hook.md b/docs/content/hook.mdindex 69b40f658..1ac5923bc 100644--- a/docs/content/hook.md+++ b/docs/content/hook.md@@ -247,7 +247,7 @@ copy = "wt step copy-ignored"`wt hook <type>` runs hooks on demand — useful for testing during development, running in CI pipelines, or re-running after a failure.-{{ terminal(cmd="wt hook pre-merge # Run all pre-merge hooks|||wt hook pre-merge test # Run hooks named __WT_QUOT__test__WT_QUOT__ from both sources|||wt hook pre-merge test build # Run hooks named __WT_QUOT__test__WT_QUOT__ and __WT_QUOT__build__WT_QUOT__|||wt hook pre-merge user: # Run all user hooks|||wt hook pre-merge project: # Run all project hooks|||wt hook pre-merge user:test # Run only user's __WT_QUOT__test__WT_QUOT__ hook|||wt hook pre-merge --yes # Skip approval prompts (for CI)|||wt hook pre-start --branch=feature/test # Override a template variable|||wt hook pre-merge -- --extra args # Forward tokens into __WT_OPEN2__ args __WT_CLOSE2__") }}+{{ terminal(cmd="wt hook pre-merge # Run all pre-merge hooks|||wt hook pre-merge test # Run hooks named __WT_QUOT__test__WT_QUOT__ from both sources|||wt hook pre-merge test build # Run hooks named __WT_QUOT__test__WT_QUOT__ and __WT_QUOT__build__WT_QUOT__|||wt hook pre-merge user: # Run all user hooks|||wt hook pre-merge project: # Run all project hooks|||wt hook pre-merge user:test # Run only user's __WT_QUOT__test__WT_QUOT__ hook|||wt hook pre-merge --yes # Skip approval prompts (for CI)|||wt hook pre-start --branch=feature/test # Override a template variable|||wt hook pre-merge -- --extra args # Forward tokens into __WT_OPEN__ args __WT_CLOSE__") }}The `user:` and `project:` prefixes filter by source. Use `user:` or `project:` alone to run all hooks from that source, or `user:name` / `project:name` to run a specific hook.diff --git a/docs/content/step.md b/docs/content/step.mdindex dfa9f1340..aaafaa890 100644--- a/docs/content/step.md+++ b/docs/content/step.md@@ -468,29 +468,29 @@ All [hook template variables and filters](@/hook.md#template-variables) are avaiGet the port for the current branch:-{% terminal(cmd="wt step eval '__WT_OPEN2__ branch | hash_port __WT_CLOSE2__'") %}+{% terminal(cmd="wt step eval '__WT_OPEN__ branch | hash_port __WT_CLOSE__'") %}16066{% end %}Use in shell substitution:-{{ terminal(cmd="curl http://localhost:$(wt step eval '__WT_OPEN2__ branch | hash_port __WT_CLOSE2__')/health") }}+{{ terminal(cmd="curl http://localhost:$(wt step eval '__WT_OPEN__ branch | hash_port __WT_CLOSE__')/health") }}Combine multiple values:-{% terminal(cmd="wt step eval '__WT_OPEN2__ branch | hash_port __WT_CLOSE2__,__WT_OPEN2__ (__WT_QUOT__supabase-api-__WT_QUOT__ ~ branch) | hash_port __WT_CLOSE2__'") %}+{% terminal(cmd="wt step eval '__WT_OPEN__ branch | hash_port __WT_CLOSE__,__WT_OPEN__ (__WT_QUOT__supabase-api-__WT_QUOT__ ~ branch) | hash_port __WT_CLOSE__'") %}16066,16739{% end %}Use conditionals and filters:-{% terminal(cmd="wt step eval '__WT_OPEN2__ branch | sanitize_db __WT_CLOSE2__'") %}+{% terminal(cmd="wt step eval '__WT_OPEN__ branch | sanitize_db __WT_CLOSE__'") %}feature_auth_oauth2_a1b{% end %}Show available template variables:-{% terminal(cmd="wt step eval --dry-run '__WT_OPEN2__ branch __WT_CLOSE2__'") %}+{% terminal(cmd="wt step eval --dry-run '__WT_OPEN__ branch __WT_CLOSE__'") %}branch=feature/auth-oauth2worktree_path=/home/user/projects/myapp-feature-auth-oauth2...@@ -558,7 +558,7 @@ Run npm install in all worktrees:Use branch name in command:-{{ terminal(cmd="wt step for-each -- __WT_QUOT__echo Branch: __WT_OPEN2__ branch __WT_CLOSE2____WT_QUOT__") }}+{{ terminal(cmd="wt step for-each -- __WT_QUOT__echo Branch: __WT_OPEN__ branch __WT_CLOSE____WT_QUOT__") }}Pull updates in worktrees with upstreams (skips others):diff --git a/docs/templates/shortcodes/terminal.html b/docs/templates/shortcodes/terminal.htmlindex 8f072b49e..c43bd02bc 100644--- a/docs/templates/shortcodes/terminal.html+++ b/docs/templates/shortcodes/terminal.html@@ -8,7 +8,7 @@{% endif %}<pre class="terminal"><code>{%- for cmd_line in cmd_lines -%}-{%- set cmd_line = cmd_line | replace(from="__WT_OPEN2__", to="{{") | replace(from="__WT_CLOSE2__", to="}}") | replace(from="__WT_QUOT__", to='"') -%}+{%- set cmd_line = cmd_line | replace(from="__WT_OPEN__", to="{{") | replace(from="__WT_CLOSE__", to="}}") | replace(from="__WT_QUOT__", to='"') -%}{%- set md = fence ~ "bash" ~ cmd_line ~ "" ~ fence -%}diff --git a/src/docs.rs b/src/docs.rsindex 65366e8bc..8e73b8884 100644--- a/src/docs.rs+++ b/src/docs.rs@@ -76,32 +76,32 @@ pub fn convert_dollar_console_to_terminal(text: &str) -> String {continue;}- // Use cmd parameter for Syntect highlighting on all blocks.- // {{ and }} are replaced with placeholders so Tera doesn't interpret- // them as template expressions. The terminal shortcode template- // replaces them back before Syntect highlighting.- // Multiple commands/comments joined with ||| delimiter;- // the template splits and highlights each individually.- let cmd_value: Vec<_> = block_lines+ // Classify each line into the cmd= stream (rendered with prompt+ // prefix and Syntect highlighting, joined by `|||`) or the output+ // body. `$ <cmd>` lines feed cmd= verbatim (with `"` and `{{`/`}}`+ // escaped past Tera); `#` lines feed cmd= so the template styles+ // them as bash-comment section headers (used by the `wt list` jq+ // recipes block). Blank lines belong to whichever side has content+ // — to cmd= when the block is command-only (visual spacing between+ // recipe groups), to body otherwise.+ let has_output = block_lines.iter()- .filter_map(|l| {- if let Some(cmd) = l.strip_prefix("$ ") {- Some(- cmd.replace('"', "__WT_QUOT__")- .replace("{{", "__WT_OPEN2__")- .replace("}}", "__WT_CLOSE2__"),- )- } else if l.starts_with('#') || l.is_empty() {- Some(l.to_string())- } else {- None // output lines go in body- }- })- .collect();- let body_lines: Vec<_> = block_lines- .iter()- .filter(|l| !l.starts_with("$ ") && !l.starts_with('#') && !l.is_empty())- .collect();+ .any(|l| !l.is_empty() && !l.starts_with("$ ") && !l.starts_with('#'));+ let mut cmd_value: Vec<String> = Vec::new();+ let mut body_lines: Vec<&&str> = Vec::new();+ for line in &block_lines {+ if let Some(cmd) = line.strip_prefix("$ ") {+ cmd_value.push(+ cmd.replace('"', "__WT_QUOT__")+ .replace("{{", "__WT_OPEN__")+ .replace("}}", "__WT_CLOSE__"),+ );+ } else if line.starts_with('#') || (line.is_empty() && !has_output) {+ cmd_value.push((*line).to_string());+ } else {+ body_lines.push(line);+ }+ }let cmd_str = cmd_value.join("|||");if body_lines.is_empty() {@@ -138,7 +138,7 @@ mod tests {assert_snapshot!(convert_dollar_console_to_terminal("```console\n$ wt step eval '{{ branch | hash_port }}'\n16066\n```"), @r#"- {% terminal(cmd="wt step eval '__WT_OPEN2__ branch | hash_port __WT_CLOSE2__'") %}+ {% terminal(cmd="wt step eval '__WT_OPEN__ branch | hash_port __WT_CLOSE__'") %}16066{% end %}"#);@@ -188,5 +188,18 @@ mod tests {"```console\n# Recent commands\n$ tail -5 log.jsonl | jq .\n\n# Failed\n$ jq 'select(.exit != 0)' log.jsonl\n```"), @r##"{{ terminal(cmd="# Recent commands|||tail -5 log.jsonl | jq .||||||# Failed|||jq 'select(.exit != 0)' log.jsonl") }}"##);++ // Blank line in mixed-mode block (cmd + output) stays in body, doesn't+ // leak into cmd= as a stray `$ ` prompt.+ assert_snapshot!(convert_dollar_console_to_terminal(+ "```console\n$ wt list\n Branch Status\n@ main\n\n○ Showing 1 worktree\n```"+ ), @r#"+ {% terminal(cmd="wt list") %}+ Branch Status+ @ main++ ○ Showing 1 worktree+ {% end %}+ "#);}}diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rsindex e4091c69b..5513d4a20 100644--- a/tests/integration_tests/readme_sync.rs+++ b/tests/integration_tests/readme_sync.rs@@ -28,14 +28,37 @@ use std::fs;use std::path::Path;use std::sync::LazyLock;+/// Opening prefix for AUTO-GENERATED markers (rest of line: `<id> — edit <source> to update -->`).+/// Two flavors:+/// - `MARKER_OPEN_PREFIX` wraps any content (used by command-page sync, help-page sections)+/// - `MARKER_OPEN_HTML_PREFIX` wraps an HTML terminal shortcode (used by standalone-doc sync)+const MARKER_OPEN_PREFIX: &str = "<!-- ⚠️ AUTO-GENERATED from ";+const MARKER_OPEN_HTML_PREFIX: &str = "<!-- ⚠️ AUTO-GENERATED-HTML from ";+const MARKER_CLOSE: &str = "<!-- END AUTO-GENERATED -->";++/// Format an open marker line for the given id. `flavor` is the prefix const.+fn format_marker_open(flavor: &str, id: &str, source_label: &str) -> String {+ format!("{flavor}{id} — edit {source_label} to update -->")+}++/// Wrap a body in `<!-- ⚠️ AUTO-GENERATED ... -->` markers.+/// Inner whitespace ("\n\n{body}\n\n") matches the historical layout that+/// downstream regexes and visual review depend on.+fn wrap_in_marker(flavor: &str, id: &str, source_label: &str, body: &str) -> String {+ let open = format_marker_open(flavor, id, source_label);+ format!("{open}\n\n{body}\n\n{MARKER_CLOSE}")+}+/// Unified pattern for all AUTO-GENERATED markers (README and docs)/// Format: <!-- ⚠️ AUTO-GENERATED from <id> — edit <source> to update -->/// ID types: path.snap (snapshot), `cmd` (help), path#anchor (section)/// Content may be wrapped in ```console``` (snapshots) or unwrapped (help/sections)static MARKER_PATTERN: LazyLock<Regex> = LazyLock::new(|| {- Regex::new(- r"(?s)<!-- ⚠️ AUTO-GENERATED from ([^\n]+?) — edit [^\n]+ to update -->\n+([\s\S]*?)\n*<!-- END AUTO-GENERATED -->",- )+ Regex::new(&format!(+ r"(?s){}([^\n]+?) — edit [^\n]+ to update -->\n+([\s\S]*?)\n*{}",+ regex::escape(MARKER_OPEN_PREFIX),+ regex::escape(MARKER_CLOSE),+ )).unwrap()});@@ -46,9 +69,11 @@ static ANSI_LITERAL_REGEX: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"\[[0-/// Format: <!-- ⚠️ AUTO-GENERATED-HTML from path.snap — edit source to update -->/// Matches both old `{% terminal() %}` and new `{% terminal(cmd="...") %}` formsstatic DOCS_SNAPSHOT_MARKER_PATTERN: LazyLock<Regex> = LazyLock::new(|| {- Regex::new(- r#"(?s)<!-- ⚠️ AUTO-GENERATED-HTML from ([^\s]+\.snap) — edit source to update -->\n+\{% terminal\([^)]*\) %\}\n(.*?)\{% end %\}\n+<!-- END AUTO-GENERATED -->"#,- )+ Regex::new(&format!(+ r"(?s){}([^\s]+\.snap) — edit source to update -->\n+\{{% terminal\([^)]*\) %\}}\n(.*?)\{{% end %\}}\n+{}",+ regex::escape(MARKER_OPEN_HTML_PREFIX),+ regex::escape(MARKER_CLOSE),+ )).unwrap()});@@ -314,17 +339,14 @@ fn format_replacement(id: &str, content: &str, format: &OutputFormat) -> String.captures(content).map(|c| format!(r#"cmd="{}""#, c.get(1).unwrap().as_str())).unwrap_or_default();- format!(- "<!-- ⚠️ AUTO-GENERATED-HTML from {} — edit source to update -->\n\n{{% terminal({}) %}}\n{}\n{{% end %}}\n\n<!-- END AUTO-GENERATED -->",- id, cmd_attr, content- )- }- OutputFormat::Unwrapped => {- format!(- "<!-- ⚠️ AUTO-GENERATED from {} — edit source to update -->\n\n{}\n\n<!-- END AUTO-GENERATED -->",- id, content+ wrap_in_marker(+ MARKER_OPEN_HTML_PREFIX,+ id,+ "source",+ &format!("{{% terminal({cmd_attr}) %}}\n{content}\n{{% end %}}"),)}+ OutputFormat::Unwrapped => wrap_in_marker(MARKER_OPEN_PREFIX, id, "source", content),}}@@ -473,18 +495,12 @@ fn expand_command_placeholders(let full_match = cap.get(0).unwrap().as_str();let placeholder_id = cap.get(1).unwrap().as_str();// Exactly one of groups 2–4 matched — pick whichever.- let raw_display_cmd = cap+ let display_cmd = cap.get(2).or_else(|| cap.get(3)).or_else(|| cap.get(4)).unwrap().as_str();- // Strip trailing `|||` delimiters: `convert_dollar_console_to_terminal`- // treats blank lines in a ```console``` body as extra empty commands and- // appends them to the `cmd=` parameter with `|||` separators. Those- // empties would render as a stray `$ ` prompt in the Zola terminal- // template.- let display_cmd = raw_display_cmd.trim_end_matches('|').trim_end();let Some(snapshot_name) = command_to_snapshot(placeholder_id) else {continue;@@ -512,12 +528,11 @@ fn expand_command_placeholders(// placeholder id, so disambiguation suffixes like `(markers)`// don't leak into the rendered prompt. Prompt ($) is added// via CSS ::before, so not included in HTML.- format!(- "<!-- ⚠️ AUTO-GENERATED from tests/snapshots/{snapshot_name} — edit source to update -->\n\n\- {{% terminal(cmd=\"{display_cmd}\") %}}\n\- {normalized}\n\- {{% end %}}\n\n\- <!-- END AUTO-GENERATED -->",+ wrap_in_marker(+ MARKER_OPEN_PREFIX,+ &format!("tests/snapshots/{snapshot_name}"),+ "source",+ &format!("{{% terminal(cmd=\"{display_cmd}\") %}}\n{normalized}\n{{% end %}}",),)}ExpandMode::Plain => {@@ -899,9 +914,11 @@ fn heading_to_anchor(heading: &str) -> String {/// These need to be converted to plain code blocks for README/// Matches both `{% terminal() %}` and `{% terminal(cmd="...") %}` formsstatic TERMINAL_MARKER_PATTERN: LazyLock<Regex> = LazyLock::new(|| {- Regex::new(- r#"(?s)(?:```bash\n[^\n]+\n```\n+)?<!-- ⚠️ AUTO-GENERATED-HTML from [^\n]+ -->\n+\{% terminal\([^)]*\) %\}\n(.*?)\{% end %\}\n+<!-- END AUTO-GENERATED -->"#,- )+ Regex::new(&format!(+ r"(?s)(?:```bash\n[^\n]+\n```\n+)?{}[^\n]+ -->\n+\{{% terminal\([^)]*\) %\}}\n(.*?)\{{% end %\}}\n+{}",+ regex::escape(MARKER_OPEN_HTML_PREFIX),+ regex::escape(MARKER_CLOSE),+ )).unwrap()});@@ -1951,7 +1968,9 @@ static ZOLA_TERMINAL_SELF_CLOSING_PATTERN: LazyLock<Regex> =static ZOLA_EXPERIMENTAL_SHORTCODE: LazyLock<Regex> =LazyLock::new(|| Regex::new(r"\{\{\s*experimental\(\)\s*\}\}").unwrap());-/// Regex to strip AUTO-GENERATED marker comments (just the comments, not content)+/// Regex to strip AUTO-GENERATED marker comments (just the comments, not content).+/// Matches both the open prefixes (with ⚠️) and the close form (with or without+/// the help-page mirrored suffix).static AUTO_GENERATED_MARKER_PATTERN: LazyLock<Regex> = LazyLock::new(|| {Regex::new(r"<!-- ⚠️ AUTO-GENERATED[^>]*-->\n*|<!-- END AUTO-GENERATED[^>]*-->\n*").unwrap()});@@ -2053,8 +2072,8 @@ fn transform_docs_for_skill(content: &str) -> String {// Replace placeholders used to escape Tera template syntax in cmd parameterslet content = content- .replace("__WT_OPEN2__", "{{")- .replace("__WT_CLOSE2__", "}}")+ .replace("__WT_OPEN__", "{{")+ .replace("__WT_CLOSE__", "}}").replace("__WT_QUOT__", "\"");// Strip AUTO-GENERATED marker comments (keep content)