# PLAN — ffind cross-shell rewrite + OBS packaging/release integration

Status: **APPROVED 2026-08-14 by user** (contract saved; execution in progress).

## Goal
Make `ffind` a cross-shell, distro-universal fuzzy file-search tool (single bash
executable + preview helper + completion snippets), then wire it into the same
OBS release pipeline as `dotbackup`: Forgejo tag -> release asset -> VPS watchdog
-> OBS noarch package (rpm/deb) -> attached to release -> `install.sh` installs
the native package.

## Approved decisions
- License: **AGPL-3.0-or-later** (user directive; matches dotbackup).
- Initial version: **0.1.0** (user approved the assumed value).
- No shell-specific wrappers: single `/usr/bin/ffind` executable works in every
  shell (bash/zsh/fish/sh exec it as an external binary). `ffind.fish` (function)
  is DELETED from the repo.
- Completion snippets included (user directive): bash, zsh, fish completion files.
- Package contents: `/usr/bin/ffind`, `/usr/bin/ffind-preview`, and the three
  completion files. Runtime deps: `fzf`, `ripgrep`, `xdg-utils`.
- OBS project: `home:Baalthasar:ffind`, package `ffind`, noarch, targets
  `openSUSE_Tumbleweed/x86_64 Debian_13/x86_64 Debian_13/aarch64`.
- Watchdog `forgejo_scm` handler must be generalized: tarball names from config
  (`source_asset`, optional `vendor_asset`), vendor skipped when unset; defaults
  keep dotbackup behavior identical.

## Part 1 — Cross-shell ffind
- New `ffind` bash script (repo root): args `[dir] [--md]` + `--version`/`-h`/`--help`;
  guards `fzf`+`rg`; feeds `(rg -n --files "$dir" | head -10000; rg --files "$dir")`
  into fzf with same prompt/colors/preview/bindings as the old ffind.fish;
  `Ctrl-Y` copies path via `ffind-preview --copy {}` (ranked chain
  wl-copy -> xclip -> xsel -> pbcopy); `Enter` runs `xdg-open`.
- `ffind-preview` extended with `--copy <line>` subcommand (centralizes parsing,
  keeps fzf binding simple).
- `completions/ffind.bash` -> `/usr/share/bash-completion/completions/ffind`;
  `completions/_ffind.zsh` -> `/usr/share/zsh/site-functions/_ffind`;
  `completions/ffind.fish` -> `/usr/share/fish/vendor_completions.d/ffind.fish`
  (completion file, NOT a function — does not shadow the binary).
- `VERSION` = 0.1.0; `LICENSE` = AGPL-3.0-or-later.
- `install.sh` rewritten (mirror dotbackup): Linux -> OBS rpm/deb via apt/zypper/dnf;
  fallback: macOS brew + script copy; source fallback for unsupported pm/arch.
- `README.md` rewritten: any-shell usage, package install, fish stale-function cleanup note.

## Part 2 — OBS pipeline
- `.forgejo/workflows/release.yml`: Job A builds `ffind-$VER.tar.xz`
  (`--transform "s|^\./|ffind-$VER/|"`, exclude .git/target), creates release,
  attaches. NO vendor.tar.xz. Job B polls `home:Baalthasar:ffind`/`ffind` for the
  3 targets, `osc getbinaries`, version-gates on `$VER`, attaches `ffind-*.rpm`/`ffind_*.deb`.
  Secrets: `RELEASE_TOKEN`, `OSCRC` (both set on repo 2026-08-14).
- `.forgejo/workflows/ci.yml`: `shellcheck ffind ffind-preview`.
- Watchdog (`Open-Build-Service/ops/watchdog/watchdog.sh`): generalize
  `forgejo_scm` (see decisions). `projects.yaml`: add ffind entry (no `vendor_asset`).
- OBS package `home:Baalthasar:ffind/ffind` created via osc with spec/debian/changes
  + seed tarball `ffind-0.1.0.tar.xz`; watchdog then SRs to `home:Baalthasar`.
- Deploy watchdog changes to VPS (`ssh Jan`, `/opt/stacks/obs-agent/`), rebuild
  `obs-watchdog:local` image.

## Validation
1. `shellcheck ffind ffind-preview` clean.
2. `./ffind --md /tmp` works in bash and zsh; `--version` prints 0.1.0; Ctrl-Y copies; Enter opens.
3. Tarball `ffind-0.1.0.tar.xz` extracts to `ffind-0.1.0/{ffind,ffind-preview,completions,VERSION,LICENSE,...}`.
4. `osc build` (3 targets) -> rpm/deb with the 5 installed files in correct dirs.
5. Watchdog regression: `--once --project dotbackup` -> no change. `--once --project ffind` bumps/syncs.
6. Tag `v0.1.0` -> Job A release -> watchdog upload -> OBS green -> Job B attaches.
7. `install.sh` installs OBS package on Tumbleweed + Debian; completions work in bash/zsh/fish.
