@hyperfixation/cli 0.1.0 → 0.1.1

package/dist/app.d.ts

@@ -9,12 +9,25 @@ export interface ResolvedApp {
     names: AppNames;
     /** The app's own migrations, which `hf migrate` and E005 both read. */
     migrationsDir: string;
-    /** `.env` under `process.env`, the precedence every dotenv loader uses. */
+    /** `.env` under `process.env` under the caller's overlay; the precedence dotenv loaders use. */
     env: Record<string, string | undefined>;
     /** `.env` alone, so `hf check` can say a name is missing from the file and not from a shell. */
     envFile: Record<string, string>;
     /** The names `.env.example` declares; the app's env contract, kept equal to `REQUIRED_ENV`. */
     declared: readonly string[];
+    /** The overlay this app was resolved with, so a command can hand the same one to a child. */
+    envOverlay: Record<string, string>;
+}
+export interface ResolveAppOptions {
+    /**
+     * Names → values laid over `.env` **and** over `process.env`.
+     *
+     * The cloud path has no `.env` to read: `hf new` runs `migrate`, `bootstrap` and
+     * `status-token` against a freshly provisioned app through the E2 tunnel, holding the
+     * connection URLs itself. Highest precedence rather than lowest, because a laptop that
+     * happens to export `DATABASE_URL` for its own dev app must not redirect a cloud run into it.
+     */
+    env?: Record<string, string>;
 }
 /**
  * Finds the app around `dir` and reads everything the other commands need from it.
@@ -23,4 +36,4 @@ export interface ResolvedApp {
  * template's `package.json` carries `__APP_NAME__`, so after substitution it already *is* the
  * record, and a second copy of the name is a second thing that can disagree.
  */
-export declare function resolveApp(dir?: string): Promise<ResolvedApp>;
+export declare function resolveApp(dir?: string, options?: ResolveAppOptions): Promise<ResolvedApp>;

package/dist/app.js

