@hyperfixation/cli 0.1.0 → 0.1.1

package/dist/providers/github.js

@@ -0,0 +1,98 @@
+import { createTransport, segment } from "./http.js";
+export const GITHUB_API_URL = "https://api.github.com";
+export class GithubClient {
+    request;
+    constructor(options) {
+        this.request = createTransport({
+            provider: "github",
+            baseUrl: options.url ?? GITHUB_API_URL,
+            headers: {
+                authorization: `Bearer ${options.token}`,
+                accept: "application/vnd.github+json",
+                "x-github-api-version": "2022-11-28",
+            },
+            fetch: options.fetch,
+        });
+    }
+    /**
+     * Who `HF_GITHUB_OWNER` is: `type` decides between `/user/repos` and `/orgs/{org}/repos`.
+     *
+     * Unauthenticated-shaped data on purpose — this endpoint answers for any account, so it is the
+     * cheapest way to settle the question without assuming the token owns the name.
+     */
+    async getUser(username) {
+        return await this.request({ method: "GET", path: `/users/${segment(username)}` });
+    }
+    /**
+     * The repository, when there may already be one.
+     *
+     * A 404 from here is "no such repository **for this token**": the same status covers absent and
+     * invisible, so a caller that means to create one must treat it as "create and let the create
+     * fail" rather than as proof the name is free.
+     */
+    async getRepository(owner, repo) {
+        return await this.request({
+            method: "GET",
+            path: `/repos/${segment(owner)}/${segment(repo)}`,
+        });
+    }
+    /** The repository for an app whose `HF_GITHUB_OWNER` is the token's own account. */
+    async createUserRepository(body) {
+        return await this.request({ method: "POST", path: "/user/repos", body });
+    }
+    /** The same, when `HF_GITHUB_OWNER` is an organization instead. */
+    async createOrgRepository(org, body) {
+        return await this.request({ method: "POST", path: `/orgs/${segment(org)}/repos`, body });
+    }
+    /**
+     * `hf doctor`'s idea of what the repository says is deployed. `ref` is `heads/main`, and is
+     * not percent-encoded: GitHub spells this parameter with the slash as a path separator.
+     */
+    async getReference(owner, repo, ref) {
+        return await this.request({
+            method: "GET",
+            path: `/repos/${segment(owner)}/${segment(repo)}/git/ref/${ref}`,
+        });
+    }
+    /**
+     * Open pull requests, unfiltered.
+     *
+     * `hf doctor` wants the `core-bump/` ones, but GitHub's `head` filter takes a whole
+     * `user:branch`, not a prefix, so the prefix match belongs to the caller.
+     */
+    async listPullRequests(owner, repo, options = {}) {
+        return await this.request({
+            method: "GET",
+            path: `/repos/${segment(owner)}/${segment(repo)}/pulls`,
+            query: { state: options.state, per_page: options.per_page },
+        });
+    }
+    /**
+     * The GitHub Apps installed for the token's user, with their slugs.
+     *
+     * `hf new` asserts both `HF_GITHUB_APP_SLUGS` entries are installed on the new repository —
+     * Coolify cannot deploy from a repository its app cannot see, and that failure otherwise
+     * surfaces as a deploy that clones nothing.
+     */
+    async listInstallations(options = {}) {
+        return await this.request({
+            method: "GET",
+            path: "/user/installations",
+            query: { per_page: options.per_page, page: options.page },
+        });
+    }
+    /** Which repositories one installation actually reaches; the other half of that assertion. */
+    async listInstallationRepositories(installationId, options = {}) {
+        return await this.request({
+            method: "GET",
+            path: `/user/installations/${segment(String(installationId))}/repositories`,
+            query: { per_page: options.per_page, page: options.page },
+        });
+    }
+    async getCombinedStatus(owner, repo, ref) {
+        return await this.request({
+            method: "GET",
+            path: `/repos/${segment(owner)}/${segment(repo)}/commits/${segment(ref)}/status`,
+        });
+    }
+}

