@hyperfixation/cli 0.1.0 → 0.1.2

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,135 @@
+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>;
+/**
+ * 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.
+ */
+export declare const OPTIONAL_CLOUD_CONFIG: readonly ConfigKey[];
+/**
+ * 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. Derived from `CONFIG_KEYS` rather than listed, because a hand-kept list is exactly
+ * what left `HF_GITHUB_TOKEN`, the Cloudflare pair and five others to fail at their own step: the
+ * ten steps between them read every key there is, so the required set is the complement of the
+ * optional one, and a key added for a step is required the moment it is named.
+ */
+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>;

package/dist/new-cloud.js

@@ -0,0 +1,219 @@
+import path from "node:path";
+import { checklistLines } from "./checklist.js";
+import { providerKeys } from "./cloud-steps/coolify.js";
+import { cloudCommands, CLOUD_STEPS, defaultTemplateFetch, spawnStepExec, } from "./cloud-steps/index.js";
+import { CONFIG_KEYS, loadOperatorConfig, pgAdminUser, postgresContainers, requireOperatorConfig, } from "./config.js";
+import { openDatabase } from "./database.js";
+import { deriveNames } from "./names.js";
+import { createSshRunner } from "./runner.js";
+import { openAppState, secretsHash, STEPS, } from "./state.js";
+/** The steps themselves; the runner is what orders and records them. */
+export { CLOUD_STEPS };
+/**
+ * The steps whose "done" depends on more than having run once.
+ *
+ * Both carry the app's secrets into the deployment — `coolify` PATCHes them as environment
+ * variables, `deploy` is what makes the containers read them — so a run that rotated a password
+ * has to redo both, even though a previous run recorded them.
+ */
+const SECRET_CARRYING_STEPS = ["coolify", "deploy"];
+/** The runner found state it will not act on: the operator has to be told, not worked around. */
+export class StepInvariantViolated extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "StepInvariantViolated";
+    }
+}
+/**
+ * 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 function envsAreCurrent(state) {
+    return state.coolify?.envsSecretsHash === secretsHash(state);
+}
+/**
+ * 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 function assertEnvsCurrent(state) {
+    if (state.steps.coolify === undefined || envsAreCurrent(state))
+        return;
+    throw new StepInvariantViolated("the app's secrets have changed since its Coolify environment was set: re-run hf new to " +
+        "PATCH the environment and redeploy (nothing was rolled back)");
+}
+/**
+ * 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 function assertRotationApplied(context) {
+    if (!context.rotated)
+        return;
+    if (context.state.isDone("coolify") && envsAreCurrent(context.state.state))
+        return;
+    throw new StepInvariantViolated("this run rotated the app's database passwords but never PATCHed them into Coolify: the " +
+        "deployed app still holds the old ones. Re-run hf new to finish the rotation.");
+}
+/**
+ * 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 async function invalidateStaleSecretSteps(state) {
+    if (envsAreCurrent(state.state))
+        return [];
+    const cleared = [];
+    for (const name of SECRET_CARRYING_STEPS) {
+        if (!state.isDone(name))
+            continue;
+        await state.clearDone(name);
+        cleared.push(name);
+    }
+    return cleared;
+}
+/**
+ * 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 async function runSteps(steps, context) {
+    assertStepOrder(steps);
+    const invalidated = await invalidateStaleSecretSteps(context.state);
+    const ran = [];
+    const skipped = [];
+    for (const step of steps) {
+        if (context.state.isDone(step.name)) {
+            skipped.push(step.name);
+            continue;
+        }
+        await step.run(context);
+        await context.state.markDone(step.name);
+        ran.push(step.name);
+    }
+    assertEnvsCurrent(context.state.state);
+    assertRotationApplied(context);
+    return { ran, skipped, invalidated };
+}
+/**
+ * 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.
+ */
+export const OPTIONAL_CLOUD_CONFIG = [
+    "HF_DB_HOST_INTERNAL",
+    "HF_DB_CONTAINER",
+    "HF_PG_ADMIN_USER",
+    "HF_ANTHROPIC_API_KEY",
+    "HF_OPENAI_API_KEY",
+    "HF_LANGFUSE_ORG_KEY",
+    "HF_LANGFUSE_PUBLIC_KEY",
+    "HF_LANGFUSE_SECRET_KEY",
+];
+/**
+ * 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. Derived from `CONFIG_KEYS` rather than listed, because a hand-kept list is exactly
+ * what left `HF_GITHUB_TOKEN`, the Cloudflare pair and five others to fail at their own step: the
+ * ten steps between them read every key there is, so the required set is the complement of the
+ * optional one, and a key added for a step is required the moment it is named.
+ */
+export const REQUIRED_CLOUD_CONFIG = CONFIG_KEYS.filter((key) => !OPTIONAL_CLOUD_CONFIG.includes(key));
+/**
+ * `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 async function newAppCloud(options) {
+    const env = options.env ?? process.env;
+    const config = options.config ?? (await loadOperatorConfig({ env }));
+    const required = requireOperatorConfig(config, REQUIRED_CLOUD_CONFIG, { env });
+    const names = deriveNames(options.name);
+    const state = await openAppState(names.given, { dir: options.stateDir, env });
+    const runner = options.runner ?? createSshRunner({ host: required.HF_SSH_HOST });
+    // `PGPASSWORD` is libpq's own name for it, and the same place `hf restore-check` reads it:
+    // Coolify's cluster password is not an hf config key, because nothing of ours should hold it.
+    const clusterAdmin = options.clusterAdmin ?? { user: pgAdminUser(config), password: env.PGPASSWORD };
+    let database;
+    const hadWriteToken = state.state.statusTokens?.write !== undefined;
+    const fqdn = `${names.given}.${required.HF_BASE_DOMAIN}`;
+    const context = {
+        state,
+        rotated: false,
+        names,
+        dir: path.resolve(options.into ?? process.cwd(), names.given),
+        config,
+        env,
+        io: options.io,
+        checklist: [],
+        exec: spawnStepExec,
+        from: options.from,
+        fetchTemplate: defaultTemplateFetch,
+        fetch: options.fetch,
+        email: options.email,
+        budgetUsd: options.budgetUsd,
+        database: async () => {
+            // The container is named so the tunnel can discover its address, but no `dockerExec`: that
+            // transport has no address, and every use of the cluster here — `provisionRoles`, the
+            // migrator, the tokens — is a pg client.
+            database ??= await openDatabase(runner, {
+                admin: clusterAdmin,
+                containers: postgresContainers(config),
+            });
+            return database;
+        },
+        commands: options.commands ?? cloudCommands,
+        now: options.now ?? (() => Date.now()),
+        sleep: options.sleep ?? (async (ms) => await new Promise((resolve) => setTimeout(resolve, ms))),
+    };
+    let result;
+    try {
+        result = await runSteps(options.steps ?? CLOUD_STEPS, context);
+    }
+    finally {
+        await database?.close();
+    }
+    const checklist = checklistLines({
+        names,
+        fqdn,
+        repo: state.state.repo,
+        dbHost: config.HF_DB_HOST_INTERNAL ?? required.HF_COOLIFY_POSTGRES_UUID,
+        stateFile: state.file,
+        providerKeysSent: providerKeys(config).map(([key]) => key),
+        // Whatever the steps themselves asked the operator to look at — the backup schedule included,
+        // which is the one thing Coolify's API cannot be asked about.
+        fromSteps: context.checklist,
+        // Shown once means the run that minted it; every later run leaves it in the state file alone.
+        writeToken: hadWriteToken ? undefined : state.state.statusTokens?.write,
+    });
+    return { ...result, dir: context.dir, fqdn, checklist };
+}
+/**
+ * `STEPS`' order is the rotation-safety argument — every fallible create before `database`, and
+ * `coolify` straight after it — so a caller that assembles its list in another order is a bug
+ * here rather than a stranded app on the box.
+ */
+function assertStepOrder(steps) {
+    const positions = steps.map((step) => STEPS.indexOf(step.name));
+    for (let index = 1; index < positions.length; index += 1) {
+        if (positions[index] <= positions[index - 1]) {
+            throw new StepInvariantViolated(`steps out of order: ${steps[index - 1].name} before ${steps[index].name}`);
+        }
+    }
+}

