From 23420b3235ff361d84cd8b6fd2cb85f81557d304 Mon Sep 17 00:00:00 2001
From: Rootiest <chris@rootiest.com>
Date: Tue, 8 Sep 2026 01:11:49 -0400
Subject: [PATCH] fix(functions): split dops.fish into dops and docker
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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.
---
 functions/docker.fish | 41 +++++++++++++++++++++++++++++++++++++++++
 functions/dops.fish   | 33 +++++++++++++++++----------------
 tests/functional.fish |  5 +++--
 3 files changed, 61 insertions(+), 18 deletions(-)
 create mode 100644 functions/docker.fish

diff --git a/functions/docker.fish b/functions/docker.fish
new file mode 100644
index 0000000..52c3115
--- /dev/null
+++ b/functions/docker.fish
@@ -0,0 +1,41 @@
+# Copyright (C) 2026 Rootiest
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# CATEGORY
+#   12-ai-and-developer-tools
+#
+# DEPENDENCIES
+#   dops
+#
+# SYNOPSIS
+#   docker [subcommand] [args...]
+#
+# DESCRIPTION
+#   Wrapper for docker that intercepts the ps subcommand and redirects it to
+#   the dops function for enhanced container listing. All other subcommands,
+#   and a bare invocation with no subcommand, are passed through to the real
+#   docker binary.
+#
+# ARGUMENTS
+#   subcommand  Docker subcommand (ps is redirected to dops)
+#   args...     Arguments forwarded to docker or dops
+#
+# EXIT STATUS
+#   Exit status of dops (for ps), or of the real docker binary otherwise
+#
+# EXAMPLE
+#   docker ps
+#   docker
+function docker --description 'Execute docker, redirecting ps to the enhanced dops listing'
+    if test -z "$argv[1]"
+        command docker
+        return
+    end
+
+    switch $argv[1]
+        case ps
+            dops $argv[2..-1]
+        case '*'
+            command docker $argv[1..-1]
+    end
+end
diff --git a/functions/dops.fish b/functions/dops.fish
index 36703a4..b1b5422 100644
--- a/functions/dops.fish
+++ b/functions/dops.fish
@@ -4,27 +4,28 @@
 # CATEGORY
 #   12-ai-and-developer-tools
 #
+# DEPENDENCIES
+#   docker
+#
 # SYNOPSIS
-#   docker [subcommand] [args...]
+#   dops [args...]
 #
 # DESCRIPTION
-#   Wrapper for docker that intercepts the ps subcommand and redirects it to
-#   the dops function for enhanced container listing. All other subcommands are
-#   passed through to the real docker binary.
+#   Enhanced container listing: runs docker ps with a clean custom table
+#   (Names, Image, Status, Ports) instead of docker's noisier default
+#   columns. Extra arguments (e.g. -a) are forwarded to docker ps.
 #
 # ARGUMENTS
-#   subcommand  Docker subcommand (ps is redirected to dops)
-#   args...     Arguments forwarded to docker or dops
+#   args...  Arguments forwarded to `docker ps`
+#
+# EXIT STATUS
+#   Exit status of `docker ps`
 #
 # EXAMPLE
-#   docker ps
-function docker --description 'Execute docker'
-    if test -n "$argv[1]"
-        switch $argv[1]
-            case ps
-                dops $argv[2..-1]
-            case '*'
-                command docker $argv[1..-1]
-        end
-    end
+#   dops
+#   dops -a
+function dops --description 'Enhanced, formatted docker ps listing'
+    __fish_help_header (status current-function) $argv; and return 0
+
+    command docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}' $argv
 end
diff --git a/tests/functional.fish b/tests/functional.fish
index 759188b..beb73bf 100644
--- a/tests/functional.fish
+++ b/tests/functional.fish
@@ -316,8 +316,9 @@ function test_every_user_facing_function_has_help
         # Published == carries a `# CATEGORY` block, matching
         # manualtools.parse_functions.
         contains -- "# CATEGORY" (string trim -- $lines); or continue
-        # Resolve the real defined name; the file stem can disagree
-        # (dops.fish defines `docker` -- see JOB-BRIEF-FINDINGS.md §1).
+        # Resolve the real defined name; the file stem can disagree with it
+        # (formerly dops.fish defined `docker` -- see JOB-BRIEF-FINDINGS.md
+        # §1, fixed by splitting it into dops.fish and docker.fish).
         set -l name (string match -rg '^\s*function\s+(\S+)' -- $lines)[1]
         test -n "$name"; or continue
         set name (string trim -c "'\"" -- $name)