@hyperfixation/cli 0.1.0 → 0.1.2

package/dist/runner.js

@@ -0,0 +1,221 @@
+import { spawn } from "node:child_process";
+import { createServer, connect as connectTcp } from "node:net";
+export class RunnerError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "RunnerError";
+    }
+}
+/**
+ * What `HF_SSH_HOST` may be: `[user@]host`, and nothing that `ssh` would read as an option.
+ *
+ * A destination beginning `-o` is `ssh`'s own `-oProxyCommand=…`, which runs whatever it says
+ * on *this* machine. The config file is the operator's, but it is also the one place an env
+ * override reaches, so the destination is checked rather than trusted.
+ */
+const SSH_HOST = /^[A-Za-z0-9._-]+(@[A-Za-z0-9._-]+)?$/;
+/**
+ * Options every `ssh` invocation carries.
+ *
+ * `BatchMode=yes` so a missing key fails instead of prompting a non-interactive run for a
+ * password; `ControlMaster=no` with `ControlPath=none` so a multiplexed session left over from
+ * the operator's own `ssh` cannot silently carry a tunnel that outlives this process, and so a
+ * broken master socket cannot wedge provisioning.
+ */
+const SSH_OPTIONS = [
+    "-o",
+    "BatchMode=yes",
+    "-o",
+    "ControlMaster=no",
+    "-o",
+    "ControlPath=none",
+];
+/** The argv `exec` runs, `ssh` excluded — the array the test asserts against. */
+export function sshExecArgv(host, command) {
+    assertHost(host);
+    // `ssh` hands the remote end one string and the login shell splits it, so the array has to be
+    // re-quoted for that shell; nothing else in this file ever builds a shell word.
+    return ["-T", ...SSH_OPTIONS, host, shellQuote(command)];
+}
+export function sshTunnelArgv(host, localPort, remotePort, remoteHost = TUNNEL_LOOPBACK) {
+    assertHost(host);
+    assertTunnelHost(remoteHost);
+    return [
+        "-N",
+        "-T",
+        ...SSH_OPTIONS,
+        "-L",
+        `${String(localPort)}:${remoteHost}:${String(remotePort)}`,
+        host,
+    ];
+}
+/** Where a forward lands when the caller names no host: the far side's own loopback. */
+export const TUNNEL_LOOPBACK = "127.0.0.1";
+/** Single-quotes one word for a POSIX remote shell. */
+export function shellQuote(command) {
+    return command.map((word) => `'${word.replaceAll("'", `'\\''`)}'`).join(" ");
+}
+export const DEFAULT_TUNNEL_READY_TIMEOUT_MS = 10_000;
+/** A `Runner` that reaches the box over `ssh`. */
+export function createSshRunner(options) {
+    const ssh = options.sshPath ?? "ssh";
+    assertHost(options.host);
+    return {
+        exec: async (command, execOptions) => await spawnCollecting(ssh, sshExecArgv(options.host, command), execOptions),
+        tunnel: async (remotePort, remoteHost = TUNNEL_LOOPBACK) => {
+            const localPort = await freeLocalPort();
+            const child = spawn(ssh, sshTunnelArgv(options.host, localPort, remotePort, remoteHost), {
+                stdio: ["ignore", "ignore", "pipe"],
+            });
+            let stderr = "";
+            child.stderr?.on("data", (chunk) => {
+                stderr += chunk.toString("utf8");
+            });
+            const exited = new Promise((resolve) => child.once("exit", () => resolve()));
+            try {
+                await waitForPort(localPort, options.tunnelReadyTimeoutMs ?? DEFAULT_TUNNEL_READY_TIMEOUT_MS, child);
+            }
+            catch (cause) {
+                child.kill("SIGTERM");
+                await exited;
+                throw new RunnerError(`ssh -L ${String(localPort)}:${remoteHost}:${String(remotePort)} never became ready` +
+                    (stderr === "" ? "" : `: ${stderr.trim()}`), { cause });
+            }
+            return {
+                localPort,
+                close: async () => {
+                    child.kill("SIGTERM");
+                    await exited;
+                },
+            };
+        },
+    };
+}
+/**
+ * A `Runner` that runs on this machine and records what it was asked to run.
+ *
+ * `tunnel()` forwards nothing — it names a port the test already has — so provisioning can be
+ * exercised end to end against the test cluster without an `ssh` anywhere in the suite.
+ */
+export function createLocalRunner(options = {}) {
+    const commands = [];
+    const tunnels = [];
+    return {
+        get commands() {
+            return commands;
+        },
+        get tunnels() {
+            return tunnels;
+        },
+        exec: async (command, execOptions) => {
+            commands.push([...command]);
+            const [bin, ...args] = command;
+            if (bin === undefined)
+                throw new RunnerError("exec was given an empty command");
+            return await spawnCollecting(bin, args, execOptions);
+        },
+        tunnel: async (remotePort) => {
+            tunnels.push(remotePort);
+            const localPort = options.tunnelPort;
+            if (localPort === undefined) {
+                throw new RunnerError("this local Runner was not given a tunnelPort");
+            }
+            return { localPort, close: async () => undefined };
+        },
+    };
+}
+async function spawnCollecting(bin, args, options = {}) {
+    const child = spawn(bin, [...args], { stdio: ["pipe", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+        stdout += chunk.toString("utf8");
+    });
+    child.stderr?.on("data", (chunk) => {
+        stderr += chunk.toString("utf8");
+    });
+    const closed = new Promise((resolve, reject) => {
+        // A child that exits before reading its stdin (`true`, a refused ssh) makes the write fail with
+        // EPIPE; the exit code already says what happened. Any other stdin error is a real failure.
+        child.stdin?.on("error", (error) => {
+            if (error.code === "EPIPE")
+                return;
+            child.kill();
+            reject(error);
+        });
+        child.once("error", reject);
+        child.once("close", (exitCode) => resolve(exitCode));
+    });
+    child.stdin?.end(options.input ?? "");
+    const code = await closed;
+    return { code, stdout, stderr };
+}
+/**
+ * A port nothing is listening on, by binding one and letting go.
+ *
+ * Inherently a race — something else on the machine may take it in between — so the ready check
+ * below is what actually decides whether the forward came up.
+ */
+async function freeLocalPort() {
+    return await new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (address === null || typeof address === "string") {
+                server.close();
+                reject(new RunnerError("could not take a local port for the tunnel"));
+                return;
+            }
+            const { port } = address;
+            server.close(() => resolve(port));
+        });
+    });
+}
+async function waitForPort(port, timeoutMs, child) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (child.exitCode !== null || child.signalCode !== null) {
+            throw new RunnerError(`ssh exited before the forward on ${String(port)} was ready`);
+        }
+        if (await canConnect(port))
+            return;
+        if (Date.now() >= deadline) {
+            throw new RunnerError(`nothing accepted on 127.0.0.1:${String(port)} within ${String(timeoutMs)}ms`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+}
+async function canConnect(port) {
+    return await new Promise((resolve) => {
+        let socket;
+        const done = (ok) => {
+            socket.removeAllListeners();
+            socket.destroy();
+            resolve(ok);
+        };
+        socket = connectTcp({ port, host: "127.0.0.1" });
+        socket.setTimeout(1_000);
+        socket.once("connect", () => done(true));
+        socket.once("error", () => done(false));
+        socket.once("timeout", () => done(false));
+    });
+}
+/**
+ * The far-side end of a `-L` forward, which is a bare address or hostname and nothing else.
+ *
+ * It arrives from `docker inspect` on the box rather than from the operator, and `-L` takes its
+ * three fields colon-separated, so a value carrying a colon or a space would silently become a
+ * different forward than the one asked for.
+ */
+function assertTunnelHost(remoteHost) {
+    if (!TUNNEL_HOST.test(remoteHost)) {
+        throw new RunnerError(`a tunnel's remote host must match ${TUNNEL_HOST.source}, got ${JSON.stringify(remoteHost)}`);
+    }
+}
+const TUNNEL_HOST = /^[A-Za-z0-9._-]+$/;
+function assertHost(host) {
+    if (!SSH_HOST.test(host)) {
+        throw new RunnerError(`HF_SSH_HOST must match ${SSH_HOST.source}, got ${JSON.stringify(host)}`);
+    }
+}

