feat: add explicit search backend selection for Linux/Arch support

[na-navi]

Background

se currently targets Windows and calls Everything's es.exe directly. This works well on Windows, but prevents Linux/Arch support because Everything is Windows-only.

The final goal is automatic backend selection by platform/config, but the first implementation should be guarded by an explicit --backend option to avoid unsafe or surprising behavior.

Goal

Introduce backend-aware search execution with explicit backend selection first.

Initial supported backends:

• everything - existing Windows / Everything / es.exe backend
• fd - Linux/Arch filename/path search backend
• rg-files - portable fallback using rg --files

Automatic backend detection is a later step. This issue should only prepare the structure and require explicit backend selection for non-Windows backends.

Proposed CLI

# Existing Windows behavior should remain unchanged
se query

# Explicit backend selection
se --backend everything query
se --backend fd query
se --backend rg-files query

# Scope/path/budget should still work
se --backend fd -p "$HOME/project" -n 20 query
se --backend fd --scope project --max-seconds 5 query
se --backend fd --caller codex --no-interactive query

Safety checks

se should validate the selected backend before search execution.

everything backend

• Requires Windows.
• Requires configured es.exe path.
• Should fail clearly if es.exe is missing.
• Existing Everything behavior should remain unchanged.

fd backend

• Requires fd available in PATH or configured path.
• Should fail clearly if fd is missing.
• Should support path-limited search.
• Should preserve result budget and timeout behavior.

rg-files backend

• Requires rg available in PATH.
• Uses rg --files and filters paths in Python.
• Intended as fallback, not as full content search.

Non-goals

• Do not implement automatic backend detection yet.
• Do not add full content search.
• Do not claim full macOS support.
• Do not change existing Windows default behavior.
• Do not make plocate part of the MVP.

Acceptance criteria

• --backend {everything,fd,rg-files} is parsed and validated.
• Existing Windows default behavior still uses Everything.
• --backend everything preserves the current es.exe path/search behavior.
• --backend fd works on Linux when fd is installed.
• --backend rg-files works when ripgrep is installed.
• -p/--path, -n/--max, --scope, --max-seconds, --stats, --log, and --caller codex --no-interactive continue to work through the backend layer.
• Non-interactive mode still rejects fzf.
• Timeout still exits with 124.
• Stats include the selected backend name.
• Tests cover backend selection and missing-backend errors without requiring Everything.

Suggested implementation shape

cmd_search
  -> derive_backend(args, config, platform)
  -> validate_backend(backend)
  -> backend.search(query, paths, max, deadline)
  -> common observation/log/stats/exit

The current es_search() path can become the everything backend first, keeping the default Windows behavior stable. Automatic backend detection should be handled in a later issue.

[na-navi]

追加メモ: Windows 既存経路の保護を最優先にしたいです。

この issue の目的は Linux/Arch 用 backend を足せる入口を作ることですが、Windows の現在の Everything / es.exe 経路はできるだけ触らない方針にしたいです。

実装方針としては、既存の se query on Windows は従来通り Everything backend に落ちることを baseline とし、Linux/POSIX 系の backend は明示的な --backend 指定でのみ有効化する形が安全だと思います。

期待する境界は以下です。

• Windows default:

  • se query は従来通り Everything / es.exe
  • 既存の出力、exit code、log、stats の意味を変えない
  • Windows 用 config / ~/.serc の既存項目を壊さない

• New backend path:

  • --backend fd
  • --backend rg-files
  • later --backend arch-linux
  • これらは明示 opt-in の別経路として扱う

できれば、cmd_search の序盤で backend を解決し、その後は小さな backend interface に委譲する程度に留めたいです。Linux 対応のために Windows の既存検索フロー全体を大きく再構成するのは避けたいです。

Acceptance criteria に追加したい観点:

• se query on Windows の default backend は Everything のまま
• --backend 未指定時の Windows 挙動は既存と同等
• backend layer の追加によって Windows の es_search() 相当の処理が意味的に変わらない
• Linux/POSIX backend の失敗・警告・fallback は Windows default path に影響しない

Design principle:

Linux/Arch support should be an opt-in backend path first, not a rewrite of the existing Windows default path.

[na-navi]

Implementation split (confirmed)

Splitting backend work across 3 PRs (and an optional 4th):

Order	Target	PR title	Scope
1	#55	feat: add explicit search backend selection	--backend layer, everything (preserved), fd, rg-files
2	#56	feat: add plocate backend	--backend plocate, strict failure, no fallback
3	#56	feat: add arch-linux backend with fd fallback	--backend arch-linux, plocate → fd fallback
4	follow-up	chore: --check diagnostics for systemd/journal	optional; may become a separate issue

This issue (#55) covers only step 1.

#55 PR scope (locked)

CLI:

se query                          # unchanged on Windows → everything
se --backend everything query     # explicit Everything
se --backend fd query             # fd backend
se --backend rg-files query       # rg --files backend

Choices: everything | fd | rg-files. plocate and arch-linux are NOT included (per non-goal "Do not make plocate part of the MVP").

Refinements pinned for #55

• R1: On non-Windows with no --backend, exit 2 with hint. Do not silently default to fd.
• R2: OS guard matrix — everything = Windows only / fd, rg-files = any platform / plocate, arch-linux = N/A in feat: add explicit search backend selection for Linux/Arch support #55.
• R3: Observation contract — --stats, --log, --json all gain backend=<name>. Existing Windows output is behaviorally compatible (the new backend=everything token in stats is the only addition).
• R4: Introduce _backend_invoke(argv, timeout) -> (stdout, rc, stderr) seam in this PR, so feat: add Arch Linux plocate backend with fd fallback #56 PRs can mock one function.
• R5: For fd / rg-files, prefer Popen streaming with -n early-stop. If bulk subprocess.run is used instead, the PR body must justify it (memory bound on large trees).
• R6: New tests/test_backend.py (do not mix into existing test_cli.py).

Acceptance reminder (from issue body)

• es.exe path / cmd_search default unchanged on Windows.
• --caller codex --no-interactive still blocks fzf.
• Timeout still exits 124.
• Stats / log carry the selected backend name.

Why this issue stays open until merge

Refs #55 (not Fixes) so Linux-side validation of fd / rg-files can happen before close.

[na-navi]

PR opened: #58

This is the #55 implementation PR for the explicit backend selector layer.

Scope:

• --backend {everything,fd,rg-files}
• Windows default remains Everything / es.exe
• non-Windows without --backend fails closed with exit 2
• stats / JSON / log include the selected backend name
• no plocate, no arch-linux, no automatic fallback

Keeping this issue open until the PR is reviewed and Linux-side fd / rg-files smoke validation is confirmed.