@hyperfixation/cli 0.1.0 → 0.1.1

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

@@ -0,0 +1,120 @@
+import { type OperatorConfig } from "../config.js";
+import type { Database } from "../database.js";
+import type { AppNames } from "../names.js";
+import type { CloudContext } from "../new-cloud.js";
+import type { FetchLike } from "../providers/http.js";
+/**
+ * A step refused to act, or a command it ran failed.
+ *
+ * Carries no provider body and no environment: the only thing a step is allowed to say about a
+ * secret is that it has one. `ProviderError` keeps the same rule for the HTTP half.
+ */
+export declare class StepFailed extends Error {
+    constructor(message: string);
+}
+/** Where a step's progress lines go; the CLI's `Io` satisfies it. */
+export interface StepOut {
+    out(line: string): void;
+}
+export interface StepExecOptions {
+    cwd: string;
+    /** Laid over this process's environment for the child alone — where a token is passed. */
+    env?: Record<string, string>;
+    /** Collect the output instead of letting the child write to the terminal. */
+    capture?: boolean;
+}
+export interface StepExecOutcome {
+    /** `null` when the child was killed by a signal. */
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * How a step runs `git` and `pnpm`.
+ *
+ * An argument array and a separate environment, never a command string: the token the repo step
+ * hands `git push` must reach it through the environment, where `ps` cannot read it, and an
+ * interpolated command line is the one shape that cannot promise that.
+ */
+export type StepExec = (command: string, args: readonly string[], options: StepExecOptions) => Promise<StepExecOutcome>;
+/** `fetchTemplate`, narrowed to what the template step asks of it so a test can be one. */
+export type TemplateFetch = (source: string | undefined, dir: string) => Promise<string>;
+/**
+ * The app's own commands, as the `coolify` step runs them through the tunnel.
+ *
+ * An interface rather than three direct calls because these are the three things a test cannot
+ * run — each needs the generated app's toolchain and a migrated database — and because the `env`
+ * overlay they take is the whole point: the cloud path never reads or writes a `.env`.
+ */
+export interface CloudCommands {
+    migrate(options: {
+        dir: string;
+        env: Record<string, string>;
+    }): Promise<void>;
+    bootstrap(options: {
+        dir: string;
+        env: Record<string, string>;
+        email: string;
+        budgetUsd: string;
+    }): Promise<void>;
+    /** The plaintext of each token it generated — the only moment either exists outside a hash. */
+    statusToken(options: {
+        dir: string;
+        env: Record<string, string>;
+    }): Promise<{
+        read?: string;
+        write?: string;
+    }>;
+}
+/** What every step of a cloud `hf new` needs beyond the state the runner keeps. */
+export interface CloudStepContext extends CloudContext {
+    names: AppNames;
+    /** Absolute path of the app directory the run creates, or adopts. */
+    dir: string;
+    config: OperatorConfig;
+    io: StepOut;
+    /**
+     * Lines to print once the run is over — things only the operator can do.
+     *
+     * Appended to, never printed here: a line about the app's DNS is no use in the middle of the
+     * provisioning it is about.
+     */
+    checklist: string[];
+    exec: StepExec;
+    /** `--from`: a giget specifier. `undefined` fetches `TEMPLATE_REPOSITORY`. */
+    from?: string;
+    fetchTemplate: TemplateFetch;
+    fetch?: FetchLike;
+    /** Named by `MissingConfig` when a step needs a key the operator has not set. */
+    env?: NodeJS.ProcessEnv;
+    /** The bootstrap admin's address and the app's starting budget; both required in the cloud. */
+    email: string;
+    budgetUsd: string;
+    /**
+     * The box's Postgres cluster, opened on first use and shared for the rest of the run.
+     *
+     * One tunnel: `database` and `coolify` both need one, and a second `ssh -L` would be a second
+     * thing to leak. The run closes it in a `finally`.
+     */
+    database(): Promise<Database>;
+    commands: CloudCommands;
+    /** The clock and the wait the `deploy` step polls against; a test replaces both. */
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+export declare const spawnStepExec: StepExec;
+export declare const defaultTemplateFetch: TemplateFetch;
+/** The real three, each under the env overlay the `coolify` step builds. */
+export declare const cloudCommands: CloudCommands;
+/** `<app>.<HF_BASE_DOMAIN>` — the host Coolify serves and the passkey relying-party origin. */
+export declare function appFqdn(context: CloudStepContext): string;
+/** Runs a command in the app directory and throws on a non-zero exit. */
+export declare function mustRun(context: CloudStepContext, command: string, args: readonly string[], options?: {
+    env?: Record<string, string>;
+    capture?: boolean;
+}): Promise<StepExecOutcome>;
+/** `HEAD`'s sha, or `undefined` when the directory has no commit yet — or no repository. */
+export declare function gitHead(context: CloudStepContext): Promise<string | undefined>;
+export declare function exists(target: string): Promise<boolean>;
+export declare function firstLine(text: string): string;
+export declare function short(sha: string): string;

package/dist/cloud-steps/context.js

@@ -0,0 +1,88 @@
+import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+import { bootstrapApp } from "../bootstrap.js";
+import { requireOperatorConfig } from "../config.js";
+import { migrateApp } from "../migrate.js";
+import { statusTokenApp } from "../status-token.js";
+import { fetchTemplate } from "../template-source.js";
+/**
+ * A step refused to act, or a command it ran failed.
+ *
+ * Carries no provider body and no environment: the only thing a step is allowed to say about a
+ * secret is that it has one. `ProviderError` keeps the same rule for the HTTP half.
+ */
+export class StepFailed extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "StepFailed";
+    }
+}
+export const spawnStepExec = async (command, args, options) => {
+    const child = spawn(command, [...args], {
+        cwd: options.cwd,
+        env: options.env === undefined ? process.env : { ...process.env, ...options.env },
+        // `inherit` for a command whose output the operator is meant to watch — `pnpm install` is
+        // minutes long — and pipes only where a step reads the answer back.
+        stdio: options.capture === true ? ["ignore", "pipe", "pipe"] : ["ignore", "inherit", "inherit"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+        stdout += chunk.toString("utf8");
+    });
+    child.stderr?.on("data", (chunk) => {
+        stderr += chunk.toString("utf8");
+    });
+    const code = await new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.once("close", (exitCode) => resolve(exitCode));
+    });
+    return { code, stdout, stderr };
+};
+export const defaultTemplateFetch = async (source, dir) => await fetchTemplate(source, dir);
+/** The real three, each under the env overlay the `coolify` step builds. */
+export const cloudCommands = {
+    // `skipRoles`: the database step created all three, and the cloud migrator cannot create one.
+    migrate: async ({ dir, env }) => {
+        await migrateApp({ dir, skipRoles: true, env });
+    },
+    bootstrap: async ({ dir, env, email, budgetUsd }) => {
+        await bootstrapApp({ dir, env, email, budgetUsd });
+    },
+    // `rotate`, because reaching this call at all means the state cache has no plaintext to reuse:
+    // whatever hash the column holds is one nothing can authenticate against any more.
+    statusToken: async ({ dir, env }) => (await statusTokenApp({ dir, env, kinds: ["read", "write"], rotate: true })).tokens,
+};
+/** `<app>.<HF_BASE_DOMAIN>` — the host Coolify serves and the passkey relying-party origin. */
+export function appFqdn(context) {
+    const { HF_BASE_DOMAIN } = requireOperatorConfig(context.config, ["HF_BASE_DOMAIN"], {
+        env: context.env,
+    });
+    return `${context.names.given}.${HF_BASE_DOMAIN}`;
+}
+/** Runs a command in the app directory and throws on a non-zero exit. */
+export async function mustRun(context, command, args, options = {}) {
+    const outcome = await context.exec(command, args, { cwd: context.dir, ...options });
+    if (outcome.code !== 0) {
+        throw new StepFailed(`${command} ${args.join(" ")} exited with code ${String(outcome.code)}` +
+            (outcome.stderr.trim() === "" ? "" : `: ${firstLine(outcome.stderr)}`));
+    }
+    return outcome;
+}
+/** `HEAD`'s sha, or `undefined` when the directory has no commit yet — or no repository. */
+export async function gitHead(context) {
+    const outcome = await context.exec("git", ["rev-parse", "HEAD"], {
+        cwd: context.dir,
+        capture: true,
+    });
+    return outcome.code === 0 ? outcome.stdout.trim() : undefined;
+}
+export async function exists(target) {
+    return await access(target).then(() => true, () => false);
+}
+export function firstLine(text) {
+    return text.trim().split("\n")[0] ?? "";
+}
+export function short(sha) {
+    return sha.length > 7 ? sha.slice(0, 7) : sha;
+}

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

