@hyperfixation/cli 0.1.0 → 0.1.2

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>;
+}

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>;