package/dist/providers/http.d.ts

@@ -0,0 +1,41 @@
+/** The one function every client talks to the network through; tests inject their own. */
+export type FetchLike = typeof globalThis.fetch;
+export type HttpMethod = "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+export interface ProviderRequest {
+    method: HttpMethod;
+    /** Path under the client's base URL, already interpolated. */
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+}
+/**
+ * A provider answered with a status outside 2xx.
+ *
+ * The response body is on `body` and deliberately **not** in `message`: a Coolify 422 echoes
+ * the fields it rejected, and those fields are the app's whole environment — its database URL,
+ * its status tokens, its Langfuse secret key. `hf` prints `error.message`, so a body that
+ * quotes a secret would land in a terminal and a scrollback. Nor is the query string included,
+ * for the same reason.
+ */
+export declare class ProviderError extends Error {
+    readonly provider: string;
+    readonly status: number;
+    readonly method: HttpMethod;
+    readonly path: string;
+    readonly body: string;
+    constructor(provider: string, request: ProviderRequest, status: number, body: string);
+}
+export interface TransportOptions {
+    /** Names the provider in errors. */
+    provider: string;
+    /** Everything before `path`, including any API prefix (`https://coolify.example/api/v1`). */
+    baseUrl: string;
+    /** Sent on every request — the authorization header, and whatever else the API insists on. */
+    headers: Record<string, string>;
+    fetch?: FetchLike;
+}
+export type Transport = <Result>(request: ProviderRequest) => Promise<Result>;
+/** Builds the `request` function the clients in this directory are written against. */
+export declare function createTransport(options: TransportOptions): Transport;
+/** Percent-encodes one path segment, so an app name can never escape into the path. */
+export declare function segment(value: string): string;

package/dist/providers/http.js

@@ -0,0 +1,56 @@
+/**
+ * A provider answered with a status outside 2xx.
+ *
+ * The response body is on `body` and deliberately **not** in `message`: a Coolify 422 echoes
+ * the fields it rejected, and those fields are the app's whole environment — its database URL,
+ * its status tokens, its Langfuse secret key. `hf` prints `error.message`, so a body that
+ * quotes a secret would land in a terminal and a scrollback. Nor is the query string included,
+ * for the same reason.
+ */
+export class ProviderError extends Error {
+    provider;
+    status;
+    method;
+    path;
+    body;
+    constructor(provider, request, status, body) {
+        super(`${provider} ${request.method} ${request.path} failed: HTTP ${status}`);
+        this.name = "ProviderError";
+        this.provider = provider;
+        this.status = status;
+        this.method = request.method;
+        this.path = request.path;
+        this.body = body;
+    }
+}
+/** Builds the `request` function the clients in this directory are written against. */
+export function createTransport(options) {
+    // Looked up per request, not captured: a test's mock server replaces `globalThis.fetch` after
+    // the clients have been constructed.
+    const doFetch = (input, init) => (options.fetch ?? globalThis.fetch)(input, init);
+    const base = options.baseUrl.replace(/\/+$/, "");
+    return async (request) => {
+        const url = new URL(base + request.path);
+        for (const [name, value] of Object.entries(request.query ?? {})) {
+            if (value !== undefined)
+                url.searchParams.set(name, String(value));
+        }
+        const headers = { accept: "application/json", ...options.headers };
+        if (request.body !== undefined)
+            headers["content-type"] = "application/json";
+        const response = await doFetch(url, {
+            method: request.method,
+            headers,
+            body: request.body === undefined ? undefined : JSON.stringify(request.body),
+        });
+        const text = await response.text();
+        if (!response.ok) {
+            throw new ProviderError(options.provider, request, response.status, text);
+        }
+        return (text === "" ? undefined : JSON.parse(text));
+    };
+}
+/** Percent-encodes one path segment, so an app name can never escape into the path. */
+export function segment(value) {
+    return encodeURIComponent(value);
+}

