@hyperfixation/cli 0.1.1 → 0.1.2

package/dist/checklist.js

@@ -13,7 +13,7 @@ export function checklistLines(input) {
         lines.push(`  - ${parts[0]}`, ...parts.slice(1).map((part) => `      ${part}`), "");
     };
     if (input.providerKeysSent.length === 0) {
-        add("The app is serving FIXTURE drafts: no ANTHROPIC_API_KEY or OPENAI_API_KEY was configured,", "so llm.run returns canned text and /api/status reports llm.mode=fixtures. Paste a key", "into Coolify's environment for this application and redeploy.");
+        add("The app is serving FIXTURE drafts: no ANTHROPIC_API_KEY or OPENAI_API_KEY was configured,", "so llm.run returns canned text. /api/status reports llm.mode=fixtures once the app's", "worker has reported the mode — until then, and on a core older than 0.1.1, it says", "unknown. Paste a key into Coolify's environment for this application and redeploy.");
     }
     add("Third-party keys go into Coolify's environment for this application — and every new name", "also has to be added to REQUIRED_ENV (src/env.ts), .env.example and all three", "environment: blocks of docker-compose.prod.yml. A name Coolify carries that compose does", "not interpolate never reaches a container, and hf new refuses the next run until they agree.");
     add(`Metabase reads through ${roleNames(names.appName).readonly}:`, `postgres://${roleNames(names.appName).readonly}:<password>@${input.dbHost}:5432/${names.databaseName}`, `the password is database.readonlyPassword in ${input.stateFile}.`);

package/dist/cloud-steps/coolify.d.ts

