@hyperfixation/cli 0.1.5 → 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/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/deploy-app.d.ts

@@ -0,0 +1,32 @@
+import { type StepExec, type StepOut } from "./cloud-steps/index.js";
+import { type OperatorConfig } from "./config.js";
+import type { FetchLike } from "./providers/http.js";
+export interface DeployAppOptions {
+    /** The app as `hf new` named it, which is also its state file's name. */
+    app: string;
+    /** The commit to deploy. Defaults to `main`'s on the app's own repository. */
+    sha?: string;
+    io: StepOut;
+    config?: OperatorConfig;
+    /** Where the per-app state files are. Defaults to `stateDir()`. */
+    stateDir?: string;
+    env?: NodeJS.ProcessEnv;
+    fetch?: FetchLike;
+    exec?: StepExec;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface DeployAppResult {
+    app: string;
+    /** The commit the app answered `/api/status` with before this returned. */
+    sha: string;
+    url: string;
+}
+/**
+ * `hf deploy <name>` — point the app at a commit and wait until it says it is serving it.
+ *
+ * The same path as `hf new`'s tenth step, and the reason there is a command at all: auto-deploy
+ * is off, so a merge to main changes nothing on the box until this runs. Everything it needs is
+ * in the state cache the provisioning run wrote; nothing here is interactive.
+ */
+export declare function deployApp(options: DeployAppOptions): Promise<DeployAppResult>;

package/dist/deploy-app.js

@@ -0,0 +1,81 @@
+import { deployCommit } from "./cloud-steps/deploy.js";
+import { spawnStepExec, StepFailed } from "./cloud-steps/index.js";
+import { gitAuthEnv } from "./cloud-steps/repo.js";
+import { loadOperatorConfig, requireOperatorConfig } from "./config.js";
+import { deriveNames } from "./names.js";
+import { CoolifyClient } from "./providers/coolify.js";
+import { openAppState } from "./state.js";
+/** What a commit looks like once `git` has resolved it; `/api/status` reports the same form. */
+const FULL_SHA = /^[0-9a-f]{40}$/;
+/**
+ * `hf deploy <name>` — point the app at a commit and wait until it says it is serving it.
+ *
+ * The same path as `hf new`'s tenth step, and the reason there is a command at all: auto-deploy
+ * is off, so a merge to main changes nothing on the box until this runs. Everything it needs is
+ * in the state cache the provisioning run wrote; nothing here is interactive.
+ */
+export async function deployApp(options) {
+    const env = options.env ?? process.env;
+    const config = options.config ?? (await loadOperatorConfig({ env }));
+    const names = deriveNames(options.app);
+    const required = requireOperatorConfig(config, ["HF_COOLIFY_URL", "HF_COOLIFY_TOKEN", "HF_BASE_DOMAIN", "HF_GITHUB_TOKEN"], { env });
+    const store = await openAppState(names.given, { dir: options.stateDir, env });
+    const { coolify, statusTokens, repo } = store.state;
+    const appUuid = coolify?.appUuid;
+    const readToken = statusTokens?.read;
+    if (appUuid === undefined || readToken === undefined) {
+        const missing = appUuid === undefined ? "Coolify application uuid" : "read status token";
+        throw new StepFailed(`${store.file} has no ${missing}: hf new has not finished provisioning ${names.given}`);
+    }
+    const sha = options.sha === undefined
+        ? await mainSha(options, repo, required.HF_GITHUB_TOKEN)
+        : options.sha;
+    if (!FULL_SHA.test(sha)) {
+        throw new StepFailed(`${sha} is not a commit sha: --sha takes the full forty hex characters, because that is ` +
+            "what /api/status reports back");
+    }
+    const fqdn = `${names.given}.${required.HF_BASE_DOMAIN}`;
+    await deployCommit({
+        name: names.given,
+        appUuid,
+        fqdn,
+        sha,
+        readToken,
+        coolify: new CoolifyClient({
+            url: required.HF_COOLIFY_URL,
+            token: required.HF_COOLIFY_TOKEN,
+            fetch: options.fetch,
+        }),
+        io: options.io,
+        now: options.now ?? (() => Date.now()),
+        sleep: options.sleep ?? (async (ms) => await new Promise((resolve) => setTimeout(resolve, ms))),
+        fetch: options.fetch,
+    });
+    await store.patch({ lastDeployedSha: sha });
+    return { app: names.given, sha, url: `https://${fqdn}` };
+}
+/**
+ * `main`'s sha on the app's repository, read with `git ls-remote` and no checkout.
+ *
+ * The remote rather than a local clone: the operator running this has just merged a pull request,
+ * and whatever is in a directory on the laptop is not what the box would build.
+ */
+async function mainSha(options, repo, token) {
+    if (repo === undefined) {
+        throw new StepFailed(`no owner/name repository in ${options.app}'s state cache: nothing can be asked what main ` +
+            "is. Pass --sha <sha>.");
+    }
+    const url = `https://github.com/${repo}.git`;
+    const exec = options.exec ?? spawnStepExec;
+    const outcome = await exec("git", ["ls-remote", url, "refs/heads/main"], {
+        cwd: process.cwd(),
+        capture: true,
+        env: gitAuthEnv(token),
+    });
+    const sha = /^([0-9a-f]{40})\s/.exec(outcome.stdout.trim())?.[1];
+    if (outcome.code !== 0 || sha === undefined) {
+        throw new StepFailed(`git ls-remote ${url} refs/heads/main named no commit: the repository may be gone, the ` +
+            "branch unborn, or HF_GITHUB_TOKEN unable to read it. Pass --sha <sha>.");
+    }
+    return sha;
+}

package/dist/doctor.js

@@ -142,7 +142,7 @@ async function doctorApp(context, name) {
         }
     }
     const report = await statusFindings(context, name, state, add);
