fzf tmux integration broken: mkfifo compatibility issue with uutils-coreutils

[Alrefai]

Issue: fzf tmux integration broken with uutils-coreutils

Problem Description

fzf key bindings (Ctrl-T, Ctrl-R) stopped working in tmux sessions after adding uutils-coreutils-noprefix to home-manager configuration. The error manifested as:

mkfifo: invalid mode: invalid digit found in string
fzf-file-widget:zle:3: widgets can only be called when ZLE is active

Initial Investigation Path

1. Suspected tmux Configuration Issues

• Hypothesis: tmux prefix key (C-s) was capturing key range
• Investigation: Checked tmux key bindings and configuration
• Result: ❌ Not the root cause - tmux config was correct

2. Suspected tmux 3.5a Breaking Changes

• Hypothesis: Recent tmux version changes affected shell integration
• Investigation: Found home-manager issue #5952 about tmux 3.5a shell handling changes
• Result: ❌ Related but not the direct cause

3. Suspected fzf Shell Integration

• Investigation:
  • Verified fzf functions were loaded (fzf-file-widget exists)
  • Confirmed key bindings were correct ("^T" fzf-file-widget)
  • Tested ZLE status (was active: $options[zle] = on)
• Result: ❌ Shell integration was working correctly

4. Environment Comparison Testing

• Method: Tested fzf behavior inside vs outside tmux
• Discovery: Same mkfifo error occurred in both environments
• Key insight: Issue wasn't tmux-specific

Root Cause Discovery

The Breakthrough

During testing, user mentioned recently adding:

uutils-coreutils-noprefix # Rust rewrite of the GNU coreutils

Confirmation Test

Commenting out uutils-coreutils-noprefix immediately fixed the issue, confirming the root cause.

Technical Analysis

The issue occurred because:

1. GNU vs Rust syntax differences: fzf shell integration uses mkfifo -m o+w (GNU syntax)
2. uutils-coreutils incompatibility: The Rust implementation expects octal modes like -m 622
3. Argument parsing failure: mkfifo -m o+w caused "invalid mode" error in uutils implementation

Solutions Explored

Solution 1: Remove Problematic Package ✅ (Temporary)

# uutils-coreutils-noprefix # Commented out

• Pros: Immediate fix
• Cons: Lose performance benefits of Rust coreutils

Solution 2: Remove Only mkfifo ✅ (Simple)

uutils-coreutils-no-mkfifo = pkgs.uutils-coreutils-noprefix.overrideAttrs (oldAttrs: {
  postInstall = (oldAttrs.postInstall or "") + ''
    rm -f $out/bin/mkfifo  # Let system use GNU version
  '';
});

• Pros: Keep Rust performance for other tools, simple implementation
• Cons: Lose Rust implementation for mkfifo entirely

Solution 3: GNU Compatibility Wrapper ✅ (Elegant)