@@ -0,0 +1,74 @@
+import { type OperatorConfig } from "../config.js";
+import type { Step } from "../new-cloud.js";
+import { type CoolifyEnvironmentVariable } from "../providers/coolify.js";
+import { StepFailed, type CloudStepContext } from "./context.js";
+/** The Coolify environment every `hf new` application lives in; created with the project. */
+export declare const COOLIFY_ENVIRONMENT = "production";
+/** Where the build pack looks for the compose file, relative to the repository root. */
+export declare const COMPOSE_LOCATION = "/docker-compose.prod.yml";
+/** The compose file the drift assertion reads, under the app's directory. */
+export declare const PROD_COMPOSE_FILE = "docker-compose.prod.yml";
+/**
+ * Set by compose itself rather than by us: `DOCKER_IMAGE` has a default in the `x-app` anchor and
+ * `SOURCE_COMMIT` is what Coolify's builder exports for the image tag and the build arg. Sending
+ * either as an application environment variable would override the deploy's own.
+ */
+export declare const COMPOSE_PROVIDED_ENV: readonly ["DOCKER_IMAGE", "SOURCE_COMMIT"];
+/** Written literally into every `environment:` block, so the deploy never carries them. */
+export declare const CONTAINER_PROVIDED_ENV: readonly ["HF_PROCESS", "HF_BUILD_SHA"];
+/**
+ * The two variables `hf new` omits when the operator has no key for them.
+ *
+ * An app with neither serves fixture drafts and says so on `/api/status` (`llm.mode`); an empty
+ * variable in Coolify's UI reads as configured, so the absence is the honest state and the
+ * checklist is what says it out loud.
+ */
+export declare const OPTIONAL_PROVIDER_ENV: readonly ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"];
+/**
+ * The app's environment and what `docker-compose.prod.yml` interpolates have diverged.
+ *
+ * Raised before the first Coolify request of the run, because the failure it prevents is silent: a
+ * variable the template added and nothing sent is an empty string in three containers, and only
+ * the one that reads it finds out.
+ */
+export declare class EnvDrift extends StepFailed {
+    readonly missing: readonly string[];
+    readonly extra: readonly string[];
+    constructor(missing: readonly string[], extra: readonly string[]);
+}
+/** Every `${VAR}` a compose file interpolates, `${VAR:-default}` and `${VAR?err}` included. */
+export declare function composeInterpolatedNames(contents: string): string[];
+/**
+ * What the deployed app needs from its environment, read from the generated app itself.
+ *
+ * Both halves, because they fail differently: `.env.example` is the declared contract (and equals
+ * `REQUIRED_ENV`, which the template's own test enforces), while the compose interpolations are
+ * what actually reaches a container. A variable in one and not the other is drift too.
+ */
+export declare function neededEnvNames(dir: string): Promise<string[]>;
+/**
+ * Refuses to PATCH an environment that is not the one the compose file needs.
+ *
+ * A provider key the operator has not configured is deliberately absent rather than missing, so it
+ * is excused here and reported in the checklist instead.
+ */
+export declare function assertEnvsMatchCompose(dir: string, sent: readonly string[]): Promise<void>;
+/**
+ * The twelve variables the deployed app runs on, or ten when no provider key is configured.
+ *
+ * Generates `BETTER_AUTH_SECRET` on first sight and records it: it is the one value in the list
+ * that no provider hands back, so a run that did not persist it would lock every existing session
+ * out on the next deploy.
+ */
+export declare function buildAppEnvs(context: CloudStepContext): Promise<CoolifyEnvironmentVariable[]>;
+/** The provider keys the operator configured, in `REQUIRED_ENV` order; absent ones are omitted. */
+export declare function providerKeys(config: OperatorConfig): [string, string][];
+/**
+ * The Coolify project, environment and application, the app's whole environment, and the three
+ * commands that have to run against the database before the first deploy.
+ *
+ * Every sub-action is found by name before it is created, and every uuid is recorded the moment
+ * the API hands it back, so a crash anywhere in here leaves a rerun with something to find rather
+ * than a second project beside the first.
+ */
+export declare const coolifyStep: Step<CloudStepContext>;

