feat(fuzzy-finder): add UX defaults and CLI_FUZZY_FINDER_OPTIONS passthrough (#534)

Add sensible fzf UX defaults and CLI_FUZZY_FINDER_OPTIONS system variable.

Default fzf options (--select-1, --exit-0, --highlight-line, --cycle) are set
as CLI args in prepareFzfOptions so they can be overridden by users.

CLI_FUZZY_FINDER_OPTIONS allows arbitrary fzf flag passthrough with last-wins
semantics. Uses google/shlex for proper shell-style word splitting, supporting
quoted arguments like --header='My Header'.

Documents --tmux incompatibility (opts.Input Go channel vs external process).
Refines CLAUDE.md no-future-proofing guideline and adds merge-over-rebase policy.

Fixes #526

Author: apstndb

CLAUDE.md

@@ -142,13 +142,14 @@ For testing best practices (table-driven tests, coverage comparison, test organi
 ### Git Practices
 - **CRITICAL**: Always use `git add <specific-files>` (never `git add .` or `git add -A`)
 - **CRITICAL**: Never rewrite pushed commits without explicit permission
+- **Conflict resolution**: Use `git merge origin/main` (not rebase). This repo uses squash merge, so commit history cleanliness doesn't matter — merge is safer and preserves context.
 - Link PRs to issues: "Fixes #issue-number"
 - Check `git status` before committing
 
 ## Important Notes
 
 - **No backward compatibility required** - not used as an external library
-- **No future-proofing** - only implement what's needed now
+- **No future-proofing, but choose correct solutions** - don't build speculative features (plugin systems, unnecessary abstractions), but when a clearly correct solution exists at similar cost, prefer it over a known-incomplete alternative. When in doubt, present options to the user rather than automatically choosing the minimal path.
 - **Issue management**: All fixes go through PRs - never close issues manually
 - **License headers**: New files use "Copyright [year] apstndb"; files from spanner-cli keep "Copyright [year] Google LLC"
 

README.md

@@ -947,6 +947,7 @@ They have almost same semantics with [Spanner JDBC properties](https://cloud.goo
 | CLI_STREAMING             | READ_WRITE | `"AUTO"`                                       |
 | CLI_TABLE_PREVIEW_ROWS    | READ_WRITE | `50`                                           |
 | CLI_FUZZY_FINDER_KEY      | READ_WRITE | `"C_T"`                                        |
+| CLI_FUZZY_FINDER_OPTIONS  | READ_WRITE | `""`                                           |
 
 > **Note**: `CLI_FORMAT` accepts the following values:
 > - `TABLE` - ASCII table with borders (default for both interactive and batch modes)
@@ -967,6 +968,10 @@ They have almost same semantics with [Spanner JDBC properties](https://cloud.goo
 >
 > For Table formats with streaming enabled, `CLI_TABLE_PREVIEW_ROWS` (default: 50) controls how many rows are used to calculate column widths before streaming the rest.
 
+> **Note**: `CLI_FUZZY_FINDER_OPTIONS` passes additional fzf options to the fuzzy finder. Options are appended after built-in defaults, so user options take precedence (last wins).
+> Built-in defaults: `--reverse`, `--no-sort`, `--select-1`, `--exit-0`, `--highlight-line`, `--cycle`, `--border=rounded`, `--info=inline-right`.
+> `--tmux` is not supported because the fuzzy finder runs fzf in-process via the Go library.
+
 ### Batch statements
 
 #### DDL batching

docs/system_variables.md

@@ -141,4 +141,24 @@ TODO
   - Batching can improve performance when importing large datasets
   - The last batch may contain fewer rows than the batch size
 
+#### Interactive / Fuzzy Finder Variables
+
+##### CLI_FUZZY_FINDER_OPTIONS
+- **Type**: STRING
+- **Default**: (empty)
+- **Description**: Additional fzf options passed to the fuzzy finder
+- **Access**: Read/Write
+- **Usage**:
+  ```sql
+  SET CLI_FUZZY_FINDER_OPTIONS = '--color=dark';
+  SET CLI_FUZZY_FINDER_OPTIONS = '--no-select-1 --no-cycle';  -- Override defaults
+  SET CLI_FUZZY_FINDER_OPTIONS = '';  -- Reset to defaults only
+  ```
+- **Notes**:
+  - Options are appended after built-in defaults, so user options take precedence (last wins)
+  - Uses standard fzf option syntax (space-separated flags)
+  - Built-in defaults: `--reverse`, `--no-sort`, `--height`, `--border=rounded`, `--info=inline-right`, `--select-1`, `--exit-0`, `--highlight-line`, `--cycle`
+  - Useful for customizing appearance (colors, layout) or behavior (sorting, preview)
+  - `--tmux` is **not supported** because the fuzzy finder runs fzf in-process via the Go library
+
 TODO: Document other CLI_* variables

go.mod

@@ -109,6 +109,7 @@ require (
 	github.com/golang/snappy v1.0.0 // indirect
 	github.com/google/jsonschema-go v0.2.0 // indirect
 	github.com/google/s2a-go v0.1.9 // indirect
+	github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/googleapis/enterprise-certificate-proxy v0.3.7 // indirect
 	github.com/googleapis/gax-go/v2 v2.15.0 // indirect

go.sum

@@ -2791,6 +2791,8 @@ github.com/google/s2a-go v0.1.7/go.mod h1:50CgR4k1jNlWBu4UfS4AcfhVe1r6pdZPygJ3R8
 github.com/google/s2a-go v0.1.8/go.mod h1:6iNWHTpQ+nfNRN5E00MSdfDwVesa8hhS32PhPO8deJA=
 github.com/google/s2a-go v0.1.9 h1:LGD7gtMgezd8a/Xak7mEWL0PjoTQFvpRudN895yqKW0=
 github.com/google/s2a-go v0.1.9/go.mod h1:YA0Ei2ZQL3acow2O62kdp9UlnvMmU7kA6Eutn0dXayM=
+github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 h1:El6M4kTTCOh6aBiKaUGG7oYTSPP8MxqL4YI3kZKwcP4=
+github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510/go.mod h1:pupxD2MaaD3pAXIBCelhxNneeOaAeabZDe5s4K6zSpQ=
 github.com/google/uuid v1.1.2/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/google/uuid v1.3.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/google/uuid v1.3.1/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=

internal/mycli/fuzzy_finder.go

@@ -31,6 +31,7 @@ import (
 	"cloud.google.com/go/spanner/admin/database/apiv1/databasepb"
 	"github.com/apstndb/lox"
 	"github.com/cloudspannerecosystem/memefish/ast"
+	"github.com/google/shlex"
 	"github.com/hymkor/go-multiline-ny"
 	fzf "github.com/junegunn/fzf/src"
 	"github.com/nyaosorg/go-readline-ny"
@@ -130,7 +131,7 @@ func (f *fuzzyFinderCommand) Call(ctx context.Context, B *readline.Buffer) readl
 	// Terminal handoff: move cursor below editor, run fzf, then restore
 	rewind := f.editor.GotoEndLine()
 
-	chosen, ok := runFzf(candidates, result.argPrefix, completionHeader(result.completionType))
+	chosen, ok := runFzf(candidates, result.argPrefix, completionHeader(result.completionType), f.cli.SystemVariables.FuzzyFinderOptions)
 
 	rewind()
 	B.RepaintLastLine()
@@ -311,6 +312,8 @@ func prepareFzfOptions(candidates []fzfItem, header string) fzfPrepared {
 		"--height=" + height,
 		"--border=rounded",
 		"--info=inline-right",
+		"--select-1", "--exit-0",
+		"--highlight-line", "--cycle",
 	}
 	if hasLabels {
 		fzfArgs = append(fzfArgs, "--delimiter="+fzfDelimiter, "--with-nth=2..")
@@ -355,11 +358,23 @@ func extractValue(line string, hasLabels bool) string {
 // runFzf runs the fzf fuzzy finder with the given candidates and optional initial query.
 // When candidates have separate Label and Value, fzf displays/searches the Label
 // but the returned string is the Value (for insertion into the buffer).
+// extraOptions is an optional string of additional fzf flags (from CLI_FUZZY_FINDER_OPTIONS)
+// that are appended after built-in defaults so user options take precedence.
 // Returns the selected Value and true, or ("", false) if cancelled or no match.
-func runFzf(candidates []fzfItem, query string, header string) (string, bool) {
+func runFzf(candidates []fzfItem, query string, header string, extraOptions string) (string, bool) {
 	prepared := prepareFzfOptions(candidates, header)
 
-	opts, err := fzf.ParseOptions(false, prepared.args)
+	args := prepared.args
+	if extraOptions != "" {
+		extra, err := shlex.Split(extraOptions)
+		if err != nil {
+			slog.Debug("fuzzy finder: parse extra options", "err", err)
+			return "", false
+		}
+		args = append(args, extra...)
+	}
+
+	opts, err := fzf.ParseOptions(false, args)
 	if err != nil {
 		slog.Debug("fuzzy finder: parse fzf options", "err", err)
 		return "", false
@@ -372,6 +387,10 @@ func runFzf(candidates []fzfItem, query string, header string) (string, bool) {
 	}
 	opts.ForceTtyIn = true
 
+	// Feed candidates via in-process Go channel.
+	// NOTE: This is incompatible with --tmux, which spawns an external fzf process
+	// that cannot read from a Go channel. With --tmux, the child process receives
+	// no input and exits immediately (especially with --exit-0).
 	inputChan := make(chan string, len(prepared.formattedLines))
 	for _, line := range prepared.formattedLines {
 		inputChan <- line
@@ -401,18 +420,31 @@ func runFzf(candidates []fzfItem, query string, header string) (string, bool) {
 // runFzfFilter runs fzf in non-interactive --filter mode for testing.
 // It returns all matching Values (after Value/Label extraction).
 // This tests the full pipeline: formatting → fzf matching → result extraction.
-func runFzfFilter(candidates []fzfItem, filter string, header string) []string {
+func runFzfFilter(candidates []fzfItem, filter string, header string, extraOptions string) []string {
 	prepared := prepareFzfOptions(candidates, header)
 
+	args := prepared.args
+	if extraOptions != "" {
+		extra, err := shlex.Split(extraOptions)
+		if err != nil {
+			return nil
+		}
+		args = append(args, extra...)
+	}
+
 	// For filter mode, strip visual-only args and add --filter.
-	filterArgs := make([]string, 0, len(prepared.args)+1)
-	for _, arg := range prepared.args {
+	filterArgs := make([]string, 0, len(args)+1)
+	for _, arg := range args {
 		// Skip args that don't apply in non-interactive filter mode.
 		if strings.HasPrefix(arg, "--height") ||
 			strings.HasPrefix(arg, "--border") ||
 			strings.HasPrefix(arg, "--reverse") ||
 			strings.HasPrefix(arg, "--info") ||
-			strings.HasPrefix(arg, "--gap") {
+			strings.HasPrefix(arg, "--gap") ||
+			strings.HasPrefix(arg, "--select-1") || strings.HasPrefix(arg, "--no-select-1") ||
+			strings.HasPrefix(arg, "--exit-0") || strings.HasPrefix(arg, "--no-exit-0") ||
+			strings.HasPrefix(arg, "--highlight-line") || strings.HasPrefix(arg, "--no-highlight-line") ||
+			strings.HasPrefix(arg, "--cycle") || strings.HasPrefix(arg, "--no-cycle") {
 			continue
 		}
 		filterArgs = append(filterArgs, arg)

internal/mycli/fuzzy_finder_test.go

@@ -907,7 +907,7 @@ func TestRunFzfFilter_SimpleMatch(t *testing.T) {
 		{Value: "alphabet"},
 	}
 
-	results := runFzfFilter(candidates, "alph", "")
+	results := runFzfFilter(candidates, "alph", "", "")
 	assert.Contains(t, results, "alpha")
 	assert.Contains(t, results, "alphabet")
 	assert.NotContains(t, results, "beta")
@@ -922,7 +922,7 @@ func TestRunFzfFilter_LabelValueSeparation(t *testing.T) {
 	}
 
 	// Filter by label text, but results should be Values.
-	results := runFzfFilter(candidates, "CREATE", "Operations")
+	results := runFzfFilter(candidates, "CREATE", "Operations", "")
 	assert.Contains(t, results, "op-123")
 	assert.NotContains(t, results, "op-456")
 	assert.NotContains(t, results, "op-789")
@@ -932,10 +932,40 @@ func TestRunFzfFilter_StatementNames(t *testing.T) {
 	items := buildStatementNameItems()
 
 	// Filter for "SHOW DATABASES" — should match the statement and return its insert text.
-	results := runFzfFilter(items, "SHOW DATABASES", "Statements")
+	results := runFzfFilter(items, "SHOW DATABASES", "Statements", "")
 	assert.Contains(t, results, "SHOW DATABASES", "should find the no-arg statement")
 }
 
+func TestRunFzfFilter_ExtraOptions(t *testing.T) {
+	candidates := []fzfItem{
+		{Value: "alpha"},
+		{Value: "beta"},
+		{Value: "gamma"},
+		{Value: "alphabet"},
+	}
+
+	// Passing extra options should not break filtering.
+	results := runFzfFilter(candidates, "alph", "", "--no-sort")
+	assert.Contains(t, results, "alpha")
+	assert.Contains(t, results, "alphabet")
+	assert.NotContains(t, results, "beta")
+	assert.NotContains(t, results, "gamma")
+
+	// Empty extra options should work identically to no options.
+	results = runFzfFilter(candidates, "beta", "", "")
+	assert.Contains(t, results, "beta")
+	assert.NotContains(t, results, "alpha")
+
+	// Quoted options should be parsed correctly (shlex).
+	results = runFzfFilter(candidates, "alph", "", "--no-sort --header='test header'")
+	assert.Contains(t, results, "alpha")
+	assert.Contains(t, results, "alphabet")
+
+	// Malformed quotes should return nil (shlex parse error).
+	results = runFzfFilter(candidates, "alph", "", "--header='unclosed")
+	assert.Nil(t, results)
+}
+
 func TestExtractValue(t *testing.T) {
 	tests := []struct {
 		name      string

internal/mycli/system_variables.go

@@ -151,6 +151,7 @@ type systemVariables struct {
 	SkipSystemCommand         bool   // CLI_SKIP_SYSTEM_COMMAND
 	SkipColumnNames           bool   // CLI_SKIP_COLUMN_NAMES
 	FuzzyFinderKey            string // CLI_FUZZY_FINDER_KEY (empty = disabled)
+	FuzzyFinderOptions        string // CLI_FUZZY_FINDER_OPTIONS
 
 	// Streaming output configuration
 	StreamingMode    enums.StreamingMode // CLI_STREAMING

internal/mycli/var_registry.go

@@ -214,6 +214,8 @@ func (r *VarRegistry) registerAll() {
 		"A boolean indicating whether to suppress column headers in output. The default is false."))
 	r.Register("CLI_FUZZY_FINDER_KEY", StringVar(&sv.FuzzyFinderKey,
 		"Key binding for fuzzy finder. Uses go-readline-ny key names (e.g., C_T, M_F, F1). Set to empty string to disable. The default is C_T (Ctrl+T)."))
+	r.Register("CLI_FUZZY_FINDER_OPTIONS", StringVar(&sv.FuzzyFinderOptions,
+		"Additional fzf options passed to the fuzzy finder. Appended after built-in defaults, so user options take precedence. Example: --color=dark --no-select-1"))
 	r.Register("CLI_STREAMING", StreamingModeVar(&sv.StreamingMode,
 		"Controls streaming output mode: AUTO (format-dependent), TRUE (always stream), FALSE (never stream). Default is AUTO."))