Skip to content

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.md
deleted file mode 100644
index 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.