package/dist/secret-file.d.ts

@@ -0,0 +1,30 @@
+/** Owner read/write and nothing else — the only mode the operator's files are read at. */
+export declare const SECRET_MODE = 384;
+/**
+ * A file that holds secrets was readable or writable by someone other than its owner.
+ *
+ * Thrown *after* the file has been tightened to 0600: the operator's next run works, and this
+ * run stops loudly enough that they can decide whether anything in it needs rotating. Nothing
+ * of the file's contents reaches the message.
+ */
+export declare class InsecureFileMode extends Error {
+    readonly file: string;
+    /** The permission bits found, before they were tightened. */
+    readonly found: number;
+    constructor(file: string, found: number);
+}
+/**
+ * Reads a file that holds secrets, or `undefined` when it does not exist.
+ *
+ * Refuses a file any other user can reach, having first tightened it — see `InsecureFileMode`.
+ */
+export declare function readSecretFile(file: string): Promise<string | undefined>;
+/**
+ * Writes a file that holds secrets, at 0600, atomically.
+ *
+ * Temp file then `rename`, because the state cache is written between provisioning steps: a
+ * crash partway through a write would otherwise leave a half-written JSON file that the next
+ * run refuses, and the passwords and tokens it held are not recoverable from anywhere else.
+ * The temp file is created 0600 too, so the secrets are never briefly world-readable.
+ */
+export declare function writeSecretFile(file: string, contents: string): Promise<void>;

