refactor: add pg_autoctl inspect and manual sub-command groups

Reorganise the operator-facing commands to make the binary more
approachable without the PG_AUTOCTL_DEBUG environment variable gate:

pg_autoctl inspect — read-only diagnostics, always visible
  inspect pgsetup   local PostgreSQL setup inspection
  inspect fsm       FSM state / list / graphviz (read-only subset)
  inspect monitor   get primary/others/candidate-count, parse-notification
  inspect show      ipaddr, cidr, lookup, hostname, reverse

pg_autoctl manual — operator-driven FSM operations for manual recovery
  manual fsm        assign / step / nodes get+set
  manual service    restart postgres|listener|node-active; pgctl on|off
  manual monitor    register / active / version
  manual coordinator add / activate / remove / update

Both groups are always visible regardless of PG_AUTOCTL_DEBUG.
PG_AUTOCTL_DEBUG now only controls log verbosity, not command visibility.

Implementation details:
- Add bool hidden field to CommandLine struct so make_hidden_command_set
  can register the internal sub-process entry points (pg_autoctl internal
  service postgres|listener|node-active) without surfacing them in --help
- The supervisor now spawns pg_autoctl internal service ... instead of
  the old pg_autoctl do service ... path; pg_autoctl do is trimmed to
  tmux and demo tooling only
- Python test helpers updated to use inspect/manual in place of do

Documentation:
- Add docs/ref/pg_autoctl_inspect.rst and pg_autoctl_inspect_pgsetup.rst,
  pg_autoctl_inspect_show.rst
- Add docs/ref/pg_autoctl_manual.rst and pg_autoctl_manual_service_restart.rst
- Trim docs/ref/pg_autoctl_do.rst to tmux/demo only; remove superseded
  pg_autoctl_do_pgsetup.rst, pg_autoctl_do_service_restart.rst,
  pg_autoctl_do_show.rst
- Update failover-state-machine.rst: pg_autoctl inspect fsm gv (no longer
  requires PG_AUTOCTL_DEBUG)

Author: dimitri

docs/failover-state-machine.rst

@@ -277,10 +277,10 @@ command, and then the node entry is removed from the monitor.
 pg_auto_failover keeper's State Machine
 ---------------------------------------
 
-When built in TEST mode, it is then possible to use the following command to
-get a visual representation of the Keeper's Finite State Machine::
+It is possible to use the following command to get a visual representation
+of the Keeper's Finite State Machine::
 
-  $ PG_AUTOCTL_DEBUG=1 pg_autoctl do fsm gv | dot -Tsvg > fsm.svg
+  $ pg_autoctl inspect fsm gv | dot -Tsvg > fsm.svg
 
 The `dot` program is part of the Graphviz suite and produces the following
 output:

docs/ref/manual.rst

@@ -20,6 +20,8 @@ have their own manual page.
    pg_autoctl_get
    pg_autoctl_set
    pg_autoctl_perform
+   pg_autoctl_inspect
+   pg_autoctl_manual
    pg_autoctl_do
    pg_autoctl_run
    pg_autoctl_watch

docs/ref/pg_autoctl_do.rst

@@ -3,121 +3,24 @@
 pg_autoctl do
 =============
 
-pg_autoctl do - Internal commands and internal QA tooling
+pg_autoctl do - Internal QA tooling (tmux sessions, demo app)
 
-The debug commands for ``pg_autoctl`` are only available when the
-environment variable ``PG_AUTOCTL_DEBUG`` is set (to any value).
-
-When testing pg_auto_failover, it is helpful to be able to play with the
-local nodes using the same lower-level API as used by the pg_auto_failover
-Finite State Machine transitions. Some commands could be useful in contexts
-other than pg_auto_failover development and QA work, so some documentation
-has been made available.
+The ``pg_autoctl do`` command group contains development and QA tooling that
+is not intended for production use. For read-only diagnostics see
+:ref:`pg_autoctl_inspect`; for manual cluster recovery operations see
+:ref:`pg_autoctl_manual`.
 
 .. toctree::
    :maxdepth: 1
 
    pg_autoctl_do_tmux
    pg_autoctl_do_demo
-   pg_autoctl_do_service_restart
-   pg_autoctl_do_show
-   pg_autoctl_do_pgsetup
 
-The low-level API is made available through the following ``pg_autoctl do``
-commands, only available in debug environments::
+``pg_autoctl do`` provides the following commands::
 
     pg_autoctl do
