fix(spec): catch duplicate registrations; feat(cd): complete from zoxide (#105)

Two fixes, independent of #103 and #104.

---

## 1. `Register` silently overwrites, and `find` was defined twice

`Register` is `Registry[s.Name] = s`, and every spec registers from an
`init()` spread across the `commands` packages. A name defined twice is
therefore resolved by package init order, and nothing anywhere reports
it.

`find` was registered in both `commands/fs/find.go` and
`commands/text/find.go`. The definitions are not equivalent — the `text`
one carries `FileGenerator("/")` and 26 options, the `fs` one has four
BSD-specific flags and no generator — so which one you got determined
whether `find` completed paths at all. Neither file gives any hint that
the other exists.

Merged into one: the BSD flags move onto the richer `text` definition
and the `fs` copy is removed. `Register` now records names it has seen
before, and a registry-wide test asserts there are none. Confirmed the
guard fails when a duplicate is reintroduced, rather than passing
vacuously.

## 2. `cd` could only complete children of the current directory

`cd` completes through `FileGenerator`, which reads exactly one
directory: the one you are standing in. So `cd proj` resolves only when
`proj` happens to be a child of the current directory, and returns
nothing at all otherwise — including for directories visited many times
a day.

That is close to the opposite of what `cd` is normally reached for, and
from the prompt it does not read as a scope limit; it reads as
completion being broken, because nothing appears.

`zoxide.extend-cd` routes `cd` through the generator `z` already uses,
so local children are offered first and zoxide's frecency database
supplies everything else:

```
# in ~/dotfiles
cd Develop  ->  ~/Development, ~/Developer, ~/Development/cnc-claims, ...
cd conf     ->  config/ (local child, still first), then ~/.config, ~/dotfiles/.config
```

Off by default. It shells out to zoxide, and offering absolute paths
from outside the current directory is a real change in what `cd`
proposes.

### The query is now cached

`zoxide query -l` is a subprocess costing ~11ms on this machine, and
generators run on **every keystroke** — that is the entire budget for a
suggestion redraw. The result is cached for two seconds; the list only
changes when the user changes directory, so the window costs nothing in
practice.

This applies to `z` and `zi` as well, which were paying that cost per
keystroke already.

---

## Testing

`go test -race ./...` passes.

Behaviour was checked by driving the built binary through a real pty
against an unmodified interactive zsh (starship, zsh-autosuggestions,
fzf-tab, atuin loaded), reading the byte stream rather than trusting
unit tests alone — the `cd Develop` and `cd conf` results above are
transcribed from that.

No new dependencies.

---------

Co-authored-by: verse91 <versedev.store@proton.me>

Author: kdbaustert

README.md

@@ -330,6 +330,9 @@ channel = "stable"       # "stable" or "nightly"
 check-interval = "24h"   # min time between update checks
 auto-update = 0          # 0 = off, 1 = auto-install, 2 = confirm first
 
+[zoxide]
+extend-cd = false  # complete `cd` from zoxide's database, not just the current directory
+
 [ai]
 enabled = false
 provider = "groq"  # "groq" or "ollama"

commands/fs/cd.go

@@ -3,6 +3,7 @@ package fs
 import (
 	"strings"
 
+	"github.com/versenilvis/iris/internal/config"
 	"github.com/versenilvis/iris/spec"
 )
 
@@ -12,6 +13,14 @@ func init() {
 		Description: "change directory",
 		MaxArgs:     0,
 		Generator: func(tokens []string, prefix string, partial string) []spec.Suggestion {
+			// The file generator only reads the current directory, so `cd proj`
+			// comes back empty unless its parent is where you already are --
+			// which is not how cd is typically used. zoxide.extend-cd folds in
+			// the frecency database that `z` already queries, making any
+			// directory zoxide has seen reachable by name from anywhere.
+			if config.Get().Zoxide.ExtendCd {
+				return ZoxideGenerator()(tokens, prefix, partial)
+			}
 			fullQuery := strings.Join(tokens[1:], " ")
 			return spec.FileGenerator("/")(tokens, prefix, fullQuery)
 		},

commands/fs/find.go

@@ -10,6 +10,8 @@ import (
 	"os"
 	"os/exec"
 	"strings"
+	"sync"
+	"time"
 
 	"github.com/versenilvis/fuzzy"
 	"github.com/versenilvis/iris/spec"
@@ -30,24 +32,56 @@ func init() {
 	})
 }
 
+// zoxideCacheTTL bounds how stale the directory list may be. Generators run on
+// every keystroke and `zoxide query -l` is a subprocess costing on the order of
+// ten milliseconds, which is the entire latency budget for a suggestion redraw.
+// The list only changes when the user changes directory, so a short window
+// costs nothing in practice.
+const zoxideCacheTTL = 2 * time.Second
+
+var zoxideCache struct {
+	sync.Mutex
+	dirs    []string
+	err     error
+	fetched time.Time
+}
+
+// zoxideDirs returns zoxide's known directories, most frecent first.
+func zoxideDirs() ([]string, error) {
+	zoxideCache.Lock()
+	defer zoxideCache.Unlock()
+
+	if !zoxideCache.fetched.IsZero() && time.Since(zoxideCache.fetched) < zoxideCacheTTL {
+		return zoxideCache.dirs, zoxideCache.err
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
+	defer cancel()
+
+	out, err := exec.CommandContext(ctx, "zoxide", "query", "-l").Output()
+	zoxideCache.fetched = time.Now()
+	zoxideCache.err = err
+	zoxideCache.dirs = nil
+	if err != nil {
+		return nil, err
+	}
+
+	for line := range strings.SplitSeq(string(bytes.TrimSpace(out)), "\n") {
+		if line = strings.TrimSpace(line); line != "" {
+			zoxideCache.dirs = append(zoxideCache.dirs, line)
+		}
+	}
+	return zoxideCache.dirs, nil
+}
+
 func ZoxideGenerator() spec.GeneratorFunc {
 	return func(tokens []string, prefix string, partial string) []spec.Suggestion {
 		fullQuery := strings.Join(tokens[1:], " ")
 		localSuggestions := spec.FileGenerator("/")(tokens, prefix, fullQuery)
 
 		var zoxideSuggestions []spec.Suggestion
-		cmd := exec.CommandContext(context.Background(), "zoxide", "query", "-l")
-		out, err := cmd.Output()
+		dirs, err := zoxideDirs()
 		if err == nil {
-			lines := strings.Split(string(bytes.TrimSpace(out)), "\n")
-			var dirs []string
-			for _, line := range lines {
-				line = strings.TrimSpace(line)
-				if line != "" {
-					dirs = append(dirs, line)
-				}
-			}
-
 			home, _ := os.UserHomeDir()
 
 			if fullQuery == "" {

commands/fs/zoxide.go

@@ -10,6 +10,13 @@ func init() {
 		Description: "search for files",
 		Generator:   spec.FileGenerator("/"),
 		Options: []spec.Option{
+			// BSD find; these came from a second `find` spec in commands/fs that
+			// silently overwrote or was overwritten by this one depending on
+			// package init order.
+			{Name: "-E", Description: "Permit find to be safely used in conjunction with xargs"},
+			{Name: "-d", Description: "Cause find to perform a depth-first traversal"},
+			{Name: "-f", Description: "Specify a file hierarch for find to traverse"},
+			{Name: "-s", Description: "Cause find to traverse the file hierarchies in lexicographical order"},
 			{Name: "-name", Description: "match by name"},
 			{Name: "-iname", Description: "match by name (case insensitive)"},
 			{Name: "-type", Description: "match by type (f=file, d=dir, l=link)"},

commands/text/find.go

@@ -103,6 +103,21 @@ type KeybindingsConfig struct {
 	NavigateRight    string `toml:"navigate-right"`
 }
 
+type ZoxideConfig struct {
+	// ExtendCd adds zoxide's frecency database to `cd` completions.
+	//
+	// Without it `cd` only offers direct children of the current directory,
+	// because that is all the file generator walks -- so `cd proj` finds
+	// nothing unless you are already standing in the parent. With it, any
+	// directory zoxide has seen is reachable by name from anywhere, which is
+	// what `cd` is usually wanted for.
+	//
+	// Off by default: it shells out to zoxide, and the suggestions are absolute
+	// paths from outside the current directory, which is a real change in what
+	// `cd` offers.
+	ExtendCd bool `toml:"extend-cd"`
+}
+
 type SuggestOnEmptyConfig struct {
 	Enabled       bool `toml:"enabled"`
 	DebounceMS    int  `toml:"debounce_ms"`
@@ -152,6 +167,7 @@ type Config struct {
 	Git         GitConfig         `toml:"git"`
 	Updater     UpdaterConfig     `toml:"updater"`
 	AI          AIConfig          `toml:"ai"`
+	Zoxide      ZoxideConfig      `toml:"zoxide"`
 	Keybindings KeybindingsConfig `toml:"keybindings"`
 }
 

internal/config/config.go

@@ -47,6 +47,9 @@ func DefaultConfig() *Config {
 				MinIntervalMS: 5000,
 			},
 		},
+		Zoxide: ZoxideConfig{
+			ExtendCd: false,
+		},
 		Keybindings: KeybindingsConfig{
 			ToggleMode:       "ctrl+r",
 			ToggleMenu:       "shift+tab",

internal/config/defaults.go

@@ -111,6 +111,11 @@ check-interval = "24h"
 # 0 = off (default, notify only), 1 = auto-install, 2 = always confirm first
 auto-update = 0
 
+[zoxide]
+# also complete cd from zoxide's frecency database, not just the
+# children of the current directory (requires zoxide on PATH)
+extend-cd = false
+
 [keybindings]
 toggle-mode = "ctrl+r"
 toggle-menu = "shift+tab"

root/config_cmd.go

@@ -296,6 +296,11 @@ check-interval = "24h"
 # 0 = off (default, notify only), 1 = auto-install, 2 = always confirm first
 auto-update = 0
 
+[zoxide]
+# also complete cd from zoxide's frecency database, not just the
+# children of the current directory (requires zoxide on PATH)
+extend-cd = false
+
 [keybindings]
 toggle-mode = "ctrl+r"
 toggle-menu = "shift+tab"

root/init.go

@@ -1,5 +1,7 @@
 package spec
 
+import "slices"
+
 type GeneratorFunc func(tokens []string, prefix string, partial string) []Suggestion
 
 // Spec defines a top-level command structure
@@ -46,13 +48,33 @@ type Suggestion struct {
 
 var Registry = map[string]*Spec{}
 
+// duplicateNames records specs registered under a name already taken.
+//
+// Registration is last-one-wins, and every spec is registered from an init()
+// spread across the commands packages, so a name defined twice resolves on
+// package init order -- and does so silently. `find` was registered in two
+// packages, and the one that lost had the file generator, which is exactly the
+// kind of difference nobody notices from reading either file.
+var duplicateNames []string
+
 // Register adds a new spec to the global Registry
 // example: Register(&Spec{Name: "git"})
 func Register(s *Spec) {
+	if _, exists := Registry[s.Name]; exists {
+		duplicateNames = append(duplicateNames, s.Name)
+	}
 	Registry[s.Name] = s
 }
 
+// DuplicateNames returns the spec names that were registered more than once.
+// A non-empty result is a bug: which definition survives is decided by package
+// init order rather than by intent.
+func DuplicateNames() []string {
+	return slices.Clone(duplicateNames)
+}
+
 // ResetRegistry clears all registered specs - use in tests only
 func ResetRegistry() {
 	Registry = make(map[string]*Spec)
+	duplicateNames = nil
 }