@hyperfixation/cli 0.1.0 → 0.1.1

package/dist/cloud-steps/template.js

@@ -0,0 +1,68 @@
+import { readFile, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { substituteTree, TEMPLATE_MARKER, TemplateError } from "../new.js";
+import { exists } from "./context.js";
+/**
+ * Where the fetch lands before it becomes the app.
+ *
+ * Beside the target rather than under `os.tmpdir()`, so the rename is a rename and not a second
+ * copy across filesystems, and dot-prefixed so a half-fetched tree does not look like an app.
+ */
+export function templateTempDir(dir) {
+    return path.join(path.dirname(dir), `.${path.basename(dir)}.hf-new`);
+}
+/**
+ * The app's files: giget's fetch of the template, substituted, renamed into place.
+ *
+ * Nothing is ever written to the target directory except by that rename, so a crash — mid-fetch,
+ * mid-substitution — leaves the target absent and the next run free to start over rather than an
+ * app-shaped directory the operator has to judge. The leftover temp directory is what that next
+ * run removes first.
+ *
+ * No `.env` is written, unlike `hf new --local`: in the cloud every value lives in Coolify's
+ * environment, and a `.env` in the app directory would only be a second copy of the app's secrets
+ * on the laptop that ran `hf new`.
+ */
+export const templateStep = {
+    name: "template",
+    run: async (context) => {
+        const { dir, names } = context;
+        if (await exists(dir)) {
+            await adoptOrRefuse(context);
+            return;
+        }
+        const temp = templateTempDir(dir);
+        await rm(temp, { recursive: true, force: true });
+        const fetched = await context.fetchTemplate(context.from, temp);
+        await substituteTree(fetched, names);
+        // The marker is what `assertTemplateSource` looks for: an app is never a template twice.
+        await rm(path.join(fetched, TEMPLATE_MARKER));
+        await rename(fetched, dir);
+        context.io.out(`${names.given}: template fetched into ${dir}`);
+    },
+};
+/**
+ * A directory already at the target: this app on a run whose state was lost, or something else.
+ *
+ * "This app" means a substituted template — its `package.json` carries the underscored app name
+ * and the marker is gone. Anything else is the local flow's rule, refused rather than written
+ * into.
+ */
+async function adoptOrRefuse(context) {
+    const { dir, names } = context;
+    const substituted = !(await exists(path.join(dir, TEMPLATE_MARKER))) && (await packageName(dir)) === names.appName;
+    if (!substituted) {
+        throw new TemplateError(`${dir} already exists; hf new will not write into it`);
+    }
+    context.io.out(`${names.given}: adopting the app directory already at ${dir}`);
+}
+async function packageName(dir) {
+    try {
+        const parsed = JSON.parse(await readFile(path.join(dir, "package.json"), "utf8"));
+        const name = parsed.name;
+        return typeof name === "string" ? name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Every key the operator's config may carry, spelled exactly as the environment variable that
+ * overrides it. One flat list of names, no nesting: these are pasted in from account pages, and
+ * a shape is one more thing to get wrong.
+ */
+export declare const CONFIG_KEYS: readonly ["HF_COOLIFY_URL", "HF_COOLIFY_TOKEN", "HF_COOLIFY_SERVER_UUID", "HF_COOLIFY_GITHUB_APP_UUID", "HF_COOLIFY_POSTGRES_UUID", "HF_DB_HOST_INTERNAL", "HF_SSH_HOST", "HF_CLOUDFLARE_TOKEN", "HF_CLOUDFLARE_ZONE_ID", "HF_BASE_DOMAIN", "HF_GITHUB_TOKEN", "HF_GITHUB_OWNER", "HF_GITHUB_APP_SLUGS", "HF_SENTRY_TOKEN", "HF_SENTRY_ORG", "HF_LANGFUSE_URL", "HF_LANGFUSE_ORG_KEY", "HF_BOX_IP", "HF_SMTP_URL", "HF_EMAIL_FROM", "HF_ANTHROPIC_API_KEY", "HF_OPENAI_API_KEY"];
+export type ConfigKey = (typeof CONFIG_KEYS)[number];
+/** What the operator has configured. Every key is optional until a command asks for it. */
+export type OperatorConfig = Partial<Record<ConfigKey, string>>;
+/** `~/.config/hf`, or `$XDG_CONFIG_HOME/hf`. Holds `config.json` and `state/`. */
+export declare function configHome(env?: NodeJS.ProcessEnv): string;
+export declare function configFile(env?: NodeJS.ProcessEnv): string;
+/** The config file exists but is not a flat JSON object of known keys to strings. */
+export declare class ConfigFileInvalid extends Error {
+    readonly file: string;
+    constructor(file: string, problem: string);
+}
+/** One command needed keys the operator has not set. Names every one of them, values never. */
+export declare class MissingConfig extends Error {
+    readonly names: readonly ConfigKey[];
+    constructor(names: readonly ConfigKey[], file: string);
+}
+export interface LoadOperatorConfigOptions {
+    /** The config file to read. Defaults to `configFile()`. */
+    file?: string;
+    /** The environment that overrides it. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Reads `~/.config/hf/config.json` and lays the environment over it.
+ *
+ * The environment wins, the same precedence an app's `.env` has under `process.env`, so a
+ * one-off `HF_COOLIFY_URL=… hf new` does not mean editing a file. A missing file is not an
+ * error here — `requireOperatorConfig` is what reports what a command actually needs, all at
+ * once, rather than one failed request at a time.
+ *
+ * The file must be mode 0600; see `readSecretFile`.
+ */
+export declare function loadOperatorConfig(options?: LoadOperatorConfigOptions): Promise<OperatorConfig>;
+/**
+ * Narrows a loaded config to the keys a command needs, or names **every** missing one.
+ *
+ * All at once on purpose: provisioning fails at the first request that needs a key it has not
+ * got, and an operator who fixes one key per run pays for a partly-provisioned app each time.
+ */
+export declare function requireOperatorConfig<Key extends ConfigKey>(config: OperatorConfig, keys: readonly Key[], options?: LoadOperatorConfigOptions): Record<Key, string>;
+/**
+ * `HF_GITHUB_APP_SLUGS` as a list: split on commas, trimmed, empties dropped.
+ *
+ * A config value is a string — one flat list of names is the whole contract — so the split lives
+ * here rather than in the file format, and an unset key is an empty list: nothing to assert.
+ */
+export declare function githubAppSlugs(config: OperatorConfig): readonly string[];

package/dist/config.js

@@ -0,0 +1,155 @@
+import { homedir } from "node:os";
+import path from "node:path";
+import { readSecretFile } from "./secret-file.js";
+/**
+ * Every key the operator's config may carry, spelled exactly as the environment variable that
+ * overrides it. One flat list of names, no nesting: these are pasted in from account pages, and
+ * a shape is one more thing to get wrong.
+ */
+export const CONFIG_KEYS = [
+    "HF_COOLIFY_URL",
+    "HF_COOLIFY_TOKEN",
+    "HF_COOLIFY_SERVER_UUID",
+    "HF_COOLIFY_GITHUB_APP_UUID",
+    "HF_COOLIFY_POSTGRES_UUID",
+    // The Postgres container's hostname on the docker network, as the app's containers see it.
+    // Configurable because Coolify's API document reports no such field: its own compose generator
+    // names the container after the database's uuid, so `HF_COOLIFY_POSTGRES_UUID` is the default a
+    // caller falls back to, and this is how a box that disagrees is told to us rather than guessed.
+    "HF_DB_HOST_INTERNAL",
+    "HF_SSH_HOST",
+    "HF_CLOUDFLARE_TOKEN",
+    "HF_CLOUDFLARE_ZONE_ID",
+    "HF_BASE_DOMAIN",
+    "HF_GITHUB_TOKEN",
+    "HF_GITHUB_OWNER",
+    // Comma-separated `app_slug`s — Coolify's GitHub App and the bump bot's — every one of which
+    // has to be installed on a new app's repository; `githubAppSlugs` is what splits it.
+    "HF_GITHUB_APP_SLUGS",
+    "HF_SENTRY_TOKEN",
+    "HF_SENTRY_ORG",
+    "HF_LANGFUSE_URL",
+    "HF_LANGFUSE_ORG_KEY",
+    "HF_BOX_IP",
+    "HF_SMTP_URL",
+    "HF_EMAIL_FROM",
+    // The two model-provider keys, and the only optional ones here. An app deployed without
+    // either serves fixture drafts (`/api/status` reports `llm.mode`), so `hf new` omits the
+    // variable altogether rather than sending an empty one and printing a checklist line — an
+    // empty value in Coolify's UI reads as configured.
+    "HF_ANTHROPIC_API_KEY",
+    "HF_OPENAI_API_KEY",
+];
+const KEYS = new Set(CONFIG_KEYS);
+/** `~/.config/hf`, or `$XDG_CONFIG_HOME/hf`. Holds `config.json` and `state/`. */
+export function configHome(env = process.env) {
+    const base = env.XDG_CONFIG_HOME;
+    return path.join(base !== undefined && base !== "" ? base : path.join(homedir(), ".config"), "hf");
+}
+export function configFile(env = process.env) {
+    return path.join(configHome(env), "config.json");
+}
+/** The config file exists but is not a flat JSON object of known keys to strings. */
+export class ConfigFileInvalid extends Error {
+    file;
+    constructor(file, problem) {
+        // The file holds tokens: the problem is described by key name, never by value, and the
+        // JSON parser's own message is dropped because it quotes the text it choked on.
+        super(`${file} is not usable hf config: ${problem}`);
+        this.name = "ConfigFileInvalid";
+        this.file = file;
+    }
+}
+/** One command needed keys the operator has not set. Names every one of them, values never. */
+export class MissingConfig extends Error {
+    names;
+    constructor(names, file) {
+        super(`${names.join(", ")} unset: set ${names.length === 1 ? "it" : "them"} in ${file} ` +
+            `or in the environment`);
+        this.name = "MissingConfig";
+        this.names = names;
+    }
+}
+/**
+ * Reads `~/.config/hf/config.json` and lays the environment over it.
+ *
+ * The environment wins, the same precedence an app's `.env` has under `process.env`, so a
+ * one-off `HF_COOLIFY_URL=… hf new` does not mean editing a file. A missing file is not an
+ * error here — `requireOperatorConfig` is what reports what a command actually needs, all at
+ * once, rather than one failed request at a time.
+ *
+ * The file must be mode 0600; see `readSecretFile`.
+ */
+export async function loadOperatorConfig(options = {}) {
+    const env = options.env ?? process.env;
+    const file = options.file ?? configFile(env);
+    const config = {};
+    const contents = await readSecretFile(file);
+    if (contents !== undefined) {
+        for (const [key, value] of Object.entries(parseConfig(contents, file))) {
+            config[key] = value;
+        }
+    }
+    for (const key of CONFIG_KEYS) {
+        const override = env[key];
+        if (override !== undefined && override !== "")
+            config[key] = override;
+    }
+    return config;
+}
+/**
+ * Narrows a loaded config to the keys a command needs, or names **every** missing one.
+ *
+ * All at once on purpose: provisioning fails at the first request that needs a key it has not
+ * got, and an operator who fixes one key per run pays for a partly-provisioned app each time.
+ */
+export function requireOperatorConfig(config, keys, options = {}) {
+    const missing = [];
+    const required = {};
+    for (const key of keys) {
+        const value = config[key];
+        if (value === undefined || value === "")
+            missing.push(key);
+        else
+            required[key] = value;
+    }
+    if (missing.length > 0) {
+        throw new MissingConfig(missing, options.file ?? configFile(options.env));
+    }
+    return required;
+}
+/**
+ * `HF_GITHUB_APP_SLUGS` as a list: split on commas, trimmed, empties dropped.
+ *
+ * A config value is a string — one flat list of names is the whole contract — so the split lives
+ * here rather than in the file format, and an unset key is an empty list: nothing to assert.
+ */
+export function githubAppSlugs(config) {
+    return (config.HF_GITHUB_APP_SLUGS ?? "")
+        .split(",")
+        .map((slug) => slug.trim())
+        .filter((slug) => slug !== "");
+}
+function parseConfig(contents, file) {
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch {
+        throw new ConfigFileInvalid(file, "it is not valid JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new ConfigFileInvalid(file, "the top level is not an object");
+    }
+    const config = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (!KEYS.has(key)) {
+            throw new ConfigFileInvalid(file, `${JSON.stringify(key)} is not an hf config key`);
+        }
+        if (typeof value !== "string") {
+            throw new ConfigFileInvalid(file, `${key} is not a string`);
+        }
+        config[key] = value;
+    }
+    return config;
+}

package/dist/database.d.ts

@@ -0,0 +1,65 @@
+import type { Runner } from "./runner.js";
+/** Rows as strings, the one shape both transports can produce without inventing types. */
+export interface QueryResult {
+    rows: string[][];
+}
+export interface QueryOptions {
+    /** Which database on the cluster to run against; defaults to the admin database. */
+    database?: string;
+}
+export type DatabaseTransport = "tunnel" | "docker-exec";
+/**
+ * One way of reaching the box's Postgres cluster as an admin.
+ *
+ * `tunnel` is the default, and the only transport that can carry the whole of E2: it hands out
+ * a libpq URL, which is what `provisionRoles()` — a `pg` client, in `@hyperfixation/db` — takes.
+ * `docker-exec` exists because Phase 0 never confirmed that the Coolify Postgres container
+ * publishes 5432 on the box's loopback; it runs the same SQL through `psql` inside the
+ * container, so `CREATE DATABASE`, the extensions and a password rotation all work, but there
+ * is no address for a client library to dial and `adminUrl` is `undefined`.
+ */
+export interface Database {
+    readonly kind: DatabaseTransport;
+    /** A libpq URL onto `databaseName`, or `undefined` when the transport has no address. */
+    adminUrl(databaseName?: string): string | undefined;
+    query(sql: string, options?: QueryOptions): Promise<QueryResult>;
+    close(): Promise<void>;
+}
+export declare class DatabaseTransportError extends Error {
+    readonly transport: DatabaseTransport;
+    constructor(transport: DatabaseTransport, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * 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 declare function redactPasswords(text: string): string;
+export interface AdminCredentials {
+    user: string;
+    password?: string;
+    /** The database to connect to for cluster-wide statements. Defaults to `postgres`. */
+    database?: string;
+}
+export interface OpenDatabaseOptions {
+    admin: AdminCredentials;
+    /** Where Postgres listens on the box's loopback. */
+    remotePort?: number;
+    /** The Coolify Postgres container, for the `docker-exec` fallback. Omit to have none. */
+    container?: string;
+}
+export declare const DEFAULT_POSTGRES_PORT = 5432;
+/**
+ * Opens the cluster over `runner`, preferring the tunnel and falling back to `docker exec`.
+ *
+ * The 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 declare function openDatabase(runner: Runner, options: OpenDatabaseOptions): Promise<Database>;
+/** The cluster at a URL this process can already dial — a test's Postgres, or a live tunnel. */
+export declare function openDatabaseUrl(adminUrl: string): Database;

package/dist/database.js

@@ -0,0 +1,142 @@
+import { Client } from "pg";
+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";
+/**
+ * Opens the cluster over `runner`, preferring the tunnel and falling back to `docker exec`.
+ *
+ * The 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;
+    let tunnel;
+    try {
+        tunnel = await runner.tunnel(remotePort);
+        const database = tunnelDatabase(adminUrlOf(options.admin, tunnel.localPort), tunnel);
+        await database.query("SELECT 1");
+        return database;
+    }
+    catch (cause) {
+        await tunnel?.close();
+        if (options.container === undefined) {
+            throw new DatabaseTransportError("tunnel", `could not reach Postgres on 127.0.0.1:${String(remotePort)} on the box, and no ` +
+                "container was named to fall back to", { cause });
+        }
+    }
+    return dockerExecDatabase(runner, options.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);
+}
+function tunnelDatabase(adminUrl, tunnel) {
+    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",
+        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,71 @@
+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 `postgres` with `SET ROLE hf_<app>`, over the tunnel a `Runner` opens.
+ *
+ * As the app role rather than as an admin because that is the only role whose answer matters —
+ * a superuser's privileges are both true whatever the migrator granted.
+ */
+export declare function tunnelPrivilegeCheck(runner: Runner, options?: {
+    container?: 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>;