@hyperfixation/cli 0.1.5 → 0.1.7

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", "version"];
 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                            write both bootstrap answers into its .env\n      --budget-usd <amount>   the app's monthly LLM budget (required; no default)\n      --email <address>       the bootstrap admin's address (required)\n      --from <dir>            template checkout (default: the sibling hyperfixation-template)\n      --into <dir>            where to create <name> (default: the working directory)\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 box's connection slots, the worker's advisory lock, the last\n                            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. An append-only table the live side has moved\n                            on from reads ok (drift +N); exits 1 on any mismatch, and on a\n                            dump older than 24 h\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      --strict                compare every table exactly; no table may drift\n\n  hf version                the @hyperfixation/cli version behind this hf, also as --version, -v\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";
@@ -11,6 +12,7 @@ import { formatRestoreCheck, restoreCheckApp } from "./restore-check.js";
 import { statusTokenApp } from "./status-token.js";
 import { requireTemplateSource } from "./template-source.js";
 import { DEV_BUDGET_USD, upApp } from "./up.js";
+import { cliVersion } from "./version.js";
 export const COMMANDS = [
     "new",
     "migrate",
@@ -20,8 +22,10 @@ export const COMMANDS = [
     "gen",
     "dev",
     "up",
+    "deploy",
     "doctor",
     "restore-check",
+    "version",
 ];
 export const USAGE = `hf — the hyperfixation CLI
 
@@ -36,10 +40,11 @@ export const USAGE = `hf — the hyperfixation CLI
       --into <dir>            where to create <name> (default: the working directory)
 
   hf new <name> --local     copy the template into ./<name>, substitute its placeholders, and
-                            prompt for the bootstrap admin's email
+                            write both bootstrap answers into its .env
+      --budget-usd <amount>   the app's monthly LLM budget (required; no default)
+      --email <address>       the bootstrap admin's address (required)
       --from <dir>            template checkout (default: the sibling hyperfixation-template)
       --into <dir>            where to create <name> (default: the working directory)
-      --email <address>       the bootstrap admin's address; skips the prompt
 
   hf up                     install, infra, migrate, bootstrap, status tokens, then hf dev —
                             the whole local loop after hf new, safe to rerun; seeds a $10
@@ -60,9 +65,15 @@ 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
+                            the box's connection slots, the worker's advisory lock, the last
+                            restore check, and open core-bump PRs. Exits 1 on any finding
 
   hf gen [generator]        the app's turbo generators
 
@@ -71,11 +82,16 @@ export const USAGE = `hf — the hyperfixation CLI
       --compose-only          bring the infrastructure up and stop
 
   hf restore-check <name>   restore the newest hf_<name> dump beside the live database and
-                            compare row counts; exits 1 on any mismatch
+                            compare row counts. An append-only table the live side has moved
+                            on from reads ok (drift +N); exits 1 on any mismatch, and on a
+                            dump older than 24 h
       --backup-dir <dir>      where the dumps are (default: Coolify's on the box)
       --from-s3               read the dump from object storage (not implemented)
+      --strict                compare every table exactly; no table may drift
 
-Every command but \`new\`, \`doctor\` and \`restore-check\` runs against the app at or above the working directory, or --dir.
+  hf version                the @hyperfixation/cli version behind this hf, also as --version, -v
+
+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),
@@ -94,6 +110,10 @@ export async function main(argv, io = consoleIo) {
         io.out(USAGE);
         return command === undefined ? 1 : 0;
     }
+    if (command === "--version" || command === "-v") {
+        io.out(await cliVersion());
+        return 0;
+    }
     if (!COMMANDS.includes(command)) {
         io.err(`unknown command ${JSON.stringify(command)}`);
         io.err(USAGE);
@@ -125,10 +145,15 @@ 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":
             return await commandRestoreCheck(argv, io);
+        case "version":
+            io.out(await cliVersion());
+            return 0;
     }
 }
 async function commandNew(argv, io) {
@@ -151,6 +176,15 @@ async function commandNew(argv, io) {
     if (!values.local) {
         return await commandNewCloud(name, values, io);
     }
+    // Refused here rather than prompted for: `hf up` reads both out of the app's `.env`, so a
+    // local app started without them is the same half-answered app the cloud path has refused
+    // since Phase 3 — one that either cannot spend or cannot stop.
+    const missing = missingBootstrapFlags(values);
+    if (missing.length > 0) {
+        io.err(`hf new ${name} --local needs ${missing.join(" and ")}: hf up reads both from the app's ` +
+            ".env and neither has a default.");
+        return 1;
+    }
     const from = values.from ?? (await requireTemplateSource());
     const result = await newApp({
         name,
@@ -158,29 +192,35 @@ async function commandNew(argv, io) {
         into: values.into,
         local: values.local,
         email: values.email,
+        budgetUsd: values["budget-usd"],
     });
     io.out(`created ${result.dir} from ${from}`);
     io.out(`  app ${result.appName}, database ${result.databaseName}`);
     io.out(`  ${result.substituted.length} file(s) substituted` +
         (result.wroteEnv ? ", .env written from .env.example" : "") +
-        (result.wroteBootstrapEmail ? ", HF_BOOTSTRAP_EMAIL set" : ""));
+        (result.wroteBootstrapEmail ? ", HF_BOOTSTRAP_EMAIL set" : "") +
+        (result.wroteBootstrapBudget ? ", HF_BOOTSTRAP_BUDGET_USD set" : ""));
     io.out("");
     io.out(`next: cd ${result.given} && hf up`);
     return 0;
 }
 /**
- * The cloud half: both inputs it cannot invent are refused up front.
+ * The two answers `hf new` cannot invent, named in the order the usage lists them.
  *
- * Neither has a default. `--email` designates the one admin an app is ever granted without an
- * admin behind it, and a budget nobody chose is a deployed app that either cannot spend or
- * cannot stop — `hf bootstrap` has refused an unset one since Phase 1, and this is the same rule
- * one command earlier, where the answer costs nothing yet.
+ * `--email` designates the one admin an app is ever granted without an admin behind it, and a
+ * budget nobody chose is an app that either cannot spend or cannot stop — `hf bootstrap` has
+ * refused an unset one since Phase 1, and this is the same rule one command earlier, where the
+ * answer costs nothing yet.
  */
