Skip to content

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

docs: add warning placement framework and validate config in wt config show (#468)

Maximilian Roos8df361558842
diff --git a/.claude/rules/cli-output-formatting.md b/.claude/rules/cli-output-formatting.md
index 577244241..da33eeca7 100644
--- a/.claude/rules/cli-output-formatting.md
+++ b/.claude/rules/cli-output-formatting.md
@@ -257,6 +257,58 @@ each type.
| "Use `--yes` to override" | "Skipping hooks (--no-verify)" |
| "Branch can be deleted" | "Worktree preserved (main worktree)" |
+**Warning placement:** When something unexpected happens, warn somewhere. Where
+depends on the nature of the issue:
+
+```
+Is it unexpected?
+├── No → Silent (e.g., gh not installed when no GitHub remote)
+└── Yes → Warn somewhere:
+ ├── Immediate impact OR temporary → Inline (warning_message or in-band indicator)
+ ├── Persists until user action → wt config show (can be checked later)
+ └── Not user-fixable → log::warn! (developer diagnostics)
+```
+
+**Inline warnings** for issues affecting the current command:
+
+| Issue | Why inline |
+|-------|------------|
+| Rate limit during CI fetch | Temporary — won't be there next time |
+| Network timeout | Temporary — retry might work |
+| Hook failed during operation | Immediate impact on this command |
+
+**`wt config show`** for issues that persist until the user fixes them. These
+don't need to interrupt every command — users can check diagnostics when
+investigating:
+
+| Issue | Why config show |
+|-------|-----------------|
+| `gh` not authenticated | User runs `gh auth login` |
+| Shell integration misconfigured | User updates shell config |
+| Config syntax errors | User fixes config file |
+
+**`log::warn!()`** for issues users cannot fix. These help developers debug but
+shouldn't clutter user output:
+
+| Issue | Why log::warn! |
+|-------|----------------|
+| JSON parse error (API changed) | Requires code fix |
+| Internal invariant violated | Developer bug |
+
+```rust
+// Inline - temporary issue affecting this command
+if is_rate_limited(&stderr) {
+ return Some(CiStatus::Error); // Shows in CI column
+}
+
+// config show - permanent, user-fixable (checked on-demand by wt config show)
+// Shell integration status is probed by wt config show, not cached
+
+// log::warn! - not user-fixable, for developer debugging
+log::warn!("Failed to parse CI JSON for {}: {}", branch, e);
+return None;
+```
+
**Command suggestions in hints:** Use "To X, run Y" pattern. End with the
command for easy copying:
diff --git a/src/commands/config.rs b/src/commands/config.rs
index 7d3ab77d3..2157f740c 100644
--- a/src/commands/config.rs
+++ b/src/commands/config.rs
@@ -3,8 +3,9 @@ use color_print::cformat;
use etcetera::base_strategy::{BaseStrategy, choose_base_strategy};
use std::fmt::Write as _;
use std::path::PathBuf;
-use worktrunk::config::WorktrunkConfig;
-use worktrunk::config::{find_unknown_project_keys, find_unknown_user_keys};
+use worktrunk::config::{
+ ProjectConfig, WorktrunkConfig, find_unknown_project_keys, find_unknown_user_keys,
+};
use worktrunk::git::Repository;
use worktrunk::path::format_path_for_display;
use worktrunk::shell::{Shell, scan_for_detection_details};
@@ -363,8 +364,15 @@ fn render_user_config(out: &mut String) -> anyhow::Result<()> {
return Ok(());
}
- // Check for unknown keys and warn
- warn_unknown_keys(out, &find_unknown_user_keys(&contents))?;
+ // Validate config (syntax + schema) and warn if invalid
+ if let Err(e) = toml::from_str::<WorktrunkConfig>(&contents) {
+ // Use gutter for error details to avoid markup interpretation of user content
+ writeln!(out, "{}", error_message("Invalid config"))?;
+ writeln!(out, "{}", format_with_gutter(&e.to_string(), None))?;
+ } else {
+ // Only check for unknown keys if config is valid
+ warn_unknown_keys(out, &find_unknown_user_keys(&contents))?;
+ }
// Display TOML with syntax highlighting (gutter at column 0)
write!(out, "{}", format_toml(&contents))?;
@@ -426,8 +434,15 @@ fn render_project_config(out: &mut String) -> anyhow::Result<()> {
return Ok(());
}
- // Check for unknown keys and warn
- warn_unknown_keys(out, &find_unknown_project_keys(&contents))?;
+ // Validate config (syntax + schema) and warn if invalid
+ if let Err(e) = toml::from_str::<ProjectConfig>(&contents) {
+ // Use gutter for error details to avoid markup interpretation of user content
+ writeln!(out, "{}", error_message("Invalid config"))?;
+ writeln!(out, "{}", format_with_gutter(&e.to_string(), None))?;
+ } else {
+ // Only check for unknown keys if config is valid
+ warn_unknown_keys(out, &find_unknown_project_keys(&contents))?;
+ }
// Display TOML with syntax highlighting (gutter at column 0)
write!(out, "{}", format_toml(&contents))?;
diff --git a/tests/integration_tests/config_show.rs b/tests/integration_tests/config_show.rs
index e7c3b812a..25a6a7079 100644
--- a/tests/integration_tests/config_show.rs
+++ b/tests/integration_tests/config_show.rs
@@ -365,6 +365,61 @@ fn test_config_show_warns_unknown_user_keys(mut repo: TestRepo, temp_home: TempD
});
}
+#[rstest]
+fn test_config_show_invalid_user_toml(mut repo: TestRepo, temp_home: TempDir) {
+ repo.setup_mock_ci_tools_unauthenticated();
+
+ // Create global config with invalid TOML syntax
+ let global_config_dir = temp_home.path().join(".config").join("worktrunk");
+ fs::create_dir_all(&global_config_dir).unwrap();
+ fs::write(
+ global_config_dir.join("config.toml"),
+ "this is not valid toml {{{",
+ )
+ .unwrap();
+
+ let settings = setup_snapshot_settings_with_home(&repo, &temp_home);
+ settings.bind(|| {
+ let mut cmd = wt_command();
+ repo.configure_wt_cmd(&mut cmd);
+ repo.configure_mock_commands(&mut cmd);
+ cmd.arg("config").arg("show").current_dir(repo.root_path());
+ set_temp_home_env(&mut cmd, temp_home.path());
+
+ assert_cmd_snapshot!(cmd);
+ });
+}
+
+#[rstest]
+fn test_config_show_invalid_project_toml(mut repo: TestRepo, temp_home: TempDir) {
+ repo.setup_mock_ci_tools_unauthenticated();
+
+ // Create valid global config
+ let global_config_dir = temp_home.path().join(".config").join("worktrunk");
+ fs::create_dir_all(&global_config_dir).unwrap();
+ fs::write(
+ global_config_dir.join("config.toml"),
+ "worktree-path = \"../{{ repo }}.{{ branch }}\"",
+ )
+ .unwrap();
+
+ // Create project config with invalid TOML syntax
+ let config_dir = repo.root_path().join(".config");
+ fs::create_dir_all(&config_dir).unwrap();
+ fs::write(config_dir.join("wt.toml"), "invalid = [unclosed bracket").unwrap();
+
+ let settings = setup_snapshot_settings_with_home(&repo, &temp_home);
+ settings.bind(|| {
+ let mut cmd = wt_command();
+ repo.configure_wt_cmd(&mut cmd);
+ repo.configure_mock_commands(&mut cmd);
+ cmd.arg("config").arg("show").current_dir(repo.root_path());
+ set_temp_home_env(&mut cmd, temp_home.path());
+
+ assert_cmd_snapshot!(cmd);
+ });
+}
+
#[rstest]
fn test_config_show_full_not_configured(mut repo: TestRepo, temp_home: TempDir) {
// Setup mock gh/glab for deterministic BINARIES output
diff --git a/tests/snapshots/integration__integration_tests__config_show__config_show_invalid_project_toml.snap b/tests/snapshots/integration__integration_tests__config_show__config_show_invalid_project_toml.snap
new file mode 100644
index 000000000..e72d8da5e
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__config_show__config_show_invalid_project_toml.snap
@@ -0,0 +1,57 @@
+---
+source: tests/integration_tests/config_show.rs
+info:
+ program: wt
+ args:
+ - config
+ - show
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ PATH: "[PATH]"
+ RUST_LOG: warn
+ SOURCE_DATE_EPOCH: "1735776000"
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+USER CONFIG ~/.config/worktrunk/config.toml
+  worktree-path = "../{{ repo }}.{{ branch }}"
+
+PROJECT CONFIG _REPO_/.config/wt.toml
+✗ Invalid config
+  TOML parse error at line 1, column 28
+  |
+  1 | invalid = [unclosed bracket
+  | ^
+  unclosed array, expected `]`
+  invalid = [unclosed bracket
+
+SHELL INTEGRATION
+▲ Shell integration not active
+  Binary invoked as: [PROJECT_ROOT]/target/debug/wt
+
+○ Skipped bash; ~/.bashrc not found
+○ Skipped zsh; ~/.zshrc not found
+○ Skipped fish; ~/.config/fish/conf.d not found
+
+OTHER wt [VERSION]
+↳ Claude Code plugin not installed (claude not found)
+○ Hyperlinks: inactive
diff --git a/tests/snapshots/integration__integration_tests__config_show__config_show_invalid_user_toml.snap b/tests/snapshots/integration__integration_tests__config_show__config_show_invalid_user_toml.snap
new file mode 100644
index 000000000..3b5b4f9b7
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__config_show__config_show_invalid_user_toml.snap
@@ -0,0 +1,57 @@
+---
+source: tests/integration_tests/config_show.rs
+info:
+ program: wt
+ args:
+ - config
+ - show
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ PATH: "[PATH]"
+ RUST_LOG: warn
+ SOURCE_DATE_EPOCH: "1735776000"
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+USER CONFIG ~/.config/worktrunk/config.toml
+✗ Invalid config
+  TOML parse error at line 1, column 6
+  |
+  1 | this is not valid toml {{{
+  | ^
+  key with no value, expected `=`
+  this is not valid toml {{{
+
+PROJECT CONFIG _REPO_/.config/wt.toml
+↳ Not found
+
+SHELL INTEGRATION
+▲ Shell integration not active
+  Binary invoked as: [PROJECT_ROOT]/target/debug/wt
+
+○ Skipped bash; ~/.bashrc not found
+○ Skipped zsh; ~/.zshrc not found
+○ Skipped fish; ~/.config/fish/conf.d not found
+
+OTHER wt [VERSION]
+↳ Claude Code plugin not installed (claude not found)
+○ Hyperlinks: inactive