@@ -17,7 +17,7 @@ export class NotAnApp extends Error {
  * template's `package.json` carries `__APP_NAME__`, so after substitution it already *is* the
  * record, and a second copy of the name is a second thing that can disagree.
  */
-export async function resolveApp(dir = process.cwd()) {
+export async function resolveApp(dir = process.cwd(), options = {}) {
     const root = await findAppRoot(path.resolve(dir));
     const manifest = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
     if (typeof manifest.name !== "string") {
@@ -25,14 +25,16 @@ export async function resolveApp(dir = process.cwd()) {
     }
     const envFile = await readEnvFile(path.join(root, ".env"));
     const example = await readEnvFile(path.join(root, ".env.example"));
+    const envOverlay = options.env ?? {};
     return {
         dir: root,
         appName: manifest.name,
         names: deriveNames(manifest.name),
         migrationsDir: path.join(root, "drizzle"),
-        env: { ...envFile, ...process.env },
+        env: { ...envFile, ...process.env, ...envOverlay },
         envFile,
         declared: Object.keys(example),
+        envOverlay,
     };
 }
 async function findAppRoot(from) {

package/dist/backup-source.d.ts

@@ -0,0 +1,47 @@
+import type { Runner } from "./runner.js";
+/** Where Coolify writes a database backup it was not told to send to S3. */
+export declare const COOLIFY_BACKUP_DIR = "/data/coolify/backups";
+export type BackupSourceKind = "local-directory" | "hetzner-s3";
+export interface BackupDump {
+    /** A path `pg_restore` can read on the runner's side. */
+    path: string;
+    /** The dump's mtime — what `hf restore-check` reports an age against. */
+    takenAt: Date;
+    /** Where it was found, for the message when nothing was. */
+    from: string;
+}
+/** One place `hf restore-check` can get the newest dump of a database from. */
+export interface BackupSource {
+    readonly kind: BackupSourceKind;
+    /** The newest dump of `databaseName`, or `undefined` when the source holds none. */
+    newest(databaseName: string): Promise<BackupDump | undefined>;
+}
+export declare class BackupSourceError extends Error {
+    readonly kind: BackupSourceKind;
+    constructor(kind: BackupSourceKind, message: string);
+}
+export interface LocalDirectoryBackupSourceOptions {
+    /** Where the dumps are listed and stat'ed: the box, or this machine in a test. */
+    runner: Runner;
+    /** Defaults to `COOLIFY_BACKUP_DIR`. */
+    directory?: string;
+    /** How deep under `directory` to look; Coolify nests dumps per database uuid. */
+    maxDepth?: number;
+}
+/**
+ * The dumps Coolify keeps on the box's own disk, newest by mtime.
+ *
+ * mtime rather than the filename's timestamp: Coolify's naming is one of the things Phase 0
+ * never pinned down, so the match is `*<database>*` and the ordering is the filesystem's.
+ */
+export declare function createLocalDirectoryBackupSource(options: LocalDirectoryBackupSourceOptions): BackupSource;
+/**
+ * The dumps in Hetzner's object storage — **not implemented**.
+ *
+ * Risk 3 of the Phase 3 order is still open: nobody has looked in `/data/coolify/backups` on the
+ * box, so which of the two sources is the real one is unknown, and the operator config has no
+ * S3 key to read (`CONFIG_KEYS` carries none). Rather than guess a bucket layout and a key name,
+ * this refuses with the one sentence that says what to do. The key, when it exists, belongs in
+ * the operator config and is never written into an app's environment.
+ */
+export declare function createS3BackupSource(): BackupSource;

package/dist/backup-source.js

@@ -0,0 +1,107 @@
+import { APP_ID } from "./names.js";
+/** Where Coolify writes a database backup it was not told to send to S3. */
+export const COOLIFY_BACKUP_DIR = "/data/coolify/backups";
+export class BackupSourceError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(`${kind}: ${message}`);
+        this.name = "BackupSourceError";
+        this.kind = kind;
+    }
+}
+const DEFAULT_MAX_DEPTH = 4;
+/**
+ * The dumps Coolify keeps on the box's own disk, newest by mtime.
+ *
+ * mtime rather than the filename's timestamp: Coolify's naming is one of the things Phase 0
+ * never pinned down, so the match is `*<database>*` and the ordering is the filesystem's.
+ */
+export function createLocalDirectoryBackupSource(options) {
+    const directory = options.directory ?? COOLIFY_BACKUP_DIR;
+    const { runner } = options;
+    return {
+        kind: "local-directory",
+        newest: async (databaseName) => {
+            assertGlobSafe(databaseName);
+            const listed = await runner.exec([
+                "find",
+                directory,
+                "-maxdepth",
+                String(options.maxDepth ?? DEFAULT_MAX_DEPTH),
+                "-type",
+                "f",
+                "-name",
+                `*${databaseName}*`,
+            ]);
+            if (listed.code !== 0) {
+                throw new BackupSourceError("local-directory", `could not list ${directory} on the box: ${listed.stderr.trim()}`);
+            }
+            const paths = listed.stdout.split("\n").filter((line) => line !== "");
+            if (paths.length === 0)
+                return undefined;
+            const mtimes = await mtimeSeconds(runner, paths);
+            let newest;
+            for (const [index, path] of paths.entries()) {
+                const seconds = mtimes[index];
+                if (seconds === undefined)
+                    continue;
+                if (newest === undefined || seconds * 1000 > newest.takenAt.getTime()) {
+                    newest = { path, takenAt: new Date(seconds * 1000), from: directory };
+                }
+            }
+            return newest;
+        },
+    };
+}
+/**
+ * `stat`, whichever one the far side has: GNU spells the mtime `-c %Y` and BSD `-f %m`, and the
+ * box is Ubuntu while the suite runs on whatever the laptop is.
+ */
+async function mtimeSeconds(runner, paths) {
+    for (const flags of [
+        ["-c", "%Y"],
+        ["-f", "%m"],
+    ]) {
+        const result = await runner.exec(["stat", ...flags, "--", ...paths]);
+        if (result.code !== 0)
+            continue;
+        const seconds = result.stdout
+            .split("\n")
+            .filter((line) => line.trim() !== "")
+            .map((line) => Number(line.trim()));
+        if (seconds.length === paths.length && seconds.every((value) => Number.isFinite(value))) {
+            return seconds;
+        }
+    }
+    throw new BackupSourceError("local-directory", "neither GNU nor BSD stat reported an mtime");
+}
+/**
+ * The dumps in Hetzner's object storage — **not implemented**.
+ *
+ * Risk 3 of the Phase 3 order is still open: nobody has looked in `/data/coolify/backups` on the
+ * box, so which of the two sources is the real one is unknown, and the operator config has no
+ * S3 key to read (`CONFIG_KEYS` carries none). Rather than guess a bucket layout and a key name,
+ * this refuses with the one sentence that says what to do. The key, when it exists, belongs in
+ * the operator config and is never written into an app's environment.
+ */
+export function createS3BackupSource() {
+    return {
+        kind: "hetzner-s3",
+        newest: async () => {
+            throw new BackupSourceError("hetzner-s3", "downloading a dump from Hetzner object storage is not implemented: the operator config " +
+                "has no S3 key yet (risk 3 of the Phase 3 order). Run without --from-s3 against " +
+                `${COOLIFY_BACKUP_DIR} on the box, or pass --backup-dir.`);
+        },
+    };
+}
+/**
+ * The database name reaches `find` as a `*name*` pattern, so it may not carry a glob character.
+ *
+ * `deriveNames` has already refused anything outside `APP_ID` by the time `hf restore-check`
+ * gets here; this is the check at the point where the string becomes a pattern.
+ */
+function assertGlobSafe(databaseName) {
+    if (!APP_ID.test(databaseName)) {
+        throw new BackupSourceError("local-directory", `${JSON.stringify(databaseName)} is not a usable database name`);
+    }
+}

package/dist/bootstrap.d.ts

@@ -12,6 +12,8 @@ export interface BootstrapAppOptions {
      * alternative for a local run.
      */
     budgetUsd?: string;
+    /** Connection URLs in place of a `.env`; see `ResolveAppOptions`. */
+    env?: Record<string, string>;
 }
 export interface BootstrapAppResult extends BootstrapResult {
     app: ResolvedApp;

package/dist/bootstrap.js

@@ -17,7 +17,7 @@ const BOOTSTRAP_BUDGET_ENV = "HF_BOOTSTRAP_BUDGET_USD";
  * seed it if it hasn't been yet — `budget_usd` has no default, so nothing else ever will.
  */
 export async function bootstrapApp(options = {}) {
-    const app = await resolveApp(options.dir);
+    const app = await resolveApp(options.dir, { env: options.env });
     const databaseUrl = requireEnv(app, "DATABASE_URL");
     const budgetUsd = options.budgetUsd ?? requireEnv(app, BOOTSTRAP_BUDGET_ENV);
     if (!Number.isFinite(Number(budgetUsd)) || Number(budgetUsd) <= 0) {

package/dist/checklist.d.ts

@@ -0,0 +1,25 @@
+import type { AppNames } from "./names.js";
+export interface ChecklistInput {
+    names: AppNames;
+    /** `<name>.<HF_BASE_DOMAIN>`, the host Coolify serves and the passkey relying-party origin. */
+    fqdn: string;
+    /** `owner/name` of the app's repository, as the state cache recorded it. */
+    repo?: string;
+    /** The hostname the app's containers reach Postgres by; Metabase is on the same network. */
+    dbHost: string;
+    /** Where the passwords and tokens this names actually live. */
+    stateFile: string;
+    /** Which of `ANTHROPIC_API_KEY`/`OPENAI_API_KEY` the environment carries. */
+    providerKeysSent: readonly string[];
+    /** Lines the steps themselves appended to `context.checklist`, in the order they ran. */
+    fromSteps?: readonly string[];
+    /** The `/api/status` write token, and only on the run that minted it. */
+    writeToken?: string;
+}
+/**
+ * What `hf new` cannot do for the operator, printed when the ten steps are done.
+ *
+ * No secret is printed but the write token, and that only on the run that generated it: every
+ * other value this names is in the state file, which is the one place any of them exists.
+ */
+export declare function checklistLines(input: ChecklistInput): string[];

package/dist/checklist.js

@@ -0,0 +1,32 @@
+import { roleNames } from "@hyperfixation/db/migrator";
+/**
+ * What `hf new` cannot do for the operator, printed when the ten steps are done.
+ *
+ * No secret is printed but the write token, and that only on the run that generated it: every
+ * other value this names is in the state file, which is the one place any of them exists.
+ */
+export function checklistLines(input) {
+    const { names, fqdn } = input;
+    const origin = `https://${fqdn}`;
+    const lines = [`${names.given} is deployed at ${origin}. What is left is yours:`, ""];
+    const add = (...parts) => {
+        lines.push(`  - ${parts[0]}`, ...parts.slice(1).map((part) => `      ${part}`), "");
+    };
+    if (input.providerKeysSent.length === 0) {
+        add("The app is serving FIXTURE drafts: no ANTHROPIC_API_KEY or OPENAI_API_KEY was configured,", "so llm.run returns canned text and /api/status reports llm.mode=fixtures. Paste a key", "into Coolify's environment for this application and redeploy.");
+    }
+    add("Third-party keys go into Coolify's environment for this application — and every new name", "also has to be added to REQUIRED_ENV (src/env.ts), .env.example and all three", "environment: blocks of docker-compose.prod.yml. A name Coolify carries that compose does", "not interpolate never reaches a container, and hf new refuses the next run until they agree.");
+    add(`Metabase reads through ${roleNames(names.appName).readonly}:`, `postgres://${roleNames(names.appName).readonly}:<password>@${input.dbHost}:5432/${names.databaseName}`, `the password is database.readonlyPassword in ${input.stateFile}.`);
+    add(`Add the line "${input.repo ?? `<owner>/${names.given}`}" to downstream.txt in`, "hyperfixation-core, so the core bump opens a pull request here. (Phase 4 creates the file;", "until then this is the line it will need.)");
+    add("Merge a core-bump/* pull request only when its checks are green — a bump that fails CI is a", "core release this app cannot take. hf doctor lists the open ones with their status.");
+    add(`Enrol your passkey from exactly ${origin}, not an alias and not an IP: APP_URL is the`, "relying-party origin, and a different host enrols a credential the app will never accept.");
+    add(`Prove the backup restores: hf restore-check ${names.given}.`);
+    // Each step's own line, last: a step knows something about its half that nothing here does.
+    for (const line of input.fromSteps ?? [])
+        add(line);
+    if (input.writeToken !== undefined) {
+        add("The /api/status write token, shown once and stored nowhere but the state file:", input.writeToken);
+    }
+    // One trailing blank from the last `add`, which reads as a gap before the shell prompt.
+    return lines.slice(0, -1);
+}

package/dist/cli.d.ts

@@ -1,6 +1,6 @@
-export declare const COMMANDS: readonly ["new", "migrate", "bootstrap", "status-token", "check", "gen", "dev", "up"];
+export declare const COMMANDS: readonly ["new", "migrate", "bootstrap", "status-token", "check", "gen", "dev", "up", "doctor", "restore-check"];
 export type Command = (typeof COMMANDS)[number];
-export declare const USAGE = "hf \u2014 the hyperfixation CLI\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 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\nEvery command but `new` 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 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 interface Io {
     out(line: string): void;
     err(line: string): void;

package/dist/cli.js

@@ -2,9 +2,12 @@ import { parseArgs } from "node:util";
 import { bootstrapApp } from "./bootstrap.js";
 import { checkApp } from "./check.js";
 import { dev, devBuildSha } from "./dev.js";
+import { doctor, doctorLines } from "./doctor.js";
 import { generate } from "./gen.js";
 import { migrateApp } from "./migrate.js";
 import { newApp } from "./new.js";
+import { newAppCloud } from "./new-cloud.js";
+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";
@@ -17,9 +20,21 @@ export const COMMANDS = [
     "gen",
     "dev",
     "up",
+    "doctor",
+    "restore-check",
 ];
 export const USAGE = `hf — the hyperfixation CLI
 
+  hf new <name>             provision the app in the cloud: fetch the template, push a private
+                            repo, register a backup, Sentry, Langfuse and DNS, create the
+                            database and its roles, create the Coolify application and its
+                            environment, deploy, and print what is left to do by hand.
+                            Resumable — a rerun repeats only what did not finish
+      --budget-usd <amount>   the app's monthly LLM budget (required; no default)
+      --email <address>       the bootstrap admin's address (required)
+      --from <specifier>      template to fetch (default: gh:grahamlutz/hyperfixation-template)
+      --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
       --from <dir>            template checkout (default: the sibling hyperfixation-template)
@@ -45,13 +60,22 @@ export const USAGE = `hf — the hyperfixation CLI
 
   hf check                  declared env, pending migrations, and E001-E006
 
+  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
+
   hf gen [generator]        the app's turbo generators
 
   hf dev                    docker compose up, then pnpm dev under HF_BUILD_SHA=dev-<timestamp>
       --no-compose            leave the dev infrastructure alone
       --compose-only          bring the infrastructure up and stop
 
-Every command but \`new\` runs against the app at or above the working directory, or --dir.
+  hf restore-check <name>   restore the newest hf_<name> dump beside the live database and
+                            compare row counts; exits 1 on any mismatch
+      --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.
 `;
 const consoleIo = {
     out: (line) => console.log(line),
@@ -101,6 +125,10 @@ async function dispatch(command, argv, io) {
             return await commandDev(argv, io);
         case "up":
             return await commandUp(argv, io);
+        case "doctor":
+            return await commandDoctor(argv, io);
+        case "restore-check":
+            return await commandRestoreCheck(argv, io);
     }
 }
 async function commandNew(argv, io) {
@@ -111,14 +139,18 @@ async function commandNew(argv, io) {
             from: { type: "string" },
             into: { type: "string" },
             email: { type: "string" },
+            "budget-usd": { type: "string" },
         },
         allowPositionals: true,
     });
     const name = positionals[0];
     if (name === undefined) {
-        io.err("hf new needs a name: hf new <name> --local");
+        io.err("hf new needs a name: hf new <name> --budget-usd <amount> --email <address>");
         return 1;
     }
+    if (!values.local) {
+        return await commandNewCloud(name, values, io);
+    }
     const from = values.from ?? (await requireTemplateSource());
     const result = await newApp({
         name,
@@ -136,6 +168,37 @@ async function commandNew(argv, io) {
     io.out(`next: cd ${result.given} && hf up`);
     return 0;
 }
+/**
+ * The cloud half: both inputs it cannot invent are refused up front.
+ *
+ * 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.
+ */
+async function commandNewCloud(name, values, io) {
+    const missing = [
+        ...(values["budget-usd"] === undefined ? ["--budget-usd <amount>"] : []),
+        ...(values.email === undefined ? ["--email <address>"] : []),
+    ];
+    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.");
+        return 1;
+    }
+    const result = await newAppCloud({
+        name,
+        budgetUsd: values["budget-usd"],
+        email: values.email,
+        from: values.from,
+        into: values.into,
+        io,
+    });
+    io.out("");
+    for (const line of result.checklist)
+        io.out(line);
+    return 0;
+}
 async function commandMigrate(argv, io) {
     const { values } = parseArgs({
         args: [...argv],
@@ -212,6 +275,13 @@ async function commandCheck(argv, io) {
         io.err(`${finding.code}: ${finding.message}`);
     return 1;
 }
+async function commandDoctor(argv, io) {
+    const { positionals } = parseArgs({ args: [...argv], allowPositionals: true });
+    const result = await doctor({ name: positionals[0] });
+    for (const line of doctorLines(result))
+        io.out(line);
+    return result.ok ? 0 : 1;
+}
 async function commandGen(argv) {
     // No `parseArgs`: everything after `hf gen` is the generator's, including flags this CLI
     // happens to share a name with.
@@ -242,6 +312,29 @@ async function commandDev(argv, io) {
     });
     return 0;
 }
+async function commandRestoreCheck(argv, io) {
+    const { values, positionals } = parseArgs({
+        args: [...argv],
+        options: {
+            "backup-dir": { type: "string" },
+            "from-s3": { type: "boolean", default: false },
+        },
+        allowPositionals: true,
+    });
+    const name = positionals[0];
+    if (name === undefined) {
+        io.err("hf restore-check needs a name: hf restore-check <name>");
+        return 1;
+    }
+    const result = await restoreCheckApp({
+        app: name,
+        backupDir: values["backup-dir"],
+        fromS3: values["from-s3"],
+    });
+    for (const line of formatRestoreCheck(result))
+        io.out(line);
+    return result.ok ? 0 : 1;
+}
 async function commandUp(argv, io) {
     const { values } = parseArgs({ args: [...argv], options: { dir: { type: "string" } } });
     const result = await upApp({ dir: values.dir });

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

@@ -0,0 +1,17 @@
+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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export declare const backupStep: Step<CloudStepContext>;

package/dist/cloud-steps/backup.js

@@ -0,0 +1,40 @@
+import { requireOperatorConfig } from "../config.js";
+import { CoolifyClient } from "../providers/coolify.js";
+/**
+ * A daily dump of the app's database, and a checklist line about the one thing the API cannot
+ * answer.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export const backupStep = {
+    name: "backup",
+    run: async (context) => {
+        const { names } = context;
+        const required = requireOperatorConfig(context.config, ["HF_COOLIFY_URL", "HF_COOLIFY_TOKEN", "HF_COOLIFY_POSTGRES_UUID"], { env: context.env });
+        const coolify = new CoolifyClient({
+            url: required.HF_COOLIFY_URL,
+            token: required.HF_COOLIFY_TOKEN,
+            fetch: context.fetch,
+        });
+        await coolify.createDatabaseBackup(required.HF_COOLIFY_POSTGRES_UUID, {
+            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`);
+    },
+};