@hyperfixation/cli 0.1.0 → 0.1.1

package/dist/new-cloud.js

@@ -0,0 +1,210 @@
+import path from "node:path";
+import { checklistLines } from "./checklist.js";
+import { providerKeys } from "./cloud-steps/coolify.js";
+import { cloudCommands, CLOUD_STEPS, defaultTemplateFetch, spawnStepExec, } from "./cloud-steps/index.js";
+import { loadOperatorConfig, requireOperatorConfig, } from "./config.js";
+import { openDatabase } from "./database.js";
+import { deriveNames } from "./names.js";
+import { createSshRunner } from "./runner.js";
+import { openAppState, secretsHash, STEPS, } from "./state.js";
+/** The steps themselves; the runner is what orders and records them. */
+export { CLOUD_STEPS };
+/**
+ * The steps whose "done" depends on more than having run once.
+ *
+ * Both carry the app's secrets into the deployment — `coolify` PATCHes them as environment
+ * variables, `deploy` is what makes the containers read them — so a run that rotated a password
+ * has to redo both, even though a previous run recorded them.
+ */
+const SECRET_CARRYING_STEPS = ["coolify", "deploy"];
+/** The runner found state it will not act on: the operator has to be told, not worked around. */
+export class StepInvariantViolated extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "StepInvariantViolated";
+    }
+}
+/**
+ * True when the secrets the Coolify envs were last PATCHed with are the ones the state holds now.
+ *
+ * A `coolify` step that has run but recorded no hash counts as stale: re-PATCHing is idempotent
+ * and cheap, and the alternative is trusting a file written before this field existed.
+ */
+export function envsAreCurrent(state) {
+    return state.coolify?.envsSecretsHash === secretsHash(state);
+}
+/**
+ * Refuses a recorded state whose deployment is authenticating with secrets that no longer exist.
+ *
+ * Silent otherwise, including for an app that has not reached `coolify` yet: a run that stops
+ * early is resumable, whereas a `coolify` recorded against passwords since rotated is a deployed
+ * app locked out of its own database with nothing left to notice it.
+ */
+export function assertEnvsCurrent(state) {
+    if (state.steps.coolify === undefined || envsAreCurrent(state))
+        return;
+    throw new StepInvariantViolated("the app's secrets have changed since its Coolify environment was set: re-run hf new to " +
+        "PATCH the environment and redeploy (nothing was rolled back)");
+}
+/**
+ * Refuses to finish a run that rotated a password without the Coolify environment catching up.
+ *
+ * The state-only check above cannot see this case on its own: a list of steps that stops before
+ * `coolify` leaves a consistent file and a deployed app on dead credentials.
+ */
+export function assertRotationApplied(context) {
+    if (!context.rotated)
+        return;
+    if (context.state.isDone("coolify") && envsAreCurrent(context.state.state))
+        return;
+    throw new StepInvariantViolated("this run rotated the app's database passwords but never PATCHed them into Coolify: the " +
+        "deployed app still holds the old ones. Re-run hf new to finish the rotation.");
+}
+/**
+ * Forgets the steps that carried secrets the app no longer has, and reports which.
+ *
+ * Done once, before the first step, and by clearing the records rather than by ignoring them:
+ * `coolify` makes the hash current again the moment it re-runs, so a per-step test would then
+ * count `deploy` as done and leave the containers reading the previous environment. Clearing also
+ * survives a crash in between — the next run sees the same two steps missing.
+ */
+export async function invalidateStaleSecretSteps(state) {
+    if (envsAreCurrent(state.state))
+        return [];
+    const cleared = [];
+    for (const name of SECRET_CARRYING_STEPS) {
+        if (!state.isDone(name))
+            continue;
+        await state.clearDone(name);
+        cleared.push(name);
+    }
+    return cleared;
+}
+/**
+ * Runs the steps of a cloud `hf new` in order, skipping what a previous run finished.
+ *
+ * A step is marked done only after its `run` resolves, so a failure leaves the step unrecorded
+ * and the next run repeats it — the one direction that is safe, since repeating a create costs a
+ * duplicate at worst while recording one that never happened costs an app nobody can finish.
+ * Errors propagate untouched: the caller prints them, and the state file is the resume point.
+ */
+export async function runSteps(steps, context) {
+    assertStepOrder(steps);
+    const invalidated = await invalidateStaleSecretSteps(context.state);
+    const ran = [];
+    const skipped = [];
+    for (const step of steps) {
+        if (context.state.isDone(step.name)) {
+            skipped.push(step.name);
+            continue;
+        }
+        await step.run(context);
+        await context.state.markDone(step.name);
+        ran.push(step.name);
+    }
+    assertEnvsCurrent(context.state.state);
+    assertRotationApplied(context);
+    return { ran, skipped, invalidated };
+}
+/**
+ * Every operator config key a cloud `hf new` needs, checked before the first step.
+ *
+ * All at once, and before anything is created: `requireOperatorConfig` names every missing key,
+ * and an operator who learns about them one failed step at a time pays for a half-provisioned app
+ * each time. The optional keys are deliberately absent — `HF_DB_HOST_INTERNAL` has a default, and
+ * the two provider keys are what the checklist warns about when they are unset.
+ */
+export const REQUIRED_CLOUD_CONFIG = [
+    "HF_COOLIFY_URL",
+    "HF_COOLIFY_TOKEN",
+    "HF_COOLIFY_SERVER_UUID",
+    "HF_COOLIFY_GITHUB_APP_UUID",
+    "HF_COOLIFY_POSTGRES_UUID",
+    "HF_SSH_HOST",
+    "HF_BASE_DOMAIN",
+    "HF_SMTP_URL",
+    "HF_EMAIL_FROM",
+    "HF_LANGFUSE_URL",
+];
+/** The cluster role `hf new` provisions the app's database and roles as. */
+const CLUSTER_ADMIN_USER = "postgres";
+/**
+ * `hf new <name>` without `--local`: the ten steps, resumable, then the checklist.
+ *
+ * Nothing here is interactive and nothing is prompted for — this runs against five APIs and a box
+ * — so every input is a flag or a config key, and a missing one is reported before the first
+ * request rather than half way through.
+ */
+export async function newAppCloud(options) {
+    const env = options.env ?? process.env;
+    const config = options.config ?? (await loadOperatorConfig({ env }));
+    const required = requireOperatorConfig(config, REQUIRED_CLOUD_CONFIG, { env });
+    const names = deriveNames(options.name);
+    const state = await openAppState(names.given, { dir: options.stateDir, env });
+    const runner = options.runner ?? createSshRunner({ host: required.HF_SSH_HOST });
+    // `PGPASSWORD` is libpq's own name for it, and the same place `hf restore-check` reads it:
+    // Coolify's cluster password is not an hf config key, because nothing of ours should hold it.
+    const clusterAdmin = options.clusterAdmin ?? { user: CLUSTER_ADMIN_USER, password: env.PGPASSWORD };
+    let database;
+    const hadWriteToken = state.state.statusTokens?.write !== undefined;
+    const fqdn = `${names.given}.${required.HF_BASE_DOMAIN}`;
+    const context = {
+        state,
+        rotated: false,
+        names,
+        dir: path.resolve(options.into ?? process.cwd(), names.given),
+        config,
+        env,
+        io: options.io,
+        checklist: [],
+        exec: spawnStepExec,
+        from: options.from,
+        fetchTemplate: defaultTemplateFetch,
+        fetch: options.fetch,
+        email: options.email,
+        budgetUsd: options.budgetUsd,
+        database: async () => {
+            // No `container`: the `docker exec psql` transport has no address, and every use of the
+            // cluster here — `provisionRoles`, the migrator, the tokens — is a pg client.
+            database ??= await openDatabase(runner, { admin: clusterAdmin });
+            return database;
+        },
+        commands: options.commands ?? cloudCommands,
+        now: options.now ?? (() => Date.now()),
+        sleep: options.sleep ?? (async (ms) => await new Promise((resolve) => setTimeout(resolve, ms))),
+    };
+    let result;
+    try {
+        result = await runSteps(options.steps ?? CLOUD_STEPS, context);
+    }
+    finally {
+        await database?.close();
+    }
+    const checklist = checklistLines({
+        names,
+        fqdn,
+        repo: state.state.repo,
+        dbHost: config.HF_DB_HOST_INTERNAL ?? required.HF_COOLIFY_POSTGRES_UUID,
+        stateFile: state.file,
+        providerKeysSent: providerKeys(config).map(([key]) => key),
+        // Whatever the steps themselves asked the operator to look at — the backup schedule included,
+        // which is the one thing Coolify's API cannot be asked about.
+        fromSteps: context.checklist,
+        // Shown once means the run that minted it; every later run leaves it in the state file alone.
+        writeToken: hadWriteToken ? undefined : state.state.statusTokens?.write,
+    });
+    return { ...result, dir: context.dir, fqdn, checklist };
+}
+/**
+ * `STEPS`' order is the rotation-safety argument — every fallible create before `database`, and
+ * `coolify` straight after it — so a caller that assembles its list in another order is a bug
+ * here rather than a stranded app on the box.
+ */
+function assertStepOrder(steps) {
+    const positions = steps.map((step) => STEPS.indexOf(step.name));
+    for (let index = 1; index < positions.length; index += 1) {
+        if (positions[index] <= positions[index - 1]) {
+            throw new StepInvariantViolated(`steps out of order: ${steps[index - 1].name} before ${steps[index].name}`);
+        }
+    }
+}