-    + monitor  Query a pg_auto_failover monitor
-    + fsm      Manually manage the keeper's state
-    + primary  Manage a PostgreSQL primary server
-    + standby  Manage a PostgreSQL standby server
-    + show     Show some debug level information
-    + pgsetup  Manage a local Postgres setup
-    + pgctl    Signal the pg_autoctl postgres service
-    + service  Run pg_autoctl sub-processes (services)
-    + tmux     Set of facilities to handle tmux interactive sessions
-    + demo     Use a demo application for pg_auto_failover
-
-    pg_autoctl do monitor
-    + get                 Get information from the monitor
-      register            Register the current node with the monitor
-      active              Call in the pg_auto_failover Node Active protocol
-      version             Check that monitor version is 1.5.0.1; alter extension update if not
-      parse-notification  parse a raw notification message
-
-    pg_autoctl do monitor get
-      primary      Get the primary node from pg_auto_failover in given formation/group
-      others       Get the other nodes from the pg_auto_failover group of hostname/port
-      coordinator  Get the coordinator node from the pg_auto_failover formation
-
-    pg_autoctl do fsm
-      init    Initialize the keeper's state on-disk
-      state   Read the keeper's state from disk and display it
-      list    List reachable FSM states from current state
-      gv      Output the FSM as a .gv program suitable for graphviz/dot
-      assign  Assign a new goal state to the keeper
-      step    Make a state transition if instructed by the monitor
-    + nodes   Manually manage the keeper's nodes list
-
-    pg_autoctl do fsm nodes
-      get  Get the list of nodes from file (see --disable-monitor)
-      set  Set the list of nodes to file (see --disable-monitor)
-
-    pg_autoctl do primary
-    + slot      Manage replication slot on the primary server
-    + adduser   Create users on primary
-      defaults  Add default settings to postgresql.conf
-      identify  Run the IDENTIFY_SYSTEM replication command on given host
-
-    pg_autoctl do primary slot
-      create  Create a replication slot on the primary server
-      drop    Drop a replication slot on the primary server
-
-    pg_autoctl do primary adduser
-      monitor  add a local user for queries from the monitor
-      replica  add a local user with replication privileges
-
-    pg_autoctl do standby
-      init     Initialize the standby server using pg_basebackup
-      rewind   Rewind a demoted primary server using pg_rewind
-      promote  Promote a standby server to become writable
-
-    pg_autoctl do show
-      ipaddr    Print this node's IP address information
-      cidr      Print this node's CIDR information
-      lookup    Print this node's DNS lookup information
-      hostname  Print this node's default hostname
-      reverse   Lookup given hostname and check reverse DNS setup
-
-    pg_autoctl do pgsetup
-      pg_ctl    Find a non-ambiguous pg_ctl program and Postgres version
-      discover  Discover local PostgreSQL instance, if any
-      ready     Return true is the local Postgres server is ready
-      wait      Wait until the local Postgres server is ready
-      logs      Outputs the Postgres startup logs
-      tune      Compute and log some Postgres tuning options
-
-    pg_autoctl do pgctl
-      on   Signal pg_autoctl postgres service to ensure Postgres is running
-      off  Signal pg_autoctl postgres service to ensure Postgres is stopped
-
-    pg_autoctl do service
-    + getpid        Get the pid of pg_autoctl sub-processes (services)
-    + restart       Restart pg_autoctl sub-processes (services)
-      pgcontroller  pg_autoctl supervised postgres controller
-      postgres      pg_autoctl service that start/stop postgres when asked
-      listener      pg_autoctl service that listens to the monitor notifications
-      node-active   pg_autoctl service that implements the node active protocol
-
-    pg_autoctl do service getpid
-      postgres     Get the pid of the pg_autoctl postgres controller service
-      listener     Get the pid of the pg_autoctl monitor listener service
-      node-active  Get the pid of the pg_autoctl keeper node-active service
-
-    pg_autoctl do service restart
-      postgres     Restart the pg_autoctl postgres controller service
-      listener     Restart the pg_autoctl monitor listener service
-      node-active  Restart the pg_autoctl keeper node-active service
+    + tmux  Set of facilities to handle tmux interactive sessions
+    + demo  Use a demo application for pg_auto_failover
 
     pg_autoctl do tmux
       script   Produce a tmux script for a demo or a test case (debug only)