Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
//! Commit generation prompt for first-time LLM setup.
//!
//! Prompts users to configure LLM commit message generation when they first
//! attempt a commit without configuration. Detects available tools (claude, codex, opencode)
//! and offers to auto-configure the recommended settings.
use std::collections::HashMap;
use std::ffi::OsStr;
use std::io::{self, IsTerminal};
use std::path::{Path, PathBuf};
use std::sync::LazyLock;
use anyhow::Context;
use color_print::cformat;
use worktrunk::config::{UserConfig, require_config_path};
use worktrunk::path::{format_path_for_display, home_dir};
use worktrunk::styling::{eprintln, format_toml, hint_message, info_message, success_message};
use super::prompt::{PromptResponse, prompt_yes_no_preview};
/// Example config file content, used to extract recommended commands.
const CONFIG_EXAMPLE: &str = include_str!("../../dev/config.example.toml");
/// Recommended commands parsed from the config example file (single source of truth).
///
/// Keyed by the h3 heading text in the config example (e.g., "Claude Code", "Codex").
static RECOMMENDED_COMMANDS: LazyLock<HashMap<String, String>> =
LazyLock::new(|| parse_recommended_commands(CONFIG_EXAMPLE));
/// Codex expands `~` in `model_instructions_file`, including when the path is
/// passed through `-c`. Keep the file outside the current repository so every
/// commit uses the same short instructions.
const CODEX_COMMIT_INSTRUCTIONS_FILE: &str = "worktrunk-commit-instructions.txt";
fn codex_instructions_path() -> anyhow::Result<PathBuf> {
let home = home_dir().ok_or_else(|| anyhow::anyhow!("Cannot determine home directory"))?;
Ok(home.join(".codex").join(CODEX_COMMIT_INSTRUCTIONS_FILE))
}
fn ensure_codex_instructions_file(path: &Path) -> anyhow::Result<bool> {
if path.exists() {
let metadata = path
.metadata()
.with_context(|| format!("Failed to inspect {}", path.display()))?;
anyhow::ensure!(
metadata.is_file() && metadata.len() > 0,
"Codex instructions file must be a nonempty file: {}",
path.display()
);
return Ok(false);
}
let parent = path
.parent()
.context("Codex instructions path has no parent directory")?;
std::fs::create_dir_all(parent)
.with_context(|| format!("Failed to create {}", parent.display()))?;
worktrunk::utils::write_new_atomically(path, ".")
.with_context(|| format!("Failed to write {}", path.display()))?;
Ok(true)
}
/// Detected LLM tool available on the system.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LlmTool {
Claude,
Codex,
OpenCode,
}
impl LlmTool {
/// Returns the command name for this tool.
pub fn command_name(&self) -> &'static str {
match self {
LlmTool::Claude => "claude",
LlmTool::Codex => "codex",
LlmTool::OpenCode => "opencode",
}
}
/// The h3 heading text in config.example.toml for this tool's section.
fn config_heading(&self) -> &'static str {
match self {
LlmTool::Claude => "Claude Code",
LlmTool::Codex => "Codex",
LlmTool::OpenCode => "OpenCode",
}
}
/// Returns the recommended configuration command for this tool.
///
/// Parsed from the examples in dev/config.example.toml,
/// which is the single source of truth for these commands.
pub fn recommended_config(&self) -> &str {
// Indexing is safe: all LlmTool variants have entries in the config example.
&RECOMMENDED_COMMANDS[self.config_heading()]
}
}
impl std::fmt::Display for LlmTool {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "{}", self.command_name())
}
}
/// Parse tool commands from the config example.
///
/// Scans the entire file for `# ### ToolName` headings followed by `# command = "..."`
/// lines. Currently only the LLM section uses this pattern; if other sections gain
/// `# command = ` lines, scope the scan to the `## LLM commit messages` section.
/// The command value is TOML-unescaped via the `toml` crate.
fn parse_recommended_commands(config: &str) -> HashMap<String, String> {
let mut commands = HashMap::new();
let mut current_heading: Option<String> = None;
for line in config.lines() {
// H3 headings: "# ### Claude Code", "# ### Codex"
if let Some(heading) = line.strip_prefix("# ### ") {
current_heading = Some(heading.trim().to_string());
continue;
}
// Command line: "# command = "...""
if let Some(toml_part) = line.strip_prefix("# ")
&& toml_part.starts_with("command = ")
&& let Some(heading) = current_heading.take()
{
// Config example is compile-time data; unwrap is safe.
let table: toml::Table = toml_part.parse().unwrap();
let cmd = table["command"].as_str().unwrap().to_string();
commands.insert(heading, cmd);
}
}
commands
}
/// Check if a command is available in PATH.
fn command_exists(cmd: &str) -> bool {
command_exists_in(cmd, std::env::var_os("PATH").as_deref())
}
/// Inner implementation that takes an explicit PATH-style search list.
///
/// Split out so tests can verify the lookup against a controlled directory
/// rather than the inherited PATH, which can omit even `which`/`where` in
/// minimal sandboxes (e.g., the Nix flake build sandbox).
fn command_exists_in(cmd: &str, paths: Option<&OsStr>) -> bool {
let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
which::which_in(cmd, paths, &cwd).is_ok()
}
/// Format a command string as TOML for display.
///
/// Uses the toml crate for proper escaping. The result may wrap in terminal
/// but is always valid TOML.
fn format_command_for_display(command: &str) -> String {
toml::Value::String(command.to_string()).to_string()
}
/// Inner implementation that accepts a command checker for testability.
fn detect_llm_tool_with(checker: impl Fn(&str) -> bool) -> Option<LlmTool> {
if checker("claude") {
Some(LlmTool::Claude)
} else if checker("codex") {
Some(LlmTool::Codex)
} else if checker("opencode") {
Some(LlmTool::OpenCode)
} else {
None
}
}
/// Detect available LLM tool on the system.
///
/// Checks for claude first (preferred), then codex, then opencode.
/// Returns None if none are found.
pub fn detect_llm_tool() -> Option<LlmTool> {
detect_llm_tool_with(command_exists)
}
/// Prompt for commit generation configuration.
///
/// Shows a one-time prompt when the user attempts to commit without LLM configuration.
/// Detects available tools and offers to auto-configure.
///
/// Note: This function does NOT emit hints about fallback messages. The existing
/// `CommitGenerator::emit_hint_if_needed()` handles that. This function only handles
/// the interactive prompt for first-time setup.
///
/// Returns `Ok(true)` if configuration was set up, `Ok(false)` otherwise.
pub fn prompt_commit_generation(config: &mut UserConfig) -> anyhow::Result<bool> {
let is_tty = io::stdin().is_terminal() && io::stderr().is_terminal();
// Skip if already configured
if config
.commit_generation(None)
.command
.as_ref()
.is_some_and(|s| !s.trim().is_empty())
{
return Ok(false);
}
// Skip if prompt was previously declined or dismissed
if config.skip_commit_generation_prompt {
return Ok(false);
}
// Skip if not a TTY (non-interactive)
if !is_tty {
return Ok(false);
}
// Detect available tool
let Some(tool) = detect_llm_tool() else {
// No tool found - set skip flag so we don't check every time
let _ =
require_config_path().and_then(|path| config.set_skip_commit_generation_prompt(&path));
return Ok(false);
};
// Build preview content (used by both ? and success cases)
let command = tool.recommended_config();
let formatted_command = format_command_for_display(command);
let config_preview = format!("[commit.generation]\ncommand = {formatted_command}");
let codex_instructions = (tool == LlmTool::Codex)
.then(codex_instructions_path)
.transpose()?;
// Point at the config file wt actually writes to — respecting --config,
// WORKTRUNK_CONFIG_PATH, and $XDG_CONFIG_HOME — rather than a hardcoded
// default. The save below resolves the same path via require_config_path.
let config_path = worktrunk::config::config_path_for_display();
// Show prompt with preview on ?
let response = prompt_yes_no_preview(
&cformat!("Configure <bold>{tool}</> for commit messages?"),
|| {
eprintln!(
"{}",
info_message(cformat!("Would add to <bold>{config_path}</>:"))
);
eprintln!("{}", format_toml(&config_preview));
if let Some(path) = &codex_instructions {
eprintln!(
"{}",
info_message(format!(
"Uses {}; creates a one-character file there if absent",
format_path_for_display(path)
))
);
}
eprintln!();
},
)?;
match response {
PromptResponse::Accepted => {
if let Some(path) = &codex_instructions {
match ensure_codex_instructions_file(path) {
Ok(true) => eprintln!(
"{}",
success_message(format!(
"Created Codex instructions: {}",
format_path_for_display(path)
))
),
Ok(false) => {}
Err(e) => {
tracing::error!(error = %e, "Failed to prepare Codex instructions");
eprintln!("{}", hint_message(format!("Codex setup failed: {e:#}")));
return Ok(false);
}
}
}
// Set the configuration
let command = command.to_string();
let save_result = require_config_path()
.and_then(|path| config.set_commit_generation_command(command.clone(), &path));
if let Err(e) = save_result {
tracing::error!(error = %e, "Failed to save config: {}", e);
eprintln!(
"{}",
hint_message(cformat!(
"Config save failed; add manually to <underline>{config_path}</>"
))
);
return Ok(false);
}
// Show what was added
eprintln!("{}", success_message(cformat!("Added to user config:")));
eprintln!("{}", format_toml(&config_preview));
if let Some(path) = &codex_instructions {
let display_path = format_path_for_display(path);
eprintln!(
"{}",
hint_message(format!(
"Keep {display_path}; the saved Codex command requires it"
))
);
}
eprintln!(
"{}",
hint_message(cformat!("View config: <underline>wt config show</>"))
);
// Blank line separates this setup phase from the main operation that follows
eprintln!();
Ok(true)
}
PromptResponse::Declined => {
// Set skip flag so we don't prompt again
let _ = require_config_path()
.and_then(|path| config.set_skip_commit_generation_prompt(&path));
Ok(false)
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use insta::assert_snapshot;
#[test]
fn test_llm_tool_command_name() {
assert_eq!(LlmTool::Claude.command_name(), "claude");
assert_eq!(LlmTool::Codex.command_name(), "codex");
assert_eq!(LlmTool::OpenCode.command_name(), "opencode");
}
#[test]
fn test_llm_tool_recommended_config() {
assert_snapshot!(LlmTool::Claude.recommended_config(), @"MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --safe-mode --setting-sources='user' --system-prompt=''");
assert_snapshot!(LlmTool::Codex.recommended_config(), @r#"codex exec -m gpt-6-luna -c model_reasoning_effort='none' -c project_doc_max_bytes=0 -c skills.max_context_tokens=1 -c agents.enabled=false -c features.goals=false -c web_search=disabled -c 'model_instructions_file="~/.codex/worktrunk-commit-instructions.txt"' -c features.shell_tool=false -c features.unified_exec=false -c features.apps=false -c features.plugins=false --ephemeral --sandbox=read-only --json - | jq -sr '[.[] | select(.item.type? == "agent_message")] | last.item.text'"#);
assert_snapshot!(LlmTool::OpenCode.recommended_config(), @"opencode run -m anthropic/claude-haiku-5-5 --variant fast");
}
#[test]
fn test_codex_instructions_file_is_minimal_and_preserves_existing_content() {
let tmp = worktrunk::testing::tempdir().unwrap();
let path = tmp.path().join(".codex/worktrunk-commit-instructions.txt");
assert!(ensure_codex_instructions_file(&path).unwrap());
assert_eq!(std::fs::read(&path).unwrap(), b".");
std::fs::write(&path, "Use my instructions").unwrap();
assert!(!ensure_codex_instructions_file(&path).unwrap());
assert_eq!(
std::fs::read_to_string(&path).unwrap(),
"Use my instructions"
);
std::fs::write(&path, "").unwrap();
assert!(ensure_codex_instructions_file(&path).is_err());
let blocked_parent = tmp.path().join("not-a-directory");
std::fs::write(&blocked_parent, "file").unwrap();
let err =
ensure_codex_instructions_file(&blocked_parent.join("instructions.txt")).unwrap_err();
assert!(
err.to_string()
.contains(&blocked_parent.display().to_string())
);
}
#[test]
fn test_parse_recommended_commands() {
let config = "\
# ### MyTool
#
# [commit.generation]
# command = \"echo hello\"
#
# ### OtherTool
#
# [commit.generation]
# command = \"jq -sr '[.[] | select(.type? == \\\"msg\\\")]'\"
";
let commands = parse_recommended_commands(config);
assert_eq!(commands.len(), 2);
assert_eq!(commands["MyTool"], "echo hello");
assert_eq!(
commands["OtherTool"],
r#"jq -sr '[.[] | select(.type? == "msg")]'"#
);
}
#[test]
fn test_parse_recommended_commands_ignores_non_command_lines() {
let config = "\
# ### ToolA
#
# [commit.generation]
# template = \"not a command\"
# ### ToolB
# command = \"real command\"
";
let commands = parse_recommended_commands(config);
// ToolA has no command line, ToolB does
assert_eq!(commands.len(), 1);
assert_eq!(commands["ToolB"], "real command");
}
#[test]
fn test_llm_tool_display() {
assert_eq!(format!("{}", LlmTool::Claude), "claude");
assert_eq!(format!("{}", LlmTool::Codex), "codex");
assert_eq!(format!("{}", LlmTool::OpenCode), "opencode");
}
#[test]
fn test_format_command_produces_valid_toml() {
// Uses toml crate for proper escaping
let result = format_command_for_display("echo hello");
assert_eq!(result, "\"echo hello\"");
// Long commands stay as single-line TOML
let cmd = LlmTool::Claude.recommended_config();
let result = format_command_for_display(cmd);
assert_snapshot!(result, @r#""MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --safe-mode --setting-sources='user' --system-prompt=''""#);
}
#[test]
fn test_format_command_special_chars() {
let result = format_command_for_display(r#"echo "hello""#);
assert_snapshot!(result, @r#"'echo "hello"'"#);
}
#[test]
fn test_command_exists_in_finds_binary_on_explicit_path() {
// Provide our own search path so the positive case doesn't depend
// on which standard tools the inherited PATH happens to ship.
let tmp = worktrunk::testing::tempdir().unwrap();
#[cfg(windows)]
let bin_name = "wt-fake-bin.exe";
#[cfg(not(windows))]
let bin_name = "wt-fake-bin";
let bin_path = tmp.path().join(bin_name);
std::fs::write(&bin_path, "").unwrap();
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
std::fs::set_permissions(&bin_path, std::fs::Permissions::from_mode(0o755)).unwrap();
}
assert!(command_exists_in(bin_name, Some(tmp.path().as_os_str())));
}
#[test]
fn test_command_exists_nonexistent() {
// A command that definitely doesn't exist
assert!(!command_exists("__nonexistent_command_12345__"));
}
#[test]
fn test_command_exists_in_returns_false_when_paths_empty() {
let tmp = worktrunk::testing::tempdir().unwrap();
assert!(!command_exists_in(
"__nonexistent__",
Some(tmp.path().as_os_str()),
));
}
#[test]
fn test_detect_llm_tool_priority() {
// All commands exist → Claude wins (highest priority)
assert_eq!(detect_llm_tool_with(|_| true), Some(LlmTool::Claude));
// Claude missing → Codex wins
assert_eq!(
detect_llm_tool_with(|cmd| cmd != "claude"),
Some(LlmTool::Codex),
);
// Only OpenCode available
assert_eq!(
detect_llm_tool_with(|cmd| cmd == "opencode"),
Some(LlmTool::OpenCode),
);
// Nothing available
assert_eq!(detect_llm_tool_with(|_| false), None);
}
}