package/dist/secret-file.js

@@ -0,0 +1,69 @@
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+/** Owner read/write and nothing else — the only mode the operator's files are read at. */
+export const SECRET_MODE = 0o600;
+/** The mode a secret directory is created at, so a new file cannot be listed by anyone else. */
+const SECRET_DIR_MODE = 0o700;
+/**
+ * A file that holds secrets was readable or writable by someone other than its owner.
+ *
+ * Thrown *after* the file has been tightened to 0600: the operator's next run works, and this
+ * run stops loudly enough that they can decide whether anything in it needs rotating. Nothing
+ * of the file's contents reaches the message.
+ */
+export class InsecureFileMode extends Error {
+    file;
+    /** The permission bits found, before they were tightened. */
+    found;
+    constructor(file, found) {
+        super(`${file} was mode ${found.toString(8).padStart(4, "0")}, not 0600: other users on this ` +
+            `machine could read it. It has been tightened to 0600 — rerun, and rotate anything it ` +
+            `holds that may have been read.`);
+        this.name = "InsecureFileMode";
+        this.file = file;
+        this.found = found;
+    }
+}
+/**
+ * Reads a file that holds secrets, or `undefined` when it does not exist.
+ *
+ * Refuses a file any other user can reach, having first tightened it — see `InsecureFileMode`.
+ */
+export async function readSecretFile(file) {
+    let mode;
+    try {
+        mode = (await stat(file)).mode & 0o777;
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return undefined;
+        throw cause;
+    }
+    if ((mode & 0o077) !== 0) {
+        await chmod(file, SECRET_MODE);
+        throw new InsecureFileMode(file, mode);
+    }
+    return await readFile(file, "utf8");
+}
+/**
+ * Writes a file that holds secrets, at 0600, atomically.
+ *
+ * Temp file then `rename`, because the state cache is written between provisioning steps: a
+ * crash partway through a write would otherwise leave a half-written JSON file that the next
+ * run refuses, and the passwords and tokens it held are not recoverable from anywhere else.
+ * The temp file is created 0600 too, so the secrets are never briefly world-readable.
+ */
+export async function writeSecretFile(file, contents) {
+    await mkdir(path.dirname(file), { recursive: true, mode: SECRET_DIR_MODE });
+    const temp = `${file}.${randomBytes(6).toString("hex")}.tmp`;
+    try {
+        await writeFile(temp, contents, { mode: SECRET_MODE });
+        await chmod(temp, SECRET_MODE);
+        await rename(temp, file);
+    }
+    catch (cause) {
+        await rm(temp, { force: true });
+        throw cause;
+    }
+}

