@hyperfixation/cli 0.1.1 → 0.1.3

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/context.d.ts

@@ -7,7 +7,8 @@ import type { FetchLike } from "../providers/http.js";
  * A step refused to act, or a command it ran failed.
  *
  * Carries no provider body and no environment: the only thing a step is allowed to say about a
- * secret is that it has one. `ProviderError` keeps the same rule for the HTTP half.
+ * secret is that it has one. `ProviderError` keeps the same rule for the HTTP half — it quotes the
+ * provider's own explanation, with every credential and every value it was sent blanked out.
  */
 export declare class StepFailed extends Error {
     constructor(message: string);

package/dist/cloud-steps/context.js

@@ -9,7 +9,8 @@ import { fetchTemplate } from "../template-source.js";
  * A step refused to act, or a command it ran failed.
  *
  * Carries no provider body and no environment: the only thing a step is allowed to say about a
- * secret is that it has one. `ProviderError` keeps the same rule for the HTTP half.
+ * secret is that it has one. `ProviderError` keeps the same rule for the HTTP half — it quotes the
+ * provider's own explanation, with every credential and every value it was sent blanked out.
  */
 export class StepFailed extends Error {
     constructor(message) {

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

@@ -6,6 +6,16 @@ import { StepFailed, type CloudStepContext } from "./context.js";
 export declare const COOLIFY_ENVIRONMENT = "production";
 /** Where the build pack looks for the compose file, relative to the repository root. */
 export declare const COMPOSE_LOCATION = "/docker-compose.prod.yml";
+/**
+ * The compose service the app's domain is attached to — the one the template publishes 3000 from.
+ *
+ * A `dockercompose` application cannot take `domains` at all (Coolify 4.3.21: 422 `The domains
+ * field cannot be used for dockercompose applications`), and `docker_compose_domains` names a
+ * service, so one of them has to be named here. A template that renamed `web` would deploy an app
+ * Coolify's proxy routes nothing to, which is why this is a constant with a test behind it rather
+ * than a literal in the payload.
+ */
+export declare const COMPOSE_DOMAIN_SERVICE = "web";
 /** The compose file the drift assertion reads, under the app's directory. */
 export declare const PROD_COMPOSE_FILE = "docker-compose.prod.yml";
 /**
@@ -24,6 +34,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 +67,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

@@ -9,6 +9,16 @@ import { appFqdn, StepFailed } from "./context.js";
 export const COOLIFY_ENVIRONMENT = "production";
 /** Where the build pack looks for the compose file, relative to the repository root. */
 export const COMPOSE_LOCATION = "/docker-compose.prod.yml";
+/**
+ * The compose service the app's domain is attached to — the one the template publishes 3000 from.
+ *
+ * A `dockercompose` application cannot take `domains` at all (Coolify 4.3.21: 422 `The domains
+ * field cannot be used for dockercompose applications`), and `docker_compose_domains` names a
+ * service, so one of them has to be named here. A template that renamed `web` would deploy an app
+ * Coolify's proxy routes nothing to, which is why this is a constant with a test behind it rather
+ * than a literal in the payload.
+ */
+export const COMPOSE_DOMAIN_SERVICE = "web";
 /** The compose file the drift assertion reads, under the app's directory. */
 export const PROD_COMPOSE_FILE = "docker-compose.prod.yml";
 /**
@@ -27,6 +37,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 +110,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 +160,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;
@@ -239,7 +265,7 @@ async function findOrCreateApplication(context, coolify, projectUuid, environmen
         docker_compose_location: COMPOSE_LOCATION,
         connect_to_docker_network: true,
         name,
-        domains: `https://${fqdn}`,
+        docker_compose_domains: [{ name: COMPOSE_DOMAIN_SERVICE, domain: `https://${fqdn}` }],
         // The `deploy` step is what deploys, once the environment is set and the database migrated.
         instant_deploy: false,
     });

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);