@hyperfixation/cli 0.1.0 → 0.1.1

package/dist/doctor.js

@@ -0,0 +1,310 @@
+import { access, readdir } from "node:fs/promises";
+import path from "node:path";
+import { checkE006, quoteIdent } from "@hyperfixation/db";
+import { Client } from "pg";
+import { loadOperatorConfig, requireOperatorConfig, } from "./config.js";
+import { openDatabase } from "./database.js";
+import { deriveNames } from "./names.js";
+import { GithubClient } from "./providers/github.js";
+import { createSshRunner } from "./runner.js";
+import { openAppState, stateDir } from "./state.js";
+/** A restore check older than this is a warning: E5 is meant to run weekly, not once. */
+export const RESTORE_CHECK_MAX_AGE_DAYS = 7;
+/** The branch prefix Phase 4's core bumps open their pull requests on. */
+export const CORE_BUMP_BRANCH_PREFIX = "core-bump/";
+/** The cluster role `hf doctor` reads privileges as, before `SET ROLE`. */
+const CLUSTER_ADMIN_USER = "postgres";
+/**
+ * `hf doctor` — what is wrong with the deployed apps, one line per finding.
+ *
+ * Every check is reported rather than thrown: an app whose status endpoint is unreachable is
+ * also an app whose E006 and whose bump PRs the operator still wants to know about, and the
+ * whole point of this command is one screen that says whether anything needs attention.
+ *
+ * Nothing here prints a secret. The read token authorizes the status request and never appears
+ * in a finding; a provider's response body is dropped for the same reason (`ProviderError`).
+ */
+export async function doctor(options = {}) {
+    const env = options.env ?? process.env;
+    const config = options.config ?? (await loadOperatorConfig({ env }));
+    const required = requireOperatorConfig(config, ["HF_BASE_DOMAIN", "HF_GITHUB_TOKEN"], { env });
+    const dir = options.stateDir ?? stateDir(env);
+    const context = {
+        dir,
+        env,
+        baseDomain: required.HF_BASE_DOMAIN,
+        github: new GithubClient({ token: required.HF_GITHUB_TOKEN, fetch: options.fetch }),
+        fetch: options.fetch ?? ((input, init) => globalThis.fetch(input, init)),
+        now: options.now ?? (() => new Date()),
+        privileges: options.privileges ?? defaultPrivilegeCheck(config, env),
+    };
+    const names = options.name === undefined ? await stateNames(dir) : [options.name];
+    const findings = [];
+    for (const name of names)
+        findings.push(...(await doctorApp(context, name)));
+    return { findings, ok: findings.every((finding) => finding.severity === "ok") };
+}
+const MARKER = { ok: "OK  ", warn: "WARN", fail: "FAIL" };
+/** The report as printed: a blank line and a header per app, then its findings. */
+export function doctorLines(result) {
+    const lines = [];
+    let app;
+    for (const finding of result.findings) {
+        if (finding.app !== app) {
+            if (app !== undefined)
+                lines.push("");
+            lines.push(finding.app);
+            app = finding.app;
+        }
+        lines.push(`  ${MARKER[finding.severity]} ${finding.check}: ${finding.message}`);
+    }
+    if (lines.length === 0)
+        lines.push("no apps in the state cache: hf new has provisioned none");
+    return lines;
+}
+/**
+ * E006 as `postgres` with `SET ROLE hf_<app>`, over the tunnel a `Runner` opens.
+ *
+ * As the app role rather than as an admin because that is the only role whose answer matters —
+ * a superuser's privileges are both true whatever the migrator granted.
+ */
+export function tunnelPrivilegeCheck(runner, options = {}) {
+    return async (target) => {
+        const db = await openDatabase(runner, {
+            admin: { user: CLUSTER_ADMIN_USER },
+            container: options.container,
+        });
+        try {
+            const adminUrl = db.adminUrl(target.databaseName);
+            if (adminUrl === undefined) {
+                throw new Error(`E006 cannot be read over the ${db.kind} transport: ${CLUSTER_ADMIN_USER} has to be ` +
+                    "a session a pg client holds open, so that SET ROLE outlives the statement");
+            }
+            await checkAppRolePrivileges(adminUrl, target.applicationRole);
+        }
+        finally {
+            await db.close();
+        }
+    };
+}
+/**
+ * `@hyperfixation/db`'s own E006, run against `adminUrl` — which must already name the app's
+ * database — after `SET ROLE`. The check itself is not restated here: a second copy of the
+ * privilege query is a second thing to keep in step with the grants the migrator makes.
+ */
+export async function checkAppRolePrivileges(adminUrl, role) {
+    const client = new Client({ connectionString: adminUrl });
+    await client.connect();
+    try {
+        await client.query(`SET ROLE ${quoteIdent(role)}`);
+        await checkE006(client);
+    }
+    finally {
+        await client.end();
+    }
+}
+function defaultPrivilegeCheck(config, env) {
+    const { HF_SSH_HOST } = requireOperatorConfig(config, ["HF_SSH_HOST"], { env });
+    return tunnelPrivilegeCheck(createSshRunner({ host: HF_SSH_HOST }));
+}
+async function doctorApp(context, name) {
+    const findings = [];
+    const add = (check, severity, message) => {
+        findings.push({ app: name, check, severity, message });
+    };
+    const file = path.join(context.dir, `${name}.json`);
+    if (!(await exists(file))) {
+        add("state", "fail", `no state file at ${file}: hf new has not provisioned ${name}`);
+        return findings;
+    }
+    let state;
+    try {
+        state = (await openAppState(name, { dir: context.dir, env: context.env })).state;
+    }
+    catch (error) {
+        add("state", "fail", flatten(error.message));
+        return findings;
+    }
+    const repo = parseRepo(state.repo);
+    let mainSha;
+    let mainShaProblem;
+    if (repo === undefined) {
+        mainShaProblem = "no owner/name repo recorded in state; main's sha cannot be read";
+    }
+    else {
+        try {
+            mainSha = (await context.github.getReference(repo.owner, repo.repo, "heads/main")).object.sha;
+        }
+        catch (error) {
+            mainShaProblem = `${state.repo ?? "?"}: ${flatten(error.message)}`;
+        }
+    }
+    const report = await statusFindings(context, name, state, add);
+    versionFinding(report?.applicationVersion, mainSha, mainShaProblem, add);
+    if (report !== undefined) {
+        budgetFinding(report.budget.current, "current", add);
+        budgetFinding(report.budget.previous, "previous", add);
+    }
+    await privilegeFindings(context, name, add);
+    restoreCheckFindings(context, state, add);
+    if (repo !== undefined)
+        await bumpFindings(context, repo, add);
+    return findings;
+}
+/** The health and run lines; `undefined` when the app did not answer, which is its own line. */
+async function statusFindings(context, name, state, add) {
+    const url = `https://${name}.${context.baseDomain}/api/status`;
+    const token = state.statusTokens?.read;
+    if (token === undefined) {
+        add("status", "fail", `no read status token in state; hf status-token has not run for ${name}`);
+        return undefined;
+    }
+    let report;
+    try {
+        report = await getStatus(context.fetch, url, token);
+    }
+    catch (error) {
+        add("status", "fail", `GET ${url}: ${flatten(error.message)}`);
+        return undefined;
+    }
+    add("status", report.health === "ok" ? "ok" : "warn", `health ${report.health}, ${String(report.anomalies)} anomaly/anomalies, core ` +
+        report.coreVersion);
+    add("runs", "ok", `${String(report.runs.running)} run(s) running`);
+    // Only `fixtures` gets a line. `live` is the expected deploy, and `unknown` is an app whose
+    // worker has not reported yet — neither is a finding, but a canned draft an operator takes
+    // for a real one is.
+    if (report.llm.mode === "fixtures") {
+        add("llm", "warn", "app is serving fixture drafts — no provider key set");
+    }
+    return report;
+}
+function versionFinding(deployed, mainSha, mainShaProblem, add) {
+    if (mainShaProblem !== undefined) {
+        add("version", "fail", mainShaProblem);
+        return;
+    }
+    if (deployed === undefined || mainSha === undefined)
+        return;
+    if (deployed === null) {
+        add("version", "warn", "the app reports no applicationVersion: HF_BUILD_SHA is unset");
+        return;
+    }
+    add("version", deployed === mainSha ? "ok" : "warn", deployed === mainSha
+        ? `applicationVersion ${short(mainSha)} is main`
+        : `applicationVersion ${short(deployed)} is not main ${short(mainSha)}`);
+}
+function budgetFinding(period, which, add) {
+    if (period === null) {
+        add("budget", "ok", `no ${which} period row yet`);
+        return;
+    }
+    const over = Number(period.spentUsd) > Number(period.budgetUsd);
+    const drifting = Number(period.driftUsd) !== 0;
+    const spend = `${period.period} spent $${period.spentUsd} of $${period.budgetUsd}`;
+    if (over || drifting) {
+        add("budget", "warn", `${spend}${over ? " — over budget" : ""}${drifting ? ` — drift $${period.driftUsd}` : ""}`);
+        return;
+    }
+    add("budget", "ok", `${spend}, no drift`);
+}
+async function privilegeFindings(context, name, add) {
+    let target;
+    try {
+        const names = deriveNames(name);
+        target = {
+            app: name,
+            databaseName: names.databaseName,
+            applicationRole: names.applicationRole,
+        };
+    }
+    catch (error) {
+        add("E006", "fail", flatten(error.message));
+        return;
+    }
+    try {
+        await context.privileges(target);
+        add("E006", "ok", `${target.applicationRole} has USAGE on dbos and INSERT on dbos.workflow_status`);
+    }
+    catch (error) {
+        add("E006", "fail", flatten(error.message));
+    }
+}
+function restoreCheckFindings(context, state, add) {
+    const last = state.lastRestoreCheckAt;
+    if (last === undefined) {
+        add("restore-check", "warn", "never run; run hf restore-check");
+        return;
+    }
+    const at = Date.parse(last);
+    if (Number.isNaN(at)) {
+        add("restore-check", "warn", `lastRestoreCheckAt is not a date: ${last}`);
+        return;
+    }
+    const days = (context.now().getTime() - at) / 86_400_000;
+    add("restore-check", days > RESTORE_CHECK_MAX_AGE_DAYS ? "warn" : "ok", `last ran ${days.toFixed(1)} day(s) ago (${last})`);
+}
+async function bumpFindings(context, repo, add) {
+    let open;
+    try {
+        open = await context.github.listPullRequests(repo.owner, repo.repo, {
+            state: "open",
+            per_page: 100,
+        });
+    }
+    catch (error) {
+        add("core-bump", "fail", flatten(error.message));
+        return;
+    }
+    const bumps = open.filter((pull) => pull.head.ref.startsWith(CORE_BUMP_BRANCH_PREFIX));
+    if (bumps.length === 0) {
+        add("core-bump", "ok", "no open core-bump pull request");
+        return;
+    }
+    for (const pull of bumps) {
+        let checks;
+        try {
+            checks = (await context.github.getCombinedStatus(repo.owner, repo.repo, pull.head.sha)).state;
+        }
+        catch (error) {
+            add("core-bump", "fail", `#${String(pull.number)}: ${flatten(error.message)}`);
+            continue;
+        }
+        add("core-bump", checks === "failure" ? "warn" : "ok", `#${String(pull.number)} ${pull.head.ref}: checks ${checks} — ${pull.html_url}`);
+    }
+}
+/**
+ * The status request, and nothing of the response body on a refusal: `/api/status` answers 401
+ * with a body of its own, and everything it would say about the token belongs nowhere near a
+ * terminal.
+ */
+async function getStatus(fetchImpl, url, token) {
+    const response = await fetchImpl(url, {
+        headers: { authorization: `Bearer ${token}`, accept: "application/json" },
+    });
+    if (!response.ok)
+        throw new Error(`HTTP ${String(response.status)}`);
+    return (await response.json());
+}
+async function stateNames(dir) {
+    const entries = await readdir(dir).catch(() => []);
+    return entries
+        .filter((entry) => entry.endsWith(".json"))
+        .map((entry) => entry.slice(0, -".json".length))
+        .sort();
+}
+function parseRepo(repo) {
+    const parts = repo?.split("/") ?? [];
+    if (parts.length !== 2 || parts[0] === "" || parts[1] === "")
+        return undefined;
+    return { owner: parts[0], repo: parts[1] };
+}
+async function exists(file) {
+    return await access(file).then(() => true, () => false);
+}
+/** One finding is one line, and `BootCheckFailure` spells its details across several. */
+function flatten(message) {
+    return message.replace(/\s*\n\s*-?\s*/g, "; ").trim();
+}
+function short(sha) {
+    return sha.length > 7 ? sha.slice(0, 7) : sha;
+}

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { main, COMMANDS, USAGE, type Command, type Io } from "./cli.js";
 export { newApp, placeholders, substitute, TemplateError, TEMPLATE_MARKER, EXCLUDED_ENTRIES, type NewAppOptions, type NewAppResult, } from "./new.js";
 export { findTemplateSource, requireTemplateSource, TEMPLATE_DIR_ENV, } from "./template-source.js";
 export { deriveNames, APP_ID, GIVEN_NAME, InvalidAppName, type AppNames } from "./names.js";