package/dist/state.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The ten steps of a cloud `hf new`, in the order it runs them. A step is recorded only once
+ * everything it created is in the state file, so a rerun resumes at the first unrecorded step
+ * rather than re-creating what the previous run already paid for.
+ *
+ * `database` sits immediately before `coolify` because it is the one step that *rotates*: a cold
+ * run gives the roles new passwords, and a deployed app keeps the old ones until the envs are
+ * PATCHed and the app redeployed. Every fallible external create — the repo, the backup, Sentry,
+ * Langfuse, the DNS record — therefore happens first, so a failure in one of them cannot leave a
+ * live app holding credentials nothing will replace.
+ */
+export declare const STEPS: readonly ["template", "install", "repo", "backup", "sentry", "langfuse", "dns", "database", "coolify", "deploy"];
+export type StepName = (typeof STEPS)[number];
+export interface StepRecord {
+    /** ISO 8601, when the step finished. */
+    doneAt: string;
+}
+export interface CoolifyState {
+    projectUuid?: string;
+    appUuid?: string;
+    /**
+     * `secretsHash` of the secrets the last bulk env PATCH carried.
+     *
+     * The `coolify` step is "done" only while this matches what the state holds now: a cold run
+     * that rotated the role passwords leaves the deployed app authenticating with the old ones, and
+     * a recorded `steps.coolify` would otherwise make a rerun skip the one PATCH that fixes it.
+     */
+    envsSecretsHash?: string;
+}
+/** The three role passwords a cold run generates. Nothing else on the laptop has a copy. */
+export interface DatabaseState {
+    migratorPassword?: string;
+    applicationPassword?: string;
+    readonlyPassword?: string;
+}
+export interface LangfuseState {
+    publicKey?: string;
+    secretKey?: string;
+}
+export interface StatusTokenState {
+    read?: string;
+    write?: string;
+}
+/**
+ * Everything one cloud app's provisioning produced, so that a rerun, `hf doctor` and
+ * `hf restore-check` do not have to ask five APIs what already exists.
+ *
+ * Every field is optional but `steps`: the file is written between steps, and each step fills
+ * in its own part.
+ */
+export interface AppState {
+    steps: Partial<Record<StepName, StepRecord>>;
+    /** `owner/name` of the app's GitHub repository. */
+    repo?: string;
+    coolify?: CoolifyState;
+    database?: DatabaseState;
+    sentryDsn?: string;
+    langfuse?: LangfuseState;
+    statusTokens?: StatusTokenState;
+    /**
+     * `BETTER_AUTH_SECRET` — generated once, for this app, and kept only here: it is the one
+     * `REQUIRED_ENV` secret no provider hands back, so nothing else can be asked for it again.
+     * Never printed; it reaches the app through the Coolify env PATCH alone.
+     */
+    betterAuthSecret?: string;
+    lastRestoreCheckAt?: string;
+    lastDeployedSha?: string;
+}
+/** 32 random bytes, the length `better-auth` documents, in the form an env var can carry. */
+export declare function generateBetterAuthSecret(): string;
+/**
+ * A fingerprint of every secret the Coolify envs carry, so a rotation is detectable without
+ * keeping a second copy of the secrets themselves.
+ *
+ * Only the values matter, not the state around them: `coolify.envsSecretsHash` is compared
+ * against this, and a step that rotated a password must come out different.
+ */
+export declare function secretsHash(state: AppState): string;
+/**
+ * The state file exists but does not parse, or does not have the shape above.
+ *
+ * Never repaired and never overwritten: the file is the only copy of three database passwords,
+ * two status tokens and a Langfuse secret key, so silently starting a fresh one would strand a
+ * deployed app whose roles nothing can log in as any more. The operator is told where the file
+ * is and decides.
+ */
+export declare class AppStateInvalid extends Error {
+    readonly file: string;
+    constructor(file: string, problem: string);
+}
+export interface AppStateStore {
+    readonly file: string;
+    /** The state as last written. Replaced, never mutated in place, by `patch` and `markDone`. */
+    readonly state: AppState;
+    isDone(step: StepName): boolean;
+    markDone(step: StepName): Promise<void>;
+    /**
+     * Forgets a step, so the next run repeats it.
+     *
+     * What a rotation needs: the secrets the `coolify` step PATCHed and the `deploy` that published
+     * them are no longer true of the app, and `patch` merges rather than removes.
+     */
+    clearDone(step: StepName): Promise<void>;
+    /**
+     * Merges `changes` in and writes the file. Object-valued keys (`coolify`, `database`,
+     * `langfuse`, `statusTokens`) merge field by field, so a step can record the one uuid it
+     * learned without carrying the rest.
+     */
+    patch(changes: Partial<AppState>): Promise<void>;
+}
+/** `~/.config/hf/state`, one `<name>.json` per app. */
+export declare function stateDir(env?: NodeJS.ProcessEnv): string;
+export declare function stateFile(name: string, env?: NodeJS.ProcessEnv): string;
+export interface OpenAppStateOptions {
+    /** The directory holding `<name>.json`. Defaults to `stateDir()`. */
+    dir?: string;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Opens one app's state cache, or starts an empty one when the file does not exist yet.
+ *
+ * The file must be mode 0600; a looser one is tightened and then refused (`InsecureFileMode`).
+ */
+export declare function openAppState(name: string, options?: OpenAppStateOptions): Promise<AppStateStore>;

package/dist/state.js

@@ -0,0 +1,217 @@
+import { createHash, randomBytes } from "node:crypto";
+import path from "node:path";
+import { configHome } from "./config.js";
+import { readSecretFile, writeSecretFile } from "./secret-file.js";
+/**
+ * The ten steps of a cloud `hf new`, in the order it runs them. A step is recorded only once
+ * everything it created is in the state file, so a rerun resumes at the first unrecorded step
+ * rather than re-creating what the previous run already paid for.
+ *
+ * `database` sits immediately before `coolify` because it is the one step that *rotates*: a cold
+ * run gives the roles new passwords, and a deployed app keeps the old ones until the envs are
+ * PATCHed and the app redeployed. Every fallible external create — the repo, the backup, Sentry,
+ * Langfuse, the DNS record — therefore happens first, so a failure in one of them cannot leave a
+ * live app holding credentials nothing will replace.
+ */
+export const STEPS = [
+    "template",
+    "install",
+    "repo",
+    "backup",
+    "sentry",
+    "langfuse",
+    "dns",
+    "database",
+    "coolify",
+    "deploy",
+];
+/** 32 random bytes, the length `better-auth` documents, in the form an env var can carry. */
+export function generateBetterAuthSecret() {
+    return randomBytes(32).toString("base64url");
+}
+/**
+ * A fingerprint of every secret the Coolify envs carry, so a rotation is detectable without
+ * keeping a second copy of the secrets themselves.
+ *
+ * Only the values matter, not the state around them: `coolify.envsSecretsHash` is compared
+ * against this, and a step that rotated a password must come out different.
+ */
+export function secretsHash(state) {
+    const database = state.database ?? {};
+    const material = [
+        database.migratorPassword,
+        database.applicationPassword,
+        database.readonlyPassword,
+        state.betterAuthSecret,
+        state.statusTokens?.read,
+        state.statusTokens?.write,
+    ];
+    return createHash("sha256").update(JSON.stringify(material)).digest("hex");
+}
+/**
+ * The state file exists but does not parse, or does not have the shape above.
+ *
+ * Never repaired and never overwritten: the file is the only copy of three database passwords,
+ * two status tokens and a Langfuse secret key, so silently starting a fresh one would strand a
+ * deployed app whose roles nothing can log in as any more. The operator is told where the file
+ * is and decides.
+ */
+export class AppStateInvalid extends Error {
+    file;
+    constructor(file, problem) {
+        super(`${file} is not a usable hf state file: ${problem}. It is the only copy of this app's ` +
+            `passwords and tokens, so nothing was overwritten — inspect it, or move it aside to ` +
+            `start over.`);
+        this.name = "AppStateInvalid";
+        this.file = file;
+    }
+}
+/** `~/.config/hf/state`, one `<name>.json` per app. */
+export function stateDir(env = process.env) {
+    return path.join(configHome(env), "state");
+}
+export function stateFile(name, env = process.env) {
+    return path.join(stateDir(env), `${name}.json`);
+}
+/**
+ * Opens one app's state cache, or starts an empty one when the file does not exist yet.
+ *
+ * The file must be mode 0600; a looser one is tightened and then refused (`InsecureFileMode`).
+ */
+export async function openAppState(name, options = {}) {
+    const env = options.env ?? process.env;
+    const file = options.dir === undefined ? stateFile(name, env) : path.join(options.dir, `${name}.json`);
+    const contents = await readSecretFile(file);
+    let state = contents === undefined ? { steps: {} } : parseAppState(contents, file);
+    const write = async (next) => {
+        await writeSecretFile(file, `${JSON.stringify(next, null, 2)}\n`);
+        state = next;
+    };
+    return {
+        file,
+        get state() {
+            return state;
+        },
+        isDone: (step) => state.steps[step] !== undefined,
+        markDone: async (step) => {
+            await write({
+                ...state,
+                steps: { ...state.steps, [step]: { doneAt: new Date().toISOString() } },
+            });
+        },
+        clearDone: async (step) => {
+            if (state.steps[step] === undefined)
+                return;
+            const steps = { ...state.steps };
+            delete steps[step];
+            await write({ ...state, steps });
+        },
+        patch: async (changes) => {
+            await write(merge(state, changes));
+        },
+    };
+}
+function merge(state, changes) {
+    return {
+        ...state,
+        ...changes,
+        steps: { ...state.steps, ...changes.steps },
+        ...mergeObject(state, changes, "coolify"),
+        ...mergeObject(state, changes, "database"),
+        ...mergeObject(state, changes, "langfuse"),
+        ...mergeObject(state, changes, "statusTokens"),
+    };
+}
+function mergeObject(state, changes, key) {
+    const change = changes[key];
+    if (change === undefined)
+        return {};
+    return { [key]: { ...state[key], ...change } };
+}
+/**
+ * The schema, hand-written because the whole contract is nine keys and a step map, and because
+ * an unknown key has to be an error rather than something a permissive parser drops on the next
+ * write.
+ */
+function parseAppState(contents, file) {
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch {
+        throw new AppStateInvalid(file, "it is not valid JSON");
+    }
+    const root = asObject(parsed, file, "the top level");
+    const state = { steps: {} };
+    for (const [key, value] of Object.entries(root)) {
+        switch (key) {
+            case "steps":
+                state.steps = parseSteps(value, file);
+                break;
+            case "repo":
+            case "sentryDsn":
+            case "betterAuthSecret":
+            case "lastRestoreCheckAt":
+            case "lastDeployedSha":
+                state[key] = asString(value, file, key);
+                break;
+            case "coolify":
+                state.coolify = parseFields(value, file, key, [
+                    "projectUuid",
+                    "appUuid",
+                    "envsSecretsHash",
+                ]);
+                break;
+            case "database":
+                state.database = parseFields(value, file, key, [
+                    "migratorPassword",
+                    "applicationPassword",
+                    "readonlyPassword",
+                ]);
+                break;
+            case "langfuse":
+                state.langfuse = parseFields(value, file, key, ["publicKey", "secretKey"]);
+                break;
+            case "statusTokens":
+                state.statusTokens = parseFields(value, file, key, ["read", "write"]);
+                break;
+            default:
+                throw new AppStateInvalid(file, `${JSON.stringify(key)} is not an hf state key`);
+        }
+    }
+    if (root.steps === undefined)
+        throw new AppStateInvalid(file, "it has no steps");
+    return state;
+}
+function parseSteps(value, file) {
+    const steps = {};
+    for (const [name, record] of Object.entries(asObject(value, file, "steps"))) {
+        if (!STEPS.includes(name)) {
+            throw new AppStateInvalid(file, `steps.${name} is not a step of hf new`);
+        }
+        const fields = asObject(record, file, `steps.${name}`);
+        steps[name] = { doneAt: asString(fields.doneAt, file, `steps.${name}.doneAt`) };
+    }
+    return steps;
+}
+function parseFields(value, file, key, fields) {
+    const out = {};
+    for (const [field, entry] of Object.entries(asObject(value, file, key))) {
+        if (!fields.includes(field)) {
+            throw new AppStateInvalid(file, `${key}.${field} is not an hf state key`);
+        }
+        out[field] = asString(entry, file, `${key}.${field}`);
+    }
+    return out;
+}
+function asObject(value, file, what) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new AppStateInvalid(file, `${what} is not an object`);
+    }
+    return value;
+}
+function asString(value, file, what) {
+    if (typeof value !== "string")
+        throw new AppStateInvalid(file, `${what} is not a string`);
+    return value;
+}

package/dist/status-token.d.ts

@@ -19,6 +19,8 @@ export interface StatusTokenAppOptions {
      * up yet" would also require `--rotate`, and `--rotate` would take out the other, live token.
      */
     explicit?: boolean;
+    /** Connection URLs in place of a `.env`; see `ResolveAppOptions`. */
+    env?: Record<string, string>;
 }
 export interface StatusTokenAppResult {
     app: ResolvedApp;

package/dist/status-token.js

@@ -35,7 +35,7 @@ export class StatusTokenAlreadySet extends Error {
  * caller; nothing here ever stores or logs it.
  */
 export async function statusTokenApp(options = {}) {
-    const app = await resolveApp(options.dir);
+    const app = await resolveApp(options.dir, { env: options.env });
     const databaseUrl = requireEnv(app, "DATABASE_URL");
     const kinds = options.kinds ?? ["read", "write"];
     const pool = new Pool({ connectionString: databaseUrl, max: 1 });