@hyperfixation/cli 0.1.3 → 0.1.5

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.js

@@ -233,12 +233,11 @@ async function findOrCreateProject(context, coolify) {
 async function productionEnvironment(context, coolify, projectUuid) {
     const environments = await coolify.listEnvironments(projectUuid);
     const production = environments.find((environment) => environment.name === COOLIFY_ENVIRONMENT);
-    if (production === undefined) {
-        throw new StepFailed(`the Coolify project ${context.names.given} has no ${COOLIFY_ENVIRONMENT} environment ` +
-            `(it has ${environments.map((environment) => environment.name).join(", ") || "none"}), ` +
-            "and the API has no endpoint that creates one: add it in Coolify and re-run hf new");
-    }
-    return production.uuid;
+    if (production !== undefined)
+        return production.uuid;
+    const created = await coolify.createEnvironment(projectUuid, { name: COOLIFY_ENVIRONMENT });
+    context.io.out(`${context.names.given}: created the ${COOLIFY_ENVIRONMENT} environment in the Coolify project`);
+    return created.uuid;
 }
 async function findOrCreateApplication(context, coolify, projectUuid, environmentUuid) {
     const name = context.names.given;

package/dist/cloud-steps/template.js

@@ -37,19 +37,33 @@ export const templateStep = {
         await substituteTree(fetched, names);
         // The marker is what `assertTemplateSource` looks for: an app is never a template twice.
         await rm(path.join(fetched, TEMPLATE_MARKER));
+        // Recorded before the rename, not after: a crash between the two must leave a directory this
+        // run's state vouches for, or the rerun would refuse the app it just made.
+        await context.state.patch({ templateStartedAt: new Date(context.now()).toISOString() });
         await rename(fetched, dir);
         context.io.out(`${names.given}: template fetched into ${dir}`);
     },
 };
 /**
- * A directory already at the target: this app on a run whose state was lost, or something else.
+ * A directory already at the target: this app on a run that crashed after the rename, or
+ * something else.
  *
- * "This app" means a substituted template — its `package.json` carries the underscored app name
- * and the marker is gone. Anything else is the local flow's rule, refused rather than written
- * into.
+ * Adopted only on a genuine resume — the state cache records that this app's template step began
+ * (`templateStartedAt`) or finished. With no such record the directory is not ours however much it
+ * looks like it: an earlier `hf new --local` leaves a substituted scaffold with the right
+ * `package.json` name, and adopting it once pushed a stale template to a new repo.
+ *
+ * On a resume, "this app" means a substituted template — its `package.json` carries the
+ * underscored app name and the marker is gone. Anything else is the local flow's rule, refused
+ * rather than written into.
  */
 async function adoptOrRefuse(context) {
-    const { dir, names } = context;
+    const { dir, names, state } = context;
+    const resuming = state.state.templateStartedAt !== undefined || state.isDone("template");
+    if (!resuming) {
+        throw new TemplateError(`${dir} already exists and hf has no record of creating it, so it will not adopt it on a ` +
+            `first run. Move it away (or delete it) and rerun; the template is fetched fresh.`);
+    }
     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`);

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

package/dist/database.js

@@ -61,8 +61,8 @@ export async function openDatabase(runner, options) {
         throw new DatabaseTransportError("tunnel", `could not reach Postgres on ${TUNNEL_LOOPBACK}:${String(remotePort)} on the box, and no ` +
             "container was named to discover an address on the docker network", { cause: loopback.failure });
     }
-    const found = await containerAddress(runner, candidates);
-    const direct = await tryTunnel(runner, options.admin, remotePort, found.address);
+    const found = await findPostgresContainer(runner, candidates);
+    const direct = await tryTunnel(runner, options.admin, remotePort, found.address, found.container);
     if ("database" in direct)
         return direct.database;
     if (options.dockerExec !== true) {
@@ -74,16 +74,13 @@ export async function openDatabase(runner, options) {
 }
 /** The cluster at a URL this process can already dial — a test's Postgres, or a live tunnel. */
 export function openDatabaseUrl(adminUrl) {
-    return tunnelDatabase(adminUrl, undefined, undefined);
+    return tunnelDatabase(adminUrl, undefined, undefined, undefined);
 }
-async function tryTunnel(runner, admin, remotePort, remoteHost) {
+async function tryTunnel(runner, admin, remotePort, remoteHost, container) {
     let tunnel;
     try {
         tunnel = await runner.tunnel(remotePort, remoteHost);
-        const database = tunnelDatabase(adminUrlOf(admin, tunnel.localPort), tunnel, {
-            host: remoteHost,
-            port: remotePort,
-        });
+        const database = tunnelDatabase(adminUrlOf(admin, tunnel.localPort), tunnel, { host: remoteHost, port: remotePort }, container);
         await database.query("SELECT 1");
         return { database };
     }
@@ -100,7 +97,7 @@ async function tryTunnel(runner, admin, remotePort, remoteHost) {
  * network something else. Every candidate that failed is reported, because which name a database
  * got is a fact about how it was created and the operator is the one who knows it.
  */
-async function containerAddress(runner, containers) {
+export async function findPostgresContainer(runner, containers) {
     const problems = [];
     for (const container of containers) {
         const command = ["docker", "inspect", "-f", DOCKER_NETWORKS_FORMAT, container];
@@ -135,7 +132,7 @@ function coolifyAddress(stdout) {
         .filter((entry) => isIPv4(entry.address));
     return (networks.find((entry) => entry.network === COOLIFY_NETWORK) ?? networks[0])?.address;
 }
-function tunnelDatabase(adminUrl, tunnel, boxAddress) {
+function tunnelDatabase(adminUrl, tunnel, boxAddress, container) {
     const clients = new Map();
     const clientFor = async (databaseName) => {
         const url = withDatabase(adminUrl, databaseName);
@@ -150,6 +147,7 @@ function tunnelDatabase(adminUrl, tunnel, boxAddress) {
     return {
         kind: "tunnel",
         boxAddress,
+        container,
         adminUrl: (databaseName) => withDatabase(adminUrl, databaseName),
         query: async (sql, queryOptions) => {
             const client = await clientFor(queryOptions?.database);
@@ -175,6 +173,7 @@ function tunnelDatabase(adminUrl, tunnel, boxAddress) {
 function dockerExecDatabase(runner, container, admin) {
     return {
         kind: "docker-exec",
+        container,
         adminUrl: () => undefined,
         query: async (sql, queryOptions) => {
             // `-f -`: the statement goes down stdin, so it never appears in the box's process list

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export { generate, GENERATOR_BIN, GENERATOR_CONFIG, NoGenerators, type GenerateO
 export { dev, devBuildSha, DEV_COMPOSE_FILE, type DevOptions, type DevResult } from "./dev.js";
 export { run, CommandFailed, type RunOptions } from "./spawn.js";
 export { createLocalRunner, createSshRunner, shellQuote, sshExecArgv, sshTunnelArgv, RunnerError, DEFAULT_TUNNEL_READY_TIMEOUT_MS, type ExecOptions, type ExecResult, type LocalRunner, type LocalRunnerOptions, type Runner, type SshRunnerOptions, type Tunnel, } from "./runner.js";
-export { openDatabase, openDatabaseUrl, redactPasswords, DatabaseTransportError, DEFAULT_POSTGRES_PORT, type AdminCredentials, type Database, type DatabaseTransport, type OpenDatabaseOptions, type QueryOptions, type QueryResult, } from "./database.js";
+export { findPostgresContainer, openDatabase, openDatabaseUrl, redactPasswords, DatabaseTransportError, DEFAULT_POSTGRES_PORT, type AdminCredentials, type Database, type DatabaseTransport, type OpenDatabaseOptions, type QueryOptions, type QueryResult, } from "./database.js";
 export { createLocalDirectoryBackupSource, createS3BackupSource, BackupSourceError, COOLIFY_BACKUP_DIR, type BackupDump, type BackupSource, type BackupSourceKind, type LocalDirectoryBackupSourceOptions, } from "./backup-source.js";
-export { formatRestoreCheck, pgRestoreArgv, restoreCheck, restoreCheckApp, RestoreCheckError, SCRATCH_SUFFIX, STALE_DUMP_HOURS, type RestoreCheckAppOptions, type RestoreCheckOptions, type RestoreCheckResult, type RestoreCheckRow, type RestoreVerdict, } from "./restore-check.js";
+export { formatRestoreCheck, pgRestoreArgv, pgRestoreInContainerArgv, restoreCheck, restoreCheckApp, RestoreCheckError, SCRATCH_SUFFIX, STALE_DUMP_HOURS, type RestoreCheckAppOptions, type RestoreCheckOptions, type RestoreCheckResult, type RestoreCheckRow, type RestoreVerdict, } from "./restore-check.js";
 export { provisionDatabase, ProvisionDatabaseError, REQUIRED_EXTENSIONS, type ProvisionDatabaseOptions, type ProvisionDatabaseResult, } from "./provision-database.js";

package/dist/index.js

@@ -15,7 +15,7 @@ export { generate, GENERATOR_BIN, GENERATOR_CONFIG, NoGenerators, } from "./gen.
 export { dev, devBuildSha, DEV_COMPOSE_FILE } from "./dev.js";
 export { run, CommandFailed } from "./spawn.js";
 export { createLocalRunner, createSshRunner, shellQuote, sshExecArgv, sshTunnelArgv, RunnerError, DEFAULT_TUNNEL_READY_TIMEOUT_MS, } from "./runner.js";
-export { openDatabase, openDatabaseUrl, redactPasswords, DatabaseTransportError, DEFAULT_POSTGRES_PORT, } from "./database.js";
+export { findPostgresContainer, openDatabase, openDatabaseUrl, redactPasswords, DatabaseTransportError, DEFAULT_POSTGRES_PORT, } from "./database.js";
 export { createLocalDirectoryBackupSource, createS3BackupSource, BackupSourceError, COOLIFY_BACKUP_DIR, } from "./backup-source.js";
-export { formatRestoreCheck, pgRestoreArgv, restoreCheck, restoreCheckApp, RestoreCheckError, SCRATCH_SUFFIX, STALE_DUMP_HOURS, } from "./restore-check.js";
+export { formatRestoreCheck, pgRestoreArgv, pgRestoreInContainerArgv, restoreCheck, restoreCheckApp, RestoreCheckError, SCRATCH_SUFFIX, STALE_DUMP_HOURS, } from "./restore-check.js";
 export { provisionDatabase, ProvisionDatabaseError, REQUIRED_EXTENSIONS, } from "./provision-database.js";

package/dist/new-cloud.d.ts

@@ -77,9 +77,10 @@ export declare function invalidateStaleSecretSteps(state: AppStateStore): Promis
 export declare function runSteps<Context extends CloudContext>(steps: readonly Step<Context>[], context: Context): Promise<RunStepsResult>;
 /**
  * The keys a cloud `hf new` runs without: three have a default derived from another key, the two
- * provider keys are what the checklist warns about when they are unset, and the three Langfuse
- * keys are three ways of configuring one step — an org key, a project key pair, or neither, which
- * the step degrades to a warning and a checklist line.
+ * provider keys are what the checklist warns about when they are unset, the three Langfuse keys
+ * are three ways of configuring one step — an org key, a project key pair, or neither, which the
+ * step degrades to a warning and a checklist line — and the S3 storage is one the backup step
+ * discovers when the box has exactly one, and warns about when it cannot.
  */
 export declare const OPTIONAL_CLOUD_CONFIG: readonly ConfigKey[];
 /**

package/dist/new-cloud.js

@@ -108,11 +108,13 @@ export async function runSteps(steps, context) {
 }
 /**
  * The keys a cloud `hf new` runs without: three have a default derived from another key, the two
- * provider keys are what the checklist warns about when they are unset, and the three Langfuse
- * keys are three ways of configuring one step — an org key, a project key pair, or neither, which
- * the step degrades to a warning and a checklist line.
+ * provider keys are what the checklist warns about when they are unset, the three Langfuse keys
+ * are three ways of configuring one step — an org key, a project key pair, or neither, which the
+ * step degrades to a warning and a checklist line — and the S3 storage is one the backup step
+ * discovers when the box has exactly one, and warns about when it cannot.
  */
 export const OPTIONAL_CLOUD_CONFIG = [
+    "HF_COOLIFY_S3_STORAGE_UUID",
     "HF_DB_HOST_INTERNAL",
     "HF_DB_CONTAINER",
     "HF_PG_ADMIN_USER",

package/dist/providers/coolify.d.ts

@@ -108,10 +108,33 @@ export interface CoolifyBackupRequest {
     database_backup_retention_amount_locally?: number;
     database_backup_retention_days_locally?: number;
 }
+/**
+ * What `PATCH /databases/{uuid}/backups/{scheduled_backup_uuid}` accepts of the fields E3 sets.
+ *
+ * Every field is optional upstream and only the ones a rerun reconciles are here: the schedule it
+ * finds was registered by an earlier `hf new`, and rewriting fields nobody set would undo whatever
+ * the operator changed in Coolify's own UI.
+ */
+export interface CoolifyBackupUpdate {
+    frequency?: string;
+    enabled?: boolean;
+    save_s3?: boolean;
+    s3_storage_uuid?: string;
+    databases_to_backup?: string;
+    dump_all?: boolean;
+}
 export interface CoolifyBackup {
     uuid: string;
     message?: string;
 }
+/** An S3 storage as `GET /s3-storages` lists it; `is_usable` is Coolify's own validation verdict. */
+export interface CoolifyS3Storage {
+    uuid: string;
+    name: string;
+    bucket?: string;
+    region?: string;
+    is_usable?: boolean;
+}
 export interface CoolifyClientOptions {
     /** `HF_COOLIFY_URL` — the instance's origin, without `/api/v1`. */
     url: string;
@@ -132,6 +155,11 @@ export declare class CoolifyClient {
     listProjects(): Promise<CoolifyProject[]>;
     getProject(uuid: string): Promise<CoolifyProject>;
     listEnvironments(projectUuid: string): Promise<CoolifyEnvironment[]>;
+    createEnvironment(projectUuid: string, body: {
+        name: string;
+    }): Promise<{
+        uuid: string;
+    }>;
     createPrivateGithubAppApplication(body: CoolifyApplicationRequest): Promise<CoolifyApplication>;
     /**
      * Every application, so a rerun can find the one it created last time by name.
@@ -148,6 +176,15 @@ export declare class CoolifyClient {
     }): Promise<CoolifyDeploymentRequest>;
     getDeployment(deploymentUuid: string): Promise<CoolifyDeployment>;
     createDatabaseBackup(databaseUuid: string, body: CoolifyBackupRequest): Promise<CoolifyBackup>;
+    updateDatabaseBackup(databaseUuid: string, backupUuid: string, body: CoolifyBackupUpdate): Promise<unknown>;
+    /**
+     * Every S3 storage the token's team has configured.
+     *
+     * A backup registered with `save_s3` and no `s3_storage_uuid` is accepted, then runs with
+     * `S3 storage configuration is missing` in its log and keeps the dump on the box alone — so the
+     * uuid has to come from somewhere, and this is the only place the API offers one.
+     */
+    listS3Storages(): Promise<CoolifyS3Storage[]>;
     /**
      * The database's scheduled backups.
      *

package/dist/providers/coolify.js

@@ -26,6 +26,13 @@ export class CoolifyClient {
             path: `/projects/${segment(projectUuid)}/environments`,
         });
     }
+    async createEnvironment(projectUuid, body) {
+        return await this.request({
+            method: "POST",
+            path: `/projects/${segment(projectUuid)}/environments`,
+            body,
+        });
+    }
     async createPrivateGithubAppApplication(body) {
         return await this.request({ method: "POST", path: "/applications/private-github-app", body });
     }
@@ -68,6 +75,23 @@ export class CoolifyClient {
             body,
         });
     }
+    async updateDatabaseBackup(databaseUuid, backupUuid, body) {
+        return await this.request({
+            method: "PATCH",
+            path: `/databases/${segment(databaseUuid)}/backups/${segment(backupUuid)}`,
+            body,
+        });
+    }
+    /**
+     * Every S3 storage the token's team has configured.
+     *
+     * A backup registered with `save_s3` and no `s3_storage_uuid` is accepted, then runs with
+     * `S3 storage configuration is missing` in its log and keeps the dump on the box alone — so the
+     * uuid has to come from somewhere, and this is the only place the API offers one.
+     */
+    async listS3Storages() {
+        return await this.request({ method: "GET", path: "/s3-storages" });
+    }
     /**
      * The database's scheduled backups.
      *

package/dist/restore-check.d.ts

@@ -36,20 +36,26 @@ export interface RestoreCheckOptions {
     app: string;
     state: AppStateStore;
     source: BackupSource;
-    /** Where `pg_restore` runs: the box, or this machine in a test. */
+    /** Where the dump file is and where `docker` is run: the box, or this machine in a test. */
     runner: Runner;
     /** How the scratch database is created and both sides are counted. */
     database: Database | string;
     /**
-     * The cluster's admin URL **as the runner sees it**, for `pg_restore`.
+     * The Postgres container `pg_restore` runs inside.
      *
-     * Not the same address as `database`: the laptop reaches the cluster through an `ssh -L`
-     * forward onto a local port, and a `pg_restore` running on the far side of that forward has to
-     * dial the box's own loopback. Defaults to `database`'s URL, which is what a test wants when
-     * both sides are the same machine.
+     * The box host has no Postgres client tools — Postgres runs only in Coolify's container — so a
+     * `pg_restore` on the host exits 127. The dump is the host's and is not mounted into the
+     * container, so it goes down `docker exec -i`'s stdin.
+     */
+    container: string;
+    /** The superuser inside the container; `HF_PG_ADMIN_USER`, default `postgres`. */
+    adminUser?: string;
+    /**
+     * @deprecated Unused: `pg_restore` no longer dials an address, it runs beside the server inside
+     * `container`. Removed in 0.2.0.
      */
     restoreAdminUrl?: string;
-    /** The `pg_restore` binary on the runner. */
+    /** The `pg_restore` binary inside the container. */
     pgRestorePath?: string;
     now?: Date;
 }
@@ -64,13 +70,32 @@ export interface RestoreCheckOptions {
  * mismatch — has to leave the warning standing until a check actually passes.
  */
 export declare function restoreCheck(options: RestoreCheckOptions): Promise<RestoreCheckResult>;
-/** The argv `restoreCheck` runs — the array the test asserts against. */
+/**
+ * The argv `restoreCheck` runs — the array the test asserts against.
+ *
+ * @deprecated The box host has no `pg_restore`; the restore runs inside the Postgres container.
+ * Use `pgRestoreInContainerArgv`. Removed in 0.2.0.
+ */
 export declare function pgRestoreArgv(options: {
     url: string;
     role: string;
     file: string;
     pgRestorePath?: string;
 }): string[];
+/**
+ * The argv `restoreCheck` runs — the array the test asserts against.
+ *
+ * No `--dbname` URL: inside the container the server is on the local socket, so the admin user
+ * and the database name are all it takes and no password crosses an argv. The dump arrives on
+ * stdin, which is why there is no file argument either.
+ */
+export declare function pgRestoreInContainerArgv(options: {
+    container: string;
+    adminUser: string;
+    database: string;
+    role: string;
+    pgRestorePath?: string;
+}): string[];
 /** The table `hf restore-check` prints, and the two lines around it. */
 export declare function formatRestoreCheck(result: RestoreCheckResult): string[];
 export interface RestoreCheckAppOptions {

package/dist/restore-check.js

@@ -1,7 +1,7 @@
 import { quoteIdent } from "@hyperfixation/db";
 import { createLocalDirectoryBackupSource, createS3BackupSource, } from "./backup-source.js";
-import { loadOperatorConfig, pgAdminUser, postgresContainers, requireOperatorConfig, } from "./config.js";
-import { openDatabase, openDatabaseUrl, redactPasswords, DEFAULT_POSTGRES_PORT, } from "./database.js";
+import { loadOperatorConfig, pgAdminUser, postgresContainers, requireOperatorConfig, DEFAULT_PG_ADMIN_USER, } from "./config.js";
+import { findPostgresContainer, openDatabase, openDatabaseUrl, redactPasswords, } from "./database.js";
 import { deriveNames } from "./names.js";
 import { REQUIRED_EXTENSIONS } from "./provision-database.js";
 import { createSshRunner } from "./runner.js";
@@ -12,7 +12,6 @@ export const SCRATCH_SUFFIX = "_restore_check";
 const MAX_IDENTIFIER_BYTES = 63;
 /** Older than this and the dump gets a warning line; it never changes the exit code. */
 export const STALE_DUMP_HOURS = 36;
-const CLUSTER_ADMIN_DATABASE = "postgres";
 export class RestoreCheckError extends Error {
     constructor(message) {
         super(message);
@@ -45,11 +44,10 @@ export async function restoreCheck(options) {
     const db = typeof options.database === "string" ? openDatabaseUrl(options.database) : options.database;
     const clusterUrl = db.adminUrl();
     if (clusterUrl === undefined) {
-        throw new RestoreCheckError(`a restore cannot be run over the ${db.kind} transport: pg_restore needs an address. ` +
-            "Name the Postgres container — HF_DB_CONTAINER, or HF_COOLIFY_POSTGRES_UUID — so the " +
-            "tunnel can discover one.");
+        throw new RestoreCheckError(`a restore cannot be checked over the ${db.kind} transport: counting the restored side ` +
+            "needs an address a client library can dial. Name the Postgres container — " +
+            "HF_DB_CONTAINER, or HF_COOLIFY_POSTGRES_UUID — so the tunnel can discover one.");
     }
-    const restoreTarget = urlOnto(options.restoreAdminUrl ?? clusterUrl, scratchDatabase);
     const now = options.now ?? new Date();
     const dumpAgeHours = (now.getTime() - dump.takenAt.getTime()) / 3_600_000;
     try {
@@ -73,7 +71,7 @@ export async function restoreCheck(options) {
                 await db.query(`GRANT CONNECT, CREATE ON DATABASE ${quoteIdent(scratchDatabase)} ` +
                     `TO ${quoteIdent(names.migratorRole)}`);
                 await scratch.query(`GRANT CREATE, USAGE ON SCHEMA public TO ${quoteIdent(names.migratorRole)}`);
-                await runRestore(options, restoreTarget, names.migratorRole, dump.path);
+                await runRestore(options, scratchDatabase, names.migratorRole, dump.path);
                 rows = compare(await countTables(db, names.databaseName), await countTables(scratch));
             }
             finally {
@@ -101,14 +99,16 @@ export async function restoreCheck(options) {
             await db.close();
     }
 }
-/** The argv `restoreCheck` runs — the array the test asserts against. */
+/**
+ * The argv `restoreCheck` runs — the array the test asserts against.
+ *
+ * @deprecated The box host has no `pg_restore`; the restore runs inside the Postgres container.
+ * Use `pgRestoreInContainerArgv`. Removed in 0.2.0.
+ */
 export function pgRestoreArgv(options) {
     return [
         options.pgRestorePath ?? "pg_restore",
         "--no-owner",
-        // Every object comes out owned by the migrator, as in the live database. `--no-comments`
-        // because a dump's `COMMENT ON EXTENSION` belongs to the admin that created the extension,
-        // and a comment nobody may set is not a restore failure.
         "--no-comments",
         `--role=${options.role}`,
         "--dbname",
@@ -116,15 +116,56 @@ export function pgRestoreArgv(options) {
         options.file,
     ];
 }
-async function runRestore(options, url, role, file) {
-    const argv = pgRestoreArgv({ url, role, file, pgRestorePath: options.pgRestorePath });
-    const result = await options.runner.exec(argv);
-    if (result.code !== 0) {
-        // `url` carries the cluster's admin password, and so does anything pg_restore echoed of it.
-        throw new RestoreCheckError(`pg_restore exited ${String(result.code)} restoring ${file}: ` +
-            redactPasswords(result.stderr.trim()));
-    }
+/**
+ * The argv `restoreCheck` runs — the array the test asserts against.
+ *
+ * No `--dbname` URL: inside the container the server is on the local socket, so the admin user
+ * and the database name are all it takes and no password crosses an argv. The dump arrives on
+ * stdin, which is why there is no file argument either.
+ */
+export function pgRestoreInContainerArgv(options) {
+    return [
+        "docker",
+        "exec",
+        "-i",
+        options.container,
+        options.pgRestorePath ?? "pg_restore",
+        "--no-owner",
+        // Every object comes out owned by the migrator, as in the live database. `--no-comments`
+        // because a dump's `COMMENT ON EXTENSION` belongs to the admin that created the extension,
+        // and a comment nobody may set is not a restore failure.
+        "--no-comments",
+        `--role=${options.role}`,
+        "-U",
+        options.adminUser,
+        "-d",
+        options.database,
+    ];
+}
+async function runRestore(options, database, role, file) {
+    const { container } = options;
+    const argv = pgRestoreInContainerArgv({
+        container,
+        adminUser: options.adminUser ?? DEFAULT_PG_ADMIN_USER,
+        database,
+        role,
+        pgRestorePath: options.pgRestorePath,
+    });
+    const result = await options.runner.exec(argv, { inputFile: file });
+    if (result.code === 0)
+        return;
+    // Anything `pg_restore` echoed of a connection string carries the cluster's admin password.
+    const stderr = redactPasswords(result.stderr.trim());
+    throw new RestoreCheckError(`pg_restore exited ${String(result.code)} restoring ${file} in ${container}: ${stderr}` +
+        (result.code === NOT_FOUND_EXIT
+            ? ` — exit ${String(NOT_FOUND_EXIT)} means "command not found". The box host has no ` +
+                "Postgres client tools; only the container does. Check that docker is on the box's " +
+                `PATH and that ${container} is the Postgres container (HF_DB_CONTAINER, or ` +
+                "HF_COOLIFY_POSTGRES_UUID)."
+            : ""));
 }
+/** A shell's, and `docker exec`'s, "command not found". */
+const NOT_FOUND_EXIT = 127;
 /**
  * Row counts for every table the app's data lives in: `hf_*`, plus every table carrying
  * `normalized_name`, which is how `@hyperfixation/db` spells a record table the app declared.
@@ -219,7 +260,8 @@ export async function restoreCheckApp(options) {
     const { HF_SSH_HOST } = requireOperatorConfig(config, ["HF_SSH_HOST"], { env });
     const runner = createSshRunner({ host: HF_SSH_HOST });
     const admin = { user: pgAdminUser(config), password: env.PGPASSWORD };
-    const db = await openDatabase(runner, { admin, containers: postgresContainers(config) });
+    const containers = postgresContainers(config);
+    const db = await openDatabase(runner, { admin, containers });
     try {
         return await restoreCheck({
             app: options.app,
@@ -229,7 +271,8 @@ export async function restoreCheckApp(options) {
                 : createLocalDirectoryBackupSource({ runner, directory: options.backupDir }),
             runner,
             database: db,
-            restoreAdminUrl: boxAdminUrl(admin, db.boxAddress),
+            container: await restoreContainer(runner, db, containers),
+            adminUser: admin.user,
         });
     }
     finally {
@@ -237,20 +280,21 @@ export async function restoreCheckApp(options) {
     }
 }
 /**
- * The cluster as the box itself sees it, where `pg_restore` runs.
+ * The container `pg_restore` runs inside.
  *
- * `address` is whatever the tunnel settled on: with 5432 unpublished the box's loopback is no more
- * a listener for `pg_restore` than for the forward, and the container's address on the docker
- * network is what both have to dial.
+ * `openDatabase` already knows it whenever the box's loopback had no listener, which is the box
+ * Coolify builds; a box that does publish 5432 answers on the loopback and never looks, so the
+ * discovery runs here instead of leaving the check with nowhere to restore.
  */
-function boxAdminUrl(admin, address) {
-    const url = new URL(`postgresql://${address?.host ?? "127.0.0.1"}`);
-    url.port = String(address?.port ?? DEFAULT_POSTGRES_PORT);
-    url.username = encodeURIComponent(admin.user);
-    if (admin.password !== undefined)
-        url.password = encodeURIComponent(admin.password);
-    url.pathname = `/${CLUSTER_ADMIN_DATABASE}`;
-    return url.toString();
+async function restoreContainer(runner, db, containers) {
+    if (db.container !== undefined)
+        return db.container;
+    if (containers.length === 0) {
+        throw new RestoreCheckError("pg_restore has to run inside the Postgres container — the box host has no Postgres " +
+            "client tools — and no container was named. Set HF_DB_CONTAINER, or " +
+            "HF_COOLIFY_POSTGRES_UUID, in the operator config.");
+    }
+    return (await findPostgresContainer(runner, containers)).container;
 }
 function urlOnto(connectionString, database) {
     const url = new URL(connectionString);

package/dist/runner.d.ts

@@ -1,6 +1,14 @@
 export interface ExecOptions {
     /** Written to the command's stdin and then closed. SQL goes here, never into argv. */
     input?: string;
+    /**
+     * A file **on the far side**, streamed into the command's stdin instead of `input`.
+     *
+     * How a dump on the box reaches a `pg_restore` that runs inside the Postgres container: the
+     * file is the host's and the process is the container's, so nothing but stdin spans the two.
+     * Takes precedence over `input`.
+     */
+    inputFile?: string;
 }
 export interface ExecResult {
     /** `null` when the command was killed by a signal or by `timeoutMs`. */
@@ -36,7 +44,7 @@ export declare class RunnerError extends Error {
     });
 }
 /** The argv `exec` runs, `ssh` excluded — the array the test asserts against. */
-export declare function sshExecArgv(host: string, command: readonly string[]): string[];
+export declare function sshExecArgv(host: string, command: readonly string[], options?: ExecOptions): string[];
 export declare function sshTunnelArgv(host: string, localPort: number, remotePort: number, remoteHost?: string): string[];
 /** Where a forward lands when the caller names no host: the far side's own loopback. */
 export declare const TUNNEL_LOOPBACK = "127.0.0.1";

package/dist/runner.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { createReadStream } from "node:fs";
 import { createServer, connect as connectTcp } from "node:net";
 export class RunnerError extends Error {
     constructor(message, options) {
@@ -31,11 +32,16 @@ const SSH_OPTIONS = [
     "ControlPath=none",
 ];
 /** The argv `exec` runs, `ssh` excluded — the array the test asserts against. */
-export function sshExecArgv(host, command) {
+export function sshExecArgv(host, command, options = {}) {
     assertHost(host);
     // `ssh` hands the remote end one string and the login shell splits it, so the array has to be
-    // re-quoted for that shell; nothing else in this file ever builds a shell word.
-    return ["-T", ...SSH_OPTIONS, host, shellQuote(command)];
+    // re-quoted for that shell; nothing else in this file ever builds a shell word. `inputFile`
+    // becomes that shell's own `<` redirection, which is the only way a far-side file reaches the
+    // stdin of a far-side command without being pulled across the link first.
+    const remote = options.inputFile === undefined
+        ? shellQuote(command)
+        : `${shellQuote(command)} < ${shellQuote([options.inputFile])}`;
+    return ["-T", ...SSH_OPTIONS, host, remote];
 }
 export function sshTunnelArgv(host, localPort, remotePort, remoteHost = TUNNEL_LOOPBACK) {
     assertHost(host);
@@ -61,7 +67,13 @@ export function createSshRunner(options) {
     const ssh = options.sshPath ?? "ssh";
     assertHost(options.host);
     return {
-        exec: async (command, execOptions) => await spawnCollecting(ssh, sshExecArgv(options.host, command), execOptions),
+        exec: async (command, execOptions) => 
+        // The redirection is the remote shell's, so `inputFile` is spent building the remote word
+        // and must not also be opened on this machine.
+        await spawnCollecting(ssh, sshExecArgv(options.host, command, execOptions), {
+            ...execOptions,
+            inputFile: undefined,
+        }),
         tunnel: async (remotePort, remoteHost = TUNNEL_LOOPBACK) => {
             const localPort = await freeLocalPort();
             const child = spawn(ssh, sshTunnelArgv(options.host, localPort, remotePort, remoteHost), {
@@ -134,19 +146,28 @@ async function spawnCollecting(bin, args, options = {}) {
     child.stderr?.on("data", (chunk) => {
         stderr += chunk.toString("utf8");
     });
+    const file = options.inputFile === undefined ? undefined : createReadStream(options.inputFile);
     const closed = new Promise((resolve, reject) => {
         // A child that exits before reading its stdin (`true`, a refused ssh) makes the write fail with
         // EPIPE; the exit code already says what happened. Any other stdin error is a real failure.
         child.stdin?.on("error", (error) => {
+            file?.destroy();
             if (error.code === "EPIPE")
                 return;
             child.kill();
             reject(error);
         });
+        file?.once("error", (cause) => {
+            child.kill();
+            reject(new RunnerError(`could not read ${String(options.inputFile)} into stdin`, { cause }));
+        });
         child.once("error", reject);
         child.once("close", (exitCode) => resolve(exitCode));
     });
-    child.stdin?.end(options.input ?? "");
+    if (file === undefined)
+        child.stdin?.end(options.input ?? "");
+    else if (child.stdin !== null)
+        file.pipe(child.stdin);
     const code = await closed;
     return { code, stdout, stderr };
 }

package/dist/state.d.ts

@@ -50,6 +50,15 @@ export interface StatusTokenState {
  */
 export interface AppState {
     steps: Partial<Record<StepName, StepRecord>>;
+    /**
+     * ISO 8601, written just before the `template` step renames the substituted fetch into place.
+     *
+     * The proof that a directory at the app's path is this run's own: `steps.template` is only
+     * recorded after the rename, so a crash in between would otherwise leave a directory no state
+     * vouches for. Without it the step refuses to adopt a directory — a stale scaffold from an
+     * earlier `hf new --local` looks exactly like a lost run.
+     */
+    templateStartedAt?: string;
     /** `owner/name` of the app's GitHub repository. */
     repo?: string;
     coolify?: CoolifyState;

package/dist/state.js

@@ -149,6 +149,7 @@ function parseAppState(contents, file) {
                 state.steps = parseSteps(value, file);
                 break;
             case "repo":
+            case "templateStartedAt":
             case "sentryDsn":
             case "betterAuthSecret":
             case "lastRestoreCheckAt":

package/package.json

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