fix: bootstrap PostgreSQL without a working service manager (#823)

[GG-O-BP]

What & why

Closes #823.

mxcli run --ensure-db only tried service and Debian's pg_ctlcluster to
start local PostgreSQL. On Arch neither command exists, so bootstrap failed even
though initdb, pg_ctl, and psql were available.

Minimal fix

• Keep the existing service / pg_ctlcluster attempts.
• Confirm that an attempted service actually becomes ready; if no service does,
  fall back to a user-owned cluster under ~/.mxcli/postgres using
  initdb / pg_ctl.
• Reuse an initialized data directory and skip pg_ctl start when that cluster
  is already running, making repeated --ensure-db calls safe.
• Provision the role/database through the user-owned cluster's direct
  postgres connection, without requiring a postgres OS account or
  passwordless sudo. Keep the original sudo -u postgres psql path for system
  clusters.

Tests

Focused command-stub tests cover:

• a ready service path (including a non-zero service command exit)
• an ineffective service falling back to initdb / pg_ctl
• missing portable tools
• first initialization
• repeated invocation on an initialized/stopped cluster
• an already-running cluster
• pg_ctl start failure
• direct and sudo superuser selection

Validation:

• go build ./...
• make vet
• go test ./cmd/mxcli/docker -count=1
• real PostgreSQL 18.4 bootstrap and repeated EnsureDatabase invocation on the
  reported Arch-shaped environment

Docs

Updated the run-local skill, docs-site page, CHANGELOG, and fix-issue symptom
entry.

[ako]

Review

Sound fix, no blockers. Three things I'd want changed before merge, all localized to startLocalPostgres/startUserCluster.

What I verified — applied the two Go files to current main in a throwaway worktree (they apply cleanly):

• go vet ./cmd/mxcli/docker clean; all 12 new subtests pass in 0.5 s.
• The reported Arch path is genuinely fixed: neither service nor pg_ctlcluster is on PATH, both LookPath calls skip, and the fallback runs immediately.

---

Moderate

1. The fallback multiplies the timeout by the number of service attempts — confirmed, not theoretical.

Moving waitPGReady inside the attempts loop means every attempt pays a full 20 s. Instrumented with a scaled-down serviceReadyTimeout, counting probe invocations:

service → isready → pg_ctlcluster → isready → initdb → pg_ctl_start
ready-waits paid = 2   (at the real timeout: 40 s)

Worst case is now 20 + 20 (services) + 30 (pg_ctl -w -t 30) + 20 (EnsureDatabase's own waitPGReady) ≈ 90 s before an error surfaces, against ~20 s before. Worse, 20 s of that is spent on {"pg_ctlcluster", "--", "start"} — the entry whose own comment admits the args are a placeholder and cannot work.

Fix: drop the pg_ctlcluster placeholder, and probe inside the loop with a short timeout (2–3 s), keeping the single long waitPGReady where it already is in EnsureDatabase.

2. --auth-host=trust disables authentication on 127.0.0.1:5432.

Confirmed via the initdb args: -U postgres --auth-local=trust --auth-host=trust. The comment justifies it with "the server binds only the local interface", but loopback is not an access control on a multi-user host: any local account becomes the postgres superuser, and PostgreSQL superuser gets COPY … PROGRAM, i.e. shell as the developer's OS user.

Fix: the socket directory is already 0700 (verified — drwx------), so trust over the socket is genuinely safe. Keep --auth-local=trust, set --auth-host=scram-sha-256, and point superuser.psql's non-sudo branch at -h <sockDir> instead of -h 127.0.0.1. The app role already has a password, so canConnectDB over TCP still works unchanged.

3. The fix-issue.md row lands mid-table.

The hunk inserts at line ~322; on current main that table ends at line 429. .gitattributes sets merge=union on that file — which keeps both sides of a conflicting hunk, so a mid-table insert against a moved table interleaves and merges "cleanly" while being wrong. The branch predates the append-at-the-end rule.

Fix: rebase and move the row to the end of the table.

Minor

• --db-host ":5432" produces a malformed server option. isLocalHost("") is true, so an empty host reaches -o "-h -p 5432 -k …"; pg_ctl splits on whitespace and postmaster reads -p as the value of -h. Confirmed in a probe. Obscure (the default fills in 127.0.0.1:5432), but a one-line guard in startUserCluster would close it.
• pg_ctl status == 0 returns early without checking the port. A cluster left running from an earlier --ensure-db --db-port 5433 satisfies status, then EnsureDatabase burns 20 s on waitPGReady against the wrong port and reports a confusing failure. Reading the port from line 4 of postmaster.pid would make it precise.
• The server log path isn't in the error. startUserCluster writes -l ~/.mxcli/postgres/server.log, but the failure message carries only pg_ctl's stdout. Naming the log file makes the error self-service.
• Service-manager output is now fully discarded (_ = exec.Command(…).Run()). If service postgresql start explains itself, the user instead sees an initdb error from two steps later.

Checklist

Bug-fix requirements met: symptom row added, tests accompany the fix, .claude/skills/mendix/run-local.md (the sync source, not the regenerated cmd/mxcli/skills/ embed dir — correct choice), the docs-site page, and the CHANGELOG all updated. Single concern, single commit.

The mdl-examples/bug-tests/ requirement is the only apparent checklist gap and is correctly N/A — there's no MDL surface here and nothing for Studio Pro to validate. The backend-abstraction, grammar, and syntax/features_*.go sections don't apply either.

Thanks for the thorough stub-test coverage — the ready/non-ready service split and the idempotency cases are exactly the right seams to pin down.

🤖 Generated with Claude Code