@@ -24,6 +24,14 @@ export declare const CONTAINER_PROVIDED_ENV: readonly ["HF_PROCESS", "HF_BUILD_S
  * checklist is what says it out loud.
  */
 export declare const OPTIONAL_PROVIDER_ENV: readonly ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"];
+/**
+ * The three `hf new` omits when the `langfuse` step provisioned no keys.
+ *
+ * All three or none: the template's gate — `instrumentation.ts` in the web, `startWorker()` in the
+ * worker — registers the span processor only when none of them is empty, so a base URL on its own
+ * configures nothing and only reads as though it did.
+ */
+export declare const OPTIONAL_LANGFUSE_ENV: readonly ["LANGFUSE_BASE_URL", "LANGFUSE_PUBLIC_KEY", "LANGFUSE_SECRET_KEY"];
 /**
  * The app's environment and what `docker-compose.prod.yml` interpolates have diverged.
  *
@@ -49,12 +57,14 @@ export declare function neededEnvNames(dir: string): Promise<string[]>;
 /**
  * Refuses to PATCH an environment that is not the one the compose file needs.
  *
- * A provider key the operator has not configured is deliberately absent rather than missing, so it
- * is excused here and reported in the checklist instead.
+ * A provider key the operator has not configured, and the three Langfuse variables when the step
+ * provisioned no keys, are deliberately absent rather than missing: each is excused here and
+ * reported in the checklist instead.
  */
 export declare function assertEnvsMatchCompose(dir: string, sent: readonly string[]): Promise<void>;
 /**
- * The twelve variables the deployed app runs on, or ten when no provider key is configured.
+ * The twelve variables the deployed app runs on, less any of the five optional ones — the two
+ * provider keys and the three Langfuse variables — that nothing provisioned.
  *
  * Generates `BETTER_AUTH_SECRET` on first sight and records it: it is the one value in the list
  * that no provider hands back, so a run that did not persist it would lock every existing session

package/dist/cloud-steps/coolify.js

@@ -27,6 +27,18 @@ export const CONTAINER_PROVIDED_ENV = ["HF_PROCESS", "HF_BUILD_SHA"];
  * checklist is what says it out loud.
  */
 export const OPTIONAL_PROVIDER_ENV = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"];
+/**
+ * The three `hf new` omits when the `langfuse` step provisioned no keys.
+ *
+ * All three or none: the template's gate — `instrumentation.ts` in the web, `startWorker()` in the
+ * worker — registers the span processor only when none of them is empty, so a base URL on its own
+ * configures nothing and only reads as though it did.
+ */
+export const OPTIONAL_LANGFUSE_ENV = [
+    "LANGFUSE_BASE_URL",
+    "LANGFUSE_PUBLIC_KEY",
+    "LANGFUSE_SECRET_KEY",
+];
 /** Which operator key carries each of them, in `REQUIRED_ENV` order. */
 const PROVIDER_ENV_SOURCE = [
     ["ANTHROPIC_API_KEY", "HF_ANTHROPIC_API_KEY"],
@@ -88,20 +100,22 @@ export async function neededEnvNames(dir) {
 /**
  * Refuses to PATCH an environment that is not the one the compose file needs.
  *
- * A provider key the operator has not configured is deliberately absent rather than missing, so it
- * is excused here and reported in the checklist instead.
+ * A provider key the operator has not configured, and the three Langfuse variables when the step
+ * provisioned no keys, are deliberately absent rather than missing: each is excused here and
+ * reported in the checklist instead.
  */
 export async function assertEnvsMatchCompose(dir, sent) {
     const needed = await neededEnvNames(dir);
     const sentNames = new Set(sent);
-    const optional = new Set(OPTIONAL_PROVIDER_ENV);
+    const optional = new Set([...OPTIONAL_PROVIDER_ENV, ...OPTIONAL_LANGFUSE_ENV]);
     const missing = needed.filter((name) => !sentNames.has(name) && !optional.has(name));
     const extra = sent.filter((name) => !needed.includes(name));
     if (missing.length > 0 || extra.length > 0)
         throw new EnvDrift(missing, extra);
 }
 /**
- * The twelve variables the deployed app runs on, or ten when no provider key is configured.
+ * The twelve variables the deployed app runs on, less any of the five optional ones — the two
+ * provider keys and the three Langfuse variables — that nothing provisioned.
  *
  * Generates `BETTER_AUTH_SECRET` on first sight and records it: it is the one value in the list
  * that no provider hands back, so a run that did not persist it would lock every existing session
@@ -136,10 +150,12 @@ export async function buildAppEnvs(context) {
         { key: "SMTP_URL", value: config.HF_SMTP_URL },
         { key: "EMAIL_FROM", value: config.HF_EMAIL_FROM },
         { key: "SENTRY_DSN", value: context.state.state.sentryDsn ?? "" },
-        { key: "LANGFUSE_BASE_URL", value: config.HF_LANGFUSE_URL },
-        { key: "LANGFUSE_PUBLIC_KEY", value: langfuse.publicKey ?? "" },
-        { key: "LANGFUSE_SECRET_KEY", value: langfuse.secretKey ?? "" },
     ];
+    // Omitted outright when the langfuse step reused nothing and created nothing: an empty trio
+    // would deploy the same telemetry — none — while reading as configured in Coolify's UI.
+    if (langfuse.publicKey !== undefined && langfuse.secretKey !== undefined) {
+        envs.push({ key: "LANGFUSE_BASE_URL", value: config.HF_LANGFUSE_URL }, { key: "LANGFUSE_PUBLIC_KEY", value: langfuse.publicKey }, { key: "LANGFUSE_SECRET_KEY", value: langfuse.secretKey });
+    }
     for (const [key, value] of providerKeys(context.config))
         envs.push({ key, value });
     return envs;

package/dist/cloud-steps/langfuse.d.ts

@@ -8,5 +8,10 @@ import type { CloudStepContext } from "./context.js";
  * once, at creation, and the only copy is the state file this run may not have — so a new key is
  * created and the old ones keep working, which costs an unused key and never an app that cannot
  * authenticate.
+ *
+ * Creating a project needs an organization-scoped key, which is a paid-plan feature: without one
+ * the step falls back to the project key pair the operator configured, and without that to a
+ * warning. Both fallbacks record the step — an app with no tracing is a deployed app, and only
+ * the operator can decide otherwise.
  */
 export declare const langfuseStep: Step<CloudStepContext>;

package/dist/cloud-steps/langfuse.js

@@ -2,6 +2,12 @@ import { requireOperatorConfig } from "../config.js";
 import { LangfuseClient } from "../providers/langfuse.js";
 /** Langfuse keeps data indefinitely at 0, and any other value needs a paid entitlement. */
 const RETENTION_DAYS = 0;
+/** Said in the warning and again in the closing checklist, so neither run nor log has to be read. */
+const NOT_CONFIGURED = "Langfuse tracing is not configured: neither HF_LANGFUSE_ORG_KEY nor an " +
+    "HF_LANGFUSE_PUBLIC_KEY/HF_LANGFUSE_SECRET_KEY pair is set, so LANGFUSE_BASE_URL, " +
+    "LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY were not sent to Coolify and the app records no " +
+    "traces. To add them later, take a project's key pair from Langfuse → project settings → API " +
+    "keys, set all three in Coolify's environment for this application, and redeploy.";
 /**
  * The app's Langfuse project and a key pair for it.
  *
@@ -10,11 +16,20 @@ const RETENTION_DAYS = 0;
  * once, at creation, and the only copy is the state file this run may not have — so a new key is
  * created and the old ones keep working, which costs an unused key and never an app that cannot
  * authenticate.
+ *
+ * Creating a project needs an organization-scoped key, which is a paid-plan feature: without one
+ * the step falls back to the project key pair the operator configured, and without that to a
+ * warning. Both fallbacks record the step — an app with no tracing is a deployed app, and only
+ * the operator can decide otherwise.
  */
 export const langfuseStep = {
     name: "langfuse",
     run: async (context) => {
         const { names } = context;
+        if ((context.config.HF_LANGFUSE_ORG_KEY ?? "") === "") {
+            await reuseOrSkip(context);
+            return;
+        }
         const required = requireOperatorConfig(context.config, ["HF_LANGFUSE_URL", "HF_LANGFUSE_ORG_KEY"], { env: context.env });
         const langfuse = new LangfuseClient({
             url: required.HF_LANGFUSE_URL,
@@ -33,3 +48,24 @@ export const langfuseStep = {
         });
     },
 };
+/**
+ * The two paths without an org key: the operator's own project key pair, or nothing.
+ *
+ * No request either way — a project-scoped pair cannot list or create projects, so there is
+ * nothing to ask Langfuse that would not fail.
+ */
+async function reuseOrSkip(context) {
+    const { names, config } = context;
+    const publicKey = config.HF_LANGFUSE_PUBLIC_KEY ?? "";
+    const secretKey = config.HF_LANGFUSE_SECRET_KEY ?? "";
+    if (publicKey === "" || secretKey === "") {
+        context.io.out(`WARNING: ${names.given}: ${NOT_CONFIGURED}`);
+        context.checklist.push(NOT_CONFIGURED);
+        return;
+    }
+    // The public key names the project without being a secret, which is the only identifier this
+    // path has: nothing here may ask Langfuse what the project is called.
+    context.io.out(`${names.given}: reusing the configured Langfuse project keys (${publicKey}) — every app ` +
+        "configured with them traces into that one project");
+    await context.state.patch({ langfuse: { publicKey, secretKey } });
+}

package/dist/cloud-steps/repo.js

@@ -4,6 +4,14 @@ import { ProviderError } from "../providers/http.js";
 import { gitHead, mustRun, short, StepFailed } from "./context.js";
 /** One page of installations, and of an installation's repositories. */
 const PER_PAGE = 100;
+/**
+ * What GitHub answers a token that may not list installations.
+ *
+ * `GET /user/installations` is documented as a GitHub App user-to-server endpoint, so every
+ * classic PAT, fine-grained PAT and OAuth token — which is what `HF_GITHUB_TOKEN` is — is refused:
+ * 403 for a `gh` OAuth token, and 401/404 for the other ways a token can be told no.
+ */
+const CANNOT_LIST = new Set([401, 403, 404]);
 /**
  * The token reaches `git` through the child's environment alone.
  *
@@ -85,7 +93,7 @@ export const repoStep = {
                 env: gitAuthEnv(required.HF_GITHUB_TOKEN),
             });
         }
-        await assertAppsInstalled(github, githubAppSlugs(context.config), fullName);
+        await checkAppsInstalled(context, github, githubAppSlugs(context.config), fullName);
         await context.state.patch({ repo: fullName });
     },
 };
@@ -95,9 +103,25 @@ export const repoStep = {
  * Coolify cannot deploy from a repository its GitHub App cannot see, and that failure otherwise
  * surfaces as a deployment that clones nothing — so it is asserted here, by name, with the URL
  * that fixes it.
+ *
+ * Unless the token may not ask at all, which is the usual case: then this degrades to a warning
+ * and a checklist line, because the repository has already been created and pushed and there is no
+ * second way to read a personal account's installations (organizations have
+ * `GET /orgs/{org}/installations`; personal accounts have nothing).
  */
-async function assertAppsInstalled(github, slugs, fullName) {
-    const installations = await allInstallations(github);
+async function checkAppsInstalled(context, github, slugs, fullName) {
+    let installations;
+    try {
+        installations = await allInstallations(github);
+    }
+    catch (error) {
+        if (!(error instanceof ProviderError) || !CANNOT_LIST.has(error.status))
+            throw error;
+        const note = unverifiedNote(slugs, fullName, error.status);
+        context.io.out(`WARNING: ${context.names.given}: ${note}`);
+        context.checklist.push(note);
+        return;
+    }
     for (const slug of slugs) {
         const installation = installations.find((candidate) => candidate.app_slug === slug);
         if (installation === undefined) {
@@ -110,6 +134,17 @@ async function assertAppsInstalled(github, slugs, fullName) {
         }
     }
 }
+/** The one thing left to the operator when the installations could not be listed. */
+function unverifiedNote(slugs, fullName, status) {
+    const apps = slugs
+        .map((slug) => `${slug} (https://github.com/apps/${slug}/installations/new)`)
+        .join(", ");
+    return (`the GitHub App installations on ${fullName} could not be verified with this token — ` +
+        `listing them needs a GitHub App user-to-server token and GitHub answered HTTP ` +
+        `${String(status)}. Check by hand that each of these is installed on the repository, or on ` +
+        `All repositories: ${apps}. Coolify's first deploy clones an empty repository if its app ` +
+        `cannot see this one.`);
+}
 async function allInstallations(github) {
     const found = [];
     for (let page = 1;; page += 1) {

package/dist/config.d.ts

@@ -3,7 +3,7 @@
  * overrides it. One flat list of names, no nesting: these are pasted in from account pages, and
  * a shape is one more thing to get wrong.
  */
-export declare const CONFIG_KEYS: readonly ["HF_COOLIFY_URL", "HF_COOLIFY_TOKEN", "HF_COOLIFY_SERVER_UUID", "HF_COOLIFY_GITHUB_APP_UUID", "HF_COOLIFY_POSTGRES_UUID", "HF_DB_HOST_INTERNAL", "HF_SSH_HOST", "HF_CLOUDFLARE_TOKEN", "HF_CLOUDFLARE_ZONE_ID", "HF_BASE_DOMAIN", "HF_GITHUB_TOKEN", "HF_GITHUB_OWNER", "HF_GITHUB_APP_SLUGS", "HF_SENTRY_TOKEN", "HF_SENTRY_ORG", "HF_LANGFUSE_URL", "HF_LANGFUSE_ORG_KEY", "HF_BOX_IP", "HF_SMTP_URL", "HF_EMAIL_FROM", "HF_ANTHROPIC_API_KEY", "HF_OPENAI_API_KEY"];
+export declare const CONFIG_KEYS: readonly ["HF_COOLIFY_URL", "HF_COOLIFY_TOKEN", "HF_COOLIFY_SERVER_UUID", "HF_COOLIFY_GITHUB_APP_UUID", "HF_COOLIFY_POSTGRES_UUID", "HF_DB_HOST_INTERNAL", "HF_DB_CONTAINER", "HF_PG_ADMIN_USER", "HF_SSH_HOST", "HF_CLOUDFLARE_TOKEN", "HF_CLOUDFLARE_ZONE_ID", "HF_BASE_DOMAIN", "HF_GITHUB_TOKEN", "HF_GITHUB_OWNER", "HF_GITHUB_APP_SLUGS", "HF_SENTRY_TOKEN", "HF_SENTRY_ORG", "HF_LANGFUSE_URL", "HF_LANGFUSE_ORG_KEY", "HF_LANGFUSE_PUBLIC_KEY", "HF_LANGFUSE_SECRET_KEY", "HF_BOX_IP", "HF_SMTP_URL", "HF_EMAIL_FROM", "HF_ANTHROPIC_API_KEY", "HF_OPENAI_API_KEY"];
 export type ConfigKey = (typeof CONFIG_KEYS)[number];
 /** What the operator has configured. Every key is optional until a command asks for it. */
 export type OperatorConfig = Partial<Record<ConfigKey, string>>;
@@ -44,6 +44,18 @@ export declare function loadOperatorConfig(options?: LoadOperatorConfigOptions):
  * got, and an operator who fixes one key per run pays for a partly-provisioned app each time.
  */
 export declare function requireOperatorConfig<Key extends ConfigKey>(config: OperatorConfig, keys: readonly Key[], options?: LoadOperatorConfigOptions): Record<Key, string>;
+/** What `HF_PG_ADMIN_USER` defaults to: the role a stock Postgres image creates. */
+export declare const DEFAULT_PG_ADMIN_USER = "postgres";
+/** The cluster superuser to log in as — Coolify's `POSTGRES_USER`, which need not be `postgres`. */
+export declare function pgAdminUser(config: OperatorConfig): string;
+/**
+ * What Coolify may have called the Postgres container on the box, in the order to try them.
+ *
+ * A standalone Postgres resource runs in a container named for the bare uuid; a database attached
+ * to a service gets `postgresql-<uuid>`. Both are asked about rather than one being guessed at,
+ * and `HF_DB_CONTAINER` replaces the pair outright. Empty when neither key is set.
+ */
+export declare function postgresContainers(config: OperatorConfig): readonly string[];
 /**
  * `HF_GITHUB_APP_SLUGS` as a list: split on commas, trimmed, empties dropped.
  *

package/dist/config.js

@@ -17,6 +17,15 @@ export const CONFIG_KEYS = [
     // names the container after the database's uuid, so `HF_COOLIFY_POSTGRES_UUID` is the default a
     // caller falls back to, and this is how a box that disagrees is told to us rather than guessed.
     "HF_DB_HOST_INTERNAL",
+    // The Postgres container's name on the box, which is what `docker inspect` is asked about when
+    // the box's loopback has no 5432 listener. Coolify names it for the bare uuid or
+    // `postgresql-<uuid>` depending on how the database was created, so `postgresContainers()`
+    // derives both from `HF_COOLIFY_POSTGRES_UUID` and this replaces the pair.
+    "HF_DB_CONTAINER",
+    // The cluster superuser to log in as. Coolify creates the cluster with its own `POSTGRES_USER`,
+    // and on the X1 box that role is not `postgres` — `psql -U postgres` there fails with
+    // `role "postgres" does not exist`. The password stays in `PGPASSWORD`, never in this file.
+    "HF_PG_ADMIN_USER",
     "HF_SSH_HOST",
     "HF_CLOUDFLARE_TOKEN",
     "HF_CLOUDFLARE_ZONE_ID",
@@ -29,7 +38,14 @@ export const CONFIG_KEYS = [
     "HF_SENTRY_TOKEN",
     "HF_SENTRY_ORG",
     "HF_LANGFUSE_URL",
+    // Optional, and all three are: an organization-scoped key pair creates the app its own project,
+    // but it is a paid-plan feature, so a Hobby account instead names an existing project's key pair
+    // here and every app it provisions traces into that one project. With none of them set the
+    // langfuse step records nothing and the three LANGFUSE_* variables are omitted rather than sent
+    // empty — an empty value in Coolify's UI reads as configured.
     "HF_LANGFUSE_ORG_KEY",
+    "HF_LANGFUSE_PUBLIC_KEY",
+    "HF_LANGFUSE_SECRET_KEY",
     "HF_BOX_IP",
     "HF_SMTP_URL",
     "HF_EMAIL_FROM",
@@ -118,6 +134,27 @@ export function requireOperatorConfig(config, keys, options = {}) {
     }
     return required;
 }
+/** What `HF_PG_ADMIN_USER` defaults to: the role a stock Postgres image creates. */
+export const DEFAULT_PG_ADMIN_USER = "postgres";
+/** The cluster superuser to log in as — Coolify's `POSTGRES_USER`, which need not be `postgres`. */
+export function pgAdminUser(config) {
+    const user = config.HF_PG_ADMIN_USER;
+    return user === undefined || user === "" ? DEFAULT_PG_ADMIN_USER : user;
+}
+/**
+ * What Coolify may have called the Postgres container on the box, in the order to try them.
+ *
+ * A standalone Postgres resource runs in a container named for the bare uuid; a database attached
+ * to a service gets `postgresql-<uuid>`. Both are asked about rather than one being guessed at,
+ * and `HF_DB_CONTAINER` replaces the pair outright. Empty when neither key is set.
+ */
+export function postgresContainers(config) {
+    const override = config.HF_DB_CONTAINER;
+    if (override !== undefined && override !== "")
+        return [override];
+    const uuid = config.HF_COOLIFY_POSTGRES_UUID;
+    return uuid === undefined || uuid === "" ? [] : [uuid, `postgresql-${uuid}`];
+}
 /**
  * `HF_GITHUB_APP_SLUGS` as a list: split on commas, trimmed, empties dropped.
  *

package/dist/database.d.ts

@@ -1,4 +1,4 @@
-import type { Runner } from "./runner.js";
+import { type Runner } from "./runner.js";
 /** Rows as strings, the one shape both transports can produce without inventing types. */
 export interface QueryResult {
     rows: string[][];
@@ -13,13 +13,22 @@ export type DatabaseTransport = "tunnel" | "docker-exec";
  *
  * `tunnel` is the default, and the only transport that can carry the whole of E2: it hands out
  * a libpq URL, which is what `provisionRoles()` — a `pg` client, in `@hyperfixation/db` — takes.
- * `docker-exec` exists because Phase 0 never confirmed that the Coolify Postgres container
- * publishes 5432 on the box's loopback; it runs the same SQL through `psql` inside the
- * container, so `CREATE DATABASE`, the extensions and a password rotation all work, but there
- * is no address for a client library to dial and `adminUrl` is `undefined`.
+ * Its far end is the box's loopback where the port is published and the container's own address
+ * on the docker network where it is not. `docker-exec` is the last resort: it runs the same SQL
+ * through `psql` inside the container, so `CREATE DATABASE`, the extensions and a password
+ * rotation all work, but there is no address for a client library to dial and `adminUrl` is
+ * `undefined`.
  */
 export interface Database {
     readonly kind: DatabaseTransport;
+    /**
+     * Where the **box** reaches this cluster, for anything that runs there rather than here —
+     * `pg_restore`, in E7. `undefined` when the transport has no address at all.
+     */
+    readonly boxAddress?: {
+        host: string;
+        port: number;
+    };
     /** A libpq URL onto `databaseName`, or `undefined` when the transport has no address. */
     adminUrl(databaseName?: string): string | undefined;
     query(sql: string, options?: QueryOptions): Promise<QueryResult>;
@@ -47,18 +56,39 @@ export interface AdminCredentials {
 }
 export interface OpenDatabaseOptions {
     admin: AdminCredentials;
-    /** Where Postgres listens on the box's loopback. */
+    /** The port Postgres listens on, wherever it is reached. */
     remotePort?: number;
-    /** The Coolify Postgres container, for the `docker-exec` fallback. Omit to have none. */
+    /**
+     * What the Coolify Postgres container may be called, in the order to try them; Coolify's own
+     * naming depends on how the database was created. The address of the first one that exists is
+     * what the tunnel forwards to when the box's loopback has no listener, and `dockerExec` runs
+     * `psql` inside it. Omit to have neither, and the loopback is then the only route.
+     */
+    containers?: readonly string[];
+    /**
+     * One container, appended to `containers`.
+     *
+     * @deprecated Coolify's naming depends on how the database was created, so a caller that knows
+     * only the uuid has two names to try; pass `containers`. Removed in 0.2.0.
+     */
     container?: string;
+    /** Last resort when no address carries a query: `psql` inside the container. Default false. */
+    dockerExec?: boolean;
 }
 export declare const DEFAULT_POSTGRES_PORT = 5432;
 /**
- * Opens the cluster over `runner`, preferring the tunnel and falling back to `docker exec`.
+ * Opens the cluster over `runner`: the box's loopback, else the container, else `docker exec`.
  *
- * The probe is a real `SELECT 1` rather than a port check: an `ssh -L` forward accepts locally
- * and only then discovers that nothing is listening on the far side, so a forward to an
- * unpublished port looks healthy until the first query.
+ * Coolify publishes nothing for its Postgres — `docker inspect` reports `{"5432/tcp": null}`, so
+ * the box's `127.0.0.1:5432` is not a listener and forwarding to it can never work. The
+ * container's address on the `coolify` network is the route in: the box host routes to it, and
+ * `ssh -L localPort:<containerIP>:5432` makes the box the hop. Publishing the port would bind
+ * every interface, which is not a trade worth making for a forward that already works.
+ *
+ * The loopback is still tried first and costs one `ssh` when it fails, because some setups do
+ * publish it. Each probe is a real `SELECT 1` rather than a port check: an `ssh -L` forward
+ * accepts locally and only then discovers that nothing is listening on the far side, so a forward
+ * to an unpublished port looks healthy until the first query.
  */
 export declare function openDatabase(runner: Runner, options: OpenDatabaseOptions): Promise<Database>;
 /** The cluster at a URL this process can already dial — a test's Postgres, or a live tunnel. */

package/dist/database.js

@@ -1,4 +1,6 @@
+import { isIPv4 } from "node:net";
 import { Client } from "pg";
+import { shellQuote, TUNNEL_LOOPBACK } from "./runner.js";
 export class DatabaseTransportError extends Error {
     transport;
     constructor(transport, message, options) {
@@ -24,35 +26,116 @@ const FIELD_SEPARATOR = "";
 export const DEFAULT_POSTGRES_PORT = 5432;
 const DEFAULT_ADMIN_DATABASE = "postgres";
 /**
- * Opens the cluster over `runner`, preferring the tunnel and falling back to `docker exec`.
+ * Docker's network→IP map for one container, as whitespace-separated `network=ip` pairs.
  *
- * The probe is a real `SELECT 1` rather than a port check: an `ssh -L` forward accepts locally
- * and only then discovers that nothing is listening on the far side, so a forward to an
- * unpublished port looks healthy until the first query.
+ * A Go template rather than `--format json` and a parse: the output is one flat line, so nothing
+ * about it depends on which docker version the box has.
+ */
+const DOCKER_NETWORKS_FORMAT = "{{range $k,$v := .NetworkSettings.Networks}}{{$k}}={{$v.IPAddress}} {{end}}";
+/** The network Coolify attaches its services to, and the one the box host can route to. */
+const COOLIFY_NETWORK = "coolify";
+/**
+ * Opens the cluster over `runner`: the box's loopback, else the container, else `docker exec`.
+ *
+ * Coolify publishes nothing for its Postgres — `docker inspect` reports `{"5432/tcp": null}`, so
+ * the box's `127.0.0.1:5432` is not a listener and forwarding to it can never work. The
+ * container's address on the `coolify` network is the route in: the box host routes to it, and
+ * `ssh -L localPort:<containerIP>:5432` makes the box the hop. Publishing the port would bind
+ * every interface, which is not a trade worth making for a forward that already works.
+ *
+ * The loopback is still tried first and costs one `ssh` when it fails, because some setups do
+ * publish it. Each probe is a real `SELECT 1` rather than a port check: an `ssh -L` forward
+ * accepts locally and only then discovers that nothing is listening on the far side, so a forward
+ * to an unpublished port looks healthy until the first query.
  */
 export async function openDatabase(runner, options) {
     const remotePort = options.remotePort ?? DEFAULT_POSTGRES_PORT;
+    const loopback = await tryTunnel(runner, options.admin, remotePort, TUNNEL_LOOPBACK);
+    if ("database" in loopback)
+        return loopback.database;
+    const candidates = [
+        ...(options.containers ?? []),
+        ...(options.container === undefined ? [] : [options.container]),
+    ];
+    if (candidates.length === 0) {
+        throw new DatabaseTransportError("tunnel", `could not reach Postgres on ${TUNNEL_LOOPBACK}:${String(remotePort)} on the box, and no ` +
+            "container was named to discover an address on the docker network", { cause: loopback.failure });
+    }
+    const found = await containerAddress(runner, candidates);
+    const direct = await tryTunnel(runner, options.admin, remotePort, found.address);
+    if ("database" in direct)
+        return direct.database;
+    if (options.dockerExec !== true) {
+        throw new DatabaseTransportError("tunnel", `could not reach Postgres on ${TUNNEL_LOOPBACK}:${String(remotePort)} on the box, nor on ` +
+            `${found.address}:${String(remotePort)}, which is where ${found.container} answers on ` +
+            "the docker network", { cause: direct.failure });
+    }
+    return dockerExecDatabase(runner, found.container, options.admin);
+}
+/** The cluster at a URL this process can already dial — a test's Postgres, or a live tunnel. */
+export function openDatabaseUrl(adminUrl) {
+    return tunnelDatabase(adminUrl, undefined, undefined);
+}
+async function tryTunnel(runner, admin, remotePort, remoteHost) {
     let tunnel;
     try {
-        tunnel = await runner.tunnel(remotePort);
-        const database = tunnelDatabase(adminUrlOf(options.admin, tunnel.localPort), tunnel);
+        tunnel = await runner.tunnel(remotePort, remoteHost);
+        const database = tunnelDatabase(adminUrlOf(admin, tunnel.localPort), tunnel, {
+            host: remoteHost,
+            port: remotePort,
+        });
         await database.query("SELECT 1");
-        return database;
+        return { database };
     }
-    catch (cause) {
+    catch (failure) {
         await tunnel?.close();
-        if (options.container === undefined) {
-            throw new DatabaseTransportError("tunnel", `could not reach Postgres on 127.0.0.1:${String(remotePort)} on the box, and no ` +
-                "container was named to fall back to", { cause });
+        return { failure };
+    }
+}
+/**
+ * The first of `containers` that exists, and its own address, asked of the box.
+ *
+ * The `coolify` network by name, because a Coolify service also sits on a per-service network
+ * that only its own stack is on; the first address is the fallback for a box that names its
+ * network something else. Every candidate that failed is reported, because which name a database
+ * got is a fact about how it was created and the operator is the one who knows it.
+ */
+async function containerAddress(runner, containers) {
+    const problems = [];
+    for (const container of containers) {
+        const command = ["docker", "inspect", "-f", DOCKER_NETWORKS_FORMAT, container];
+        const result = await runner.exec(command);
+        if (result.code !== 0) {
+            problems.push(`${container}: ${shellQuote(command)} exited ${String(result.code)}: ` +
+                result.stderr.trim());
+            continue;
+        }
+        const address = coolifyAddress(result.stdout);
+        if (address === undefined) {
+            problems.push(`${container}: no IPv4 address on any docker network, ${shellQuote(command)} printed ` +
+                JSON.stringify(result.stdout.trim()));
+            continue;
         }
+        return { container, address };
     }
-    return dockerExecDatabase(runner, options.container, options.admin);
+    throw new DatabaseTransportError("tunnel", `no Postgres container on the box under any name tried (${containers.join(", ")}): ` +
+        problems.join("; "));
 }
-/** The cluster at a URL this process can already dial — a test's Postgres, or a live tunnel. */
-export function openDatabaseUrl(adminUrl) {
-    return tunnelDatabase(adminUrl, undefined);
+/** The `coolify` network's address in `docker inspect`'s output, else the first one there is. */
+function coolifyAddress(stdout) {
+    const networks = stdout
+        .split(/\s+/)
+        .filter((pair) => pair.includes("="))
+        .map((pair) => ({
+        network: pair.slice(0, pair.indexOf("=")),
+        address: pair.slice(pair.indexOf("=") + 1),
+    }))
+        // An IPv4 literal and nothing else: this goes into an `ssh -L` field, and a container with no
+        // address on a network reports the key with an empty value.
+        .filter((entry) => isIPv4(entry.address));
+    return (networks.find((entry) => entry.network === COOLIFY_NETWORK) ?? networks[0])?.address;
 }
-function tunnelDatabase(adminUrl, tunnel) {
+function tunnelDatabase(adminUrl, tunnel, boxAddress) {
     const clients = new Map();
     const clientFor = async (databaseName) => {
         const url = withDatabase(adminUrl, databaseName);
@@ -66,6 +149,7 @@ function tunnelDatabase(adminUrl, tunnel) {
     };
     return {
         kind: "tunnel",
+        boxAddress,
         adminUrl: (databaseName) => withDatabase(adminUrl, databaseName),
         query: async (sql, queryOptions) => {
             const client = await clientFor(queryOptions?.database);

package/dist/doctor.d.ts

@@ -55,13 +55,14 @@ export declare function doctor(options?: DoctorOptions): Promise<DoctorResult>;
 /** The report as printed: a blank line and a header per app, then its findings. */
 export declare function doctorLines(result: DoctorResult): string[];
 /**
- * E006 as `postgres` with `SET ROLE hf_<app>`, over the tunnel a `Runner` opens.
+ * E006 as the cluster admin with `SET ROLE hf_<app>`, over the tunnel a `Runner` opens.
  *
  * As the app role rather than as an admin because that is the only role whose answer matters —
  * a superuser's privileges are both true whatever the migrator granted.
  */
 export declare function tunnelPrivilegeCheck(runner: Runner, options?: {
-    container?: string;
+    containers?: readonly string[];
+    adminUser?: string;
 }): PrivilegeCheck;
 /**
  * `@hyperfixation/db`'s own E006, run against `adminUrl` — which must already name the app's

package/dist/doctor.js

@@ -2,7 +2,7 @@ import { access, readdir } from "node:fs/promises";
 import path from "node:path";
 import { checkE006, quoteIdent } from "@hyperfixation/db";
 import { Client } from "pg";
-import { loadOperatorConfig, requireOperatorConfig, } from "./config.js";
+import { DEFAULT_PG_ADMIN_USER, loadOperatorConfig, pgAdminUser, postgresContainers, requireOperatorConfig, } from "./config.js";
 import { openDatabase } from "./database.js";
 import { deriveNames } from "./names.js";
 import { GithubClient } from "./providers/github.js";
@@ -12,8 +12,6 @@ import { openAppState, stateDir } from "./state.js";
 export const RESTORE_CHECK_MAX_AGE_DAYS = 7;
 /** The branch prefix Phase 4's core bumps open their pull requests on. */
 export const CORE_BUMP_BRANCH_PREFIX = "core-bump/";
-/** The cluster role `hf doctor` reads privileges as, before `SET ROLE`. */
-const CLUSTER_ADMIN_USER = "postgres";
 /**
  * `hf doctor` — what is wrong with the deployed apps, one line per finding.
  *
@@ -63,21 +61,22 @@ export function doctorLines(result) {
     return lines;
 }
 /**
- * E006 as `postgres` with `SET ROLE hf_<app>`, over the tunnel a `Runner` opens.
+ * E006 as the cluster admin with `SET ROLE hf_<app>`, over the tunnel a `Runner` opens.
  *
  * As the app role rather than as an admin because that is the only role whose answer matters —
  * a superuser's privileges are both true whatever the migrator granted.
  */
 export function tunnelPrivilegeCheck(runner, options = {}) {
+    const adminUser = options.adminUser ?? DEFAULT_PG_ADMIN_USER;
     return async (target) => {
         const db = await openDatabase(runner, {
-            admin: { user: CLUSTER_ADMIN_USER },
-            container: options.container,
+            admin: { user: adminUser },
+            containers: options.containers,
         });
         try {
             const adminUrl = db.adminUrl(target.databaseName);
             if (adminUrl === undefined) {
-                throw new Error(`E006 cannot be read over the ${db.kind} transport: ${CLUSTER_ADMIN_USER} has to be ` +
+                throw new Error(`E006 cannot be read over the ${db.kind} transport: ${adminUser} has to be ` +
                     "a session a pg client holds open, so that SET ROLE outlives the statement");
             }
             await checkAppRolePrivileges(adminUrl, target.applicationRole);
@@ -105,7 +104,10 @@ export async function checkAppRolePrivileges(adminUrl, role) {
 }
 function defaultPrivilegeCheck(config, env) {
     const { HF_SSH_HOST } = requireOperatorConfig(config, ["HF_SSH_HOST"], { env });
-    return tunnelPrivilegeCheck(createSshRunner({ host: HF_SSH_HOST }));
+    return tunnelPrivilegeCheck(createSshRunner({ host: HF_SSH_HOST }), {
+        containers: postgresContainers(config),
+        adminUser: pgAdminUser(config),
+    });
 }
 async function doctorApp(context, name) {
     const findings = [];
@@ -141,7 +143,7 @@ async function doctorApp(context, name) {
     }
     const report = await statusFindings(context, name, state, add);
     versionFinding(report?.applicationVersion, mainSha, mainShaProblem, add);
-    if (report !== undefined) {
+    if (report?.budget !== undefined) {
         budgetFinding(report.budget.current, "current", add);
         budgetFinding(report.budget.previous, "previous", add);
     }
@@ -161,23 +163,75 @@ async function statusFindings(context, name, state, add) {
     }
     let report;
     try {
-        report = await getStatus(context.fetch, url, token);
+        report = readStatus(await getStatus(context.fetch, url, token));
     }
     catch (error) {
         add("status", "fail", `GET ${url}: ${flatten(error.message)}`);
         return undefined;
     }
-    add("status", report.health === "ok" ? "ok" : "warn", `health ${report.health}, ${String(report.anomalies)} anomaly/anomalies, core ` +
-        report.coreVersion);
-    add("runs", "ok", `${String(report.runs.running)} run(s) running`);
-    // Only `fixtures` gets a line. `live` is the expected deploy, and `unknown` is an app whose
-    // worker has not reported yet — neither is a finding, but a canned draft an operator takes
-    // for a real one is.
-    if (report.llm.mode === "fixtures") {
+    const anomalies = report.anomalies === undefined ? UNKNOWN : String(report.anomalies);
+    add("status", 
+    // Only a health the app actually reported can be a warning: a field it did not answer with
+    // says nothing about the deployment, and a WARN the operator cannot act on is noise.
+    report.health === undefined || report.health === "ok" ? "ok" : "warn", `health ${report.health ?? UNKNOWN}, ${anomalies} anomaly/anomalies, core ` +
+        (report.coreVersion ?? UNKNOWN));
+    if (report.runsRunning !== undefined) {
+        add("runs", "ok", `${String(report.runsRunning)} run(s) running`);
+    }
+    // Only `fixtures` gets a line. `live` is the expected deploy, and `unknown` — as is a core too
+    // old to have the field at all — is an app that has not said; neither is a finding, but a
+    // canned draft an operator takes for a real one is.
+    if (report.llmMode === "fixtures") {
         add("llm", "warn", "app is serving fixture drafts — no provider key set");
     }
     return report;
 }
+const UNKNOWN = "unknown";
+function readStatus(payload) {
+    const report = record(payload);
+    const budget = record(report.budget);
+    return {
+        health: text(report.health),
+        anomalies: numeric(report.anomalies),
+        coreVersion: text(report.coreVersion),
+        applicationVersion: report.applicationVersion === null ? null : text(report.applicationVersion),
+        runsRunning: numeric(record(report.runs).running),
+        llmMode: text(record(report.llm).mode),
+        budget: isRecord(report.budget)
+            ? { current: readPeriod(budget.current), previous: readPeriod(budget.previous) }
+            : undefined,
+    };
+}
+/** `null` for a period the app has no row for, which is also how a malformed one reads. */
+function readPeriod(value) {
+    if (!isRecord(value))
+        return null;
+    return {
+        period: text(value.period),
+        budgetUsd: text(value.budgetUsd),
+        spentUsd: text(value.spentUsd),
+        driftUsd: text(value.driftUsd),
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function record(value) {
+    return isRecord(value) ? value : {};
+}
+function text(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function numeric(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/** A money column as a number, or `undefined` when the app did not report a usable one. */
+function amount(value) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
 function versionFinding(deployed, mainSha, mainShaProblem, add) {
     if (mainShaProblem !== undefined) {
         add("version", "fail", mainShaProblem);
@@ -198,9 +252,13 @@ function budgetFinding(period, which, add) {
         add("budget", "ok", `no ${which} period row yet`);
         return;
     }
-    const over = Number(period.spentUsd) > Number(period.budgetUsd);
-    const drifting = Number(period.driftUsd) !== 0;
-    const spend = `${period.period} spent $${period.spentUsd} of $${period.budgetUsd}`;
+    const spent = amount(period.spentUsd);
+    const budget = amount(period.budgetUsd);
+    const drift = amount(period.driftUsd);
+    const over = spent !== undefined && budget !== undefined && spent > budget;
+    const drifting = drift !== undefined && drift !== 0;
+    const spend = `${period.period ?? UNKNOWN} spent $${period.spentUsd ?? UNKNOWN} ` +
+        `of $${period.budgetUsd ?? UNKNOWN}`;
     if (over || drifting) {
         add("budget", "warn", `${spend}${over ? " — over budget" : ""}${drifting ? ` — drift $${period.driftUsd}` : ""}`);
         return;
@@ -283,7 +341,7 @@ async function getStatus(fetchImpl, url, token) {
     });
     if (!response.ok)
         throw new Error(`HTTP ${String(response.status)}`);
-    return (await response.json());
+    return await response.json();
 }
 async function stateNames(dir) {
     const entries = await readdir(dir).catch(() => []);

package/dist/new-cloud.d.ts

@@ -75,13 +75,22 @@ export declare function invalidateStaleSecretSteps(state: AppStateStore): Promis
  * Errors propagate untouched: the caller prints them, and the state file is the resume point.
  */
 export declare function runSteps<Context extends CloudContext>(steps: readonly Step<Context>[], context: Context): Promise<RunStepsResult>;
+/**
+ * The keys a cloud `hf new` runs without: three have a default derived from another key, the two
+ * provider keys are what the checklist warns about when they are unset, and the three Langfuse
+ * keys are three ways of configuring one step — an org key, a project key pair, or neither, which
+ * the step degrades to a warning and a checklist line.
+ */
+export declare const OPTIONAL_CLOUD_CONFIG: readonly ConfigKey[];
 /**
  * Every operator config key a cloud `hf new` needs, checked before the first step.
  *
  * All at once, and before anything is created: `requireOperatorConfig` names every missing key,
  * and an operator who learns about them one failed step at a time pays for a half-provisioned app
- * each time. The optional keys are deliberately absent — `HF_DB_HOST_INTERNAL` has a default, and
- * the two provider keys are what the checklist warns about when they are unset.
+ * each time. Derived from `CONFIG_KEYS` rather than listed, because a hand-kept list is exactly
+ * what left `HF_GITHUB_TOKEN`, the Cloudflare pair and five others to fail at their own step: the
+ * ten steps between them read every key there is, so the required set is the complement of the
+ * optional one, and a key added for a step is required the moment it is named.
  */
 export declare const REQUIRED_CLOUD_CONFIG: readonly ConfigKey[];
 export interface NewAppCloudOptions {

package/dist/new-cloud.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import { checklistLines } from "./checklist.js";
 import { providerKeys } from "./cloud-steps/coolify.js";
 import { cloudCommands, CLOUD_STEPS, defaultTemplateFetch, spawnStepExec, } from "./cloud-steps/index.js";
-import { loadOperatorConfig, requireOperatorConfig, } from "./config.js";
+import { CONFIG_KEYS, loadOperatorConfig, pgAdminUser, postgresContainers, requireOperatorConfig, } from "./config.js";
 import { openDatabase } from "./database.js";
 import { deriveNames } from "./names.js";
 import { createSshRunner } from "./runner.js";
@@ -106,28 +106,33 @@ export async function runSteps(steps, context) {
     assertRotationApplied(context);
     return { ran, skipped, invalidated };
 }
+/**
+ * The keys a cloud `hf new` runs without: three have a default derived from another key, the two
+ * provider keys are what the checklist warns about when they are unset, and the three Langfuse
+ * keys are three ways of configuring one step — an org key, a project key pair, or neither, which
+ * the step degrades to a warning and a checklist line.
+ */
+export const OPTIONAL_CLOUD_CONFIG = [
+    "HF_DB_HOST_INTERNAL",
+    "HF_DB_CONTAINER",
+    "HF_PG_ADMIN_USER",
+    "HF_ANTHROPIC_API_KEY",
+    "HF_OPENAI_API_KEY",
+    "HF_LANGFUSE_ORG_KEY",
+    "HF_LANGFUSE_PUBLIC_KEY",
+    "HF_LANGFUSE_SECRET_KEY",
+];
 /**
  * Every operator config key a cloud `hf new` needs, checked before the first step.
  *
  * All at once, and before anything is created: `requireOperatorConfig` names every missing key,
  * and an operator who learns about them one failed step at a time pays for a half-provisioned app
- * each time. The optional keys are deliberately absent — `HF_DB_HOST_INTERNAL` has a default, and
- * the two provider keys are what the checklist warns about when they are unset.
+ * each time. Derived from `CONFIG_KEYS` rather than listed, because a hand-kept list is exactly
+ * what left `HF_GITHUB_TOKEN`, the Cloudflare pair and five others to fail at their own step: the
+ * ten steps between them read every key there is, so the required set is the complement of the
+ * optional one, and a key added for a step is required the moment it is named.
  */
-export const REQUIRED_CLOUD_CONFIG = [
-    "HF_COOLIFY_URL",
-    "HF_COOLIFY_TOKEN",
-    "HF_COOLIFY_SERVER_UUID",
-    "HF_COOLIFY_GITHUB_APP_UUID",
-    "HF_COOLIFY_POSTGRES_UUID",
-    "HF_SSH_HOST",
-    "HF_BASE_DOMAIN",
-    "HF_SMTP_URL",
-    "HF_EMAIL_FROM",
-    "HF_LANGFUSE_URL",
-];
-/** The cluster role `hf new` provisions the app's database and roles as. */
-const CLUSTER_ADMIN_USER = "postgres";
+export const REQUIRED_CLOUD_CONFIG = CONFIG_KEYS.filter((key) => !OPTIONAL_CLOUD_CONFIG.includes(key));
 /**
  * `hf new <name>` without `--local`: the ten steps, resumable, then the checklist.
  *
@@ -144,7 +149,7 @@ export async function newAppCloud(options) {
     const runner = options.runner ?? createSshRunner({ host: required.HF_SSH_HOST });
     // `PGPASSWORD` is libpq's own name for it, and the same place `hf restore-check` reads it:
     // Coolify's cluster password is not an hf config key, because nothing of ours should hold it.
-    const clusterAdmin = options.clusterAdmin ?? { user: CLUSTER_ADMIN_USER, password: env.PGPASSWORD };
+    const clusterAdmin = options.clusterAdmin ?? { user: pgAdminUser(config), password: env.PGPASSWORD };
     let database;
     const hadWriteToken = state.state.statusTokens?.write !== undefined;
     const fqdn = `${names.given}.${required.HF_BASE_DOMAIN}`;
@@ -164,9 +169,13 @@ export async function newAppCloud(options) {
         email: options.email,
         budgetUsd: options.budgetUsd,
         database: async () => {
-            // No `container`: the `docker exec psql` transport has no address, and every use of the
-            // cluster here — `provisionRoles`, the migrator, the tokens — is a pg client.
-            database ??= await openDatabase(runner, { admin: clusterAdmin });
+            // The container is named so the tunnel can discover its address, but no `dockerExec`: that
+            // transport has no address, and every use of the cluster here — `provisionRoles`, the
+            // migrator, the tokens — is a pg client.
+            database ??= await openDatabase(runner, {
+                admin: clusterAdmin,
+                containers: postgresContainers(config),
+            });
             return database;
         },
         commands: options.commands ?? cloudCommands,

package/dist/provision-database.js

@@ -44,8 +44,8 @@ export async function provisionDatabase(target, options) {
     const adminUrl = db.adminUrl();
     if (adminUrl === undefined) {
         throw new ProvisionDatabaseError(`roles cannot be provisioned over the ${db.kind} transport: provisionRoles() is a pg ` +
-            "client and needs an address. Publish the Coolify Postgres port on the box's loopback " +
-            "so the tunnel works.");
+            "client and needs an address. Name the Postgres container — HF_DB_CONTAINER, or " +
+            "HF_COOLIFY_POSTGRES_UUID — so the tunnel can discover one.");
     }
     try {
         const createdDatabase = await createDatabaseIfAbsent(db, names.databaseName);

package/dist/restore-check.js

@@ -1,6 +1,6 @@
 import { quoteIdent } from "@hyperfixation/db";
 import { createLocalDirectoryBackupSource, createS3BackupSource, } from "./backup-source.js";
-import { loadOperatorConfig, requireOperatorConfig } from "./config.js";
+import { loadOperatorConfig, pgAdminUser, postgresContainers, requireOperatorConfig, } from "./config.js";
 import { openDatabase, openDatabaseUrl, redactPasswords, DEFAULT_POSTGRES_PORT, } from "./database.js";
 import { deriveNames } from "./names.js";
 import { REQUIRED_EXTENSIONS } from "./provision-database.js";
@@ -12,8 +12,6 @@ export const SCRATCH_SUFFIX = "_restore_check";
 const MAX_IDENTIFIER_BYTES = 63;
 /** Older than this and the dump gets a warning line; it never changes the exit code. */
 export const STALE_DUMP_HOURS = 36;
-/** The box's Coolify Postgres superuser — the role the whole check runs as. */
-const CLUSTER_ADMIN_USER = "postgres";
 const CLUSTER_ADMIN_DATABASE = "postgres";
 export class RestoreCheckError extends Error {
     constructor(message) {
@@ -48,7 +46,8 @@ export async function restoreCheck(options) {
     const clusterUrl = db.adminUrl();
     if (clusterUrl === undefined) {
         throw new RestoreCheckError(`a restore cannot be run over the ${db.kind} transport: pg_restore needs an address. ` +
-            "Publish the Coolify Postgres port on the box's loopback so the tunnel works.");
+            "Name the Postgres container — HF_DB_CONTAINER, or HF_COOLIFY_POSTGRES_UUID — so the " +
+            "tunnel can discover one.");
     }
     const restoreTarget = urlOnto(options.restoreAdminUrl ?? clusterUrl, scratchDatabase);
     const now = options.now ?? new Date();
@@ -219,8 +218,8 @@ export async function restoreCheckApp(options) {
     const config = await loadOperatorConfig({ env });
     const { HF_SSH_HOST } = requireOperatorConfig(config, ["HF_SSH_HOST"], { env });
     const runner = createSshRunner({ host: HF_SSH_HOST });
-    const admin = { user: CLUSTER_ADMIN_USER, password: env.PGPASSWORD };
-    const db = await openDatabase(runner, { admin });
+    const admin = { user: pgAdminUser(config), password: env.PGPASSWORD };
+    const db = await openDatabase(runner, { admin, containers: postgresContainers(config) });
     try {
         return await restoreCheck({
             app: options.app,
@@ -230,17 +229,23 @@ export async function restoreCheckApp(options) {
                 : createLocalDirectoryBackupSource({ runner, directory: options.backupDir }),
             runner,
             database: db,
-            restoreAdminUrl: boxAdminUrl(admin),
+            restoreAdminUrl: boxAdminUrl(admin, db.boxAddress),
         });
     }
     finally {
         await db.close();
     }
 }
-/** The cluster as the box itself sees it, where `pg_restore` runs. */
-function boxAdminUrl(admin) {
-    const url = new URL("postgresql://127.0.0.1");
-    url.port = String(DEFAULT_POSTGRES_PORT);
+/**
+ * The cluster as the box itself sees it, where `pg_restore` runs.
+ *
+ * `address` is whatever the tunnel settled on: with 5432 unpublished the box's loopback is no more
+ * a listener for `pg_restore` than for the forward, and the container's address on the docker
+ * network is what both have to dial.
+ */
+function boxAdminUrl(admin, address) {
+    const url = new URL(`postgresql://${address?.host ?? "127.0.0.1"}`);
+    url.port = String(address?.port ?? DEFAULT_POSTGRES_PORT);
     url.username = encodeURIComponent(admin.user);
     if (admin.password !== undefined)
         url.password = encodeURIComponent(admin.password);

package/dist/runner.d.ts

@@ -22,8 +22,13 @@ export interface Tunnel {
  */
 export interface Runner {
     exec(command: readonly string[], options?: ExecOptions): Promise<ExecResult>;
-    /** Forwards a local port to `127.0.0.1:<remotePort>` on the far side. */
-    tunnel(remotePort: number): Promise<Tunnel>;
+    /**
+     * Forwards a local port to `<remoteHost>:<remotePort>` as the far side sees it.
+     *
+     * `remoteHost` defaults to the far side's own loopback; it is an address on a network the far
+     * side can route to, which is how a container that publishes nothing is still reachable.
+     */
+    tunnel(remotePort: number, remoteHost?: string): Promise<Tunnel>;
 }
 export declare class RunnerError extends Error {
     constructor(message: string, options?: {
@@ -32,7 +37,9 @@ export declare class RunnerError extends Error {
 }
 /** The argv `exec` runs, `ssh` excluded — the array the test asserts against. */
 export declare function sshExecArgv(host: string, command: readonly string[]): string[];
-export declare function sshTunnelArgv(host: string, localPort: number, remotePort: number): string[];
+export declare function sshTunnelArgv(host: string, localPort: number, remotePort: number, remoteHost?: string): string[];
+/** Where a forward lands when the caller names no host: the far side's own loopback. */
+export declare const TUNNEL_LOOPBACK = "127.0.0.1";
 /** Single-quotes one word for a POSIX remote shell. */
 export declare function shellQuote(command: readonly string[]): string;
 export interface SshRunnerOptions {

package/dist/runner.js

@@ -37,17 +37,20 @@ export function sshExecArgv(host, command) {
     // re-quoted for that shell; nothing else in this file ever builds a shell word.
     return ["-T", ...SSH_OPTIONS, host, shellQuote(command)];
 }
-export function sshTunnelArgv(host, localPort, remotePort) {
+export function sshTunnelArgv(host, localPort, remotePort, remoteHost = TUNNEL_LOOPBACK) {
     assertHost(host);
+    assertTunnelHost(remoteHost);
     return [
         "-N",
         "-T",
         ...SSH_OPTIONS,
         "-L",
-        `${String(localPort)}:127.0.0.1:${String(remotePort)}`,
+        `${String(localPort)}:${remoteHost}:${String(remotePort)}`,
         host,
     ];
 }
+/** Where a forward lands when the caller names no host: the far side's own loopback. */
+export const TUNNEL_LOOPBACK = "127.0.0.1";
 /** Single-quotes one word for a POSIX remote shell. */
 export function shellQuote(command) {
     return command.map((word) => `'${word.replaceAll("'", `'\\''`)}'`).join(" ");
@@ -59,9 +62,9 @@ export function createSshRunner(options) {
     assertHost(options.host);
     return {
         exec: async (command, execOptions) => await spawnCollecting(ssh, sshExecArgv(options.host, command), execOptions),
-        tunnel: async (remotePort) => {
+        tunnel: async (remotePort, remoteHost = TUNNEL_LOOPBACK) => {
             const localPort = await freeLocalPort();
-            const child = spawn(ssh, sshTunnelArgv(options.host, localPort, remotePort), {
+            const child = spawn(ssh, sshTunnelArgv(options.host, localPort, remotePort, remoteHost), {
                 stdio: ["ignore", "ignore", "pipe"],
             });
             let stderr = "";
@@ -75,7 +78,7 @@ export function createSshRunner(options) {
             catch (cause) {
                 child.kill("SIGTERM");
                 await exited;
-                throw new RunnerError(`ssh -L ${String(localPort)}:127.0.0.1:${String(remotePort)} never became ready` +
+                throw new RunnerError(`ssh -L ${String(localPort)}:${remoteHost}:${String(remotePort)} never became ready` +
                     (stderr === "" ? "" : `: ${stderr.trim()}`), { cause });
             }
             return {
@@ -131,14 +134,20 @@ async function spawnCollecting(bin, args, options = {}) {
     child.stderr?.on("data", (chunk) => {
         stderr += chunk.toString("utf8");
     });
-    // A child that exits before reading its stdin (`true`, a refused ssh) makes the write fail with
-    // EPIPE; the exit code already says what happened, so it must not surface as an unhandled error.
-    child.stdin?.on("error", () => { });
-    child.stdin?.end(options.input ?? "");
-    const code = await new Promise((resolve, reject) => {
+    const closed = new Promise((resolve, reject) => {
+        // A child that exits before reading its stdin (`true`, a refused ssh) makes the write fail with
+        // EPIPE; the exit code already says what happened. Any other stdin error is a real failure.
+        child.stdin?.on("error", (error) => {
+            if (error.code === "EPIPE")
+                return;
+            child.kill();
+            reject(error);
+        });
         child.once("error", reject);
         child.once("close", (exitCode) => resolve(exitCode));
     });
+    child.stdin?.end(options.input ?? "");
+    const code = await closed;
     return { code, stdout, stderr };
 }
 /**
@@ -192,6 +201,19 @@ async function canConnect(port) {
         socket.once("timeout", () => done(false));
     });
 }
+/**
+ * The far-side end of a `-L` forward, which is a bare address or hostname and nothing else.
+ *
+ * It arrives from `docker inspect` on the box rather than from the operator, and `-L` takes its
+ * three fields colon-separated, so a value carrying a colon or a space would silently become a
+ * different forward than the one asked for.
+ */
+function assertTunnelHost(remoteHost) {
+    if (!TUNNEL_HOST.test(remoteHost)) {
+        throw new RunnerError(`a tunnel's remote host must match ${TUNNEL_HOST.source}, got ${JSON.stringify(remoteHost)}`);
+    }
+}
+const TUNNEL_HOST = /^[A-Za-z0-9._-]+$/;
 function assertHost(host) {
     if (!SSH_HOST.test(host)) {
         throw new RunnerError(`HF_SSH_HOST must match ${SSH_HOST.source}, got ${JSON.stringify(host)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperfixation/cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "MIT",
   "description": "The hf binary and its Turborepo generator templates",
   "repository": {
@@ -29,15 +29,15 @@
     "!dist/test-support/**"
   ],
   "dependencies": {
-    "@hyperfixation/auth": "0.1.1",
-    "@hyperfixation/core": "0.1.1",
-    "@hyperfixation/db": "0.1.1",
+    "@hyperfixation/auth": "0.1.2",
+    "@hyperfixation/core": "0.1.2",
+    "@hyperfixation/db": "0.1.2",
     "giget": "3.3.1",
     "pg": "^8.23.0"
   },
   "devDependencies": {
-    "@hyperfixation/eslint-config": "0.1.1",
-    "@hyperfixation/testing": "0.1.1",
+    "@hyperfixation/eslint-config": "0.1.2",
+    "@hyperfixation/testing": "0.1.2",
     "@microsoft/api-extractor": "^7.59.1",
     "@types/pg": "^8.23.1",
     "eslint": "^10.10.0",