Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
refactor(docs): unify AUTO-GENERATED marker form; share constants across crate boundary (#2418)
Maximilian Roos8abefbce82b5
diff --git a/docs/content/claude-code.md b/docs/content/claude-code.mdindex 035cef40b..0cb150c9d 100644--- a/docs/content/claude-code.md+++ b/docs/content/claude-code.md@@ -38,7 +38,7 @@ Claude Code is designed to load the skill automatically when it detects worktrunThe plugin tracks Claude sessions with status markers in `wt list`:-<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__list__list_with_user_marker.snap — edit source to update -->+<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__list__list_with_user_marker.snap — edit source to update -->{% terminal(cmd="wt list") %}<span class="cmd">wt list</span>diff --git a/docs/content/llm-commits.md b/docs/content/llm-commits.mdindex e43b65abd..64fc41fb8 100644--- a/docs/content/llm-commits.md+++ b/docs/content/llm-commits.md@@ -63,7 +63,7 @@ These examples assume a feature worktree with changes to commit.Squashes all changes (uncommitted + existing commits) into one commit with an LLM-generated message, then merges to the default branch:-<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__merge__docs_merge_squash_llm.snap — edit source to update -->+<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__merge__docs_merge_squash_llm.snap — edit source to update -->{% terminal(cmd="wt merge") %}<span class="cmd">wt merge</span>@@ -93,7 +93,7 @@ Squashes all changes (uncommitted + existing commits) into one commit with an LLStages and commits with LLM-generated message:-<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__merge__docs_step_commit_llm.snap — edit source to update -->+<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__merge__docs_step_commit_llm.snap — edit source to update -->{% terminal(cmd="wt step commit") %}<span class="cmd">wt step commit</span>@@ -108,7 +108,7 @@ Stages and commits with LLM-generated message:Squashes branch commits into one with LLM-generated message:-<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__merge__docs_step_squash_llm.snap — edit source to update -->+<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__merge__docs_step_squash_llm.snap — edit source to update -->{% terminal(cmd="wt step squash") %}<span class="cmd">wt step squash</span>diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.mdindex a996cbdfc..142f6d343 100644--- a/docs/content/tips-patterns.md+++ b/docs/content/tips-patterns.md@@ -59,7 +59,7 @@ server = "lsof -ti :{{ branch | hash_port }} -sTCP:LISTEN | xargs kill 2>/dev/nuThe URL column in `wt list` shows each worktree's dev server:-<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__list__tips_dev_server_workflow.snap — edit source to update -->+<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__list__tips_dev_server_workflow.snap — edit source to update -->{% terminal(cmd="wt list") %}<span class="cmd">wt list</span>diff --git a/docs/content/worktrunk.md b/docs/content/worktrunk.mdindex 5715fd5b8..e524858cd 100644--- a/docs/content/worktrunk.md+++ b/docs/content/worktrunk.md@@ -135,7 +135,7 @@ Alternatively, disable Windows Terminal's alias (Settings → Privacy & securityCreate a worktree for a new feature:-<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__list__quickstart_switch.snap — edit source to update -->+<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__list__quickstart_switch.snap — edit source to update -->{% terminal(cmd="wt switch --create feature-auth") %}<span class="cmd">wt switch --create feature-auth</span>@@ -146,7 +146,7 @@ Create a worktree for a new feature:This creates a new branch and worktree, then switches to it. Do your work, then check all worktrees with [`wt list`](@/list.md):-<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__list__quickstart_list.snap — edit source to update -->+<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__list__quickstart_list.snap — edit source to update -->{% terminal(cmd="wt list") %}<span class="cmd">wt list</span>@@ -169,7 +169,7 @@ When done, either:**Local merge** — squash, rebase onto main, fast-forward merge, clean up:-<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__list__quickstart_merge.snap — edit source to update -->+<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__list__quickstart_merge.snap — edit source to update -->{% terminal(cmd="wt merge main") %}<span class="cmd">wt merge main</span>diff --git a/src/docs.rs b/src/docs.rsindex 8e73b8884..7bb470452 100644--- a/src/docs.rs+++ b/src/docs.rs@@ -24,6 +24,19 @@ pub const SUBDOC_MARKER_PREFIX: &str = "<!-- subdoc: ";/// docs site (rendered as a `<picture>` figure). Stripped from skill output.pub const DEMO_MARKER_PREFIX: &str = "<!-- demo: ";+/// Open-marker prefix for an auto-generated region in a docs file.+/// Followed by `<id> — edit <source> to update -->`. Both `--help-page` (the+/// producer in `src/help.rs`) and the doc-sync test (the consumer in+/// `tests/integration_tests/readme_sync.rs`) reference this so the literal+/// can't drift between sides.+pub const MARKER_OPEN_PREFIX: &str = "<!-- ⚠️ AUTO-GENERATED from ";++/// Standard close marker for an auto-generated region. The help-page emitter+/// uses a mirrored variant (`<!-- END AUTO-GENERATED from <id> -->`) so two+/// adjacent regions can be parsed without ambiguity; everything else uses+/// this bare form.+pub const MARKER_CLOSE: &str = "<!-- END AUTO-GENERATED -->";+/// Convert `$ `‐prefixed console blocks into `{% terminal() %}` shortcodes.////// All shell commands in `console` blocks use `$ ` prefix. This function detectsdiff --git a/src/help.rs b/src/help.rsindex 51992ba62..b0ff22936 100644--- a/src/help.rs+++ b/src/help.rs@@ -51,7 +51,7 @@ use ansi_str::AnsiStr;use clap::ColorChoice;use clap::error::ErrorKind;use worktrunk::docs::{- BADGE_EXPERIMENTAL_HTML, DEMO_MARKER_PREFIX, SUBDOC_MARKER_PREFIX,+ BADGE_EXPERIMENTAL_HTML, DEMO_MARKER_PREFIX, MARKER_OPEN_PREFIX, SUBDOC_MARKER_PREFIX,convert_dollar_console_to_terminal,};use worktrunk::styling::{eprintln, println};@@ -122,14 +122,15 @@ impl PageMode {fn emit_header(self, subcommand: &str) {match self {Self::Web => std::println!(- "<!-- ⚠️ AUTO-GENERATED from `wt {subcommand} --help-page` — edit cli.rs to update -->"+ "{MARKER_OPEN_PREFIX}`wt {subcommand} --help-page` — edit cli.rs to update -->"),Self::Plain => std::println!("# wt {subcommand}"),}std::println!();}- /// Emit the closing END marker (web only).+ /// Emit the closing END marker (web only). Mirrors the open id so the sync+ /// test can pair adjacent regions unambiguously.fn emit_footer(self, subcommand: &str) {if matches!(self, Self::Web) {std::println!();diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rsindex 5513d4a20..c23124dbc 100644--- a/tests/integration_tests/readme_sync.rs+++ b/tests/integration_tests/readme_sync.rs@@ -28,31 +28,21 @@ 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 -->")-}+use worktrunk::docs::{MARKER_CLOSE, MARKER_OPEN_PREFIX};/// 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}")+fn wrap_in_marker(id: &str, source_label: &str, body: &str) -> String {+ format!(+ "{MARKER_OPEN_PREFIX}{id} — edit {source_label} to update -->\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)+/// Unified pattern for all AUTO-GENERATED markers.+/// 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(&format!(r"(?s){}([^\n]+?) — edit [^\n]+ to update -->\n+([\s\S]*?)\n*{}",@@ -65,13 +55,14 @@ static MARKER_PATTERN: LazyLock<Regex> = LazyLock::new(|| {/// Regex for literal bracket notation (as stored in snapshots) - used by literal_to_escapestatic ANSI_LITERAL_REGEX: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"\[[0-9;]*m").unwrap());-/// Regex to find docs snapshot markers (HTML output)-/// Format: <!-- ⚠️ AUTO-GENERATED-HTML from path.snap — edit source to update -->-/// Matches both old `{% terminal() %}` and new `{% terminal(cmd="...") %}` forms+/// Regex to find snapshot-driven terminal-shortcode markers in standalone docs files+/// (worktrunk.md, llm-commits.md, etc.) for in-place refresh. The `.snap` ID+/// requirement and `{% terminal() %}` body together are specific enough to+/// exclude command-page help-region markers and other AUTO-GENERATED users.static DOCS_SNAPSHOT_MARKER_PATTERN: LazyLock<Regex> = LazyLock::new(|| {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_OPEN_PREFIX),regex::escape(MARKER_CLOSE),)).unwrap()@@ -195,22 +186,6 @@ impl MarkerType {Self::Snapshot}}-- /// Get the OutputFormat for this marker type- fn output_format(&self) -> OutputFormat {- match self {- Self::Snapshot => unreachable!("README has no snapshot markers"),- Self::Help | Self::Section => OutputFormat::Unwrapped,- }- }-- /// Extract inner content (help/sections are unwrapped)- fn extract_inner(&self, content: &str) -> String {- match self {- Self::Snapshot => unreachable!("README has no snapshot markers"),- Self::Help | Self::Section => content.to_string(),- }- }}/// Parse a snapshot file, returning the user-facing output content@@ -327,27 +302,24 @@ fn replace_placeholders(content: &str) -> String {.into_owned()}-/// Format replacement content based on output format+/// Format replacement content based on output format. The `wrap_in_marker`+/// envelope is identical for both; only the body construction varies.fn format_replacement(id: &str, content: &str, format: &OutputFormat) -> String {- match format {+ let body = match format {OutputFormat::DocsHtml => {- // Extract command from <span class="cmd"> in body to also emit as cmd= parameter- // The cmd= parameter enables giallo syntax highlighting in the shortcode- // The span is kept in body for stable sync comparisons+ // Extract command from <span class="cmd"> in body to also emit as+ // cmd= parameter (enables giallo syntax highlighting). The span+ // stays in body so sync comparisons remain stable.let cmd_re = Regex::new(r#"^<span class="cmd">([^<]+)</span>"#).unwrap();let cmd_attr = cmd_re.captures(content).map(|c| format!(r#"cmd="{}""#, c.get(1).unwrap().as_str())).unwrap_or_default();- wrap_in_marker(- MARKER_OPEN_HTML_PREFIX,- id,- "source",- &format!("{{% terminal({cmd_attr}) %}}\n{content}\n{{% end %}}"),- )+ format!("{{% terminal({cmd_attr}) %}}\n{content}\n{{% end %}}")}- OutputFormat::Unwrapped => wrap_in_marker(MARKER_OPEN_PREFIX, id, "source", content),- }+ OutputFormat::Unwrapped => content.to_string(),+ };+ wrap_in_marker(id, "source", &body)}/// Update sections matching a pattern in content@@ -529,7 +501,6 @@ fn expand_command_placeholders(// don't leak into the rendered prompt. Prompt ($) is added// via CSS ::before, so not included in HTML.wrap_in_marker(- MARKER_OPEN_PREFIX,&format!("tests/snapshots/{snapshot_name}"),"source",&format!("{{% terminal(cmd=\"{display_cmd}\") %}}\n{normalized}\n{{% end %}}",),@@ -909,14 +880,15 @@ fn heading_to_anchor(heading: &str) -> String {.join("-")}-/// Regex to match terminal shortcodes with AUTO-GENERATED-HTML markers-/// Optionally captures a preceding bash code block (which becomes redundant)-/// These need to be converted to plain code blocks for README-/// Matches both `{% terminal() %}` and `{% terminal(cmd="...") %}` forms+/// Regex to match terminal-shortcode AUTO-GENERATED markers in docs files,+/// for conversion to plain code blocks when extracting sections into README.+/// Optionally consumes a preceding ```bash``` block (rendered redundant by+/// the cmd= parameter on the shortcode).+/// Matches both `{% terminal() %}` and `{% terminal(cmd="...") %}` forms.static TERMINAL_MARKER_PATTERN: LazyLock<Regex> = LazyLock::new(|| {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_OPEN_PREFIX),regex::escape(MARKER_CLOSE),)).unwrap()@@ -948,7 +920,7 @@ fn strip_html(content: &str) -> String {/// - `[text](@/page.md#anchor)` → `[text](https://worktrunk.dev/page/#anchor)`/// - `{% rawcode() %}...{% end %}` → `<pre>...</pre>`/// - `<figure class="demo">...<img src="/assets/X.gif"...>...</figure>` → ``-/// - AUTO-GENERATED-HTML terminal markers → plain code blocks+/// - AUTO-GENERATED terminal markers → plain code blocks/// - `{{ terminal(cmd="...") }}` → ```bash code blocksfn transform_zola_to_github(content: &str) -> String {// Transform internal links@@ -1060,14 +1032,19 @@ fn sync_readme_markers(let total = matches.len();- // Process in reverse order to preserve positions- for (start, end, id, current_with_wrapper) in matches.into_iter().rev() {- let marker_type = MarkerType::from_id(&id);-- // Strip wrapper from current content (snapshots have ```console```, others are raw)- let current_inner = marker_type.extract_inner(¤t_with_wrapper);+ // Process in reverse order to preserve positions. README markers are always+ // Help/Section (unwrapped); a Snapshot marker would mean a stale shortcode+ // leaked through `transform_zola_to_github` and is a real bug to surface.+ for (start, end, id, current) in matches.into_iter().rev() {+ if matches!(MarkerType::from_id(&id), MarkerType::Snapshot) {+ errors.push(format!(+ "❌ {id}: README must not contain snapshot markers — \+ transform_zola_to_github should have stripped this"+ ));+ continue;+ }- let expected = match generate_readme_content(&id, ¤t_with_wrapper, project_root) {+ let expected = match generate_readme_content(&id, ¤t, project_root) {Ok(content) => content,Err(e) => {errors.push(format!("❌ {}: {}", id, e));@@ -1076,8 +1053,8 @@ fn sync_readme_markers(};// Compare with trim_lines normalization applied once to each side- if trim_lines(¤t_inner) != trim_lines(&expected) {- let replacement = format_replacement(&id, &expected, &marker_type.output_format());+ if trim_lines(¤t) != trim_lines(&expected) {+ let replacement = format_replacement(&id, &expected, &OutputFormat::Unwrapped);result.replace_range(start..end, &replacement);updated += 1;}@@ -1717,7 +1694,7 @@ fn sync_docs_snapshots(doc_path: &Path, project_root: &Path) -> Result<usize, Vefn test_docs_quickstart_examples_are_in_sync() {let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));- // Process all docs files with AUTO-GENERATED-HTML markers+ // Process all docs files with snapshot-driven AUTO-GENERATED markerslet doc_files = ["docs/content/worktrunk.md","docs/content/claude-code.md",@@ -1907,12 +1884,16 @@ fn sync_command_pages(project_root: &Path) -> (Vec<String>, Vec<String>) {current.clone()};- // Find the help-page marker region using mirrored END tag- // Pattern: <!-- ⚠️ AUTO-GENERATED from `wt cmd --help-page` ... --> ... <!-- END AUTO-GENERATED from `wt cmd --help-page` -->+ // Find the help-page marker region. The help-page emitter uses a+ // mirrored close (`<!-- END AUTO-GENERATED from <id> -->`) so that+ // adjacent regions never need backtracking past the wrong one — match+ // the same id literally on both sides.+ let id_re = regex::escape(&format!("`wt {cmd} --help-page`"));let marker_pattern = Regex::new(&format!(- r"(?s)<!-- ⚠️ AUTO-GENERATED from `wt {} --help-page`[^>]*-->.*?<!-- END AUTO-GENERATED from `wt {} --help-page` -->",- cmd, cmd- )).unwrap();+ r"(?s){open}{id_re}[^>]*-->.*?<!-- END AUTO-GENERATED from {id_re} -->",+ open = regex::escape(MARKER_OPEN_PREFIX),+ ))+ .unwrap();let new_content = if let Some(m) = marker_pattern.find(&new_content) {let before = &new_content[..m.start()];diff --git a/tests/integration_tests/user_hooks.rs b/tests/integration_tests/user_hooks.rsindex 8ea18eb71..cadd71d06 100644--- a/tests/integration_tests/user_hooks.rs+++ b/tests/integration_tests/user_hooks.rs@@ -2317,10 +2317,8 @@ fn test_args_indexing_and_length_in_hook_template(repo: TestRepo) {// all work the same as in alias templates.repo.write_test_config(r#"[pre-start]-test = "echo '{{ args[0] | default(__WT_QUOT__none__WT_QUOT__) }}:{{ args | length }}' > args_seq.txt"-"#- .replace("__WT_QUOT__", "'")- .as_str(),+test = "echo '{{ args[0] | default('none') }}:{{ args | length }}' > args_seq.txt"+"#,);let output = repo