Skip to content

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.md
index 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_c
All `$ ` 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.md
index 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.md
index 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 avai
Get 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-oauth2
worktree_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.html
index 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.rs
index 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.rs
index 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="...") %}` forms
static 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="...") %}` forms
static 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 parameters
let content = content
- .replace("__WT_OPEN2__", "{{")
- .replace("__WT_CLOSE2__", "}}")
+ .replace("__WT_OPEN__", "{{")
+ .replace("__WT_CLOSE__", "}}")
.replace("__WT_QUOT__", "\"");
// Strip AUTO-GENERATED marker comments (keep content)