package/dist/new.d.ts

@@ -55,3 +55,5 @@ export declare function newApp(options: NewAppOptions): Promise<NewAppResult>;
 /** The placeholder map. Exported because `hf check` reports a leftover placeholder by name. */
 export declare function placeholders(names: AppNames): Record<string, string>;
 export declare function substitute(contents: string, names: AppNames): string;
+/** Substitutes every placeholder in a copied tree; the cloud `template` step reuses this one. */
+export declare function substituteTree(dir: string, names: AppNames): Promise<string[]>;

package/dist/new.js

@@ -115,7 +115,8 @@ async function assertTemplateSource(source) {
         throw new TemplateError(`${source} has no ${TEMPLATE_MARKER}: it is not a hyperfixation template checkout`);
     }
 }
-async function substituteTree(dir, names) {
+/** Substitutes every placeholder in a copied tree; the cloud `template` step reuses this one. */
+export async function substituteTree(dir, names) {
     const changed = [];
     for (const file of await walk(dir)) {
         if (BINARY_EXTENSIONS.has(path.extname(file)))

package/dist/providers/cloudflare.d.ts

@@ -0,0 +1,49 @@
+import { type FetchLike } from "./http.js";
+export declare const CLOUDFLARE_API_URL = "https://api.cloudflare.com/client/v4";
+export interface CloudflareDnsRecord {
+    id: string;
+    type: string;
+    name: string;
+    content: string;
+    proxied: boolean;
+    ttl: number;
+}
+/** Cloudflare wraps every answer; `success: false` still arrives as HTTP 200 on some routes. */
+export interface CloudflareEnvelope<Result> {
+    success: boolean;
+    errors: {
+        code: number;
+        message: string;
+    }[];
+    result: Result;
+}
+/**
+ * The one record `hf new` writes: `A <app>.<HF_BASE_DOMAIN>` → `HF_BOX_IP`, DNS-only.
+ *
+ * `proxied: false` is the decided domain scheme — Coolify's proxy terminates TLS, and a
+ * proxied record would both need Full-strict and hide the box from Coolify's ACME challenge.
+ */
+export interface CloudflareARecord {
+    type: "A";
+    name: string;
+    content: string;
+    ttl: number;
+    proxied: boolean;
+    comment?: string;
+}
+export interface CloudflareClientOptions {
+    /** `HF_CLOUDFLARE_TOKEN`. */
+    token: string;
+    /** Overridden only by tests; the real API has one address. */
+    url?: string;
+    fetch?: FetchLike;
+}
+export declare class CloudflareClient {
+    private readonly request;
+    constructor(options: CloudflareClientOptions);
+    listDnsRecords(zoneId: string, filters?: {
+        name?: string;
+        type?: string;
+    }): Promise<CloudflareEnvelope<CloudflareDnsRecord[]>>;
+    createDnsRecord(zoneId: string, record: CloudflareARecord): Promise<CloudflareEnvelope<CloudflareDnsRecord>>;
+}

package/dist/providers/cloudflare.js

@@ -0,0 +1,27 @@
+import { createTransport, segment } from "./http.js";
+export const CLOUDFLARE_API_URL = "https://api.cloudflare.com/client/v4";
+export class CloudflareClient {
+    request;
+    constructor(options) {
+        this.request = createTransport({
+            provider: "cloudflare",
+            baseUrl: options.url ?? CLOUDFLARE_API_URL,
+            headers: { authorization: `Bearer ${options.token}` },
+            fetch: options.fetch,
+        });
+    }
+    async listDnsRecords(zoneId, filters = {}) {
+        return await this.request({
+            method: "GET",
+            path: `/zones/${segment(zoneId)}/dns_records`,
+            query: { name: filters.name, type: filters.type },
+        });
+    }
+    async createDnsRecord(zoneId, record) {
+        return await this.request({
+            method: "POST",
+            path: `/zones/${segment(zoneId)}/dns_records`,
+            body: record,
+        });
+    }
+}

package/dist/providers/coolify.d.ts

@@ -0,0 +1,148 @@
+import { type FetchLike } from "./http.js";
+export interface CoolifyProject {
+    uuid: string;
+    name: string;
+    description?: string;
+}
+/** Coolify's environment model carries a uuid the documented schema does not list. */
+export interface CoolifyEnvironment {
+    uuid: string;
+    name: string;
+}
+/**
+ * The application `hf new` creates: a docker-compose build pack on the app's own private
+ * repository, reached through the Coolify GitHub App.
+ *
+ * `environment_uuid` and `environment_name` are both required by the API document even though
+ * its prose says either will do — so both are required here, and the uuid is what
+ * `listEnvironments` is for.
+ */
+export interface CoolifyApplicationRequest {
+    project_uuid: string;
+    server_uuid: string;
+    environment_name: string;
+    environment_uuid: string;
+    github_app_uuid: string;
+    /** `owner/name`, as Coolify stores it for a GitHub App source. */
+    git_repository: string;
+    git_branch: string;
+    build_pack: "nixpacks" | "railpack" | "static" | "dockerfile" | "dockercompose";
+    name?: string;
+    description?: string;
+    /** Comma-separated; the app's `https://<name>.<HF_BASE_DOMAIN>`. */
+    domains?: string;
+    ports_exposes?: string;
+    docker_compose_location?: string;
+    connect_to_docker_network?: boolean;
+    instant_deploy?: boolean;
+    is_auto_deploy_enabled?: boolean;
+}
+export interface CoolifyApplication {
+    uuid: string;
+}
+/** What `GET /applications` returns per item; the document's `Application` has both of these. */
+export interface CoolifyApplicationSummary {
+    uuid: string;
+    name: string;
+    fqdn?: string;
+}
+/**
+ * What `PATCH /databases/{uuid}` accepts of the fields E2 might need.
+ *
+ * Narrow on purpose: the document lists every engine's credentials, and nothing in it attaches a
+ * database to a docker network — `is_public`/`public_port` is the only reach the API has over how
+ * a database is addressed.
+ */
+export interface CoolifyDatabaseUpdate {
+    name?: string;
+    description?: string;
+    is_public?: boolean;
+    public_port?: number;
+}
+export interface CoolifyEnvironmentVariable {
+    key: string;
+    value: string;
+    is_preview?: boolean;
+    is_literal?: boolean;
+    is_multiline?: boolean;
+    is_shown_once?: boolean;
+}
+export interface CoolifyDeploymentRequest {
+    deployments: {
+        message: string;
+        resource_uuid: string;
+        deployment_uuid: string;
+    }[];
+}
+export interface CoolifyDeployment {
+    deployment_uuid: string;
+    /** `queued` | `in_progress` | `finished` | `failed` | `cancelled-by-user`, as Coolify sets it. */
+    status: string;
+    commit?: string;
+    logs?: string;
+}
+export interface CoolifyBackupRequest {
+    /** A cron expression, or one of `every_minute`…`yearly`. */
+    frequency: string;
+    enabled?: boolean;
+    save_s3?: boolean;
+    s3_storage_uuid?: string;
+    /** Comma-separated database names — the app's `hf_<name>`, not the whole cluster. */
+    databases_to_backup?: string;
+    dump_all?: boolean;
+    backup_now?: boolean;
+    database_backup_retention_amount_locally?: number;
+    database_backup_retention_days_locally?: number;
+}
+export interface CoolifyBackup {
+    uuid: string;
+    message?: string;
+}
+export interface CoolifyClientOptions {
+    /** `HF_COOLIFY_URL` — the instance's origin, without `/api/v1`. */
+    url: string;
+    /** `HF_COOLIFY_TOKEN`. */
+    token: string;
+    fetch?: FetchLike;
+}
+export declare class CoolifyClient {
+    private readonly request;
+    constructor(options: CoolifyClientOptions);
+    createProject(body: {
+        name: string;
+        description?: string;
+    }): Promise<{
+        uuid: string;
+    }>;
+    /** Every project on the instance; `hf new` finds its own by name rather than creating a second. */
+    listProjects(): Promise<CoolifyProject[]>;
+    getProject(uuid: string): Promise<CoolifyProject>;
+    listEnvironments(projectUuid: string): Promise<CoolifyEnvironment[]>;
+    createPrivateGithubAppApplication(body: CoolifyApplicationRequest): Promise<CoolifyApplication>;
+    /**
+     * Every application, so a rerun can find the one it created last time by name.
+     *
+     * The state cache is the first place to look for the uuid; this is what answers the case where
+     * the application exists but the state file does not, which is a cold run against a live app.
+     */
+    listApplications(options?: {
+        tag?: string;
+    }): Promise<CoolifyApplicationSummary[]>;
+    updateEnvsBulk(appUuid: string, data: readonly CoolifyEnvironmentVariable[]): Promise<unknown>;
+    deploy(uuid: string, options?: {
+        force?: boolean;
+    }): Promise<CoolifyDeploymentRequest>;
+    getDeployment(deploymentUuid: string): Promise<CoolifyDeployment>;
+    createDatabaseBackup(databaseUuid: string, body: CoolifyBackupRequest): Promise<CoolifyBackup>;
+    /**
+     * The database's scheduled backups.
+     *
+     * `unknown`, not a model: upstream documents this response as a string whose example reads
+     * "Content is very complex. Will be implemented later.", so there is nothing to type against.
+     * A caller that needs a field has to narrow it against the box itself.
+     */
+    listDatabaseBackups(databaseUuid: string): Promise<unknown>;
+    /** The database as Coolify holds it — undocumented in shape, same as the backups list. */
+    getDatabase(uuid: string): Promise<unknown>;
+    updateDatabase(uuid: string, body: CoolifyDatabaseUpdate): Promise<unknown>;
+}