-    versionFinding(report?.applicationVersion, mainSha, mainShaProblem, add);
+    versionFinding(name, report?.applicationVersion, mainSha, mainShaProblem, add);
     if (report?.budget !== undefined) {
         budgetFinding(report.budget.current, "current", add);
         budgetFinding(report.budget.previous, "previous", add);
@@ -232,7 +232,14 @@ function amount(value) {
     const parsed = Number(value);
     return Number.isFinite(parsed) ? parsed : undefined;
 }
-function versionFinding(deployed, mainSha, mainShaProblem, add) {
+/**
+ * What the app answers against what its repository's main holds.
+ *
+ * The mismatch names `hf deploy` because nothing else closes it: Coolify's push auto-deploy is
+ * disabled on every application `hf new` creates, so a merged pull request sits unpublished until
+ * an operator says so.
+ */
+function versionFinding(name, deployed, mainSha, mainShaProblem, add) {
     if (mainShaProblem !== undefined) {
         add("version", "fail", mainShaProblem);
         return;
@@ -245,7 +252,7 @@ function versionFinding(deployed, mainSha, mainShaProblem, add) {
     }
     add("version", deployed === mainSha ? "ok" : "warn", deployed === mainSha
         ? `applicationVersion ${short(mainSha)} is main`
-        : `applicationVersion ${short(deployed)} is not main ${short(mainSha)}`);
+        : `applicationVersion ${short(deployed)} is not main ${short(mainSha)} — run hf deploy ${name}`);
 }
 function budgetFinding(period, which, add) {
     if (period === null) {

package/dist/providers/coolify.d.ts

@@ -80,6 +80,23 @@ export interface CoolifyEnvironmentVariable {
     is_literal?: boolean;
     is_multiline?: boolean;
     is_shown_once?: boolean;
+    /**
+     * Whether the builder interpolates the variable, and whether the containers get it.
+     *
+     * Both default true in Coolify's UI and neither is in the document's *request* schemas —
+     * only in its `EnvironmentVariable` model — but the box accepts and stores them (verified
+     * against 4.3.21). `SOURCE_COMMIT` needs both: it is the compose image tag and build arg as
+     * well as the `HF_BUILD_SHA` three services read.
+     */
+    is_buildtime?: boolean;
+    is_runtime?: boolean;
+}
+/** One entry of `GET /applications/{uuid}/envs`, narrowed to what an upsert has to match on. */
+export interface CoolifyEnvEntry {
+    uuid: string;
+    key: string;
+    value?: string;
+    is_preview?: boolean;
 }
 export interface CoolifyDeploymentRequest {
     deployments: {
@@ -171,6 +188,13 @@ export declare class CoolifyClient {
         tag?: string;
     }): Promise<CoolifyApplicationSummary[]>;
     updateEnvsBulk(appUuid: string, data: readonly CoolifyEnvironmentVariable[]): Promise<unknown>;
+    /** Every environment variable on the application, preview and non-preview alike. */
+    listEnvs(appUuid: string): Promise<CoolifyEnvEntry[]>;
+    createEnv(appUuid: string, variable: CoolifyEnvironmentVariable): Promise<{
+        uuid: string;
+    }>;
+    /** Keyed by `key` — and by `is_preview`, which is why an upsert sends the entry's own flag. */
+    updateEnv(appUuid: string, variable: CoolifyEnvironmentVariable): Promise<unknown>;
     deploy(uuid: string, options?: {
         force?: boolean;
     }): Promise<CoolifyDeploymentRequest>;

package/dist/providers/coolify.js

@@ -55,6 +55,27 @@ export class CoolifyClient {
             secrets: data.map((variable) => variable.value),
         });
     }
+    /** Every environment variable on the application, preview and non-preview alike. */
+    async listEnvs(appUuid) {
+        return await this.request({ method: "GET", path: `/applications/${segment(appUuid)}/envs` });
+    }
+    async createEnv(appUuid, variable) {
+        return await this.request({
+            method: "POST",
+            path: `/applications/${segment(appUuid)}/envs`,
+            body: variable,
+            secrets: [variable.value],
+        });
+    }
+    /** Keyed by `key` — and by `is_preview`, which is why an upsert sends the entry's own flag. */
+    async updateEnv(appUuid, variable) {
+        return await this.request({
+            method: "PATCH",
+            path: `/applications/${segment(appUuid)}/envs`,
+            body: variable,
+            secrets: [variable.value],
+        });
+    }
     async deploy(uuid, options = {}) {
         return await this.request({
             method: "POST",

package/package.json

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