fix: split dops/docker, fix header doc gaps from Job 3 findings #135

2026-09-08T05:22:52Z

rootiest commented

2026-09-08 05:22:52 +00:00

Addresses AGENTS/JOB-BRIEF-FINDINGS.md (Job 3's out-of-scope findings). Based on feat/header-driven-help since the header-doc gaps and the help-flag exempt list only exist on that branch — merge that PR first, or merge this into it.

1. `dops`/`docker` split (live bug)

functions/dops.fish defined function docker, not dops. dops was never defined; docker was only conditionally defined as a side effect of the failed dops autoload, so its behavior could silently change mid-session depending on what a prior command had touched.

functions/dops.fish now defines a real dops: a formatted docker ps (custom Names/Image/Status/Ports table), with its own --help. The old docstring promised "enhanced container listing" but no such logic existed anywhere in the repo — this is newly authored.
functions/docker.fish is a new file holding the ps-redirect wrapper, fixed to call the now-real dops (previously called itself, since the still-undefined dops and the misnamed docker were the same function).
Bare docker with no arguments no longer falls through an if with no else (the fish false-zero, AGENTS.md standing gotcha #5) and silently does nothing — it now runs the real docker binary, which prints its own usage.
tests/functional.fish: updated the now-stale comment about why the help-flag check resolves the real function name instead of the file stem.

2. Cosmetic: blank line in `sponge_filter_secrets.fish`

Removed the blank line between the header comment and the function line — the only file in functions/ with that gap. No runtime effect; the renderer's tolerance for this case is left in place deliberately (documented in the commit), it's not dead code.

3. Missing `EXIT STATUS` header docs

Fills the gaps the header-help audit recorded: 16 argument-less functions gain EXIT STATUS, and 8 that already document ARGUMENTS gain it too.

Not touched: gip6, ld, parur, sudo-toggle, upgrade — the audit's "missing ARGUMENTS" group. Re-checked their bodies against that claim: none of the five take a positional argument ($argv only appears forwarded to the --help check), so an ARGUMENTS section would document something that doesn't exist. All five already have EXIT STATUS.

Verification

fish -n on every touched file.
fish tests/run-tests.fish: 317/317, including test_every_user_facing_function_has_help.
Manually exercised dops --help, docker ps (reaches the real docker socket via the new wrapper), and bare docker (now prints real usage instead of nothing).

Addresses `AGENTS/JOB-BRIEF-FINDINGS.md` (Job 3's out-of-scope findings). Based on `feat/header-driven-help` since the header-doc gaps and the help-flag exempt list only exist on that branch — merge that PR first, or merge this into it. ## 1. `dops`/`docker` split (live bug) `functions/dops.fish` defined `function docker`, not `dops`. `dops` was never defined; `docker` was only conditionally defined as a side effect of the failed `dops` autoload, so its behavior could silently change mid-session depending on what a prior command had touched. - `functions/dops.fish` now defines a real `dops`: a formatted `docker ps` (custom Names/Image/Status/Ports table), with its own `--help`. The old docstring promised "enhanced container listing" but no such logic existed anywhere in the repo — this is newly authored. - `functions/docker.fish` is a new file holding the `ps`-redirect wrapper, fixed to call the now-real `dops` (previously called itself, since the still-undefined `dops` and the misnamed `docker` were the same function). - Bare `docker` with no arguments no longer falls through an `if` with no `else` (the fish false-zero, `AGENTS.md` standing gotcha #5) and silently does nothing — it now runs the real `docker` binary, which prints its own usage. - `tests/functional.fish`: updated the now-stale comment about why the help-flag check resolves the real function name instead of the file stem. ## 2. Cosmetic: blank line in `sponge_filter_secrets.fish` Removed the blank line between the header comment and the `function` line — the only file in `functions/` with that gap. No runtime effect; the renderer's tolerance for this case is left in place deliberately (documented in the commit), it's not dead code. ## 3. Missing `EXIT STATUS` header docs Fills the gaps the header-help audit recorded: 16 argument-less functions gain `EXIT STATUS`, and 8 that already document `ARGUMENTS` gain it too. Not touched: `gip6`, `ld`, `parur`, `sudo-toggle`, `upgrade` — the audit's "missing ARGUMENTS" group. Re-checked their bodies against that claim: none of the five take a positional argument (`$argv` only appears forwarded to the `--help` check), so an `ARGUMENTS` section would document something that doesn't exist. All five already have `EXIT STATUS`. ## Verification - `fish -n` on every touched file. - `fish tests/run-tests.fish`: 317/317, including `test_every_user_facing_function_has_help`. - Manually exercised `dops --help`, `docker ps` (reaches the real docker socket via the new wrapper), and bare `docker` (now prints real usage instead of nothing).

rootiest changed target branch from feat/header-driven-help to main

2026-09-08 05:39:26 +00:00

rootiest added 3 commits 2026-09-08 05:39:26 +00:00

fix(functions): split dops.fish into dops and docker 23420b3235

dops.fish defined `docker`, not `dops`. dops was never defined; docker
was only conditionally defined as a side effect of the failed dops
autoload, so its behavior could silently change mid-session. See
JOB-BRIEF-FINDINGS.md §1.

- functions/dops.fish now defines dops: a real enhanced `docker ps`
  listing (custom Names/Image/Status/Ports table), with its own --help.
- functions/docker.fish is a new file holding the ps-redirect wrapper,
  fixed to actually call dops (previously called the still-undefined
  dops from inside itself).
- Bare `docker` with no arguments no longer falls through an
  if-with-no-else (the fish false-zero, AGENTS.md standing gotcha #5)
  and does nothing; it now runs the real docker binary, which prints
  its own usage.
- tests/functional.fish: updated the now-stale comment explaining why
  the help-flag check resolves the real function name instead of the
  file stem.

style(functions): remove blank line in sponge_filter_secrets.fish header 3aa462a2b8

The man-page comment header was separated from the function line by a
blank line -- the only file in functions/ with that gap. Cosmetic, no
runtime effect (manualtools and the help-flag renderer both tolerate
it by walking past a blank separator). See JOB-BRIEF-FINDINGS.md §2;
the renderer's tolerance for this case is left in place deliberately,
it is not dead code.

docs(functions): add missing EXIT STATUS header docs dccf897c9f

Fills the gaps recorded in JOB-BRIEF-FINDINGS.md for the functions
converted to header-driven --help: 16 argument-less functions gain an
EXIT STATUS section (check_fish_deps, claude-docs, claude-pr, cleanup,
fast, fzf-update, gip, gip4, hist, limine-edit, lock, ports,
screensleep, steam-dl, swapstat, tmux-clean), and 8 functions that
already document ARGUMENTS gain EXIT STATUS too (lD, lsr, lss, lstree,
lt, ltr, lx, qr).

Not touched: gip6, ld, parur, sudo-toggle, upgrade, the JOB-BRIEF's
'missing ARGUMENTS' group. Re-checked their bodies against that claim
-- none of the five take a positional argument ($argv only appears
forwarded to the --help check), so an ARGUMENTS section would document
something that doesn't exist. All five already have EXIT STATUS.

rootiest added 1 commit 2026-09-08 05:40:46 +00:00

Merge remote-tracking branch 'origin/main' into fix/dops-docker-and-header-gaps 6b2cc3aefc

rootiest merged commit 6679d19a09 into main

2026-09-08 05:40:57 +00:00

rootiest deleted branch fix/dops-docker-and-header-gaps

2026-09-08 05:40:58 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: rootiest/fish-config#135

fix: split dops/docker, fix header doc gaps from Job 3 findings #135

1. dops/docker split (live bug)

2. Cosmetic: blank line in sponge_filter_secrets.fish

3. Missing EXIT STATUS header docs

Verification

1. `dops`/`docker` split (live bug)

2. Cosmetic: blank line in `sponge_filter_secrets.fish`

3. Missing `EXIT STATUS` header docs