Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: Remove ISSUE.md
Maximilian Roosdf0a67002786
diff --git a/ISSUE.md b/ISSUE.mddeleted file mode 100644index 783a5b3d3..000000000--- a/ISSUE.md+++ /dev/null@@ -1,624 +0,0 @@-# Shell Completion System: Refactoring and Remaining Optimization Opportunities--## Executive Summary--We successfully refactored the shell completion system to use clap introspection instead of manual string parsing, reducing the codebase by 305 lines (from 426 to 121 net lines). However, we've identified a remaining function (`should_complete_positional_arg`) that still uses manual parsing and has known bugs. This report documents the refactoring, the remaining issues, and options for further improvement.--## Background: Why Custom Completion?--The codebase uses a **custom completion implementation** rather than clap's `unstable-dynamic` feature for several reasons (from `src/commands/completion.rs:1-11`):--1. **unstable-dynamic is an unstable API** that may change between versions-2. **Need conditional completion logic** (e.g., don't complete branches when `--create` is present)-3. **Need runtime-fetched values** (git branches) with context-aware filtering-4. **Need precise control** over positional argument state tracking with flags--This approach uses stable clap APIs and handles edge cases that clap's completion system isn't designed for.--## What We've Accomplished--### Original Problem--Tab completion for `--base=<value>` format wasn't working:--```bash-wt switch --create --execute=claude --base=<tab> # No completion-wt switch --create --execute=claude --base <tab> # Worked fine-```--The code only handled space-separated format (`--base <value>`), not equals format (`--base=value`).--### Initial "Hacky" Solution--The original fix added equals-format detection to manual parsing logic:--```rust-// Check if we're completing a flag value-// Handle both formats: --base <value> and --base=<value>--// First, check if the last argument is --base=... or -b=...-if let Some(last_arg) = args.last()- && (last_arg.starts_with("--base=") || last_arg.starts_with("-b="))-{- return CompletionContext::BaseFlag;-}--// Then check if the previous argument was --base or -b (space-separated format)-if args.len() >= 3 {- let prev_arg = &args[args.len() - 2];- if prev_arg == "--base" || prev_arg == "-b" {- return CompletionContext::BaseFlag;- }-}-```--This worked but was **brittle and hardcoded**.--### Comprehensive Refactoring--We replaced the entire manual parsing system with clap-based introspection:--#### Before (Old Approach)--```rust-#[derive(Debug, PartialEq)]-enum CompletionContext {- SwitchBranch, // Hardcoded for switch command- PushTarget, // Hardcoded for push command- MergeTarget, // Hardcoded for merge command- RemoveBranch, // Hardcoded for remove command- BaseFlag, // Hardcoded for --base flag- Unknown,-}--fn parse_completion_context(args: &[String]) -> CompletionContext {- // 70+ lines of manual parsing:- // - Find subcommand by skipping global flags- // - Check if last arg is --base=...- // - Check if prev arg is --base- // - Check subcommand name and return hardcoded enum variant-}--pub fn handle_complete(args: Vec<String>) -> Result<(), GitError> {- let context = parse_completion_context(&args);-- match context {- CompletionContext::SwitchBranch- | CompletionContext::PushTarget- | CompletionContext::MergeTarget- | CompletionContext::RemoveBranch- | CompletionContext::BaseFlag => {- // Fetch and print branches- }- CompletionContext::Unknown => {- // Use clap_fallback for ValueEnums- }- }-}-```--#### After (New Approach)--```rust-/// Represents what we're trying to complete-#[derive(Debug)]-enum CompletionTarget<'a> {- /// Completing a value for an option flag (e.g., --base <value> or --base=<value>)- Option(&'a Arg, String), // (clap Arg, prefix to complete)- /// Completing a positional branch argument (switch/push/merge/remove commands)- PositionalBranch(String), // prefix to complete- /// No special completion needed- Unknown,-}--fn detect_completion_target<'a>(args: &[String], cmd: &'a Command) -> CompletionTarget<'a> {- // Walk command tree to find active subcommand- let mut cur = cmd;- let mut subcommand_name = None;- // ... (walk logic)-- // Check for --arg=value format- if let Some(equals_pos) = last.find('=') {- let flag_part = &last[..equals_pos];- let value_part = &last[equals_pos + 1..];-- if let Some(long) = flag_part.strip_prefix("--")- && let Some(arg) = cur.get_opts().find(|a| a.get_long().is_some_and(|l| l == long))- {- return CompletionTarget::Option(arg, value_part.to_string());- }- // ... (short form check)- }-- // Check for --arg value format (space-separated)- if let Some(p) = prev {- if let Some(long) = p.strip_prefix("--")- && let Some(arg) = cur.get_opts().find(|a| a.get_long().is_some_and(|l| l == long))- {- return CompletionTarget::Option(arg, last.to_string());- }- // ... (short form check)- }-- // Check positional branch arguments using subcommand name- if let Some(subcmd) = subcommand_name {- match subcmd {- "switch" => {- let has_create = args.iter().any(|arg| arg == "--create" || arg == "-c");- if !has_create && should_complete_positional_arg(args, i) {- return CompletionTarget::PositionalBranch(last.to_string());- }- }- "push" | "merge" | "remove" => {- if should_complete_positional_arg(args, i) {- return CompletionTarget::PositionalBranch(last.to_string());- }- }- _ => {}- }- }-- CompletionTarget::Unknown-}--pub fn handle_complete(args: Vec<String>) -> Result<(), GitError> {- let mut cmd = crate::cli::Cli::command();- cmd.build(); // Required for introspection-- let target = detect_completion_target(&args, &cmd);-- match target {- CompletionTarget::Option(arg, prefix) => {- // Check if this is the "base" option that needs branch completion- if arg.get_long() == Some("base") {- // Complete with all branches (runtime-fetched values)- let branches = get_branches_for_completion(|| Repository::current().all_branches());- for branch in branches {- println!("{}", branch);- }- } else {- // Use the arg's declared possible_values (ValueEnum types)- let items = items_from_arg(arg, &prefix);- if !items.is_empty() {- print_items(items);- }- }- }- CompletionTarget::PositionalBranch(_prefix) => {- // Complete with all branches (runtime-fetched values)- let branches = get_branches_for_completion(|| Repository::current().all_branches());- for branch in branches {- println!("{}", branch);- }- }- CompletionTarget::Unknown => {- // Check for positionals with ValueEnum possible_values- // ... (handles init <Shell>, beta run-hook <HookType>)- }- }-- Ok(())-}-```--### Benefits of Refactoring--1. **Automatic `=` format support for ALL flags** - not just `--base`, but any future flags with values-2. **No hardcoded command names** - uses clap's knowledge of command structure-3. **Returns clap `Arg` objects** - can query metadata, possible_values, etc.-4. **More maintainable** - adding new flags with custom completion is easier-5. **Reduced code size** - 305 lines removed (426 → 121 net lines)--### Test Results--All tests pass after refactoring:--```bash-$ cargo test --test integration completion --quiet-running 29 tests-.............................-test result: ok. 29 passed; 0 failed; 0 ignored; 0 measured; 265 filtered out--$ cargo test --quiet 2>&1 | tail -5-test result: ok. 294 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out--$ pre-commit run --all-files-fix end of files.........................................................Passed-check yaml...............................................................Passed-mixed line ending........................................................Passed-trim trailing whitespace.................................................Passed-typos....................................................................Passed-Check for formatting with cargo fmt......................................Passed-Check for linting issues with cargo clippy...............................Passed-markdown-link-check......................................................Passed-no-dbg...................................................................Passed-```--## Remaining Issue: `should_complete_positional_arg`--### The Problem--One function still uses manual parsing and has **known bugs**:--```rust-/// Check if a positional argument should be completed-/// Returns true if we're still completing the first positional arg-/// Returns false if the positional arg has been provided and we've moved past it-fn should_complete_positional_arg(args: &[String], start_index: usize) -> bool {- let mut i = start_index;-- while i < args.len() {- let arg = &args[i];-- if arg == "--base" || arg == "-b" {- // Skip flag and its value- i += 2;- } else if arg.starts_with("--") || (arg.starts_with('-') && arg.len() > 1) {- // Skip other flags- i += 1;- } else if !arg.is_empty() {- // Found a positional argument- // Only continue completing if it's at the last position- return i >= args.len() - 1;- } else {- // Empty string (cursor position)- i += 1;- }- }-- // No positional arg found yet - should complete- true-}-```--### Current Hardcoded Checks--```bash-$ rg '== "--' src/commands/completion.rs-if arg == "--base" || arg == "-b" {- if tok == "--source" || tok == "--internal" || tok == "-v" || tok == "--verbose" {- let has_create = args.iter().any(|arg| arg == "--create" || arg == "-c");- if tok == "--source" || tok == "--internal" || tok == "-v" || tok == "--verbose" {-```--### Bug: Incomplete Flag Handling--The function hardcodes `--base` and `-b` but **misses `--execute`**, which also takes a value:--```rust-// From src/cli.rs - switch command flags that take values-base: Option<String>, // Detected ✅-execute: Option<String>, // MISSING ❌-```--**Reproduction scenario:**--```bash-wt switch --execute "code ." <tab>-# BUG: "code" is treated as the branch positional argument-# Should skip "code" because --execute takes a value-# Result: Might not complete branches correctly-```--### Additional Hardcoded Patterns--1. **Global flags** (lines 125, 247):- ```rust- if tok == "--source" || tok == "--internal" || tok == "-v" || tok == "--verbose"- ```- Could query `cmd.get_global_opts()` instead--2. **`--create` flag detection** (line 193):- ```rust- let has_create = args.iter().any(|arg| arg == "--create" || arg == "-c");- ```- Could check if `cur.get_opts().find(|a| a.get_long() == Some("create"))`--### Why This Function Exists--The function attempts to answer: **"Has the user already provided the positional argument?"**--This is needed because:-- Branch completion should only happen when completing the first positional-- Flags can appear anywhere: `wt switch --base main feature` or `wt switch feature --base main`-- Need to distinguish: `wt switch feat<tab>` (complete) vs `wt switch feature <tab>` (don't complete)--Example scenarios:--```bash-wt switch <tab> # should_complete = true-wt switch feat<tab> # should_complete = true (still completing first arg)-wt switch feature <tab> # should_complete = false (already provided branch)-wt switch --base main <tab> # should_complete = true (no branch yet)-wt switch --base main feat<tab> # should_complete = true (still completing branch)-wt switch --base main feature <tab> # should_complete = false (branch provided)-```--The challenge is **parsing without clap's state machine** - we need to manually skip flags and their values.--## Options for Further Improvement--### Option A: Use Clap Introspection for Flag Detection--Pass the clap `Command` to `should_complete_positional_arg` and query which flags take values:--```rust-fn should_complete_positional_arg(args: &[String], start_index: usize, cmd: &Command) -> bool {- let mut i = start_index;-- while i < args.len() {- let arg = &args[i];-- // Check if this is a flag that takes a value- if let Some(stripped) = arg.strip_prefix("--") {- // Long form- if let Some(opt) = cmd.get_opts().find(|o| o.get_long() == Some(stripped)) {- if opt.get_num_args().map_or(false, |n| n.max_values() > Some(0)) {- // This flag takes a value, skip it- i += 2;- continue;- }- }- i += 1;- } else if arg.starts_with('-') && arg.len() > 1 {- // Short form or combined flags- // More complex: could be -abc (three flags) or -b value- // Would need to check each character- i += 1;- } else if !arg.is_empty() {- return i >= args.len() - 1;- } else {- i += 1;- }- }-- true-}-```--**Pros:**-- No hardcoded flag names-- Automatically handles new flags-- More robust--**Cons:**-- More complex-- Handling short flags is tricky (`-b value` vs `-abc`)-- Handling `--flag=value` format needs special care--### Option B: Simplify by Counting Non-Flag Args--Instead of trying to be precise about which flags take values, just count non-flag arguments:--```rust-fn should_complete_positional_arg(args: &[String], start_index: usize) -> bool {- let mut positional_count = 0;-- for arg in &args[start_index..] {- // Skip flags and their potential values- if arg.starts_with('-') {- continue;- }-- // Skip empty strings (cursor position)- if arg.is_empty() {- continue;- }-- // Count as positional- positional_count += 1;- }-- // We want to complete if we haven't found a positional yet,- // or if the last arg is a partial positional (at cursor)- positional_count <= 1-}-```--**Pros:**-- Much simpler-- No need to know which flags take values-- Handles `--flag=value` automatically--**Cons:**-- Less precise - might treat flag values as positionals-- Could have edge cases like: `wt switch --execute "my branch name" <tab>`- (would count "my branch name" as a positional)--### Option C: Use Clap's Parser--The most robust approach would be to use clap's actual parser to understand what's been consumed:--```rust-use clap::Parser;--fn should_complete_positional_arg(args: &[String], cmd: &Command) -> bool {- // Try parsing with clap up to the current position- // Check if the positional has been filled- // This would require more invasive changes to use clap's internal parser state-}-```--**Pros:**-- Most accurate-- Handles all edge cases-- Uses clap's own logic--**Cons:**-- Requires understanding clap's internal parser-- More invasive changes-- Might require partial parsing (non-standard use of clap)--### Option D: Keep Current Implementation, Document Limitations--Accept the current limitations and document them:--```rust-/// Check if a positional argument should be completed-///-/// Returns true if we're still completing the first positional arg-/// Returns false if the positional arg has been provided and we've moved past it-///-/// LIMITATIONS:-/// - Only handles --base/-b flag (missing --execute/-x)-/// - Doesn't handle --flag=value format-/// - Assumes flags with values are consumed as two args-fn should_complete_positional_arg(args: &[String], start_index: usize) -> bool {- // Current implementation...-}-```--Add `--execute` to the hardcoded list:--```rust-if arg == "--base" || arg == "-b" || arg == "--execute" || arg == "-x" {- // Skip flag and its value- i += 2;-}-```--**Pros:**-- Minimal changes-- Keeps working code--**Cons:**-- Still brittle-- Requires manual updates for new flags-- Doesn't handle `--flag=value` format--## Open Questions and Research Needs--### 1. How do other shell completion systems handle this?--**Question:** How do bash-completion, zsh-completion, and fish-completion handle the problem of "has this positional been provided yet" when flags can appear anywhere?--**Research needed:**-- Look at bash-completion source code-- Check how git's completion handles: `git checkout <flags> branch` vs `git checkout branch <flags>`-- See if there are standard patterns for this--**Why it matters:** We might be reinventing the wheel. There could be established patterns.--### 2. Can we use clap's partial parsing?--**Question:** Does clap provide any APIs for partial parsing that could help here?--**Research needed:**-- Check clap documentation for partial parsing-- Look for examples of using clap for completion in other projects-- Check if clap_complete has utilities we're missing--**Why it matters:** We might be able to leverage clap's parser instead of manual parsing.--### 3. What completion behavior do users expect?--**Question:** What happens in practice when flags take values that look like branch names?--**Examples:**-```bash-wt switch --execute "checkout feature-branch" <tab>-# Should this complete? The string "checkout feature-branch" is a valid branch name-# But it's the value of --execute, not a positional-```--**Research needed:**-- Test how git completion handles: `git checkout -b "master" <tab>`-- Check bash-completion best practices-- Look at other CLI tools with similar patterns--**Why it matters:** Edge cases might be acceptable if they're rare in practice.--### 4. Performance impact of clap introspection?--**Question:** Does calling `cmd.get_opts()` and iterating on every keystroke have performance implications?--**Assumptions carrying load:**-- We assume clap introspection is fast enough for completion-- We assume calling `.build()` on every completion is acceptable--**Research needed:**-- Benchmark: `time wt complete wt switch --base <args>`-- Compare manual parsing vs clap introspection performance-- Check if we should cache the built command--**Why it matters:** Completion needs to be fast (<100ms ideally).--### 5. Should we handle `--flag=value` in positional detection?--**Question:** Does `should_complete_positional_arg` need to handle `--flag=value` format, or is the current behavior acceptable?--**Current behavior:**-```bash-wt switch --base=main feat<tab> # Works - completes branches-wt switch --execute="code ." feat<tab> # Might work? Need to test-```--**Research needed:**-- Test actual behavior with `--execute="value"` format-- Check if shells split `--flag=value` before passing to completion-- Verify if this is a real problem or theoretical--**Why it matters:** Might already work due to shell argument parsing.--## Recommendations--Based on the analysis, I recommend **Option A (Use Clap Introspection)** because:--1. **Consistency** - Matches the pattern we established in the refactoring-2. **Maintainability** - No hardcoded flag names-3. **Correctness** - Handles all flags that take values, not just `--base`--The implementation would:-- Query `cmd.get_opts()` to find flags that take values-- Handle `--flag=value` format by detecting `=` before checking-- Keep the existing logic for counting positionals--Before implementing, I suggest:-1. **Research** shell completion patterns (Question 1)-2. **Test** edge cases with `--execute` to confirm the bug (Question 5)-3. **Benchmark** to ensure performance is acceptable (Question 4)--## Code Context: Switch Command Definition--For reference, here's the `switch` command definition from `src/cli.rs:376-399`:--```rust-Switch {- /// Branch name, worktree path, '@' for current HEAD, or '-' for previous branch- branch: String,-- /// Create a new branch- #[arg(short = 'c', long)]- create: bool,-- /// Base branch to create from (only with --create). Use '@' for current HEAD- #[arg(short = 'b', long)]- base: Option<String>,-- /// Execute command after switching- #[arg(short = 'x', long)]- execute: Option<String>,-- /// Auto-approve project commands without saving approvals.- #[arg(short = 'f', long)]- force: bool,-- /// Skip all project hooks: post-create and post-start.- #[arg(long)]- no_verify: bool,-}-```--Flags that take values:-- `--base` / `-b` → `Option<String>` ✅ Currently handled-- `--execute` / `-x` → `Option<String>` ❌ **Missing from should_complete_positional_arg**--## Conclusion--The refactoring successfully eliminated 305 lines of brittle manual parsing by using clap introspection. The remaining `should_complete_positional_arg` function has a similar opportunity for improvement:--- **Current state:** Hardcoded checks for `--base`, missing `--execute`-- **Goal:** Use clap to query which flags take values-- **Benefit:** Automatic handling of all current and future flags--The key challenge is balancing **precision** (correctly identifying when a positional has been provided) with **simplicity** (not reimplementing clap's parser). Option A provides the best balance by using clap's metadata while keeping the existing positional-counting logic.