Rewrite remembering in Go

The shell pipeline (sed | sort | tee | awk | sort | cut | "$@"
plus the cut | uniq | awk profile rewrite) becomes a single static
binary with the same observable behaviour, pinned by the original
ranking.sh, signals.sh and cli-opts.sh suites, now aimed at
remembering.bin:

- the profile keeps the exact on-disk format, COUNT profile TEXT,
  byte-sorted with new picks appended at 1 and offered-but-never-
  picked entries persisted at 0;
- the menu stays count-descending with byte-order ties, stdin
  alone defines what is offered, and duplicate profile lines sum
  for ranking but collapse to the highest count on rewrite, as
  sort | uniq -f1 did;
- the wrapped command's exit status is forwarded as-is (128+sig
  for signal deaths), its stderr passes through, and an empty pick
  learns nothing;
- the profile rewrite stays atomic via .tmp plus rename.

Per the house CLI conventions, -h/-V/--help/--version are gone
(the manpage is the documentation; bad options print the usage on
stderr and exit 2), and getopts-style attached option arguments
(-pNAME) are not accepted any more --- no script in the wild used
them.

The project layout follows rot: raw go tool compile/link Makefile,
mkdeps.sh-generated deps.mk, white-box unit suite, fuzz target
over the profile parse/serialize roundtrip, functional pick
roundtrip, a 1M-line ranking benchmark, and a single English
asciidoc manpage absorbing the old .5 page; the po4a/aux release
machinery goes away.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

1 files changed, 160 insertions, 0 deletions

diff --git a/doc/remembering.en.1.adoc b/doc/remembering.en.1.adoc
new file mode 100644
index 0000000..9d5f859
--- /dev/null
+++ b/doc/remembering.en.1.adoc
@@ -0,0 +1,160 @@
+= remembering(1)
+
+
+
+== NAME
+
+remembering - add memory to dmenu, fzf and similar menu tools.
+
+
+
+== SYNOPSYS
+
+*remembering* [_-p PROFILE_] -- _COMMAND_...
+
+
+
+== EXAMPLES
+
+
+=== A dmenu launcher that learns
+
+[source,sh]
+....
+$ printf 'firefox\nmpv\nmutt\n' | remembering -p apps -- dmenu
+....
+
+The first time, the menu comes up alphabetical.  Pick `mutt` a few
+times and it comes up first.
+
+
+=== Open a file with fzf, most-used first
+
+[source,sh]
+....
+$ ls | remembering -- fzf
+....
+
+Without _-p_, the profile is derived from the current directory,
+so every directory gets its own ranking with no setup.
+
+
+
+== DESCRIPTION
+
+*remembering* sits between a list of choices and the menu tool
+that picks from them.  It reads the choices from _stdin_, feeds
+them to _COMMAND_ sorted by how often each one was picked before,
+takes what _COMMAND_ prints as the pick, bumps that pick's count
+in the profile, and prints the pick.
+
+The lines on _stdin_ define what is offered: the profile only
+ranks them.  Most-picked lines come first; ties are broken in byte
+order; never-picked lines keep their byte order at the bottom.
+
+The pick does not have to be one of the offered lines --- whatever
+_COMMAND_ prints is learnt, so menu tools that accept free text
+(such as `dmenu`) grow new entries on first use.  Lines that were
+offered but never picked are remembered with a count of zero, and
+profile entries that stop appearing on _stdin_ are kept --- the
+profile accumulates the universe of choices it has seen.
+
+The profile is rewritten atomically (a sibling `.tmp` file plus
+rename), so a crash never leaves a half-written profile.
+
+*remembering* is transparent in pipelines: _COMMAND_'s _stderr_
+(where dmenu and fzf draw their interface) passes through, and its
+exit status is forwarded.  A cancelled menu --- a nonzero exit ---
+aborts the run with the same status and learns nothing.  A
+successful run that picks nothing (empty output) also learns
+nothing, and exits 0.
+
+
+
+== OPTIONS
+
+*-p* _PROFILE_::
+The profile name to gather and store the ranking under (default:
+the current directory, with every `/` turned into `!`).
+
+
+
+== IO
+
+
+=== STDIN
+
+The menu choices, one per line, in any order.
+
+
+=== STDOUT
+
+The pick, when there is one, followed by a newline.  _COMMAND_'s
+own output is captured, not echoed.
+
+
+=== STDERR
+
+_COMMAND_'s _stderr_, passed through untouched, and error
+messages.
+
+
+=== INPUT AND OUTPUT FILES
+
+The profile, at:
+
+[source,sh]
+....
+${XDG_DATA_HOME:-$HOME/.local/share}/remembering/$PROFILE
+....
+
+It is a plain text file with one line per known choice:
+
+[source,sh]
+....
+2 profile firefox
+0 profile mpv
+7 profile mutt
+....
+
+The count comes first, the literal word `profile` second, and the
+choice's text --- spaces included --- runs to the end of the line.
+Lines are kept in byte order, with a newly learnt pick appended at
+the end.  The file is made to be hand-edited: delete a line to
+forget it, edit a count to re-rank it.
+
+
+
+== EXIT STATUS
+
+0::  The pick was learnt and printed, or there was nothing to
+learn (empty pick).
+
+1::  A runtime error, such as an unreadable or unwritable profile.
+
+2::  Usage error: an unknown option, or a missing _COMMAND_.
+
+Otherwise, _COMMAND_'s own nonzero exit status, forwarded as-is
+(or 128 plus the signal number when it was killed by a signal).
+
+
+
+== SEE ALSO
+
+dmenu(1), fzf(1), sort(1)
+
+
+
+== AUTHORS
+
+mailto:eu@euandre.org[EuAndreh] and contributors.
+
+
+
+== BUGS
+
+* Report bugs to the mailto:~euandreh/public-inbox@lists.sr.ht[mailing list].
+  Use the subject "[remembering] BUG or TASK: <description>".
+* Browse bugs https://euandre.org/git/remembering/TODOs.html[online].
+* https://euandre.org/git/remembering/[Homepage].
+* https://lists.sr.ht/~euandreh/public-inbox?search=%5Bremembering%5D[Comments and discussions].