package/dist/new.d.ts

@@ -55,3 +55,5 @@ export declare function newApp(options: NewAppOptions): Promise<NewAppResult>;
 /** The placeholder map. Exported because `hf check` reports a leftover placeholder by name. */
 export declare function placeholders(names: AppNames): Record<string, string>;
 export declare function substitute(contents: string, names: AppNames): string;
+/** Substitutes every placeholder in a copied tree; the cloud `template` step reuses this one. */
+export declare function substituteTree(dir: string, names: AppNames): Promise<string[]>;

package/dist/new.js

@@ -115,7 +115,8 @@ async function assertTemplateSource(source) {
         throw new TemplateError(`${source} has no ${TEMPLATE_MARKER}: it is not a hyperfixation template checkout`);
     }
 }
-async function substituteTree(dir, names) {
+/** Substitutes every placeholder in a copied tree; the cloud `template` step reuses this one. */
+export async function substituteTree(dir, names) {
     const changed = [];
     for (const file of await walk(dir)) {
         if (BINARY_EXTENSIONS.has(path.extname(file)))

package/dist/providers/cloudflare.d.ts

@@ -0,0 +1,49 @@
+import { type FetchLike } from "./http.js";
+export declare const CLOUDFLARE_API_URL = "https://api.cloudflare.com/client/v4";
+export interface CloudflareDnsRecord {
+    id: string;
+    type: string;
+    name: string;
+    content: string;
+    proxied: boolean;
+    ttl: number;
+}
+/** Cloudflare wraps every answer; `success: false` still arrives as HTTP 200 on some routes. */
+export interface CloudflareEnvelope<Result> {
+    success: boolean;
+    errors: {
+        code: number;
+        message: string;
+    }[];
+    result: Result;
+}
+/**
+ * The one record `hf new` writes: `A <app>.<HF_BASE_DOMAIN>` → `HF_BOX_IP`, DNS-only.
+ *
+ * `proxied: false` is the decided domain scheme — Coolify's proxy terminates TLS, and a
+ * proxied record would both need Full-strict and hide the box from Coolify's ACME challenge.
+ */
+export interface CloudflareARecord {
+    type: "A";
+    name: string;
+    content: string;
+    ttl: number;
+    proxied: boolean;
+    comment?: string;
+}
+export interface CloudflareClientOptions {
+    /** `HF_CLOUDFLARE_TOKEN`. */
+    token: string;
+    /** Overridden only by tests; the real API has one address. */
+    url?: string;
+    fetch?: FetchLike;
+}
+export declare class CloudflareClient {
+    private readonly request;
+    constructor(options: CloudflareClientOptions);
+    listDnsRecords(zoneId: string, filters?: {
+        name?: string;
+        type?: string;
+    }): Promise<CloudflareEnvelope<CloudflareDnsRecord[]>>;
+    createDnsRecord(zoneId: string, record: CloudflareARecord): Promise<CloudflareEnvelope<CloudflareDnsRecord>>;
+}

package/dist/providers/cloudflare.js

@@ -0,0 +1,27 @@
+import { createTransport, segment } from "./http.js";
+export const CLOUDFLARE_API_URL = "https://api.cloudflare.com/client/v4";
+export class CloudflareClient {
+    request;
+    constructor(options) {
+        this.request = createTransport({
+            provider: "cloudflare",
+            baseUrl: options.url ?? CLOUDFLARE_API_URL,
+            headers: { authorization: `Bearer ${options.token}` },
+            fetch: options.fetch,
+        });
+    }
+    async listDnsRecords(zoneId, filters = {}) {
+        return await this.request({
+            method: "GET",
+            path: `/zones/${segment(zoneId)}/dns_records`,
+            query: { name: filters.name, type: filters.type },
+        });
+    }
+    async createDnsRecord(zoneId, record) {
+        return await this.request({
+            method: "POST",
+            path: `/zones/${segment(zoneId)}/dns_records`,
+            body: record,
+        });
+    }
+}

package/dist/providers/coolify.d.ts

@@ -0,0 +1,148 @@
+import { type FetchLike } from "./http.js";
+export interface CoolifyProject {
+    uuid: string;
+    name: string;
+    description?: string;
+}
+/** Coolify's environment model carries a uuid the documented schema does not list. */
+export interface CoolifyEnvironment {
+    uuid: string;
+    name: string;
+}
+/**
+ * The application `hf new` creates: a docker-compose build pack on the app's own private
+ * repository, reached through the Coolify GitHub App.
+ *
+ * `environment_uuid` and `environment_name` are both required by the API document even though
+ * its prose says either will do — so both are required here, and the uuid is what
+ * `listEnvironments` is for.
+ */
+export interface CoolifyApplicationRequest {
+    project_uuid: string;
+    server_uuid: string;
+    environment_name: string;
+    environment_uuid: string;
+    github_app_uuid: string;
+    /** `owner/name`, as Coolify stores it for a GitHub App source. */
+    git_repository: string;
+    git_branch: string;
+    build_pack: "nixpacks" | "railpack" | "static" | "dockerfile" | "dockercompose";
+    name?: string;
+    description?: string;
+    /** Comma-separated; the app's `https://<name>.<HF_BASE_DOMAIN>`. */
+    domains?: string;
+    ports_exposes?: string;
+    docker_compose_location?: string;
+    connect_to_docker_network?: boolean;
+    instant_deploy?: boolean;
+    is_auto_deploy_enabled?: boolean;
+}
+export interface CoolifyApplication {
+    uuid: string;
+}
+/** What `GET /applications` returns per item; the document's `Application` has both of these. */
+export interface CoolifyApplicationSummary {
+    uuid: string;
+    name: string;
+    fqdn?: string;
+}
+/**
+ * What `PATCH /databases/{uuid}` accepts of the fields E2 might need.
+ *
+ * Narrow on purpose: the document lists every engine's credentials, and nothing in it attaches a
+ * database to a docker network — `is_public`/`public_port` is the only reach the API has over how
+ * a database is addressed.
+ */
+export interface CoolifyDatabaseUpdate {
+    name?: string;
+    description?: string;
+    is_public?: boolean;
+    public_port?: number;
+}
+export interface CoolifyEnvironmentVariable {
+    key: string;
+    value: string;
+    is_preview?: boolean;
+    is_literal?: boolean;
+    is_multiline?: boolean;
+    is_shown_once?: boolean;
+}
+export interface CoolifyDeploymentRequest {
+    deployments: {
+        message: string;
+        resource_uuid: string;
+        deployment_uuid: string;
+    }[];
+}
+export interface CoolifyDeployment {
+    deployment_uuid: string;
+    /** `queued` | `in_progress` | `finished` | `failed` | `cancelled-by-user`, as Coolify sets it. */
+    status: string;
+    commit?: string;
+    logs?: string;
+}
+export interface CoolifyBackupRequest {
+    /** A cron expression, or one of `every_minute`…`yearly`. */
+    frequency: string;
+    enabled?: boolean;
+    save_s3?: boolean;
+    s3_storage_uuid?: string;
+    /** Comma-separated database names — the app's `hf_<name>`, not the whole cluster. */
+    databases_to_backup?: string;
+    dump_all?: boolean;
+    backup_now?: boolean;
+    database_backup_retention_amount_locally?: number;
+    database_backup_retention_days_locally?: number;
+}
+export interface CoolifyBackup {
+    uuid: string;
+    message?: string;
+}
+export interface CoolifyClientOptions {
+    /** `HF_COOLIFY_URL` — the instance's origin, without `/api/v1`. */
+    url: string;
+    /** `HF_COOLIFY_TOKEN`. */
+    token: string;
+    fetch?: FetchLike;
+}
+export declare class CoolifyClient {
+    private readonly request;
+    constructor(options: CoolifyClientOptions);
+    createProject(body: {
+        name: string;
+        description?: string;
+    }): Promise<{
+        uuid: string;
+    }>;
+    /** Every project on the instance; `hf new` finds its own by name rather than creating a second. */
+    listProjects(): Promise<CoolifyProject[]>;
+    getProject(uuid: string): Promise<CoolifyProject>;
+    listEnvironments(projectUuid: string): Promise<CoolifyEnvironment[]>;
+    createPrivateGithubAppApplication(body: CoolifyApplicationRequest): Promise<CoolifyApplication>;
+    /**
+     * Every application, so a rerun can find the one it created last time by name.
+     *
+     * The state cache is the first place to look for the uuid; this is what answers the case where
+     * the application exists but the state file does not, which is a cold run against a live app.
+     */
+    listApplications(options?: {
+        tag?: string;
+    }): Promise<CoolifyApplicationSummary[]>;
+    updateEnvsBulk(appUuid: string, data: readonly CoolifyEnvironmentVariable[]): Promise<unknown>;
+    deploy(uuid: string, options?: {
+        force?: boolean;
+    }): Promise<CoolifyDeploymentRequest>;
+    getDeployment(deploymentUuid: string): Promise<CoolifyDeployment>;
+    createDatabaseBackup(databaseUuid: string, body: CoolifyBackupRequest): Promise<CoolifyBackup>;
+    /**
+     * The database's scheduled backups.
+     *
+     * `unknown`, not a model: upstream documents this response as a string whose example reads
+     * "Content is very complex. Will be implemented later.", so there is nothing to type against.
+     * A caller that needs a field has to narrow it against the box itself.
+     */
+    listDatabaseBackups(databaseUuid: string): Promise<unknown>;
+    /** The database as Coolify holds it — undocumented in shape, same as the backups list. */
+    getDatabase(uuid: string): Promise<unknown>;
+    updateDatabase(uuid: string, body: CoolifyDatabaseUpdate): Promise<unknown>;
+}

package/dist/providers/coolify.js

@@ -0,0 +1,87 @@
+import { createTransport, segment } from "./http.js";
+export class CoolifyClient {
+    request;
+    constructor(options) {
+        this.request = createTransport({
+            provider: "coolify",
+            baseUrl: `${options.url.replace(/\/+$/, "")}/api/v1`,
+            headers: { authorization: `Bearer ${options.token}` },
+            fetch: options.fetch,
+        });
+    }
+    async createProject(body) {
+        return await this.request({ method: "POST", path: "/projects", body });
+    }
+    /** Every project on the instance; `hf new` finds its own by name rather than creating a second. */
+    async listProjects() {
+        return await this.request({ method: "GET", path: "/projects" });
+    }
+    async getProject(uuid) {
+        return await this.request({ method: "GET", path: `/projects/${segment(uuid)}` });
+    }
+    async listEnvironments(projectUuid) {
+        return await this.request({
+            method: "GET",
+            path: `/projects/${segment(projectUuid)}/environments`,
+        });
+    }
+    async createPrivateGithubAppApplication(body) {
+        return await this.request({ method: "POST", path: "/applications/private-github-app", body });
+    }
+    /**
+     * Every application, so a rerun can find the one it created last time by name.
+     *
+     * The state cache is the first place to look for the uuid; this is what answers the case where
+     * the application exists but the state file does not, which is a cold run against a live app.
+     */
+    async listApplications(options = {}) {
+        return await this.request({ method: "GET", path: "/applications", query: { tag: options.tag } });
+    }
+    async updateEnvsBulk(appUuid, data) {
+        return await this.request({
+            method: "PATCH",
+            path: `/applications/${segment(appUuid)}/envs/bulk`,
+            body: { data },
+        });
+    }
+    async deploy(uuid, options = {}) {
+        return await this.request({
+            method: "POST",
+            path: "/deploy",
+            query: { uuid, force: options.force },
+        });
+    }
+    async getDeployment(deploymentUuid) {
+        return await this.request({
+            method: "GET",
+            path: `/deployments/${segment(deploymentUuid)}`,
+        });
+    }
+    async createDatabaseBackup(databaseUuid, body) {
+        return await this.request({
+            method: "POST",
+            path: `/databases/${segment(databaseUuid)}/backups`,
+            body,
+        });
+    }
+    /**
+     * The database's scheduled backups.
+     *
+     * `unknown`, not a model: upstream documents this response as a string whose example reads
+     * "Content is very complex. Will be implemented later.", so there is nothing to type against.
+     * A caller that needs a field has to narrow it against the box itself.
+     */
+    async listDatabaseBackups(databaseUuid) {
+        return await this.request({
+            method: "GET",
+            path: `/databases/${segment(databaseUuid)}/backups`,
+        });
+    }
+    /** The database as Coolify holds it — undocumented in shape, same as the backups list. */
+    async getDatabase(uuid) {
+        return await this.request({ method: "GET", path: `/databases/${segment(uuid)}` });
+    }
+    async updateDatabase(uuid, body) {
+        return await this.request({ method: "PATCH", path: `/databases/${segment(uuid)}`, body });
+    }
+}

package/dist/providers/github.d.ts

@@ -0,0 +1,117 @@
+import { type FetchLike } from "./http.js";
+export declare const GITHUB_API_URL = "https://api.github.com";
+export interface GithubRepository {
+    full_name: string;
+    clone_url: string;
+    default_branch: string;
+    private: boolean;
+}
+export interface GithubReference {
+    ref: string;
+    object: {
+        sha: string;
+        type: string;
+    };
+}
+export interface GithubPullRequest {
+    number: number;
+    title: string;
+    html_url: string;
+    head: {
+        ref: string;
+        sha: string;
+    };
+}
+export interface GithubCombinedStatus {
+    /** `success` | `pending` | `failure`. */
+    state: string;
+    total_count: number;
+}
+/** `GET /users/{username}`, for the one question `hf new` asks of it: account or organization. */
+export interface GithubUser {
+    login: string;
+    /** `User` | `Organization`; which of the two repository-creation endpoints applies. */
+    type: string;
+}
+export interface GithubInstallation {
+    id: number;
+    app_id: number;
+    /** The slug `HF_GITHUB_APP_SLUGS` names — Coolify's app, and the bump bot's. */
+    app_slug: string;
+}
+export interface GithubInstallations {
+    total_count: number;
+    installations: GithubInstallation[];
+}
+export interface GithubInstallationRepositories {
+    total_count: number;
+    repository_selection?: string;
+    repositories: GithubRepository[];
+}
+export interface GithubRepositoryRequest {
+    name: string;
+    description?: string;
+    private?: boolean;
+    auto_init?: boolean;
+}
+export interface GithubClientOptions {
+    /** `HF_GITHUB_TOKEN`. */
+    token: string;
+    url?: string;
+    fetch?: FetchLike;
+}
+export declare class GithubClient {
+    private readonly request;
+    constructor(options: GithubClientOptions);
+    /**
+     * 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.
+     */
+    getUser(username: string): Promise<GithubUser>;
+    /**
+     * 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.
+     */
+    getRepository(owner: string, repo: string): Promise<GithubRepository>;
+    /** The repository for an app whose `HF_GITHUB_OWNER` is the token's own account. */
+    createUserRepository(body: GithubRepositoryRequest): Promise<GithubRepository>;
+    /** The same, when `HF_GITHUB_OWNER` is an organization instead. */
+    createOrgRepository(org: string, body: GithubRepositoryRequest): Promise<GithubRepository>;
+    /**
+     * `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.
+     */
+    getReference(owner: string, repo: string, ref: string): Promise<GithubReference>;
+    /**
+     * 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.
+     */
+    listPullRequests(owner: string, repo: string, options?: {
+        state?: "open" | "closed" | "all";
+        per_page?: number;
+    }): Promise<GithubPullRequest[]>;
+    /**
+     * 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.
+     */
+    listInstallations(options?: {
+        per_page?: number;
+        page?: number;
+    }): Promise<GithubInstallations>;
+    /** Which repositories one installation actually reaches; the other half of that assertion. */
+    listInstallationRepositories(installationId: number, options?: {
+        per_page?: number;
+        page?: number;
+    }): Promise<GithubInstallationRepositories>;
+    getCombinedStatus(owner: string, repo: string, ref: string): Promise<GithubCombinedStatus>;
+}