@hyperfixation/cli 0.1.0 → 0.1.2

package/dist/database.js

@@ -0,0 +1,226 @@
+import { isIPv4 } from "node:net";
+import { Client } from "pg";
+import { shellQuote, TUNNEL_LOOPBACK } from "./runner.js";
+export class DatabaseTransportError extends Error {
+    transport;
+    constructor(transport, message, options) {
+        super(`${transport}: ${message}`, options);
+        this.name = "DatabaseTransportError";
+        this.transport = transport;
+    }
+}
+/**
+ * Blanks anything that looks like a password before it reaches a message.
+ *
+ * `psql` echoes the failing statement, and the failing statement is sometimes an `ALTER ROLE
+ * … PASSWORD`; a connection string carries one in its authority. Neither may reach a terminal
+ * or a scrollback, so every transport error goes through here on the way out.
+ */
+export function redactPasswords(text) {
+    return text
+        .replace(/(PASSWORD\s+)'(?:[^']|'')*'/gi, "$1'***'")
+        .replace(/(:\/\/[^:@/\s]+):[^@/\s]+@/g, "$1:***@");
+}
+/** Separates the columns of a `psql -A` row; no SQL value this provisions can contain it. */
+const FIELD_SEPARATOR = "";
+export const DEFAULT_POSTGRES_PORT = 5432;
+const DEFAULT_ADMIN_DATABASE = "postgres";
+/**
+ * Docker's network→IP map for one container, as whitespace-separated `network=ip` pairs.
+ *
+ * A Go template rather than `--format json` and a parse: the output is one flat line, so nothing
+ * about it depends on which docker version the box has.
+ */
+const DOCKER_NETWORKS_FORMAT = "{{range $k,$v := .NetworkSettings.Networks}}{{$k}}={{$v.IPAddress}} {{end}}";
+/** The network Coolify attaches its services to, and the one the box host can route to. */
+const COOLIFY_NETWORK = "coolify";
+/**
+ * Opens the cluster over `runner`: the box's loopback, else the container, else `docker exec`.
+ *
+ * Coolify publishes nothing for its Postgres — `docker inspect` reports `{"5432/tcp": null}`, so
+ * the box's `127.0.0.1:5432` is not a listener and forwarding to it can never work. The
+ * container's address on the `coolify` network is the route in: the box host routes to it, and
+ * `ssh -L localPort:<containerIP>:5432` makes the box the hop. Publishing the port would bind
+ * every interface, which is not a trade worth making for a forward that already works.
+ *
+ * The loopback is still tried first and costs one `ssh` when it fails, because some setups do
+ * publish it. Each probe is a real `SELECT 1` rather than a port check: an `ssh -L` forward
+ * accepts locally and only then discovers that nothing is listening on the far side, so a forward
+ * to an unpublished port looks healthy until the first query.
+ */
+export async function openDatabase(runner, options) {
+    const remotePort = options.remotePort ?? DEFAULT_POSTGRES_PORT;
+    const loopback = await tryTunnel(runner, options.admin, remotePort, TUNNEL_LOOPBACK);
+    if ("database" in loopback)
+        return loopback.database;
+    const candidates = [
+        ...(options.containers ?? []),
+        ...(options.container === undefined ? [] : [options.container]),
+    ];
+    if (candidates.length === 0) {
+        throw new DatabaseTransportError("tunnel", `could not reach Postgres on ${TUNNEL_LOOPBACK}:${String(remotePort)} on the box, and no ` +
+            "container was named to discover an address on the docker network", { cause: loopback.failure });
+    }
+    const found = await containerAddress(runner, candidates);
+    const direct = await tryTunnel(runner, options.admin, remotePort, found.address);
+    if ("database" in direct)
+        return direct.database;
+    if (options.dockerExec !== true) {
+        throw new DatabaseTransportError("tunnel", `could not reach Postgres on ${TUNNEL_LOOPBACK}:${String(remotePort)} on the box, nor on ` +
+            `${found.address}:${String(remotePort)}, which is where ${found.container} answers on ` +
+            "the docker network", { cause: direct.failure });
+    }
+    return dockerExecDatabase(runner, found.container, options.admin);
+}
+/** The cluster at a URL this process can already dial — a test's Postgres, or a live tunnel. */
+export function openDatabaseUrl(adminUrl) {
+    return tunnelDatabase(adminUrl, undefined, undefined);
+}
+async function tryTunnel(runner, admin, remotePort, remoteHost) {
+    let tunnel;
+    try {
+        tunnel = await runner.tunnel(remotePort, remoteHost);
+        const database = tunnelDatabase(adminUrlOf(admin, tunnel.localPort), tunnel, {
+            host: remoteHost,
+            port: remotePort,
+        });
+        await database.query("SELECT 1");
+        return { database };
+    }
+    catch (failure) {
+        await tunnel?.close();
+        return { failure };
+    }
+}
+/**
+ * The first of `containers` that exists, and its own address, asked of the box.
+ *
+ * The `coolify` network by name, because a Coolify service also sits on a per-service network
+ * that only its own stack is on; the first address is the fallback for a box that names its
+ * network something else. Every candidate that failed is reported, because which name a database
+ * got is a fact about how it was created and the operator is the one who knows it.
+ */
+async function containerAddress(runner, containers) {
+    const problems = [];
+    for (const container of containers) {
+        const command = ["docker", "inspect", "-f", DOCKER_NETWORKS_FORMAT, container];
+        const result = await runner.exec(command);
+        if (result.code !== 0) {
+            problems.push(`${container}: ${shellQuote(command)} exited ${String(result.code)}: ` +
+                result.stderr.trim());
+            continue;
+        }
+        const address = coolifyAddress(result.stdout);
+        if (address === undefined) {
+            problems.push(`${container}: no IPv4 address on any docker network, ${shellQuote(command)} printed ` +
+                JSON.stringify(result.stdout.trim()));
+            continue;
+        }
+        return { container, address };
+    }
+    throw new DatabaseTransportError("tunnel", `no Postgres container on the box under any name tried (${containers.join(", ")}): ` +
+        problems.join("; "));
+}
+/** The `coolify` network's address in `docker inspect`'s output, else the first one there is. */
+function coolifyAddress(stdout) {
+    const networks = stdout
+        .split(/\s+/)
+        .filter((pair) => pair.includes("="))
+        .map((pair) => ({
+        network: pair.slice(0, pair.indexOf("=")),
+        address: pair.slice(pair.indexOf("=") + 1),
+    }))
+        // An IPv4 literal and nothing else: this goes into an `ssh -L` field, and a container with no
+        // address on a network reports the key with an empty value.
+        .filter((entry) => isIPv4(entry.address));
+    return (networks.find((entry) => entry.network === COOLIFY_NETWORK) ?? networks[0])?.address;
+}
+function tunnelDatabase(adminUrl, tunnel, boxAddress) {
+    const clients = new Map();
+    const clientFor = async (databaseName) => {
+        const url = withDatabase(adminUrl, databaseName);
+        const existing = clients.get(url);
+        if (existing !== undefined)
+            return existing;
+        const client = new Client({ connectionString: url });
+        await client.connect();
+        clients.set(url, client);
+        return client;
+    };
+    return {
+        kind: "tunnel",
+        boxAddress,
+        adminUrl: (databaseName) => withDatabase(adminUrl, databaseName),
+        query: async (sql, queryOptions) => {
+            const client = await clientFor(queryOptions?.database);
+            try {
+                const result = await client.query({ text: sql, rowMode: "array" });
+                const rows = result.rows ?? [];
+                return { rows: rows.map((row) => row.map(String)) };
+            }
+            catch (cause) {
+                throw new DatabaseTransportError("tunnel", redactPasswords(cause.message), {
+                    cause,
+                });
+            }
+        },
+        close: async () => {
+            for (const client of clients.values())
+                await client.end();
+            clients.clear();
+            await tunnel?.close();
+        },
+    };
+}
+function dockerExecDatabase(runner, container, admin) {
+    return {
+        kind: "docker-exec",
+        adminUrl: () => undefined,
+        query: async (sql, queryOptions) => {
+            // `-f -`: the statement goes down stdin, so it never appears in the box's process list
+            // and never has to survive a second round of shell quoting.
+            const result = await runner.exec([
+                "docker",
+                "exec",
+                "-i",
+                container,
+                "psql",
+                "-v",
+                "ON_ERROR_STOP=1",
+                "-qtAF",
+                FIELD_SEPARATOR,
+                "-U",
+                admin.user,
+                "-d",
+                queryOptions?.database ?? admin.database ?? DEFAULT_ADMIN_DATABASE,
+                "-f",
+                "-",
+            ], { input: sql });
+            if (result.code !== 0) {
+                throw new DatabaseTransportError("docker-exec", `psql exited ${String(result.code)}: ${redactPasswords(result.stderr.trim())}`);
+            }
+            const rows = result.stdout
+                .split("\n")
+                .filter((line) => line !== "")
+                .map((line) => line.split(FIELD_SEPARATOR));
+            return { rows };
+        },
+        close: async () => undefined,
+    };
+}
+function adminUrlOf(admin, localPort) {
+    const url = new URL("postgresql://127.0.0.1");
+    url.port = String(localPort);
+    url.username = encodeURIComponent(admin.user);
+    if (admin.password !== undefined)
+        url.password = encodeURIComponent(admin.password);
+    url.pathname = `/${encodeURIComponent(admin.database ?? DEFAULT_ADMIN_DATABASE)}`;
+    return url.toString();
+}
+function withDatabase(connectionString, databaseName) {
+    if (databaseName === undefined)
+        return connectionString;
+    const url = new URL(connectionString);
+    url.pathname = `/${encodeURIComponent(databaseName)}`;
+    return url.toString();
+}

