Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

test(readme-sync): expand snapshot output in skill reference files (#2049)

Maximilian Roos34b87fde969c
diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.md
index e2c13f08f..305179bd2 100644
--- a/skills/worktrunk/reference/config.md
+++ b/skills/worktrunk/reference/config.md
@@ -873,9 +873,15 @@ Custom status text or emoji shown in the `wt list` Status column.
Markers appear at the end of the Status column, after git symbols:
-<!-- wt list (markers) -->
-```bash
-wt list
+```
+$ wt list
+ Branch Status HEAD± main↕ Remote⇅ Commit Age Message
+@ main ^⇡ ⇡1 33323bc1 1d Initial commit
++ feature-api ↑ 🤖 ↑1 70343f03 1d Add REST API endpoints
++ review-ui ? ↑ 💬 ↑1 a585d6ed 1d Add dashboard component
++ wip-docs ? – 33323bc1 1d Initial commit
+
+○ Showing 4 worktrees, 2 with changes, 2 ahead, 1 column hidden
```
### Use cases
diff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.md
index 4bae1dbfe..158db20da 100644
--- a/skills/worktrunk/reference/list.md
+++ b/skills/worktrunk/reference/list.md
@@ -14,23 +14,43 @@ The table renders progressively: branch names, paths, and commit hashes appear i
List all worktrees:
-<!-- wt list -->
-```bash
+```
$ wt list
+ Branch Status HEAD± main↕ Remote⇅ Commit Age Message
+@ feature-api + ↕⇡ +54 -5 ↑4 ↓1 ⇡3 6814f02a 30m Add API tests
+^ main ^⇅ ⇡1 ⇣1 41ee0834 4d Merge fix-auth: hardened to…
++ fix-auth ↕| ↑2 ↓1 | b772e68b 5h Add secure token storage
++ fix-typos _| | 41ee0834 4d Merge fix-auth: hardened to…
+
+○ Showing 4 worktrees, 1 with changes, 2 ahead, 1 column hidden
```
Include CI status, line diffs, and LLM summaries:
-<!-- wt list --full -->
-```bash
+```
$ wt list --full
+ Branch Status HEAD± main↕ main…± Summary Remote⇅ CI Commit
+@ feature-api + ↕⇡ +54 -5 ↑4 ↓1 +234 -24 Refactor API to REST architecture with middleware ⇡3 ● 6814f02a
+^ main ^⇅ ⇡1 ⇣1 ● 41ee0834
++ fix-auth ↕| ↑2 ↓1 +25 -11 Harden auth with constant-time token validation | ● b772e68b
++ fix-typos _| | ● 41ee0834
+
+○ Showing 4 worktrees, 1 with changes, 2 ahead, 3 columns hidden
```
Include branches that don't have worktrees:
-<!-- wt list --branches --full -->
-```bash
+```
$ wt list --branches --full
+ Branch Status HEAD± main↕ main…± Summary Remote⇅ CI Commit
+@ feature-api + ↕⇡ +54 -5 ↑4 ↓1 +234 -24 Refactor API to REST architecture with middleware ⇡3 ● 6814f02a
+^ main ^⇅ ⇡1 ⇣1 ● 41ee0834
++ fix-auth ↕| ↑2 ↓1 +25 -11 Harden auth with constant-time token validation | ● b772e68b
++ fix-typos _| | ● 41ee0834
+ exp /↕ ↑2 ↓1 +137 Explore GraphQL schema and resolvers 96379229
+ wip /↕ ↑1 ↓1 +33 Start API documentation b40716dc
+
+○ Showing 4 worktrees, 2 branches, 1 with changes, 4 ahead, 3 columns hidden
```
Output as JSON for scripting:
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index b043b63e0..7b46679f2 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -21,6 +21,7 @@
#![cfg(not(windows))]
use crate::common::wt_command;
+use ansi_str::AnsiStr;
use ansi_to_html::convert as ansi_to_html;
use regex::Regex;
use std::fs;
@@ -378,6 +379,16 @@ fn update_section(
static COMMAND_PLACEHOLDER_PATTERN: LazyLock<Regex> =
LazyLock::new(|| Regex::new(r"<!-- (wt [^>]+) -->\n```bash\nwt [^\n]+\n```").unwrap());
+/// Regex for command placeholders in --help-page --plain output
+/// Matches: <!-- wt <id> -->\n```bash\n[$ ]wt <cmd>\n```
+/// Plain mode preserves the source block verbatim (skips convert_dollar_console_to_terminal),
+/// so blocks with and without the `$ ` prompt both appear — the prompt is optional.
+/// Group 1 captures the placeholder id (used for snapshot lookup, e.g. `wt list (markers)`);
+/// group 2 captures the actual command to display (e.g. `wt list`).
+static COMMAND_PLACEHOLDER_PATTERN_PLAIN: LazyLock<Regex> = LazyLock::new(|| {
+ Regex::new(r"<!-- (wt [^>]+) -->\n```bash\n(?:\$ )?(wt [^\n]+)\n```").unwrap()
+});
+
/// Map commands to their snapshot files for help page expansion
fn command_to_snapshot(command: &str) -> Option<&'static str> {
match command {
@@ -454,6 +465,59 @@ fn expand_command_placeholders(content: &str, snapshots_dir: &Path) -> Result<St
Ok(result)
}
+/// Expand command placeholders in --help-page --plain output to plain code blocks
+///
+/// Finds `<!-- wt <id> -->` + ```bash\n[$ ]wt <cmd>\n``` blocks and replaces them
+/// with code blocks containing the command and its plain text snapshot output.
+///
+/// The placeholder id (e.g. `wt list (markers)`) is used for snapshot lookup;
+/// the displayed command comes from the block body so disambiguation suffixes
+/// like `(markers)` don't leak into the rendered prompt.
+///
+/// Commands without a snapshot mapping are left as plain code blocks.
+fn expand_command_placeholders_plain(
+ content: &str,
+ snapshots_dir: &Path,
+) -> Result<String, String> {
+ let mut result = content.to_string();
+ let mut errors = Vec::new();
+
+ for cap in COMMAND_PLACEHOLDER_PATTERN_PLAIN.captures_iter(content) {
+ let full_match = cap.get(0).unwrap().as_str();
+ let placeholder_id = cap.get(1).unwrap().as_str();
+ let display_cmd = cap.get(2).unwrap().as_str();
+
+ let Some(snapshot_name) = command_to_snapshot(placeholder_id) else {
+ continue;
+ };
+
+ let snapshot_path = snapshots_dir.join(snapshot_name);
+ if !snapshot_path.exists() {
+ errors.push(format!(
+ "Snapshot file not found: {} (for command '{}')",
+ snapshot_path.display(),
+ placeholder_id
+ ));
+ continue;
+ }
+
+ let snapshot_content = fs::read_to_string(&snapshot_path)
+ .map_err(|e| format!("Failed to read {}: {}", snapshot_path.display(), e))?;
+
+ let plain = trim_lines(&parse_snapshot_content_for_skill(&snapshot_content));
+
+ let replacement = format!("```\n$ {display_cmd}\n{plain}\n```");
+
+ result = result.replace(full_match, &replacement);
+ }
+
+ if !errors.is_empty() {
+ return Err(errors.join("\n"));
+ }
+
+ Ok(result)
+}
+
/// Convert literal bracket notation [32m to actual escape sequences \x1b[32m
fn literal_to_escape(text: &str) -> String {
ANSI_LITERAL_REGEX
@@ -501,6 +565,14 @@ fn parse_snapshot_content_for_docs(content: &str) -> Result<String, String> {
Ok(clean_ansi_html(&html))
}
+/// Parse snapshot content for skill reference files (plain text, ANSI stripped)
+fn parse_snapshot_content_for_skill(content: &str) -> String {
+ let content = parse_snapshot_raw(content);
+ let content = replace_placeholders(&content);
+ let content = literal_to_escape(&content);
+ content.ansi_strip().into_owned()
+}
+
/// Ensure each line ends with a reset code so ansi-to-html produces clean per-line HTML
///
/// When trailing ANSI resets are stripped from snapshots for cross-platform consistency,
@@ -2110,6 +2182,10 @@ fn generate_skill_from_help(cmd: &str, project_root: &Path) -> Result<String, St
));
}
+ // Expand command placeholders (e.g., <!-- wt list --> → plain text snapshot output)
+ let snapshots_dir = project_root.join("tests/snapshots");
+ let content = expand_command_placeholders_plain(&content, &snapshots_dir)?;
+
Ok(finalize_skill_content(&content))
}