-export { resolveApp, NotAnApp, type ResolvedApp } from "./app.js";
+export { resolveApp, NotAnApp, type ResolveAppOptions, type ResolvedApp } from "./app.js";
 export { declaredNames, parseEnvFile, readEnvFile } from "./env-file.js";
 export { MissingEnv, requireEnv } from "./require-env.js";
 export { credentialsOf, provisionLocalRoles, type LocalRoleOptions, type LocalRoleResult, } from "./roles.js";
@@ -14,3 +14,8 @@ export { probeApp, type AppRegistry } from "./probe.js";
 export { generate, GENERATOR_BIN, GENERATOR_CONFIG, NoGenerators, type GenerateOptions, } from "./gen.js";
 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 { 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 { provisionDatabase, ProvisionDatabaseError, REQUIRED_EXTENSIONS, type ProvisionDatabaseOptions, type ProvisionDatabaseResult, } from "./provision-database.js";

package/dist/index.js

@@ -14,3 +14,8 @@ export { probeApp } from "./probe.js";
 export { generate, GENERATOR_BIN, GENERATOR_CONFIG, NoGenerators, } from "./gen.js";
 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 { 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 { provisionDatabase, ProvisionDatabaseError, REQUIRED_EXTENSIONS, } from "./provision-database.js";

package/dist/migrate.d.ts

@@ -6,7 +6,18 @@ export interface MigrateAppOptions {
     dir?: string;
     /** Skips role provisioning — the cloud path, where `hf new` created the roles. */
     skipRoles?: boolean;
+    /** Connection URLs and anything else the app needs, in place of a `.env`; see `ResolveAppOptions`. */
+    env?: Record<string, string>;
 }
+/**
+ * The environment the app's `migrate.ts` runs under.
+ *
+ * With an overlay — the cloud path — it is the overlay alone plus `INHERITED_ENV`, **not**
+ * `process.env`: the operator's laptop is where `HF_COOLIFY_TOKEN`, `HF_GITHUB_TOKEN` and the
+ * Cloudflare and Sentry tokens live, and none of them is the app's to hold. A local run has no
+ * overlay and keeps Phase 1's behaviour, `.env` under the shell it was started from.
+ */
+export declare function migrateChildEnv(app: ResolvedApp): NodeJS.ProcessEnv;
 export interface MigrateAppResult {
     app: ResolvedApp;
     roles: LocalRoleResult | undefined;

package/dist/migrate.js

@@ -5,6 +5,30 @@ import { credentialsOf, provisionLocalRoles } from "./roles.js";
 import { run } from "./spawn.js";
 /** The entrypoint track B's template ships; the same file the deployed `migrate` service runs. */
 export const MIGRATE_ENTRY = "migrate.ts";
+/**
+ * Names the migrator child inherits from this process when an overlay supplies the rest.
+ *
+ * `HOME` because pnpm, tsx and `psql` all write under it; `TMPDIR` and `SHELL` because Node's
+ * own child machinery uses them.
+ */
+const INHERITED_ENV = ["PATH", "HOME", "TMPDIR", "SHELL"];
+/**
+ * The environment the app's `migrate.ts` runs under.
+ *
+ * With an overlay — the cloud path — it is the overlay alone plus `INHERITED_ENV`, **not**
+ * `process.env`: the operator's laptop is where `HF_COOLIFY_TOKEN`, `HF_GITHUB_TOKEN` and the
+ * Cloudflare and Sentry tokens live, and none of them is the app's to hold. A local run has no
+ * overlay and keeps Phase 1's behaviour, `.env` under the shell it was started from.
+ */
+export function migrateChildEnv(app) {
+    if (Object.keys(app.envOverlay).length === 0) {
+        return { ...app.env, HF_PROCESS: "migrate" };
+    }
+    const inherited = {};
+    for (const name of INHERITED_ENV)
+        inherited[name] = process.env[name];
+    return { ...inherited, ...app.envOverlay, HF_PROCESS: "migrate" };
+}
 /**
  * `hf migrate` — the application role, then the app's own migrator entrypoint.
  *
@@ -17,7 +41,7 @@ export const MIGRATE_ENTRY = "migrate.ts";
  * The first half is the CLI's own, and only local: a container never creates a role.
  */
 export async function migrateApp(options = {}) {
-    const app = await resolveApp(options.dir);
+    const app = await resolveApp(options.dir, { env: options.env });
     const databaseUrl = requireEnv(app, "DATABASE_URL");
     const migratorUrl = requireEnv(app, "MIGRATOR_DATABASE_URL");
     let roles;
@@ -31,7 +55,7 @@ export async function migrateApp(options = {}) {
     }
     await run(process.execPath, ["--import", "tsx", path.join(app.dir, MIGRATE_ENTRY)], {
         cwd: app.dir,
-        env: { ...app.env, HF_PROCESS: "migrate" },
+        env: migrateChildEnv(app),
     });
     return { app, roles };
 }

package/dist/new-cloud.d.ts

@@ -0,0 +1,126 @@
+import { CLOUD_STEPS, type CloudCommands, type CloudStepContext } from "./cloud-steps/index.js";
+import { type ConfigKey, type OperatorConfig } from "./config.js";
+import { type AdminCredentials } from "./database.js";
+import type { FetchLike } from "./providers/http.js";
+import { type Runner } from "./runner.js";
+import { type AppState, type AppStateStore, type StepName } from "./state.js";
+/** The steps themselves; the runner is what orders and records them. */
+export { CLOUD_STEPS };
+/**
+ * What the runner itself is handed. The steps get `CloudStepContext`, which extends it.
+ */
+export interface CloudContext {
+    state: AppStateStore;
+    /**
+     * Set by the `database` step when it gave an existing role a new password.
+     *
+     * The deployed app still holds the old one at that moment, so the run is only safe once the
+     * Coolify envs and a redeploy have followed; `assertEnvsCurrent` is what refuses to call it
+     * finished before that.
+     */
+    rotated: boolean;
+}
+export interface Step<Context extends CloudContext = CloudContext> {
+    name: StepName;
+    run(context: Context): Promise<void>;
+}
+export interface RunStepsResult {
+    ran: readonly StepName[];
+    /** Recorded by an earlier run, and still current. */
+    skipped: readonly StepName[];
+    /** Recorded by an earlier run, but against secrets since rotated; forgotten and run again. */
+    invalidated: readonly StepName[];
+}
+/** The runner found state it will not act on: the operator has to be told, not worked around. */
+export declare class StepInvariantViolated extends Error {
+    constructor(message: string);
+}
+/**
+ * True when the secrets the Coolify envs were last PATCHed with are the ones the state holds now.
+ *
+ * A `coolify` step that has run but recorded no hash counts as stale: re-PATCHing is idempotent
+ * and cheap, and the alternative is trusting a file written before this field existed.
+ */
+export declare function envsAreCurrent(state: AppState): boolean;
+/**
+ * Refuses a recorded state whose deployment is authenticating with secrets that no longer exist.
+ *
+ * Silent otherwise, including for an app that has not reached `coolify` yet: a run that stops
+ * early is resumable, whereas a `coolify` recorded against passwords since rotated is a deployed
+ * app locked out of its own database with nothing left to notice it.
+ */
+export declare function assertEnvsCurrent(state: AppState): void;
+/**
+ * Refuses to finish a run that rotated a password without the Coolify environment catching up.
+ *
+ * The state-only check above cannot see this case on its own: a list of steps that stops before
+ * `coolify` leaves a consistent file and a deployed app on dead credentials.
+ */
+export declare function assertRotationApplied(context: CloudContext): void;
+/**
+ * Forgets the steps that carried secrets the app no longer has, and reports which.
+ *
+ * Done once, before the first step, and by clearing the records rather than by ignoring them:
+ * `coolify` makes the hash current again the moment it re-runs, so a per-step test would then
+ * count `deploy` as done and leave the containers reading the previous environment. Clearing also
+ * survives a crash in between — the next run sees the same two steps missing.
+ */
+export declare function invalidateStaleSecretSteps(state: AppStateStore): Promise<readonly StepName[]>;
+/**
+ * Runs the steps of a cloud `hf new` in order, skipping what a previous run finished.
+ *
+ * A step is marked done only after its `run` resolves, so a failure leaves the step unrecorded
+ * and the next run repeats it — the one direction that is safe, since repeating a create costs a
+ * duplicate at worst while recording one that never happened costs an app nobody can finish.
+ * Errors propagate untouched: the caller prints them, and the state file is the resume point.
+ */
+export declare function runSteps<Context extends CloudContext>(steps: readonly Step<Context>[], context: Context): Promise<RunStepsResult>;
+/**
+ * Every operator config key a cloud `hf new` needs, checked before the first step.
+ *
+ * All at once, and before anything is created: `requireOperatorConfig` names every missing key,
+ * and an operator who learns about them one failed step at a time pays for a half-provisioned app
+ * each time. The optional keys are deliberately absent — `HF_DB_HOST_INTERNAL` has a default, and
+ * the two provider keys are what the checklist warns about when they are unset.
+ */
+export declare const REQUIRED_CLOUD_CONFIG: readonly ConfigKey[];
+export interface NewAppCloudOptions {
+    name: string;
+    /** Required in the cloud: a deployed app never starts under a cap nobody chose. */
+    budgetUsd: string;
+    /** Required in the cloud: there is no prompt and no `.env` to carry it. */
+    email: string;
+    from?: string;
+    /** Where `<name>` is created. Defaults to the working directory. */
+    into?: string;
+    io: {
+        out(line: string): void;
+    };
+    config?: OperatorConfig;
+    env?: NodeJS.ProcessEnv;
+    /** Where the per-app state files are. Defaults to `stateDir()`. */
+    stateDir?: string;
+    /** Replaces `CLOUD_STEPS`; the tests run a shorter list, never a different order. */
+    steps?: readonly Step<CloudStepContext>[];
+    commands?: CloudCommands;
+    runner?: Runner;
+    /** The cluster admin the database is provisioned as. Defaults to `postgres`/`PGPASSWORD`. */
+    clusterAdmin?: AdminCredentials;
+    fetch?: FetchLike;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface NewAppCloudResult extends RunStepsResult {
+    dir: string;
+    fqdn: string;
+    /** What the operator still has to do, ready to print. */
+    checklist: readonly string[];
+}
+/**
+ * `hf new <name>` without `--local`: the ten steps, resumable, then the checklist.
+ *
+ * Nothing here is interactive and nothing is prompted for — this runs against five APIs and a box
+ * — so every input is a flag or a config key, and a missing one is reported before the first
+ * request rather than half way through.
+ */
+export declare function newAppCloud(options: NewAppCloudOptions): Promise<NewAppCloudResult>;