package/dist/cloud-steps/coolify.js

@@ -0,0 +1,300 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { requireOperatorConfig } from "../config.js";
+import { declaredNames } from "../env-file.js";
+import { CoolifyClient } from "../providers/coolify.js";
+import { generateBetterAuthSecret, secretsHash } from "../state.js";
+import { appFqdn, StepFailed } from "./context.js";
+/** The Coolify environment every `hf new` application lives in; created with the project. */
+export const COOLIFY_ENVIRONMENT = "production";
+/** Where the build pack looks for the compose file, relative to the repository root. */
+export const COMPOSE_LOCATION = "/docker-compose.prod.yml";
+/** The compose file the drift assertion reads, under the app's directory. */
+export const PROD_COMPOSE_FILE = "docker-compose.prod.yml";
+/**
+ * Set by compose itself rather than by us: `DOCKER_IMAGE` has a default in the `x-app` anchor and
+ * `SOURCE_COMMIT` is what Coolify's builder exports for the image tag and the build arg. Sending
+ * either as an application environment variable would override the deploy's own.
+ */
+export const COMPOSE_PROVIDED_ENV = ["DOCKER_IMAGE", "SOURCE_COMMIT"];
+/** Written literally into every `environment:` block, so the deploy never carries them. */
+export const CONTAINER_PROVIDED_ENV = ["HF_PROCESS", "HF_BUILD_SHA"];
+/**
+ * The two variables `hf new` omits when the operator has no key for them.
+ *
+ * An app with neither serves fixture drafts and says so on `/api/status` (`llm.mode`); an empty
+ * variable in Coolify's UI reads as configured, so the absence is the honest state and the
+ * checklist is what says it out loud.
+ */
+export const OPTIONAL_PROVIDER_ENV = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"];
+/** Which operator key carries each of them, in `REQUIRED_ENV` order. */
+const PROVIDER_ENV_SOURCE = [
+    ["ANTHROPIC_API_KEY", "HF_ANTHROPIC_API_KEY"],
+    ["OPENAI_API_KEY", "HF_OPENAI_API_KEY"],
+];
+/** The operator config the environment itself is built out of. */
+const REQUIRED_FOR_ENVS = [
+    "HF_COOLIFY_POSTGRES_UUID",
+    "HF_SMTP_URL",
+    "HF_EMAIL_FROM",
+    "HF_LANGFUSE_URL",
+];
+/**
+ * The app's environment and what `docker-compose.prod.yml` interpolates have diverged.
+ *
+ * Raised before the first Coolify request of the run, because the failure it prevents is silent: a
+ * variable the template added and nothing sent is an empty string in three containers, and only
+ * the one that reads it finds out.
+ */
+export class EnvDrift extends StepFailed {
+    missing;
+    extra;
+    constructor(missing, extra) {
+        super(`the app's environment has drifted from ${PROD_COMPOSE_FILE}: ` +
+            [
+                missing.length === 0 ? "" : `${missing.join(", ")} needed but not sent`,
+                extra.length === 0 ? "" : `${extra.join(", ")} sent but not needed`,
+            ]
+                .filter((part) => part !== "")
+                .join("; ") +
+            ". Nothing was sent to Coolify — reconcile .env.example, REQUIRED_ENV and every " +
+            "environment: block first.");
+        this.name = "EnvDrift";
+        this.missing = missing;
+        this.extra = extra;
+    }
+}
+/** Every `${VAR}` a compose file interpolates, `${VAR:-default}` and `${VAR?err}` included. */
+export function composeInterpolatedNames(contents) {
+    const names = new Set();
+    for (const match of contents.matchAll(/\$\{([A-Za-z_][A-Za-z0-9_]*)[^}]*\}/g)) {
+        names.add(match[1]);
+    }
+    return [...names];
+}
+/**
+ * What the deployed app needs from its environment, read from the generated app itself.
+ *
+ * Both halves, because they fail differently: `.env.example` is the declared contract (and equals
+ * `REQUIRED_ENV`, which the template's own test enforces), while the compose interpolations are
+ * what actually reaches a container. A variable in one and not the other is drift too.
+ */
+export async function neededEnvNames(dir) {
+    const declared = declaredNames(await readFile(path.join(dir, ".env.example"), "utf8"));
+    const interpolated = composeInterpolatedNames(await readFile(path.join(dir, PROD_COMPOSE_FILE), "utf8"));
+    const provided = new Set([...COMPOSE_PROVIDED_ENV, ...CONTAINER_PROVIDED_ENV]);
+    return [...new Set([...declared, ...interpolated])].filter((name) => !provided.has(name));
+}
+/**
+ * Refuses to PATCH an environment that is not the one the compose file needs.
+ *
+ * A provider key the operator has not configured is deliberately absent rather than missing, so it
+ * is excused here and reported in the checklist instead.
+ */
+export async function assertEnvsMatchCompose(dir, sent) {
+    const needed = await neededEnvNames(dir);
+    const sentNames = new Set(sent);
+    const optional = new Set(OPTIONAL_PROVIDER_ENV);
+    const missing = needed.filter((name) => !sentNames.has(name) && !optional.has(name));
+    const extra = sent.filter((name) => !needed.includes(name));
+    if (missing.length > 0 || extra.length > 0)
+        throw new EnvDrift(missing, extra);
+}
+/**
+ * The twelve variables the deployed app runs on, or ten when no provider key is configured.
+ *
+ * Generates `BETTER_AUTH_SECRET` on first sight and records it: it is the one value in the list
+ * that no provider hands back, so a run that did not persist it would lock every existing session
+ * out on the next deploy.
+ */
+export async function buildAppEnvs(context) {
+    const config = requireOperatorConfig(context.config, REQUIRED_FOR_ENVS, { env: context.env });
+    const { names } = context;
+    const database = context.state.state.database ?? {};
+    if (database.applicationPassword === undefined || database.migratorPassword === undefined) {
+        throw new StepFailed("no database passwords in the state cache: the database step has not run for this app");
+    }
+    if (context.state.state.betterAuthSecret === undefined) {
+        await context.state.patch({ betterAuthSecret: generateBetterAuthSecret() });
+    }
+    // The hostname the app's containers reach Postgres by, which is not the one the tunnel uses.
+    // Coolify's own compose generator names the container after the database's uuid;
+    // `HF_DB_HOST_INTERNAL` is how a box that disagrees says so.
+    const host = context.config.HF_DB_HOST_INTERNAL ?? config.HF_COOLIFY_POSTGRES_UUID;
+    const langfuse = context.state.state.langfuse ?? {};
+    const envs = [
+        {
+            key: "DATABASE_URL",
+            value: internalUrl(names.applicationRole, database.applicationPassword, host, names.databaseName),
+        },
+        {
+            key: "MIGRATOR_DATABASE_URL",
+            value: internalUrl(names.migratorRole, database.migratorPassword, host, names.databaseName),
+        },
+        { key: "APP_URL", value: `https://${appFqdn(context)}` },
+        { key: "BETTER_AUTH_SECRET", value: context.state.state.betterAuthSecret ?? "" },
+        { key: "SMTP_URL", value: config.HF_SMTP_URL },
+        { key: "EMAIL_FROM", value: config.HF_EMAIL_FROM },
+        { key: "SENTRY_DSN", value: context.state.state.sentryDsn ?? "" },
+        { key: "LANGFUSE_BASE_URL", value: config.HF_LANGFUSE_URL },
+        { key: "LANGFUSE_PUBLIC_KEY", value: langfuse.publicKey ?? "" },
+        { key: "LANGFUSE_SECRET_KEY", value: langfuse.secretKey ?? "" },
+    ];
+    for (const [key, value] of providerKeys(context.config))
+        envs.push({ key, value });
+    return envs;
+}
+/** The provider keys the operator configured, in `REQUIRED_ENV` order; absent ones are omitted. */
+export function providerKeys(config) {
+    const pairs = [];
+    for (const [name, source] of PROVIDER_ENV_SOURCE) {
+        const value = config[source];
+        if (value !== undefined && value !== "")
+            pairs.push([name, value]);
+    }
+    return pairs;
+}
+/**
+ * The Coolify project, environment and application, the app's whole environment, and the three
+ * commands that have to run against the database before the first deploy.
+ *
+ * Every sub-action is found by name before it is created, and every uuid is recorded the moment
+ * the API hands it back, so a crash anywhere in here leaves a rerun with something to find rather
+ * than a second project beside the first.
+ */
+export const coolifyStep = {
+    name: "coolify",
+    run: async (context) => {
+        const { state, names } = context;
+        const required = requireOperatorConfig(context.config, ["HF_COOLIFY_URL", "HF_COOLIFY_TOKEN"], { env: context.env });
+        const coolify = new CoolifyClient({
+            url: required.HF_COOLIFY_URL,
+            token: required.HF_COOLIFY_TOKEN,
+            fetch: context.fetch,
+        });
+        // Before the first request, so drift costs nothing but the message.
+        const envs = await buildAppEnvs(context);
+        await assertEnvsMatchCompose(context.dir, envs.map((env) => env.key));
+        const projectUuid = await findOrCreateProject(context, coolify);
+        const environmentUuid = await productionEnvironment(context, coolify, projectUuid);
+        const appUuid = await findOrCreateApplication(context, coolify, projectUuid, environmentUuid);
+        // Unconditionally, every time this step runs. The step is recorded only while
+        // `coolify.envsSecretsHash` still matches the state's secrets, so a rotation has already made
+        // the runner forget it — which means "not done" and "the secrets moved" both land here.
+        await coolify.updateEnvsBulk(appUuid, envs);
+        context.io.out(`${names.given}: ${String(envs.length)} environment variable(s) set in Coolify`);
+        await runThroughTunnel(context, envs);
+        // Last, not straight after the PATCH: `status-token` mints secrets that `secretsHash` covers,
+        // so a hash recorded before it would be stale the moment this step returned.
+        await state.patch({ coolify: { envsSecretsHash: secretsHash(state.state) } });
+    },
+};
+async function findOrCreateProject(context, coolify) {
+    const name = context.names.given;
+    const existing = (await coolify.listProjects()).find((project) => project.name === name);
+    if (existing !== undefined) {
+        await context.state.patch({ coolify: { projectUuid: existing.uuid } });
+        return existing.uuid;
+    }
+    const created = await coolify.createProject({
+        name,
+        description: `hyperfixation app ${name}`,
+    });
+    await context.state.patch({ coolify: { projectUuid: created.uuid } });
+    context.io.out(`${name}: created the Coolify project ${name}`);
+    return created.uuid;
+}
+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;
+}
+async function findOrCreateApplication(context, coolify, projectUuid, environmentUuid) {
+    const name = context.names.given;
+    const existing = (await coolify.listApplications()).find((application) => application.name === name);
+    if (existing !== undefined) {
+        await context.state.patch({ coolify: { appUuid: existing.uuid } });
+        return existing.uuid;
+    }
+    const repo = context.state.state.repo;
+    if (repo === undefined) {
+        throw new StepFailed("no owner/name repository in the state cache: the repo step has not run for this app");
+    }
+    const required = requireOperatorConfig(context.config, ["HF_COOLIFY_SERVER_UUID", "HF_COOLIFY_GITHUB_APP_UUID"], { env: context.env });
+    const fqdn = appFqdn(context);
+    const created = await coolify.createPrivateGithubAppApplication({
+        project_uuid: projectUuid,
+        server_uuid: required.HF_COOLIFY_SERVER_UUID,
+        environment_name: COOLIFY_ENVIRONMENT,
+        environment_uuid: environmentUuid,
+        github_app_uuid: required.HF_COOLIFY_GITHUB_APP_UUID,
+        git_repository: repo,
+        git_branch: "main",
+        build_pack: "dockercompose",
+        docker_compose_location: COMPOSE_LOCATION,
+        connect_to_docker_network: true,
+        name,
+        domains: `https://${fqdn}`,
+        // The `deploy` step is what deploys, once the environment is set and the database migrated.
+        instant_deploy: false,
+    });
+    await context.state.patch({ coolify: { appUuid: created.uuid } });
+    context.io.out(`${name}: created the Coolify application at https://${fqdn}`);
+    return created.uuid;
+}
+/**
+ * `migrate`, `bootstrap` and `status-token` against the new database, through the E2 tunnel.
+ *
+ * The children get the app's own environment with the two connection URLs pointed at the tunnel —
+ * never a `.env`, and never this laptop's: an operator with their own `DATABASE_URL` exported would
+ * otherwise have the tokens provisioned into a dev database.
+ */
+async function runThroughTunnel(context, envs) {
+    const { names } = context;
+    const database = await context.database();
+    const local = database.adminUrl(names.databaseName);
+    if (local === undefined) {
+        throw new StepFailed(`migrate, bootstrap and status-token cannot run over the ${database.kind} transport: each ` +
+            "is a pg client and needs an address. Publish the Coolify Postgres port on the box's " +
+            "loopback so the tunnel works.");
+    }
+    const stored = context.state.state.database ?? {};
+    const overlay = {};
+    for (const env of envs)
+        overlay[env.key] = env.value;
+    overlay.DATABASE_URL = asRole(local, names.applicationRole, stored.applicationPassword ?? "");
+    overlay.MIGRATOR_DATABASE_URL = asRole(local, names.migratorRole, stored.migratorPassword ?? "");
+    // The roles already exist — the database step created them — and the migrator role in the cloud
+    // cannot create one anyway.
+    await context.commands.migrate({ dir: context.dir, env: overlay });
+    context.io.out(`${names.given}: migrated ${names.databaseName}`);
+    await context.commands.bootstrap({
+        dir: context.dir,
+        env: overlay,
+        email: context.email,
+        budgetUsd: context.budgetUsd,
+    });
+    context.io.out(`${names.given}: bootstrapped ${context.email} with a $${context.budgetUsd} budget`);
+    // The state file is the only copy of the plaintext, so "already minted" means "in the state",
+    // not "hashed in the database" — and a rerun that finds a hash it has no plaintext for has to
+    // replace it, which is what `rotate` is for. Nothing else holds either token.
+    if (context.state.state.statusTokens?.read === undefined) {
+        const tokens = await context.commands.statusToken({ dir: context.dir, env: overlay });
+        await context.state.patch({ statusTokens: tokens });
+        context.io.out(`${names.given}: minted the /api/status read and write tokens`);
+    }
+}
+function internalUrl(role, password, host, databaseName) {
+    return `postgres://${encodeURIComponent(role)}:${encodeURIComponent(password)}@${host}:5432/${databaseName}`;
+}
+function asRole(url, role, password) {
+    const parsed = new URL(url);
+    parsed.username = encodeURIComponent(role);
+    parsed.password = encodeURIComponent(password);
+    return parsed.toString();
+}

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