package/dist/doctor.d.ts

@@ -0,0 +1,72 @@
+import { type OperatorConfig } from "./config.js";
+import type { FetchLike } from "./providers/http.js";
+import { type Runner } from "./runner.js";
+/** A restore check older than this is a warning: E5 is meant to run weekly, not once. */
+export declare const RESTORE_CHECK_MAX_AGE_DAYS = 7;
+/** The branch prefix Phase 4's core bumps open their pull requests on. */
+export declare const CORE_BUMP_BRANCH_PREFIX = "core-bump/";
+export type Severity = "ok" | "warn" | "fail";
+export interface DoctorFinding {
+    /** The app as the state cache names it. */
+    app: string;
+    /** `state`, `status`, `runs`, `version`, `budget`, `E006`, `restore-check`, `core-bump`. */
+    check: string;
+    severity: Severity;
+    message: string;
+}
+export interface DoctorResult {
+    findings: readonly DoctorFinding[];
+    /** No warning and no failure; `hf doctor` exits 0 exactly when this is true. */
+    ok: boolean;
+}
+/** The names E006 is read against: `SET ROLE <applicationRole>` in `<databaseName>`. */
+export interface PrivilegeTarget {
+    app: string;
+    databaseName: string;
+    applicationRole: string;
+}
+/** E006 for one app: resolves when both privileges are there, throws naming what is not. */
+export type PrivilegeCheck = (target: PrivilegeTarget) => Promise<void>;
+export interface DoctorOptions {
+    /** One app; otherwise every app the state cache knows about. */
+    name?: string;
+    /** Defaults to `loadOperatorConfig()`. */
+    config?: OperatorConfig;
+    /** Where the per-app state files are. Defaults to `stateDir()`. */
+    stateDir?: string;
+    fetch?: FetchLike;
+    /** The clock the restore-check age is measured against. */
+    now?: () => Date;
+    /** How E006 is read. Defaults to the tunnel to `HF_SSH_HOST` as `postgres`. */
+    privileges?: PrivilegeCheck;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * `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 declare function doctor(options?: DoctorOptions): Promise<DoctorResult>;
+/** The report as printed: a blank line and a header per app, then its findings. */
+export declare function doctorLines(result: DoctorResult): string[];
+/**
+ * E006 as the cluster admin 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 declare function tunnelPrivilegeCheck(runner: Runner, options?: {
+    containers?: readonly string[];
+    adminUser?: string;
+}): PrivilegeCheck;
+/**
+ * `@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 declare function checkAppRolePrivileges(adminUrl: string, role: string): Promise<void>;

package/dist/doctor.js

@@ -0,0 +1,368 @@
+import { access, readdir } from "node:fs/promises";
+import path from "node:path";
+import { checkE006, quoteIdent } from "@hyperfixation/db";
+import { Client } from "pg";
+import { DEFAULT_PG_ADMIN_USER, loadOperatorConfig, pgAdminUser, postgresContainers, 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/";
+/**
+ * `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 the cluster admin 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 = {}) {
+    const adminUser = options.adminUser ?? DEFAULT_PG_ADMIN_USER;
+    return async (target) => {
+        const db = await openDatabase(runner, {
+            admin: { user: adminUser },
+            containers: options.containers,
+        });
+        try {
+            const adminUrl = db.adminUrl(target.databaseName);
+            if (adminUrl === undefined) {
+                throw new Error(`E006 cannot be read over the ${db.kind} transport: ${adminUser} 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 }), {
+        containers: postgresContainers(config),
+        adminUser: pgAdminUser(config),
+    });
+}
+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?.budget !== 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 = readStatus(await getStatus(context.fetch, url, token));
+    }
+    catch (error) {
+        add("status", "fail", `GET ${url}: ${flatten(error.message)}`);
+        return undefined;
+    }
+    const anomalies = report.anomalies === undefined ? UNKNOWN : String(report.anomalies);
+    add("status", 
+    // Only a health the app actually reported can be a warning: a field it did not answer with
+    // says nothing about the deployment, and a WARN the operator cannot act on is noise.
+    report.health === undefined || report.health === "ok" ? "ok" : "warn", `health ${report.health ?? UNKNOWN}, ${anomalies} anomaly/anomalies, core ` +
+        (report.coreVersion ?? UNKNOWN));
+    if (report.runsRunning !== undefined) {
+        add("runs", "ok", `${String(report.runsRunning)} run(s) running`);
+    }
+    // Only `fixtures` gets a line. `live` is the expected deploy, and `unknown` — as is a core too
+    // old to have the field at all — is an app that has not said; neither is a finding, but a
+    // canned draft an operator takes for a real one is.
+    if (report.llmMode === "fixtures") {
+        add("llm", "warn", "app is serving fixture drafts — no provider key set");
+    }
+    return report;
+}
+const UNKNOWN = "unknown";
+function readStatus(payload) {
+    const report = record(payload);
+    const budget = record(report.budget);
+    return {
+        health: text(report.health),
+        anomalies: numeric(report.anomalies),
+        coreVersion: text(report.coreVersion),
+        applicationVersion: report.applicationVersion === null ? null : text(report.applicationVersion),
+        runsRunning: numeric(record(report.runs).running),
+        llmMode: text(record(report.llm).mode),
+        budget: isRecord(report.budget)
+            ? { current: readPeriod(budget.current), previous: readPeriod(budget.previous) }
+            : undefined,
+    };
+}
+/** `null` for a period the app has no row for, which is also how a malformed one reads. */
+function readPeriod(value) {
+    if (!isRecord(value))
+        return null;
+    return {
+        period: text(value.period),
+        budgetUsd: text(value.budgetUsd),
+        spentUsd: text(value.spentUsd),
+        driftUsd: text(value.driftUsd),
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function record(value) {
+    return isRecord(value) ? value : {};
+}
+function text(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function numeric(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/** A money column as a number, or `undefined` when the app did not report a usable one. */
+function amount(value) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+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 spent = amount(period.spentUsd);
+    const budget = amount(period.budgetUsd);
+    const drift = amount(period.driftUsd);
+    const over = spent !== undefined && budget !== undefined && spent > budget;
+    const drifting = drift !== undefined && drift !== 0;
+    const spend = `${period.period ?? UNKNOWN} spent $${period.spentUsd ?? UNKNOWN} ` +
+        `of $${period.budgetUsd ?? UNKNOWN}`;
+    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";