package/dist/providers/langfuse.d.ts

@@ -0,0 +1,41 @@
+import { type FetchLike } from "./http.js";
+export interface LangfuseProject {
+    id: string;
+    name: string;
+}
+export interface LangfuseProjects {
+    data: LangfuseProject[];
+}
+export interface LangfuseApiKey {
+    id: string;
+    publicKey: string;
+    /** Returned once, at creation; Langfuse never shows it again. */
+    secretKey: string;
+    note?: string;
+}
+export interface LangfuseClientOptions {
+    /** `HF_LANGFUSE_URL` — the instance's origin. */
+    url: string;
+    /**
+     * `HF_LANGFUSE_ORG_KEY`, spelled `<publicKey>:<secretKey>`: Langfuse authenticates with HTTP
+     * Basic, and an organization-scoped key is a pair, so the pair is one config value rather
+     * than two that can be set out of step with each other.
+     */
+    orgKey: string;
+    fetch?: FetchLike;
+}
+export declare class LangfuseClient {
+    private readonly request;
+    constructor(options: LangfuseClientOptions);
+    /** The org key's projects; a rerun finds the app's own by name instead of creating a second. */
+    listProjects(): Promise<LangfuseProjects>;
+    /** `retention` is required by the API: 0 keeps data indefinitely. */
+    createProject(body: {
+        name: string;
+        retention: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<LangfuseProject>;
+    createApiKey(projectId: string, body?: {
+        note?: string;
+    }): Promise<LangfuseApiKey>;
+}

package/dist/providers/langfuse.js

@@ -0,0 +1,29 @@
+import { createTransport, segment } from "./http.js";
+export class LangfuseClient {
+    request;
+    constructor(options) {
+        this.request = createTransport({
+            provider: "langfuse",
+            baseUrl: options.url.replace(/\/+$/, ""),
+            headers: {
+                authorization: `Basic ${Buffer.from(options.orgKey, "utf8").toString("base64")}`,
+            },
+            fetch: options.fetch,
+        });
+    }
+    /** The org key's projects; a rerun finds the app's own by name instead of creating a second. */
+    async listProjects() {
+        return await this.request({ method: "GET", path: "/api/public/projects" });
+    }
+    /** `retention` is required by the API: 0 keeps data indefinitely. */
+    async createProject(body) {
+        return await this.request({ method: "POST", path: "/api/public/projects", body });
+    }
+    async createApiKey(projectId, body = {}) {
+        return await this.request({
+            method: "POST",
+            path: `/api/public/projects/${segment(projectId)}/apiKeys`,
+            body,
+        });
+    }
+}

package/dist/providers/sentry.d.ts

@@ -0,0 +1,31 @@
+import { type FetchLike } from "./http.js";
+export declare const SENTRY_URL = "https://sentry.io";
+export interface SentryProject {
+    id: string;
+    slug: string;
+    name: string;
+}
+export interface SentryProjectKey {
+    id: string;
+    name: string;
+    dsn: {
+        public: string;
+    };
+}
+export interface SentryClientOptions {
+    /** `HF_SENTRY_TOKEN`. */
+    token: string;
+    url?: string;
+    fetch?: FetchLike;
+}
+export declare class SentryClient {
+    private readonly request;
+    constructor(options: SentryClientOptions);
+    createProject(org: string, body: {
+        name: string;
+        slug?: string;
+        platform?: string;
+    }): Promise<SentryProject>;
+    /** The DSN `hf new` writes into `SENTRY_DSN` is `keys[0].dsn.public`. */
+    listProjectKeys(org: string, project: string): Promise<SentryProjectKey[]>;
+}

package/dist/providers/sentry.js

@@ -0,0 +1,27 @@
+import { createTransport, segment } from "./http.js";
+export const SENTRY_URL = "https://sentry.io";
+export class SentryClient {
+    request;
+    constructor(options) {
+        this.request = createTransport({
+            provider: "sentry",
+            baseUrl: options.url ?? SENTRY_URL,
+            headers: { authorization: `Bearer ${options.token}` },
+            fetch: options.fetch,
+        });
+    }
+    async createProject(org, body) {
+        return await this.request({
+            method: "POST",
+            path: `/api/0/organizations/${segment(org)}/projects/`,
+            body,
+        });
+    }
+    /** The DSN `hf new` writes into `SENTRY_DSN` is `keys[0].dsn.public`. */
+    async listProjectKeys(org, project) {
+        return await this.request({
+            method: "GET",
+            path: `/api/0/projects/${segment(org)}/${segment(project)}/keys/`,
+        });
+    }
+}

package/dist/provision-database.d.ts

@@ -0,0 +1,42 @@
+import { type RoleNames } from "@hyperfixation/db/migrator";
+import { type Database } from "./database.js";
+import type { AppStateStore } from "./state.js";
+/** Created in the app's database before its first migration; both are `hf_*` table columns. */
+export declare const REQUIRED_EXTENSIONS: readonly ["vector", "pg_trgm"];
+export declare class ProvisionDatabaseError extends Error {
+    constructor(message: string);
+}
+export interface ProvisionDatabaseOptions {
+    /** The name `hf new` was given; `hf_<app>` and the three roles derive from it. */
+    app: string;
+    state: AppStateStore;
+    /** Create the `_ro` role Metabase reads through. Default true. */
+    readonlyRole?: boolean;
+}
+export interface ProvisionDatabaseResult {
+    databaseName: string;
+    roles: RoleNames;
+    createdDatabase: boolean;
+    /** Nothing was issued: the `database` step was already recorded. */
+    alreadyDone: boolean;
+    /**
+     * A role that already existed was given a new password — a cold run against a live app.
+     *
+     * The deployed containers still hold the old one, so E3 has to order this
+     * rotate → Coolify env → redeploy; a caller that ignores this locks the app out of its own
+     * database until the next deploy.
+     */
+    rotated: boolean;
+}
+/**
+ * The app's database, its extensions and its three roles, resumable and safe to rerun.
+ *
+ * Passwords live only in the state cache, and the order here is what keeps that honest: every
+ * password is written to the file **after** the cluster has accepted it, never before. A crash
+ * in between therefore leaves a state file that lags the database rather than one that leads
+ * it, and the next run — which still sees the step unrecorded, and still has no password to
+ * reuse — generates a fresh one and `ALTER`s again. Converging costs one more rotation; the
+ * other order would leave a file whose passwords nothing can log in with, and those files are
+ * the only copy there is.
+ */
+export declare function provisionDatabase(target: Database | string, options: ProvisionDatabaseOptions): Promise<ProvisionDatabaseResult>;

package/dist/provision-database.js

@@ -0,0 +1,107 @@
+import { randomBytes } from "node:crypto";
+import { quoteIdent } from "@hyperfixation/db";
+import { provisionRoles, roleNames } from "@hyperfixation/db/migrator";
+import { openDatabaseUrl } from "./database.js";
+import { deriveNames } from "./names.js";
+/** Created in the app's database before its first migration; both are `hf_*` table columns. */
+export const REQUIRED_EXTENSIONS = ["vector", "pg_trgm"];
+export class ProvisionDatabaseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ProvisionDatabaseError";
+    }
+}
+/**
+ * The app's database, its extensions and its three roles, resumable and safe to rerun.
+ *
+ * Passwords live only in the state cache, and the order here is what keeps that honest: every
+ * password is written to the file **after** the cluster has accepted it, never before. A crash
+ * in between therefore leaves a state file that lags the database rather than one that leads
+ * it, and the next run — which still sees the step unrecorded, and still has no password to
+ * reuse — generates a fresh one and `ALTER`s again. Converging costs one more rotation; the
+ * other order would leave a file whose passwords nothing can log in with, and those files are
+ * the only copy there is.
+ */
+export async function provisionDatabase(target, options) {
+    // `deriveNames` is `assertAppName`'s rule with hyphens allowed in the typed name only, so a
+    // name carrying a quote, a semicolon or a `$(` is refused here rather than quoted downstream.
+    const names = deriveNames(options.app);
+    const roles = roleNames(names.appName);
+    const { state } = options;
+    const stored = state.state.database ?? {};
+    if (state.isDone("database") &&
+        stored.migratorPassword !== undefined &&
+        stored.applicationPassword !== undefined) {
+        return {
+            databaseName: names.databaseName,
+            roles,
+            createdDatabase: false,
+            alreadyDone: true,
+            rotated: false,
+        };
+    }
+    const db = typeof target === "string" ? openDatabaseUrl(target) : target;
+    const adminUrl = db.adminUrl();
+    if (adminUrl === undefined) {
+        throw new ProvisionDatabaseError(`roles cannot be provisioned over the ${db.kind} transport: provisionRoles() is a pg ` +
+            "client and needs an address. Publish the Coolify Postgres port on the box's loopback " +
+            "so the tunnel works.");
+    }
+    try {
+        const createdDatabase = await createDatabaseIfAbsent(db, names.databaseName);
+        for (const extension of REQUIRED_EXTENSIONS) {
+            await db.query(`CREATE EXTENSION IF NOT EXISTS ${quoteIdent(extension)}`, {
+                database: names.databaseName,
+            });
+        }
+        const wanted = options.readonlyRole !== false;
+        // A cold run is one with no password to reuse; it is a *rotation* only when the roles are
+        // already there, which is the case that strands a deployed app on its old credentials.
+        const regenerating = stored.migratorPassword === undefined || stored.applicationPassword === undefined;
+        const rotated = regenerating && (await anyRoleExists(db, [roles.migrator, roles.application]));
+        const provisioned = await provisionRoles(adminUrl, {
+            appName: names.appName,
+            databaseName: names.databaseName,
+            migratorPassword: stored.migratorPassword,
+            applicationPassword: stored.applicationPassword,
+            readonlyPassword: wanted ? (stored.readonlyPassword ?? generatePassword()) : undefined,
+        });
+        await state.patch({
+            database: {
+                migratorPassword: provisioned.migratorPassword,
+                applicationPassword: provisioned.applicationPassword,
+                ...(provisioned.readonlyPassword === undefined
+                    ? {}
+                    : { readonlyPassword: provisioned.readonlyPassword }),
+            },
+        });
+        await state.markDone("database");
+        return { databaseName: names.databaseName, roles, createdDatabase, alreadyDone: false, rotated };
+    }
+    finally {
+        if (typeof target === "string")
+            await db.close();
+    }
+}
+async function createDatabaseIfAbsent(db, databaseName) {
+    const { rows } = await db.query(`SELECT 1 FROM pg_database WHERE datname = ${quoteLiteral(databaseName)}`);
+    if (rows.length > 0)
+        return false;
+    await db.query(`CREATE DATABASE ${quoteIdent(databaseName)}`);
+    return true;
+}
+async function anyRoleExists(db, roles) {
+    const list = roles.map(quoteLiteral).join(", ");
+    const { rows } = await db.query(`SELECT 1 FROM pg_roles WHERE rolname IN (${list})`);
+    return rows.length > 0;
+}
+/**
+ * The `_ro` password. `provisionRoles` generates the other two itself, but creates the
+ * read-only role only when it is handed one.
+ */
+function generatePassword() {
+    return randomBytes(24).toString("base64url");
+}
+function quoteLiteral(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}