-async function commandNewCloud(name, values, io) {
-    const missing = [
+function missingBootstrapFlags(values) {
+    return [
         ...(values["budget-usd"] === undefined ? ["--budget-usd <amount>"] : []),
         ...(values.email === undefined ? ["--email <address>"] : []),
     ];
+}
+/** The cloud half: both inputs are refused up front, with nowhere else to carry them. */
+async function commandNewCloud(name, values, io) {
+    const missing = missingBootstrapFlags(values);
     if (missing.length > 0) {
         io.err(`hf new ${name} needs ${missing.join(" and ")}: a cloud app has no prompt and no .env to ` +
             "carry either. Pass --local for Phase 1's local copy.");
@@ -275,6 +315,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] });
@@ -318,6 +373,7 @@ async function commandRestoreCheck(argv, io) {
         options: {
             "backup-dir": { type: "string" },
             "from-s3": { type: "boolean", default: false },
+            strict: { type: "boolean", default: false },
         },
         allowPositionals: true,
     });
@@ -330,6 +386,7 @@ async function commandRestoreCheck(argv, io) {
         app: name,
         backupDir: values["backup-dir"],
         fromS3: values["from-s3"],
+        strict: values.strict,
     });
     for (const line of formatRestoreCheck(result))
         io.out(line);

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/cloud-steps/template.d.ts

@@ -1,12 +1,7 @@
 import type { Step } from "../new-cloud.js";
+import { templateTempDir } from "../new.js";
 import { type CloudStepContext } from "./context.js";
-/**
- * Where the fetch lands before it becomes the app.
- *
- * Beside the target rather than under `os.tmpdir()`, so the rename is a rename and not a second
- * copy across filesystems, and dot-prefixed so a half-fetched tree does not look like an app.
- */
-export declare function templateTempDir(dir: string): string;
+export { templateTempDir };
 /**
  * The app's files: giget's fetch of the template, substituted, renamed into place.
  *

package/dist/cloud-steps/template.js

@@ -1,16 +1,8 @@
 import { readFile, rename, rm } from "node:fs/promises";
 import path from "node:path";
-import { substituteTree, TEMPLATE_MARKER, TemplateError } from "../new.js";
+import { scratchInTheWay, substituteTree, targetInTheWay, templateTempDir, TEMPLATE_MARKER, TemplateError, } from "../new.js";
 import { exists } from "./context.js";
-/**
- * Where the fetch lands before it becomes the app.
- *
- * Beside the target rather than under `os.tmpdir()`, so the rename is a rename and not a second
- * copy across filesystems, and dot-prefixed so a half-fetched tree does not look like an app.
- */
-export function templateTempDir(dir) {
-    return path.join(path.dirname(dir), `.${path.basename(dir)}.hf-new`);
-}
+export { templateTempDir };
 /**
  * The app's files: giget's fetch of the template, substituted, renamed into place.
  *
@@ -32,7 +24,15 @@ export const templateStep = {
             return;
         }
         const temp = templateTempDir(dir);
-        await rm(temp, { recursive: true, force: true });
+        if (await exists(temp)) {
+            // Cleared only on a resume, by the same rule the target directory gets: `fetchStartedAt`
+            // says a run of *this* app fetched into that path, and without it the directory is someone
+            // else's however much its name looks like ours.
+            if (context.state.state.templateFetchStartedAt === undefined)
+                throw scratchInTheWay(temp);
+            await rm(temp, { recursive: true, force: true });
+        }
+        await context.state.patch({ templateFetchStartedAt: new Date(context.now()).toISOString() });
         const fetched = await context.fetchTemplate(context.from, temp);
         await substituteTree(fetched, names);
         // The marker is what `assertTemplateSource` looks for: an app is never a template twice.
@@ -66,7 +66,7 @@ async function adoptOrRefuse(context) {
     }
     const substituted = !(await exists(path.join(dir, TEMPLATE_MARKER))) && (await packageName(dir)) === names.appName;
     if (!substituted) {
-        throw new TemplateError(`${dir} already exists; hf new will not write into it`);
+        throw targetInTheWay(dir);
     }
     context.io.out(`${names.given}: adopting the app directory already at ${dir}`);
 }

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