feat(provision): accept a unix socket host

[mrcsin]

semibase could not connect over a unix socket, which blocks its intended container use.

Options.connect built a connection string as a url.URL whose authority came from net.JoinHostPort. A socket directory is a filesystem path, and its slashes are not valid in a URL authority — url.Parse rejects the result with invalid URL escape "%2F" before any network call happens.

That matters because of how the official postgres image works. Its entrypoint starts a temporary server with listen_addresses empty — no TCP at all — and runs everything in /docker-entrypoint-initdb.d/ against it over the socket. So semibase create could not run as an init script, which is exactly what SemiPlot's test bench needs in order to have one container provision itself before its port opens.

What changed

A socket host now goes into the URL's host query parameter instead of the authority: postgres://user:pass@/db?host=%2Fvar%2Frun%2Fpostgresql&port=5432. The TCP string is byte-identical to what it was — hostnames, IP literals, IPv6 in brackets, non-default ports.

Socket detection matches pgconn.isAbsolutePath clause for clause, including its quirk of requiring an upper-case Windows drive letter, so this tool and the driver never disagree about what a socket host is. The @ abstract-namespace form is deliberately excluded: measured against the pinned pgx, pgconn.NetworkAddress("@abstract", 5432) returns tcp, so pgx has no abstract-socket support and routing @ into the host parameter would advertise something that does not exist.

The error and "Done" messages name the socket file rather than a host:port that was never dialled.

Verification

The mechanism was proven end to end before this PR was opened, not argued:

• A container built from postgres:17-alpine with this binary in /docker-entrypoint-initdb.d/ provisions over the socket. docker logs shows the temp server listening on the Unix socket with no TCP line, then create completing.
• Provisioned before the port opens: a poller started ahead of the database, connecting as semiplot_reader every 100 ms, never once saw role does not exist or database does not exist. The first connection that authenticated already saw the complete result.
• Negative control: the same image built from master's binary fails with invalid URL escape "%2F", the container exits 1, and the port never opens.
• Fail-closed proven, not assumed: re-running with a deliberately wrong --expected-major exits 1 and the port stays shut.

CI gains a step that runs that same recipe, so the motivating path is covered rather than only its string construction. The step was executed locally against Docker 29.7.2 before being written into the workflow; no GitHub Actions run has been observed yet.

TestConnectionStringIsDialedAsTheRightNetwork asserts pgconn.NetworkAddress yields unix for the socket form and tcp for TCP — the property that matters, rather than a golden string copy-pasted from the implementation.

Notes for the consumer

Facts measured while proving this, which SemiPlot's Dockerfile will need:

• socket directory /var/run/postgresql; init scripts run as postgres, uid 70, cwd /
• superuser auth during init is local trust; no super password needed
• init scripts run only on an empty PGDATA, so a reused volume skips them entirely
• docker-proxy binds the published host port immediately, so a raw TCP-connect readiness probe is a false positive — probe with pg_isready or a real query
• the entrypoint sources a non-executable .sh rather than running it, so the init script must be executable or set -e and exec inside it would hijack the entrypoint process

🤖 Generated with Claude Code