package/dist/restore-check.d.ts

@@ -0,0 +1,91 @@
+import { type BackupDump, type BackupSource } from "./backup-source.js";
+import { type Database } from "./database.js";
+import { type Runner } from "./runner.js";
+import { type AppStateStore } from "./state.js";
+/** Appended to `hf_<app>` for the database the dump is restored into and then dropped. */
+export declare const SCRATCH_SUFFIX = "_restore_check";
+/** Older than this and the dump gets a warning line; it never changes the exit code. */
+export declare const STALE_DUMP_HOURS = 36;
+export type RestoreVerdict = "ok" | "mismatch" | "live only" | "restored only";
+export interface RestoreCheckRow {
+    table: string;
+    /** Absent when the table is not in the live database. */
+    live?: number;
+    /** Absent when the table is not in the restored dump. */
+    restored?: number;
+    verdict: RestoreVerdict;
+}
+export interface RestoreCheckResult {
+    databaseName: string;
+    /** Created and dropped by this call; never left behind. */
+    scratchDatabase: string;
+    dump: BackupDump;
+    dumpAgeHours: number;
+    /** The dump is older than `STALE_DUMP_HOURS`. Informational. */
+    dumpStale: boolean;
+    /** One row per table, `hf_*` or carrying `normalized_name`, sorted by name. */
+    rows: readonly RestoreCheckRow[];
+    /** Every row's verdict is `ok`. The command's exit code is `ok ? 0 : 1`. */
+    ok: boolean;
+}
+export declare class RestoreCheckError extends Error {
+    constructor(message: string);
+}
+export interface RestoreCheckOptions {
+    /** The name `hf new` was given; `hf_<app>` and the migrator role derive from it. */
+    app: string;
+    state: AppStateStore;
+    source: BackupSource;
+    /** Where `pg_restore` runs: the box, or this machine in a test. */
+    runner: Runner;
+    /** How the scratch database is created and both sides are counted. */
+    database: Database | string;
+    /**
+     * The cluster's admin URL **as the runner sees it**, for `pg_restore`.
+     *
+     * Not the same address as `database`: the laptop reaches the cluster through an `ssh -L`
+     * forward onto a local port, and a `pg_restore` running on the far side of that forward has to
+     * dial the box's own loopback. Defaults to `database`'s URL, which is what a test wants when
+     * both sides are the same machine.
+     */
+    restoreAdminUrl?: string;
+    /** The `pg_restore` binary on the runner. */
+    pgRestorePath?: string;
+    now?: Date;
+}
+/**
+ * Restores the newest dump of `hf_<app>` beside the live database and compares row counts.
+ *
+ * The scratch database is dropped in a `finally`: it holds a full copy of the app's data, so
+ * leaving one behind on a failure would double the disk the app uses until someone noticed.
+ *
+ * `lastRestoreCheckAt` is written only by a run that counted both sides and found them equal.
+ * `hf doctor` warns on a stale timestamp, so a check that died halfway — or one that found a
+ * mismatch — has to leave the warning standing until a check actually passes.
+ */
+export declare function restoreCheck(options: RestoreCheckOptions): Promise<RestoreCheckResult>;
+/** The argv `restoreCheck` runs — the array the test asserts against. */
+export declare function pgRestoreArgv(options: {
+    url: string;
+    role: string;
+    file: string;
+    pgRestorePath?: string;
+}): string[];
+/** The table `hf restore-check` prints, and the two lines around it. */
+export declare function formatRestoreCheck(result: RestoreCheckResult): string[];
+export interface RestoreCheckAppOptions {
+    app: string;
+    /** Where the dumps are; defaults to Coolify's backup directory on the box. */
+    backupDir?: string;
+    /** Read the dump from Hetzner object storage instead. Not implemented; see `backup-source`. */
+    fromS3?: boolean;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * `hf restore-check <name>`: the operator config, an `ssh` runner onto the box, and the check.
+ *
+ * The cluster admin password comes from libpq's own `PGPASSWORD` until E3 records Coolify's — the
+ * operator config has no key for it, and inventing one before the box has been looked at is
+ * exactly what risk 3 warns against.
+ */
+export declare function restoreCheckApp(options: RestoreCheckAppOptions): Promise<RestoreCheckResult>;