uutils-coreutils-fzf-compat = pkgs.uutils-coreutils-noprefix.overrideAttrs (oldAttrs: {
  postInstall = (oldAttrs.postInstall or "") + ''
    # Create GNU-compatible wrapper for mkfifo
    mv $out/bin/mkfifo $out/bin/.mkfifo-uutils
    
    cat > $out/bin/mkfifo << 'EOF'
#!/usr/bin/env bash
set -euo pipefail

# Find the actual uutils coreutils multicall binary
uutils_coreutils="$(dirname "$(readlink -f "$0")")/.mkfifo-uutils"

# Handle GNU coreutils compatibility for fzf
if [[ $# -ge 2 && "$1" == "-m" && "$2" == "o+w" ]]; then
  # Convert GNU syntax to octal: o+w = 622 (owner rw, group w, other w)
  shift 2
  exec "$uutils_coreutils" mkfifo -m 622 "$@"
else
  # Pass through all other arguments unchanged
  exec "$uutils_coreutils" mkfifo "$@"
fi
EOF
    chmod +x $out/bin/mkfifo
  '';
});

Key Technical Insights

uutils-coreutils Architecture

• Uses multicall binary approach (single coreutils executable)
• Determines tool behavior via symlink name or explicit subcommand
• When calling directly: coreutils mkfifo -m 622 file (not just coreutils -m 622 file)

Wrapper Design Patterns

1. Hidden file pattern: mv mkfifo .mkfifo-uutils (dot prefix hides implementation detail)
2. Runtime path resolution: $(dirname "$(readlink -f "$0")") for build-time → runtime compatibility
3. Transparent compatibility: Wrapper intercepts specific GNU syntax while passing through everything else

Permission Translation

• GNU syntax: -m o+w (symbolic: owner+group+other write)
• Octal equivalent: -m 622 (owner: rw-, group: -w-, other: -w-)

Debugging Methodology Learnings

1. Start with recent changes: "What changed recently?" led to the breakthrough
2. Environment isolation: Testing inside/outside tmux helped rule out tmux-specific issues
3. Incremental hypothesis testing: Systematically ruled out configuration, version, and integration issues
4. Binary inspection: Understanding the multicall binary architecture was crucial for the final solution

Impact & Resolution

• Root cause: Package compatibility issue, not configuration problem
• Final solution: Elegant wrapper maintaining Rust performance with GNU compatibility
• Broader lesson: Alternative coreutils implementations can have subtle compatibility differences

This issue demonstrates the importance of compatibility layers when adopting modern tool replacements in complex environments.

[Alrefai]

Technical Deep Dive: The Wrapper Script Explained

Script Breakdown

#!/usr/bin/env bash
set -euo pipefail

# Find the actual uutils coreutils multicall binary
uutils_coreutils="$(dirname "$(readlink -f "$0")")/.mkfifo-uutils"

# Handle GNU coreutils compatibility for fzf
if [[ $# -ge 2 && "$1" == "-m" && "$2" == "o+w" ]]; then
  # Convert GNU syntax to octal: o+w = 622 (owner rw, group w, other w)
  shift 2
  exec "$uutils_coreutils" mkfifo -m 622 "$@"
else
  # Pass through all other arguments unchanged
  exec "$uutils_coreutils" mkfifo "$@"
fi

How It Works

1. Path Resolution

uutils_coreutils="$(dirname "$(readlink -f "$0")")/.mkfifo-uutils"

• $0 = current script path (/nix/store/.../bin/mkfifo)
• readlink -f = resolve all symlinks to get real path
• dirname = get directory (/nix/store/.../bin/)
• /.mkfifo-uutils = append hidden filename

This finds the renamed original binary in the same directory.

2. Argument Detection

if [[ $# -ge 2 && "$1" == "-m" && "$2" == "o+w" ]]; then

• $# = argument count (must be at least 2)
• "$1" == "-m" = first arg is the mode flag
• "$2" == "o+w" = second arg is GNU permission syntax

This specifically targets the problematic fzf call: mkfifo -m o+w /tmp/file

3. Translation & Execution

shift 2                                          # Remove -m o+w from $@
exec "$uutils_coreutils" mkfifo -m 622 "$@"    # Call: coreutils mkfifo -m 622 /tmp/file

Why It Didn't Work Before

Previous Attempt Issues:

1. Missing subcommand name:

   # ❌ WRONG - uutils didn't know which tool to run
   exec "$uutils_mkfifo" -m 622 "$@"
   
   # ✅ CORRECT - explicitly tell uutils to run mkfifo
   exec "$uutils_mkfifo" mkfifo -m 622 "$@"

2. uutils-coreutils architecture:

   • Uses a single binary (coreutils) for all tools
   • Binary determines which tool to run based on:
     • How it's called (symlink name)
     • Or explicit subcommand argument
   • When we renamed mkfifo → .mkfifo-uutils, it lost the name hint

The Discovery Process:

1. First clue: ls -la .mkfifo-uutils showed coreutils symlink
2. Second clue: Error -m: function/utility not found meant shell couldn't parse the command
3. Key insight: uutils needs to know which subcommand to execute

Why It Works Now

Correct Architecture Understanding:

# uutils-coreutils multicall binary structure:
coreutils ls /path          # acts as ls
coreutils mkfifo -m 622     # acts as mkfifo  
coreutils cat file          # acts as cat

Our wrapper correctly calls:

exec "$uutils_coreutils" mkfifo -m 622 "$@"
#    ^^^^^^^^^^^^^^^      ^^^^^^  ^^^^^^^^
#    multicall binary     subcommand args

Perfect Compatibility Layer:

• GNU tools: mkfifo -m o+w /tmp/file
• Our wrapper: Translates to mkfifo -m 622 /tmp/file
• uutils: Understands octal permissions (622)
• Result: ✅ Works seamlessly

Design Patterns Used

Hidden File Pattern

mv $out/bin/mkfifo $out/bin/.mkfifo-uutils

• Purpose: Hide implementation details from users
• Benefit: Clean bin/ directory listing
• Convention: Dot-prefixed files are internal/backing files

Accurate Variable Naming

uutils_coreutils="path/to/.mkfifo-uutils"  # Points to multicall binary
exec "$uutils_coreutils" mkfifo "$@"       # Call with explicit subcommand

• Clarity: Variable name matches what it actually contains
• Intent: Shows we're using the multicall binary architecture
• Maintenance: Future developers understand the structure immediately

The Elegant Solution

This approach is elegant because:

1. Transparent: Tools calling mkfifo don't know there's a wrapper
2. Efficient: Direct exec, no shell overhead after translation
3. Robust: Handles both GNU and octal syntax
4. Self-contained: Everything in one package
5. Maintainable: Clear logic, easy to extend

The key breakthrough was understanding that uutils-coreutils is fundamentally different from GNU coreutils - it's a single multicall binary that needs explicit subcommand specification when called directly.