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.mdindex 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 thecommand for easy copying:diff --git a/src/commands/config.rs b/src/commands/config.rsindex 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.rsindex 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 outputdiff --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.snapnew file mode 100644index 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 -----+[36mUSER CONFIG[39m ~/.config/worktrunk/config.toml+[107m [0m worktree-path = [32m"../{{ repo }}.{{ branch }}"++[36mPROJECT CONFIG[39m _REPO_/.config/wt.toml+[31m✗[39m [31mInvalid config[39m+[107m [0m TOML parse error at line 1, column 28+[107m [0m |+[107m [0m 1 | invalid = [unclosed bracket+[107m [0m | ^+[107m [0m unclosed array, expected `]`+[107m [0m invalid = [unclosed bracket++[36mSHELL INTEGRATION[39m+[33m▲[39m [33mShell integration not active[39m+[107m [0m Binary invoked as: [1m[PROJECT_ROOT]/target/debug/wt[22m++[2m○[22m [2mSkipped bash; ~/.bashrc not found[22m+[2m○[22m [2mSkipped zsh; ~/.zshrc not found[22m+[2m○[22m [2mSkipped fish; ~/.config/fish/conf.d not found[22m++[36mOTHER[39m wt [VERSION]+[2m↳[22m [2mClaude Code plugin not installed ([1mclaude[22m not found)[22m+[2m○[22m Hyperlinks: [1minactive[22mdiff --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.snapnew file mode 100644index 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 -----+[36mUSER CONFIG[39m ~/.config/worktrunk/config.toml+[31m✗[39m [31mInvalid config[39m+[107m [0m TOML parse error at line 1, column 6+[107m [0m |+[107m [0m 1 | this is not valid toml {{{+[107m [0m | ^+[107m [0m key with no value, expected `=`+[107m [0m this is not valid toml {{{++[36mPROJECT CONFIG[39m _REPO_/.config/wt.toml+[2m↳[22m [2mNot found[22m++[36mSHELL INTEGRATION[39m+[33m▲[39m [33mShell integration not active[39m+[107m [0m Binary invoked as: [1m[PROJECT_ROOT]/target/debug/wt[22m++[2m○[22m [2mSkipped bash; ~/.bashrc not found[22m+[2m○[22m [2mSkipped zsh; ~/.zshrc not found[22m+[2m○[22m [2mSkipped fish; ~/.config/fish/conf.d not found[22m++[36mOTHER[39m wt [VERSION]+[2m↳[22m [2mClaude Code plugin not installed ([1mclaude[22m not found)[22m+[2m○[22m Hyperlinks: [1minactive[22m