@@ -0,0 +1,12 @@
+import type { Step } from "../new-cloud.js";
+import type { CloudStepContext } from "./context.js";
+/**
+ * `hf_<app>`, its extensions and its three roles, immediately before `coolify`.
+ *
+ * Immediately before on purpose. This is the one step that rotates — a run with no password in the
+ * state cache gives an existing role a new one — and a deployed app keeps the old password until
+ * `coolify` PATCHes the environment and `deploy` restarts the containers. Everything fallible
+ * therefore happens earlier, and `rotated` is what refuses to call a run that stopped in between
+ * finished.
+ */
+export declare const databaseStep: Step<CloudStepContext>;

package/dist/cloud-steps/database.js

@@ -0,0 +1,25 @@
+import { provisionDatabase } from "../provision-database.js";
+/**
+ * `hf_<app>`, its extensions and its three roles, immediately before `coolify`.
+ *
+ * Immediately before on purpose. This is the one step that rotates — a run with no password in the
+ * state cache gives an existing role a new one — and a deployed app keeps the old password until
+ * `coolify` PATCHes the environment and `deploy` restarts the containers. Everything fallible
+ * therefore happens earlier, and `rotated` is what refuses to call a run that stopped in between
+ * finished.
+ */
+export const databaseStep = {
+    name: "database",
+    run: async (context) => {
+        const { names } = context;
+        const result = await provisionDatabase(await context.database(), {
+            app: names.given,
+            state: context.state,
+        });
+        if (result.rotated)
+            context.rotated = true;
+        context.io.out(`${names.given}: ${result.createdDatabase ? "created" : "found"} ${result.databaseName}, ` +
+            `roles ${result.roles.migrator}, ${result.roles.application}, ${result.roles.readonly}` +
+            (result.rotated ? " (passwords rotated — Coolify and a redeploy follow)" : ""));
+    },
+};

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

@@ -0,0 +1,18 @@
+import type { Step } from "../new-cloud.js";
+import { type CloudStepContext } from "./context.js";
+/**
+ * How long the step waits for Coolify to build and for the app to report the sha it built.
+ *
+ * One deadline for both halves: what the operator is waiting on is a deployed app answering with
+ * the right version, and a build that took fourteen minutes has not left time for anything else.
+ */
+export declare const DEPLOY_TIMEOUT_MS: number;
+/**
+ * Deploy, wait for the build, then wait for the app to say it is running that commit.
+ *
+ * Never skipped while it is not recorded, and recorded only once `/api/status` reports the pushed
+ * sha: a redeploy costs a rebuild, whereas a `deploy` marked done off the API's own "finished"
+ * would hide a container that came up on the previous image — which is exactly what a rotation
+ * needs this step to rule out.
+ */
+export declare const deployStep: Step<CloudStepContext>;