@hyperfixation/cli 0.1.0 → 0.1.2

package/dist/cloud-steps/sentry.js

@@ -0,0 +1,55 @@
+import { requireOperatorConfig } from "../config.js";
+import { ProviderError } from "../providers/http.js";
+import { SentryClient } from "../providers/sentry.js";
+import { StepFailed } from "./context.js";
+/**
+ * The app's Sentry project, and the DSN the deployment reports to.
+ *
+ * The keys endpoint is both the lookup and the answer: a 200 means the project is there and hands
+ * back its DSN in the same request, so a cold run against an existing project neither creates a
+ * second one nor needs a list of every project the token can see. Only a 404 creates.
+ *
+ * The DSN reaches the app through the Coolify env PATCH; it is a credential, so it is recorded in
+ * the state and never printed.
+ */
+export const sentryStep = {
+    name: "sentry",
+    run: async (context) => {
+        const { names } = context;
+        const required = requireOperatorConfig(context.config, ["HF_SENTRY_TOKEN", "HF_SENTRY_ORG"], {
+            env: context.env,
+        });
+        const org = required.HF_SENTRY_ORG;
+        const sentry = new SentryClient({ token: required.HF_SENTRY_TOKEN, fetch: context.fetch });
+        let keys = await listKeys(sentry, org, names.appName);
+        if (keys === undefined) {
+            await sentry.createProject(org, {
+                name: names.appName,
+                slug: names.appName,
+                platform: "node",
+            });
+            keys = await sentry.listProjectKeys(org, names.appName);
+            context.io.out(`${names.given}: created the Sentry project ${org}/${names.appName}`);
+        }
+        else {
+            context.io.out(`${names.given}: adopting the Sentry project ${org}/${names.appName}`);
+        }
+        const dsn = keys[0]?.dsn.public;
+        if (dsn === undefined) {
+            throw new StepFailed(`the Sentry project ${org}/${names.appName} has no client key: create one in Sentry and ` +
+                "re-run hf new");
+        }
+        await context.state.patch({ sentryDsn: dsn });
+    },
+};
+/** The project's keys, or `undefined` when Sentry says there is no such project. */
+async function listKeys(sentry, org, project) {
+    try {
+        return await sentry.listProjectKeys(org, project);
+    }
+    catch (error) {
+        if (error instanceof ProviderError && error.status === 404)
+            return undefined;
+        throw error;
+    }
+}

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

@@ -0,0 +1,22 @@
+import type { Step } from "../new-cloud.js";
+import { type CloudStepContext } 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 declare function templateTempDir(dir: string): string;
+/**
+ * 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 declare const templateStep: Step<CloudStepContext>;

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,65 @@
+/**
+ * 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_DB_CONTAINER", "HF_PG_ADMIN_USER", "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_LANGFUSE_PUBLIC_KEY", "HF_LANGFUSE_SECRET_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>;
+/** What `HF_PG_ADMIN_USER` defaults to: the role a stock Postgres image creates. */
+export declare const DEFAULT_PG_ADMIN_USER = "postgres";
+/** The cluster superuser to log in as — Coolify's `POSTGRES_USER`, which need not be `postgres`. */
+export declare function pgAdminUser(config: OperatorConfig): string;
+/**
+ * What Coolify may have called the Postgres container on the box, in the order to try them.
+ *
+ * A standalone Postgres resource runs in a container named for the bare uuid; a database attached
+ * to a service gets `postgresql-<uuid>`. Both are asked about rather than one being guessed at,
+ * and `HF_DB_CONTAINER` replaces the pair outright. Empty when neither key is set.
+ */
+export declare function postgresContainers(config: OperatorConfig): readonly 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,192 @@
+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",
+    // The Postgres container's name on the box, which is what `docker inspect` is asked about when
+    // the box's loopback has no 5432 listener. Coolify names it for the bare uuid or
+    // `postgresql-<uuid>` depending on how the database was created, so `postgresContainers()`
+    // derives both from `HF_COOLIFY_POSTGRES_UUID` and this replaces the pair.
+    "HF_DB_CONTAINER",
+    // The cluster superuser to log in as. Coolify creates the cluster with its own `POSTGRES_USER`,
+    // and on the X1 box that role is not `postgres` — `psql -U postgres` there fails with
+    // `role "postgres" does not exist`. The password stays in `PGPASSWORD`, never in this file.
+    "HF_PG_ADMIN_USER",
+    "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",
+    // Optional, and all three are: an organization-scoped key pair creates the app its own project,
+    // but it is a paid-plan feature, so a Hobby account instead names an existing project's key pair
+    // here and every app it provisions traces into that one project. With none of them set the
+    // langfuse step records nothing and the three LANGFUSE_* variables are omitted rather than sent
+    // empty — an empty value in Coolify's UI reads as configured.
+    "HF_LANGFUSE_ORG_KEY",
+    "HF_LANGFUSE_PUBLIC_KEY",
+    "HF_LANGFUSE_SECRET_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;
+}
+/** What `HF_PG_ADMIN_USER` defaults to: the role a stock Postgres image creates. */
+export const DEFAULT_PG_ADMIN_USER = "postgres";
+/** The cluster superuser to log in as — Coolify's `POSTGRES_USER`, which need not be `postgres`. */
+export function pgAdminUser(config) {
+    const user = config.HF_PG_ADMIN_USER;
+    return user === undefined || user === "" ? DEFAULT_PG_ADMIN_USER : user;
+}
+/**
+ * What Coolify may have called the Postgres container on the box, in the order to try them.
+ *
+ * A standalone Postgres resource runs in a container named for the bare uuid; a database attached
+ * to a service gets `postgresql-<uuid>`. Both are asked about rather than one being guessed at,
+ * and `HF_DB_CONTAINER` replaces the pair outright. Empty when neither key is set.
+ */
+export function postgresContainers(config) {
+    const override = config.HF_DB_CONTAINER;
+    if (override !== undefined && override !== "")
+        return [override];
+    const uuid = config.HF_COOLIFY_POSTGRES_UUID;
+    return uuid === undefined || uuid === "" ? [] : [uuid, `postgresql-${uuid}`];
+}
+/**
+ * `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,95 @@
+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.
+ * Its far end is the box's loopback where the port is published and the container's own address
+ * on the docker network where it is not. `docker-exec` is the last resort: 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;
+    /**
+     * Where the **box** reaches this cluster, for anything that runs there rather than here —
+     * `pg_restore`, in E7. `undefined` when the transport has no address at all.
+     */
+    readonly boxAddress?: {
+        host: string;
+        port: number;
+    };
+    /** 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;
+    /** The port Postgres listens on, wherever it is reached. */
+    remotePort?: number;
+    /**
+     * What the Coolify Postgres container may be called, in the order to try them; Coolify's own
+     * naming depends on how the database was created. The address of the first one that exists is
+     * what the tunnel forwards to when the box's loopback has no listener, and `dockerExec` runs
+     * `psql` inside it. Omit to have neither, and the loopback is then the only route.
+     */
+    containers?: readonly string[];
+    /**
+     * One container, appended to `containers`.
+     *
+     * @deprecated Coolify's naming depends on how the database was created, so a caller that knows
+     * only the uuid has two names to try; pass `containers`. Removed in 0.2.0.
+     */
+    container?: string;
+    /** Last resort when no address carries a query: `psql` inside the container. Default false. */
+    dockerExec?: boolean;
+}
+export declare const DEFAULT_POSTGRES_PORT = 5432;
+/**
+ * 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 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;