@hyperfixation/cli 0.1.4 → 0.1.6

package/dist/cli.d.ts

@@ -1,6 +1,6 @@
-export declare const COMMANDS: readonly ["new", "migrate", "bootstrap", "status-token", "check", "gen", "dev", "up", "doctor", "restore-check"];
+export declare const COMMANDS: readonly ["new", "migrate", "bootstrap", "status-token", "check", "gen", "dev", "up", "deploy", "doctor", "restore-check"];
 export type Command = (typeof COMMANDS)[number];
-export declare const USAGE = "hf \u2014 the hyperfixation CLI\n\n  hf new <name>             provision the app in the cloud: fetch the template, push a private\n                            repo, register a backup, Sentry, Langfuse and DNS, create the\n                            database and its roles, create the Coolify application and its\n                            environment, deploy, and print what is left to do by hand.\n                            Resumable \u2014 a rerun repeats only what did not finish\n      --budget-usd <amount>   the app's monthly LLM budget (required; no default)\n      --email <address>       the bootstrap admin's address (required)\n      --from <specifier>      template to fetch (default: gh:grahamlutz/hyperfixation-template)\n      --into <dir>            where to create <name> (default: the working directory)\n\n  hf new <name> --local     copy the template into ./<name>, substitute its placeholders, and\n                            prompt for the bootstrap admin's email\n      --from <dir>            template checkout (default: the sibling hyperfixation-template)\n      --into <dir>            where to create <name> (default: the working directory)\n      --email <address>       the bootstrap admin's address; skips the prompt\n\n  hf up                     install, infra, migrate, bootstrap, status tokens, then hf dev \u2014\n                            the whole local loop after hf new, safe to rerun; seeds a $10\n                            budget unless HF_BOOTSTRAP_BUDGET_USD is set in .env\n\n  hf migrate                create the application role, then run the app's migrate.ts\n      --skip-roles            the cloud path, where the roles already exist\n\n  hf bootstrap              grant the app its one bootstrap admin, and seed hf_app_state\n      --email <address>       the address to promote; otherwise HF_BOOTSTRAP_EMAIL\n      --budget-usd <amount>    the app's starting budget; otherwise HF_BOOTSTRAP_BUDGET_USD\n\n  hf status-token           provision /api/status's read and write tokens\n      --read                   only the read token; refuses if it is already set\n      --write                  only the write token; refuses if it is already set\n      --rotate                 replace a token that is already set\n                               (no flags: fills in whichever of the two is unset)\n\n  hf check                  declared env, pending migrations, and E001-E006\n\n  hf doctor [name]          every deployed app in the state cache, or one: /api/status under its\n                            read token, the deployed version against main, E006 as the app role,\n                            the last restore check, and open core-bump PRs. Exits 1 on any finding\n\n  hf gen [generator]        the app's turbo generators\n\n  hf dev                    docker compose up, then pnpm dev under HF_BUILD_SHA=dev-<timestamp>\n      --no-compose            leave the dev infrastructure alone\n      --compose-only          bring the infrastructure up and stop\n\n  hf restore-check <name>   restore the newest hf_<name> dump beside the live database and\n                            compare row counts; exits 1 on any mismatch\n      --backup-dir <dir>      where the dumps are (default: Coolify's on the box)\n      --from-s3               read the dump from object storage (not implemented)\n\nEvery command but `new`, `doctor` and `restore-check` runs against the app at or above the working directory, or --dir.\n";
+export declare const USAGE = "hf \u2014 the hyperfixation CLI\n\n  hf new <name>             provision the app in the cloud: fetch the template, push a private\n                            repo, register a backup, Sentry, Langfuse and DNS, create the\n                            database and its roles, create the Coolify application and its\n                            environment, deploy, and print what is left to do by hand.\n                            Resumable \u2014 a rerun repeats only what did not finish\n      --budget-usd <amount>   the app's monthly LLM budget (required; no default)\n      --email <address>       the bootstrap admin's address (required)\n      --from <specifier>      template to fetch (default: gh:grahamlutz/hyperfixation-template)\n      --into <dir>            where to create <name> (default: the working directory)\n\n  hf new <name> --local     copy the template into ./<name>, substitute its placeholders, and\n                            prompt for the bootstrap admin's email\n      --from <dir>            template checkout (default: the sibling hyperfixation-template)\n      --into <dir>            where to create <name> (default: the working directory)\n      --email <address>       the bootstrap admin's address; skips the prompt\n\n  hf up                     install, infra, migrate, bootstrap, status tokens, then hf dev \u2014\n                            the whole local loop after hf new, safe to rerun; seeds a $10\n                            budget unless HF_BOOTSTRAP_BUDGET_USD is set in .env\n\n  hf migrate                create the application role, then run the app's migrate.ts\n      --skip-roles            the cloud path, where the roles already exist\n\n  hf bootstrap              grant the app its one bootstrap admin, and seed hf_app_state\n      --email <address>       the address to promote; otherwise HF_BOOTSTRAP_EMAIL\n      --budget-usd <amount>    the app's starting budget; otherwise HF_BOOTSTRAP_BUDGET_USD\n\n  hf status-token           provision /api/status's read and write tokens\n      --read                   only the read token; refuses if it is already set\n      --write                  only the write token; refuses if it is already set\n      --rotate                 replace a token that is already set\n                               (no flags: fills in whichever of the two is unset)\n\n  hf check                  declared env, pending migrations, and E001-E006\n\n  hf deploy <name>          set SOURCE_COMMIT to a commit, deploy it, and wait until /api/status\n                            reports it. Coolify's push auto-deploy is off, so this is what\n                            publishes a merge to main\n      --sha <sha>             the commit to deploy (default: main's, via git ls-remote)\n\n  hf doctor [name]          every deployed app in the state cache, or one: /api/status under its\n                            read token, the deployed version against main, E006 as the app role,\n                            the last restore check, and open core-bump PRs. Exits 1 on any finding\n\n  hf gen [generator]        the app's turbo generators\n\n  hf dev                    docker compose up, then pnpm dev under HF_BUILD_SHA=dev-<timestamp>\n      --no-compose            leave the dev infrastructure alone\n      --compose-only          bring the infrastructure up and stop\n\n  hf restore-check <name>   restore the newest hf_<name> dump beside the live database and\n                            compare row counts; exits 1 on any mismatch\n      --backup-dir <dir>      where the dumps are (default: Coolify's on the box)\n      --from-s3               read the dump from object storage (not implemented)\n\nEvery command but `new`, `deploy`, `doctor` and `restore-check` runs against the app at or above the working directory, or --dir.\n";
 export interface Io {
     out(line: string): void;
     err(line: string): void;

package/dist/cli.js

@@ -1,6 +1,7 @@
 import { parseArgs } from "node:util";
 import { bootstrapApp } from "./bootstrap.js";
 import { checkApp } from "./check.js";
+import { deployApp } from "./deploy-app.js";
 import { dev, devBuildSha } from "./dev.js";
 import { doctor, doctorLines } from "./doctor.js";
 import { generate } from "./gen.js";
@@ -20,6 +21,7 @@ export const COMMANDS = [
     "gen",
     "dev",
     "up",
+    "deploy",
     "doctor",
     "restore-check",
 ];
@@ -60,6 +62,11 @@ export const USAGE = `hf — the hyperfixation CLI
 
   hf check                  declared env, pending migrations, and E001-E006
 
+  hf deploy <name>          set SOURCE_COMMIT to a commit, deploy it, and wait until /api/status
+                            reports it. Coolify's push auto-deploy is off, so this is what
+                            publishes a merge to main
+      --sha <sha>             the commit to deploy (default: main's, via git ls-remote)
+
   hf doctor [name]          every deployed app in the state cache, or one: /api/status under its
                             read token, the deployed version against main, E006 as the app role,
                             the last restore check, and open core-bump PRs. Exits 1 on any finding
@@ -75,7 +82,7 @@ export const USAGE = `hf — the hyperfixation CLI
       --backup-dir <dir>      where the dumps are (default: Coolify's on the box)
       --from-s3               read the dump from object storage (not implemented)
 
-Every command but \`new\`, \`doctor\` and \`restore-check\` runs against the app at or above the working directory, or --dir.
+Every command but \`new\`, \`deploy\`, \`doctor\` and \`restore-check\` runs against the app at or above the working directory, or --dir.
 `;
 const consoleIo = {
     out: (line) => console.log(line),
@@ -125,6 +132,8 @@ async function dispatch(command, argv, io) {
             return await commandDev(argv, io);
         case "up":
             return await commandUp(argv, io);
+        case "deploy":
+            return await commandDeploy(argv, io);
         case "doctor":
             return await commandDoctor(argv, io);
         case "restore-check":
@@ -275,6 +284,21 @@ async function commandCheck(argv, io) {
         io.err(`${finding.code}: ${finding.message}`);
     return 1;
 }
+async function commandDeploy(argv, io) {
+    const { values, positionals } = parseArgs({
+        args: [...argv],
+        options: { sha: { type: "string" } },
+        allowPositionals: true,
+    });
+    const name = positionals[0];
+    if (name === undefined) {
+        io.err("hf deploy needs a name: hf deploy <name> [--sha <sha>]");
+        return 1;
+    }
+    // Every progress line the deploy prints — including the last one — is the command's output.
+    await deployApp({ app: name, sha: values.sha, io });
+    return 0;
+}
 async function commandDoctor(argv, io) {
     const { positionals } = parseArgs({ args: [...argv], allowPositionals: true });
     const result = await doctor({ name: positionals[0] });

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

@@ -1,17 +1,19 @@
 import type { Step } from "../new-cloud.js";
 import type { CloudStepContext } from "./context.js";
 /**
- * A daily dump of the app's database, and a checklist line about the one thing the API cannot
- * answer.
+ * A daily dump of the app's database, off the box.
  *
- * Every other step detects its own previous work by name; this one cannot. Coolify documents the
- * backups list as "Content is very complex. Will be implemented later.", so there is no response
- * to read a schedule out of, and a POST is the only way to find out anything at all. So the step
- * registers the schedule and says out loud that a duplicate from an earlier run is possible —
- * being told to look is better than a silent second dump, and better than a step that never runs
- * because it cannot prove it is needed.
+ * Coolify accepts `save_s3: true` with no `s3_storage_uuid`, runs the backup, logs `S3 storage
+ * configuration is missing or has been deleted (S3 storage ID: null). S3 backup has been disabled`
+ * and keeps the only copy on the same disk as the database — which is not a backup. So the storage
+ * is resolved first: `HF_COOLIFY_S3_STORAGE_UUID`, or the one usable storage on the box when there
+ * is exactly one. None or several and the step does not guess: it registers the schedule
+ * `save_s3: false` and says so in a warning and the closing checklist, because a schedule that is
+ * honestly local-only beats one that looks remote in the UI and is not.
  *
- * The state record is written by the runner once this resolves, so a failed POST leaves the step
- * unrecorded and the next run registers it instead.
+ * A rerun reconciles rather than duplicates: the schedules are listed and the one for this app's
+ * database is PATCHed. Coolify documents that list as "Content is very complex. Will be implemented
+ * later.", so the response is narrowed by hand and anything unreadable falls back to the old
+ * behaviour — register, and say out loud that a duplicate is possible.
  */
 export declare const backupStep: Step<CloudStepContext>;

package/dist/cloud-steps/backup.js

@@ -1,18 +1,21 @@
 import { requireOperatorConfig } from "../config.js";
 import { CoolifyClient } from "../providers/coolify.js";
+import { ProviderError } from "../providers/http.js";
 /**
- * A daily dump of the app's database, and a checklist line about the one thing the API cannot
- * answer.
+ * A daily dump of the app's database, off the box.
  *
- * Every other step detects its own previous work by name; this one cannot. Coolify documents the
- * backups list as "Content is very complex. Will be implemented later.", so there is no response
- * to read a schedule out of, and a POST is the only way to find out anything at all. So the step
- * registers the schedule and says out loud that a duplicate from an earlier run is possible —
- * being told to look is better than a silent second dump, and better than a step that never runs
- * because it cannot prove it is needed.
+ * Coolify accepts `save_s3: true` with no `s3_storage_uuid`, runs the backup, logs `S3 storage
+ * configuration is missing or has been deleted (S3 storage ID: null). S3 backup has been disabled`
+ * and keeps the only copy on the same disk as the database — which is not a backup. So the storage
+ * is resolved first: `HF_COOLIFY_S3_STORAGE_UUID`, or the one usable storage on the box when there
+ * is exactly one. None or several and the step does not guess: it registers the schedule
+ * `save_s3: false` and says so in a warning and the closing checklist, because a schedule that is
+ * honestly local-only beats one that looks remote in the UI and is not.
  *
- * The state record is written by the runner once this resolves, so a failed POST leaves the step
- * unrecorded and the next run registers it instead.
+ * A rerun reconciles rather than duplicates: the schedules are listed and the one for this app's
+ * database is PATCHed. Coolify documents that list as "Content is very complex. Will be implemented
+ * later.", so the response is narrowed by hand and anything unreadable falls back to the old
+ * behaviour — register, and say out loud that a duplicate is possible.
  */
 export const backupStep = {
     name: "backup",
@@ -24,17 +27,90 @@ export const backupStep = {
             token: required.HF_COOLIFY_TOKEN,
             fetch: context.fetch,
         });
-        await coolify.createDatabaseBackup(required.HF_COOLIFY_POSTGRES_UUID, {
+        const storage = await resolveStorage(context, coolify);
+        const schedule = {
             frequency: "daily",
             enabled: true,
             // This app's database alone: `dump_all` would put every app on the cluster in one dump, and
             // E5 restores one database at a time.
             databases_to_backup: names.databaseName,
             dump_all: false,
-            backup_now: false,
-        });
-        context.io.out(`${names.given}: registered a daily backup of ${names.databaseName}`);
-        context.checklist.push(`check Coolify for an existing backup schedule for ${names.databaseName} — the API cannot ` +
-            `list schedules, so an earlier run may have left a second one`);
+            ...(storage === undefined
+                ? { save_s3: false }
+                : { save_s3: true, s3_storage_uuid: storage }),
+        };
+        const where = storage === undefined ? "on the box only" : "to S3";
+        const database = required.HF_COOLIFY_POSTGRES_UUID;
+        const existing = await existingSchedule(coolify, database, names.databaseName);
+        if (typeof existing === "object") {
+            await coolify.updateDatabaseBackup(database, existing.uuid, schedule);
+            context.io.out(`${names.given}: updated the daily backup of ${names.databaseName} ${where}, ` +
+                `the schedule an earlier run registered`);
+            return;
+        }
+        await coolify.createDatabaseBackup(database, { ...schedule, backup_now: false });
+        context.io.out(`${names.given}: registered a daily backup of ${names.databaseName} ${where}`);
+        if (existing === "unreadable") {
+            context.checklist.push(`check Coolify for a second backup schedule for ${names.databaseName} — its backups list ` +
+                `could not be read, so an earlier run may have left one`);
+        }
     },
 };
+/**
+ * The S3 storage the dump goes to, or `undefined` with the reason said out loud.
+ *
+ * The config key wins outright and is not checked against the list: an operator who named a uuid
+ * has answered the question, and a `GET` that disagrees would only be a second opinion about a
+ * storage Coolify itself will validate.
+ */
+async function resolveStorage(context, coolify) {
+    const configured = context.config.HF_COOLIFY_S3_STORAGE_UUID;
+    if (configured !== undefined && configured !== "")
+        return configured;
+    const usable = (await coolify.listS3Storages()).filter((storage) => storage.is_usable === true);
+    if (usable.length === 1)
+        return usable[0].uuid;
+    const note = localOnlyNote(context.names.databaseName, usable);
+    context.io.out(`WARNING: ${context.names.given}: ${note}`);
+    context.checklist.push(note);
+    return undefined;
+}
+/** What is left to the operator when the step will not pick a storage for them. */
+function localOnlyNote(databaseName, usable) {
+    const problem = usable.length === 0
+        ? "Coolify has no usable S3 storage"
+        : `Coolify has ${String(usable.length)} usable S3 storages (${usable
+            .map((storage) => `${storage.name} (${storage.uuid})`)
+            .join(", ")}) and hf will not choose between them`;
+    return (`${databaseName}'s daily backup is local-only — every copy sits on the same box as the ` +
+        `database, so losing the box loses the data. ${problem}. Set HF_COOLIFY_S3_STORAGE_UUID to ` +
+        `the storage to upload to (Coolify → Storages → the S3 storage → uuid in the URL), adding ` +
+        `one there first if there is none, and re-run hf new.`);
+}
+/**
+ * This app's existing schedule, `"none"` for a list that has none, and `"unreadable"` for a list
+ * this cannot narrow — a shape upstream does not document, or a box that refuses the request.
+ */
+async function existingSchedule(coolify, databaseUuid, databaseName) {
+    let listed;
+    try {
+        listed = await coolify.listDatabaseBackups(databaseUuid);
+    }
+    catch (error) {
+        if (!(error instanceof ProviderError))
+            throw error;
+        return "unreadable";
+    }
+    if (!Array.isArray(listed))
+        return "unreadable";
+    for (const entry of listed) {
+        if (typeof entry !== "object" || entry === null)
+            return "unreadable";
+        const { uuid, databases_to_backup } = entry;
+        if (typeof uuid !== "string" || typeof databases_to_backup !== "string")
+            return "unreadable";
+        if (databases_to_backup === databaseName)
+            return { uuid };
+    }
+    return "none";
+}

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

@@ -19,9 +19,12 @@ 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";
 /**
- * Set by compose itself rather than by us: `DOCKER_IMAGE` has a default in the `x-app` anchor and
- * `SOURCE_COMMIT` is what Coolify's builder exports for the image tag and the build arg. Sending
- * either as an application environment variable would override the deploy's own.
+ * Interpolated by the compose file but never part of this step's bulk PATCH.
+ *
+ * `DOCKER_IMAGE` has a default in the `x-app` anchor. `SOURCE_COMMIT` is written by the `deploy`
+ * step instead, once per deployment and against the commit being deployed — it is not one of the
+ * app's secrets, so it belongs neither in `secretsHash` nor in a PATCH that a rotation replays.
+ * Both are excused here rather than counted as drift.
  */
 export declare const COMPOSE_PROVIDED_ENV: readonly ["DOCKER_IMAGE", "SOURCE_COMMIT"];
 /** Written literally into every `environment:` block, so the deploy never carries them. */

package/dist/cloud-steps/coolify.js

@@ -22,9 +22,12 @@ 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";
 /**
- * Set by compose itself rather than by us: `DOCKER_IMAGE` has a default in the `x-app` anchor and
- * `SOURCE_COMMIT` is what Coolify's builder exports for the image tag and the build arg. Sending
- * either as an application environment variable would override the deploy's own.
+ * Interpolated by the compose file but never part of this step's bulk PATCH.
+ *
+ * `DOCKER_IMAGE` has a default in the `x-app` anchor. `SOURCE_COMMIT` is written by the `deploy`
+ * step instead, once per deployment and against the commit being deployed — it is not one of the
+ * app's secrets, so it belongs neither in `secretsHash` nor in a PATCH that a rotation replays.
+ * Both are excused here rather than counted as drift.
  */
 export const COMPOSE_PROVIDED_ENV = ["DOCKER_IMAGE", "SOURCE_COMMIT"];
 /** Written literally into every `environment:` block, so the deploy never carries them. */
@@ -267,6 +270,10 @@ async function findOrCreateApplication(context, coolify, projectUuid, environmen
         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,
+        // Coolify's default is true: a push to main would then deploy whatever arrived against
+        // whatever `SOURCE_COMMIT` happened to hold, and the app would report a version it is not
+        // running. Every deploy goes through `hf` — `hf new`'s tenth step, or `hf deploy <name>`.
+        is_auto_deploy_enabled: false,
     });
     await context.state.patch({ coolify: { appUuid: created.uuid } });
     context.io.out(`${name}: created the Coolify application at https://${fqdn}`);

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

@@ -1,5 +1,7 @@
 import type { Step } from "../new-cloud.js";
-import { type CloudStepContext } from "./context.js";
+import { CoolifyClient } from "../providers/coolify.js";
+import type { FetchLike } from "../providers/http.js";
+import { type CloudStepContext, type StepOut } from "./context.js";
 /**
  * How long the step waits for Coolify to build and for the app to report the sha it built.
  *
@@ -7,6 +9,41 @@ import { type CloudStepContext } from "./context.js";
  * the right version, and a build that took fourteen minutes has not left time for anything else.
  */
 export declare const DEPLOY_TIMEOUT_MS: number;
+/**
+ * The compose variable that carries the deployed commit, and the one channel there is for it.
+ *
+ * Coolify's docker-compose build pack passes the commit into nothing: no `--build-arg`, nothing
+ * in the compose environment, and no `.git` in the build context even with
+ * `is_preserve_repository_enabled` — so the Dockerfile's `git rev-parse HEAD` fallback cannot run
+ * there either, and the worker dies at startup on an unresolved `HF_BUILD_SHA` (verified on the
+ * box, 4.3.21). What Coolify *does* do is materialise an application environment entry for every
+ * `${VAR}` the compose file interpolates, which is what this fills in before every deploy.
+ */
+export declare const SOURCE_COMMIT_ENV = "SOURCE_COMMIT";
+/** One deployment of one commit: everything `deployCommit` needs that a step context also has. */
+export interface DeployTarget {
+    /** The app as the state cache names it — the prefix on every line this prints. */
+    name: string;
+    appUuid: string;
+    fqdn: string;
+    /** The exact commit being deployed; `/api/status` has to report this one. */
+    sha: string;
+    /** `/api/status`'s read token, which is the only way to ask what the app is running. */
+    readToken: string;
+    coolify: CoolifyClient;
+    io: StepOut;
+    now(): number;
+    sleep(ms: number): Promise<void>;
+    fetch?: FetchLike;
+}
+/**
+ * `SOURCE_COMMIT`, then the deploy, then the wait — in that order and never another.
+ *
+ * The environment write is what the build reads, so a deploy triggered first would build the
+ * previous commit's tag and the wait would then time out against a version the app is right to
+ * report. Both `hf new`'s tenth step and `hf deploy` come through here for that reason.
+ */
+export declare function deployCommit(target: DeployTarget): Promise<void>;
 /**
  * Deploy, wait for the build, then wait for the app to say it is running that commit.
  *

package/dist/cloud-steps/deploy.js

@@ -12,6 +12,37 @@ const FIRST_POLL_MS = 2_000;
 const MAX_POLL_MS = 15_000;
 /** Coolify's one terminal success; `failed` and `cancelled-*` are the terminal failures. */
 const FINISHED = "finished";
+/**
+ * The compose variable that carries the deployed commit, and the one channel there is for it.
+ *
+ * Coolify's docker-compose build pack passes the commit into nothing: no `--build-arg`, nothing
+ * in the compose environment, and no `.git` in the build context even with
+ * `is_preserve_repository_enabled` — so the Dockerfile's `git rev-parse HEAD` fallback cannot run
+ * there either, and the worker dies at startup on an unresolved `HF_BUILD_SHA` (verified on the
+ * box, 4.3.21). What Coolify *does* do is materialise an application environment entry for every
+ * `${VAR}` the compose file interpolates, which is what this fills in before every deploy.
+ */
+export const SOURCE_COMMIT_ENV = "SOURCE_COMMIT";
+/**
+ * `SOURCE_COMMIT`, then the deploy, then the wait — in that order and never another.
+ *
+ * The environment write is what the build reads, so a deploy triggered first would build the
+ * previous commit's tag and the wait would then time out against a version the app is right to
+ * report. Both `hf new`'s tenth step and `hf deploy` come through here for that reason.
+ */
+export async function deployCommit(target) {
+    const deadline = target.now() + DEPLOY_TIMEOUT_MS;
+    await setSourceCommit(target);
+    const { deployments } = await target.coolify.deploy(target.appUuid, { force: true });
+    const deploymentUuid = deployments[0]?.deployment_uuid;
+    if (deploymentUuid === undefined) {
+        throw new StepFailed(`Coolify accepted the deploy of ${target.name} but named no deployment`);
+    }
+    target.io.out(`${target.name}: deployment ${deploymentUuid} queued`);
+    await waitForBuild(target, deploymentUuid, deadline);
+    await waitForVersion(target, deadline);
+    target.io.out(`${target.name}: serving ${short(target.sha)} at https://${target.fqdn}`);
+}
 /**
  * Deploy, wait for the build, then wait for the app to say it is running that commit.
  *
@@ -32,59 +63,92 @@ export const deployStep = {
         if (sha === undefined) {
             throw new StepFailed(`${context.dir} has no commit to deploy: the install step has not run`);
         }
+        const fqdn = appFqdn(context);
+        const readToken = context.state.state.statusTokens?.read;
+        if (readToken === undefined) {
+            throw new StepFailed(`no read status token in the state cache: nothing can ask https://${fqdn}/api/status ` +
+                "what it is running");
+        }
         const required = requireOperatorConfig(context.config, ["HF_COOLIFY_URL", "HF_COOLIFY_TOKEN"], { env: context.env });
-        const coolify = new CoolifyClient({
-            url: required.HF_COOLIFY_URL,
-            token: required.HF_COOLIFY_TOKEN,
+        await deployCommit({
+            name: names.given,
+            appUuid,
+            fqdn,
+            sha,
+            readToken,
+            coolify: new CoolifyClient({
+                url: required.HF_COOLIFY_URL,
+                token: required.HF_COOLIFY_TOKEN,
+                fetch: context.fetch,
+            }),
+            io: context.io,
+            now: context.now,
+            sleep: context.sleep,
             fetch: context.fetch,
         });
-        const deadline = context.now() + DEPLOY_TIMEOUT_MS;
-        const { deployments } = await coolify.deploy(appUuid, { force: true });
-        const deploymentUuid = deployments[0]?.deployment_uuid;
-        if (deploymentUuid === undefined) {
-            throw new StepFailed(`Coolify accepted the deploy of ${names.given} but named no deployment`);
-        }
-        context.io.out(`${names.given}: deployment ${deploymentUuid} queued`);
-        await waitForBuild(context, coolify, deploymentUuid, deadline);
-        await waitForVersion(context, sha, deadline);
         await context.state.patch({ lastDeployedSha: sha });
-        context.io.out(`${names.given}: serving ${short(sha)} at https://${appFqdn(context)}`);
     },
 };
-async function waitForBuild(context, coolify, deploymentUuid, deadline) {
+/**
+ * Points `SOURCE_COMMIT` at the commit about to be deployed, creating the entry if it is absent.
+ *
+ * Idempotent, and deliberately outside the `coolify` step's bulk PATCH: this is a value `hf` sets
+ * per deploy rather than one of the app's secrets, so it is neither in `secretsHash` nor in what
+ * `assertEnvsMatchCompose` compares. Every entry Coolify lists under the name is written, because
+ * a compose parse materialises a preview entry beside the non-preview one and the deploy reads
+ * its own.
+ */
+async function setSourceCommit(target) {
+    const existing = (await target.coolify.listEnvs(target.appUuid)).filter((entry) => entry.key === SOURCE_COMMIT_ENV);
+    const variable = {
+        key: SOURCE_COMMIT_ENV,
+        value: target.sha,
+        is_buildtime: true,
+        is_runtime: true,
+    };
+    if (existing.length === 0) {
+        await target.coolify.createEnv(target.appUuid, variable);
+    }
+    else {
+        for (const entry of existing) {
+            await target.coolify.updateEnv(target.appUuid, {
+                ...variable,
+                is_preview: entry.is_preview ?? false,
+            });
+        }
+    }
+    target.io.out(`${target.name}: ${SOURCE_COMMIT_ENV}=${short(target.sha)} set in Coolify`);
+}
+async function waitForBuild(target, deploymentUuid, deadline) {
     for (let wait = FIRST_POLL_MS;; wait = Math.min(wait * 2, MAX_POLL_MS)) {
-        const deployment = await coolify.getDeployment(deploymentUuid);
+        const deployment = await target.coolify.getDeployment(deploymentUuid);
         if (deployment.status === FINISHED)
             return;
         if (deployment.status.startsWith("failed") || deployment.status.startsWith("cancelled")) {
             throw new StepFailed(`Coolify deployment ${deploymentUuid} ended ${deployment.status}: read the build log in ` +
                 "Coolify, fix it, and re-run hf new");
         }
-        if (context.now() >= deadline) {
+        if (target.now() >= deadline) {
             throw new StepFailed(`Coolify deployment ${deploymentUuid} was still ${deployment.status} after ` +
                 `${String(DEPLOY_TIMEOUT_MS / 60_000)} minutes`);
         }
-        await context.sleep(wait);
+        await target.sleep(wait);
     }
 }
 /**
- * Polls `/api/status` under the read token until it reports `sha`.
+ * Polls `/api/status` under the read token until it reports `target.sha`.
  *
  * A refusal or an unparseable answer is not a failure here — the containers are restarting, and the
  * old ones answer until the new ones are healthy — so only the deadline ends this loop.
  */
-async function waitForVersion(context, sha, deadline) {
-    const url = `https://${appFqdn(context)}/api/status`;
-    const token = context.state.state.statusTokens?.read;
-    if (token === undefined) {
-        throw new StepFailed(`no read status token in the state cache: nothing can ask ${url} what it is running`);
-    }
-    const doFetch = context.fetch ?? ((input, init) => globalThis.fetch(input, init));
+async function waitForVersion(target, deadline) {
+    const url = `https://${target.fqdn}/api/status`;
+    const doFetch = target.fetch ?? ((input, init) => globalThis.fetch(input, init));
     let last = "nothing yet";
     for (let wait = FIRST_POLL_MS;; wait = Math.min(wait * 2, MAX_POLL_MS)) {
         try {
             const response = await doFetch(url, {
-                headers: { authorization: `Bearer ${token}`, accept: "application/json" },
+                headers: { authorization: `Bearer ${target.readToken}`, accept: "application/json" },
             });
             if (!response.ok) {
                 last = `HTTP ${String(response.status)}`;
@@ -92,7 +156,7 @@ async function waitForVersion(context, sha, deadline) {
             else {
                 const report = (await response.json());
                 const version = report.applicationVersion;
-                if (version === sha)
+                if (version === target.sha)
                     return;
                 last = version === null ? "no applicationVersion" : `applicationVersion ${short(version)}`;
             }
@@ -100,11 +164,11 @@ async function waitForVersion(context, sha, deadline) {
         catch (error) {
             last = error.message;
         }
-        if (context.now() >= deadline) {
-            throw new StepFailed(`${url} never reported ${short(sha)} within ` +
+        if (target.now() >= deadline) {
+            throw new StepFailed(`${url} never reported ${short(target.sha)} within ` +
                 `${String(DEPLOY_TIMEOUT_MS / 60_000)} minutes (last: ${last}). The build finished, so ` +
-                "check that SOURCE_COMMIT reached the image — hf doctor reports the same mismatch.");
+                `check that ${SOURCE_COMMIT_ENV} reached the image — hf doctor reports the same mismatch.`);
         }
-        await context.sleep(wait);
+        await target.sleep(wait);
     }
 }

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_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 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_COOLIFY_S3_STORAGE_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>>;

package/dist/config.js

@@ -12,6 +12,11 @@ export const CONFIG_KEYS = [
     "HF_COOLIFY_SERVER_UUID",
     "HF_COOLIFY_GITHUB_APP_UUID",
     "HF_COOLIFY_POSTGRES_UUID",
+    // Optional: the Coolify S3 storage the daily dump is uploaded to. Unset, the backup step asks
+    // `GET /s3-storages` and takes the one usable storage when there is exactly one; this is how a
+    // box with several — or with one the step should not pick — is told which, rather than guessed
+    // at. With neither the schedule is registered local-only and the step warns.
+    "HF_COOLIFY_S3_STORAGE_UUID",
     // The Postgres container's hostname on the docker network, as the app's containers see it.
     // Configurable because Coolify's API document reports no such field: its own compose generator
     // names the container after the database's uuid, so `HF_COOLIFY_POSTGRES_UUID` is the default a

package/dist/database.d.ts

@@ -29,6 +29,14 @@ export interface Database {
         host: string;
         port: number;
     };
+    /**
+     * The Postgres container this cluster runs in, when opening it had to discover one.
+     *
+     * What `hf restore-check` runs `pg_restore` inside: the box host has no Postgres client tools,
+     * only the container does. `undefined` when the box's own loopback answered and no container
+     * was ever looked for.
+     */
+    readonly container?: string;
     /** 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>;
@@ -93,3 +101,15 @@ export declare const DEFAULT_POSTGRES_PORT = 5432;
 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. */
 export declare function openDatabaseUrl(adminUrl: string): Database;
+/**
+ * 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.
+ */
+export declare function findPostgresContainer(runner: Runner, containers: readonly string[]): Promise<{
+    container: string;
+    address: string;
+}>;