@hyperfixation/cli 0.1.0 → 0.1.2

package/dist/cloud-steps/deploy.js

@@ -0,0 +1,110 @@
+import { requireOperatorConfig } from "../config.js";
+import { CoolifyClient } from "../providers/coolify.js";
+import { appFqdn, gitHead, short, StepFailed } from "./context.js";
+/**
+ * How long the step waits for Coolify to build and for the app to report the sha it built.
+ *
+ * One deadline for both halves: what the operator is waiting on is a deployed app answering with
+ * the right version, and a build that took fourteen minutes has not left time for anything else.
+ */
+export const DEPLOY_TIMEOUT_MS = 15 * 60_000;
+const FIRST_POLL_MS = 2_000;
+const MAX_POLL_MS = 15_000;
+/** Coolify's one terminal success; `failed` and `cancelled-*` are the terminal failures. */
+const FINISHED = "finished";
+/**
+ * Deploy, wait for the build, then wait for the app to say it is running that commit.
+ *
+ * Never skipped while it is not recorded, and recorded only once `/api/status` reports the pushed
+ * sha: a redeploy costs a rebuild, whereas a `deploy` marked done off the API's own "finished"
+ * would hide a container that came up on the previous image — which is exactly what a rotation
+ * needs this step to rule out.
+ */
+export const deployStep = {
+    name: "deploy",
+    run: async (context) => {
+        const { names } = context;
+        const appUuid = context.state.state.coolify?.appUuid;
+        if (appUuid === undefined) {
+            throw new StepFailed("no Coolify application uuid in the state cache: the coolify step has not run for this app");
+        }
+        const sha = await gitHead(context);
+        if (sha === undefined) {
+            throw new StepFailed(`${context.dir} has no commit to deploy: the install step has not run`);
+        }
+        const required = requireOperatorConfig(context.config, ["HF_COOLIFY_URL", "HF_COOLIFY_TOKEN"], { env: context.env });
+        const coolify = new CoolifyClient({
+            url: required.HF_COOLIFY_URL,
+            token: required.HF_COOLIFY_TOKEN,
+            fetch: context.fetch,
+        });
+        const deadline = context.now() + DEPLOY_TIMEOUT_MS;
+        const { deployments } = await coolify.deploy(appUuid, { force: true });
+        const deploymentUuid = deployments[0]?.deployment_uuid;
+        if (deploymentUuid === undefined) {
+            throw new StepFailed(`Coolify accepted the deploy of ${names.given} but named no deployment`);
+        }
+        context.io.out(`${names.given}: deployment ${deploymentUuid} queued`);
+        await waitForBuild(context, coolify, deploymentUuid, deadline);
+        await waitForVersion(context, sha, deadline);
+        await context.state.patch({ lastDeployedSha: sha });
+        context.io.out(`${names.given}: serving ${short(sha)} at https://${appFqdn(context)}`);
+    },
+};
+async function waitForBuild(context, coolify, deploymentUuid, deadline) {
+    for (let wait = FIRST_POLL_MS;; wait = Math.min(wait * 2, MAX_POLL_MS)) {
+        const deployment = await coolify.getDeployment(deploymentUuid);
+        if (deployment.status === FINISHED)
+            return;
+        if (deployment.status.startsWith("failed") || deployment.status.startsWith("cancelled")) {
+            throw new StepFailed(`Coolify deployment ${deploymentUuid} ended ${deployment.status}: read the build log in ` +
+                "Coolify, fix it, and re-run hf new");
+        }
+        if (context.now() >= deadline) {
+            throw new StepFailed(`Coolify deployment ${deploymentUuid} was still ${deployment.status} after ` +
+                `${String(DEPLOY_TIMEOUT_MS / 60_000)} minutes`);
+        }
+        await context.sleep(wait);
+    }
+}
+/**
+ * Polls `/api/status` under the read token until it reports `sha`.
+ *
+ * A refusal or an unparseable answer is not a failure here — the containers are restarting, and the
+ * old ones answer until the new ones are healthy — so only the deadline ends this loop.
+ */
+async function waitForVersion(context, sha, deadline) {
+    const url = `https://${appFqdn(context)}/api/status`;
+    const token = context.state.state.statusTokens?.read;
+    if (token === undefined) {
+        throw new StepFailed(`no read status token in the state cache: nothing can ask ${url} what it is running`);
+    }
+    const doFetch = context.fetch ?? ((input, init) => globalThis.fetch(input, init));
+    let last = "nothing yet";
+    for (let wait = FIRST_POLL_MS;; wait = Math.min(wait * 2, MAX_POLL_MS)) {
+        try {
+            const response = await doFetch(url, {
+                headers: { authorization: `Bearer ${token}`, accept: "application/json" },
+            });
+            if (!response.ok) {
+                last = `HTTP ${String(response.status)}`;
+            }
+            else {
+                const report = (await response.json());
+                const version = report.applicationVersion;
+                if (version === sha)
+                    return;
+                last = version === null ? "no applicationVersion" : `applicationVersion ${short(version)}`;
+            }
+        }
+        catch (error) {
+            last = error.message;
+        }
+        if (context.now() >= deadline) {
+            throw new StepFailed(`${url} never reported ${short(sha)} within ` +
+                `${String(DEPLOY_TIMEOUT_MS / 60_000)} minutes (last: ${last}). The build finished, so ` +
+                "check that SOURCE_COMMIT reached the image — hf doctor reports the same mismatch.");
+        }
+        await context.sleep(wait);
+    }
+}

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

@@ -0,0 +1,11 @@
+import type { Step } from "../new-cloud.js";
+import { type CloudStepContext } from "./context.js";
+/**
+ * `A <app>.<HF_BASE_DOMAIN>` → `HF_BOX_IP`, DNS-only, and exactly one of them.
+ *
+ * An existing record with the right address is the step's own previous work. One with a different
+ * address is somebody's live hostname: it is never overwritten, and a second A record is never
+ * added either — two of them would round-robin between the box and whatever that is, which looks
+ * like an intermittent outage rather than a misconfiguration.
+ */
+export declare const dnsStep: Step<CloudStepContext>;

package/dist/cloud-steps/dns.js

@@ -0,0 +1,53 @@
+import { requireOperatorConfig } from "../config.js";
+import { CloudflareClient } from "../providers/cloudflare.js";
+import { StepFailed } from "./context.js";
+/** Cloudflare's "automatic"; the record is DNS-only, so nothing caches it for long. */
+const TTL_AUTOMATIC = 1;
+/**
+ * `A <app>.<HF_BASE_DOMAIN>` → `HF_BOX_IP`, DNS-only, and exactly one of them.
+ *
+ * An existing record with the right address is the step's own previous work. One with a different
+ * address is somebody's live hostname: it is never overwritten, and a second A record is never
+ * added either — two of them would round-robin between the box and whatever that is, which looks
+ * like an intermittent outage rather than a misconfiguration.
+ */
+export const dnsStep = {
+    name: "dns",
+    run: async (context) => {
+        const { names } = context;
+        const required = requireOperatorConfig(context.config, ["HF_CLOUDFLARE_TOKEN", "HF_CLOUDFLARE_ZONE_ID", "HF_BASE_DOMAIN", "HF_BOX_IP"], { env: context.env });
+        const fqdn = `${names.given}.${required.HF_BASE_DOMAIN}`;
+        const cloudflare = new CloudflareClient({
+            token: required.HF_CLOUDFLARE_TOKEN,
+            fetch: context.fetch,
+        });
+        const listed = assertSuccess(await cloudflare.listDnsRecords(required.HF_CLOUDFLARE_ZONE_ID, { name: fqdn, type: "A" }), `list the A records for ${fqdn}`);
+        const existing = listed[0];
+        if (existing !== undefined) {
+            if (existing.content !== required.HF_BOX_IP) {
+                throw new StepFailed(`${fqdn} already has an A record pointing at ${existing.content}, not the box at ` +
+                    `${required.HF_BOX_IP}: hf new neither overwrites an A record nor adds a second one. ` +
+                    `Point it at the box, or delete it, and re-run hf new.`);
+            }
+            context.io.out(`${names.given}: ${fqdn} already points at ${required.HF_BOX_IP}`);
+            return;
+        }
+        assertSuccess(await cloudflare.createDnsRecord(required.HF_CLOUDFLARE_ZONE_ID, {
+            type: "A",
+            name: fqdn,
+            content: required.HF_BOX_IP,
+            ttl: TTL_AUTOMATIC,
+            proxied: false,
+            comment: `hf new ${names.given}`,
+        }), `create the A record for ${fqdn}`);
+        context.io.out(`${names.given}: ${fqdn} A ${required.HF_BOX_IP}, DNS-only`);
+    },
+};
+/** Cloudflare answers `success: false` with HTTP 200 on some routes, which no transport catches. */
+function assertSuccess(envelope, what) {
+    if (!envelope.success) {
+        const detail = envelope.errors.map((error) => error.message).join("; ");
+        throw new StepFailed(`cloudflare could not ${what}${detail === "" ? "" : `: ${detail}`}`);
+    }
+    return envelope.result;
+}

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

@@ -0,0 +1,21 @@
+import type { Step } from "../new-cloud.js";
+import { backupStep } from "./backup.js";
+import type { CloudStepContext } from "./context.js";
+import { coolifyStep } from "./coolify.js";
+import { databaseStep } from "./database.js";
+import { deployStep } from "./deploy.js";
+import { dnsStep } from "./dns.js";
+import { installStep } from "./install.js";
+import { langfuseStep } from "./langfuse.js";
+import { repoStep } from "./repo.js";
+import { sentryStep } from "./sentry.js";
+import { templateStep } from "./template.js";
+/**
+ * The steps of a cloud `hf new`, in `STEPS` order — which `runSteps` asserts, because that order
+ * is the rotation-safety argument rather than a preference.
+ */
+export declare const CLOUD_STEPS: readonly Step<CloudStepContext>[];
+export { backupStep, coolifyStep, databaseStep, deployStep, dnsStep, installStep, langfuseStep, repoStep, sentryStep, templateStep, };
+export { EnvDrift, neededEnvNames } from "./coolify.js";
+export { DEPLOY_TIMEOUT_MS } from "./deploy.js";
+export { appFqdn, cloudCommands, defaultTemplateFetch, spawnStepExec, StepFailed, type CloudCommands, type CloudStepContext, type StepExec, type StepExecOptions, type StepExecOutcome, type StepOut, type TemplateFetch, } from "./context.js";

package/dist/cloud-steps/index.js

@@ -0,0 +1,30 @@
+import { backupStep } from "./backup.js";
+import { coolifyStep } from "./coolify.js";
+import { databaseStep } from "./database.js";
+import { deployStep } from "./deploy.js";
+import { dnsStep } from "./dns.js";
+import { installStep } from "./install.js";
+import { langfuseStep } from "./langfuse.js";
+import { repoStep } from "./repo.js";
+import { sentryStep } from "./sentry.js";
+import { templateStep } from "./template.js";
+/**
+ * The steps of a cloud `hf new`, in `STEPS` order — which `runSteps` asserts, because that order
+ * is the rotation-safety argument rather than a preference.
+ */
+export const CLOUD_STEPS = [
+    templateStep,
+    installStep,
+    repoStep,
+    backupStep,
+    sentryStep,
+    langfuseStep,
+    dnsStep,
+    databaseStep,
+    coolifyStep,
+    deployStep,
+];
+export { backupStep, coolifyStep, databaseStep, deployStep, dnsStep, installStep, langfuseStep, repoStep, sentryStep, templateStep, };
+export { EnvDrift, neededEnvNames } from "./coolify.js";
+export { DEPLOY_TIMEOUT_MS } from "./deploy.js";
+export { appFqdn, cloudCommands, defaultTemplateFetch, spawnStepExec, StepFailed, } from "./context.js";

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

@@ -0,0 +1,12 @@
+import type { Step } from "../new-cloud.js";
+import { type CloudStepContext } from "./context.js";
+/**
+ * `pnpm install`, then the app's own first commit.
+ *
+ * Done means `git rev-parse HEAD` answers, which is also how a run with no state file detects the
+ * work of a previous one: the commit is the artefact, and a `node_modules` is not evidence of
+ * anything.
+ */
+export declare const installStep: Step<CloudStepContext>;
+/** Every file the template fetch left, relative to the app directory, `EXCLUDED_ENTRIES` aside. */
+export declare function templatedFiles(dir: string): Promise<string[]>;

package/dist/cloud-steps/install.js

@@ -0,0 +1,53 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { EXCLUDED_ENTRIES } from "../new.js";
+import { gitHead, mustRun, short } from "./context.js";
+/**
+ * `pnpm install`, then the app's own first commit.
+ *
+ * Done means `git rev-parse HEAD` answers, which is also how a run with no state file detects the
+ * work of a previous one: the commit is the artefact, and a `node_modules` is not evidence of
+ * anything.
+ */
+export const installStep = {
+    name: "install",
+    run: async (context) => {
+        const { names } = context;
+        const head = await gitHead(context);
+        if (head !== undefined) {
+            context.io.out(`${names.given}: adopting the commit already in ${context.dir} (${short(head)})`);
+            return;
+        }
+        // Listed before `pnpm install`, so the paths handed to `git add` cannot include a
+        // `node_modules` the lockfile install is about to create.
+        const files = await templatedFiles(context.dir);
+        await mustRun(context, "pnpm", ["install"]);
+        await mustRun(context, "git", ["init", "-b", "main"]);
+        // Explicit paths, never `git add -A`: the template's `.gitignore` is one of the files being
+        // added and is therefore not in force yet, and `.env` is the file that must not be committed.
+        await mustRun(context, "git", ["add", "--", ...files]);
+        await mustRun(context, "git", [
+            "commit",
+            "-m",
+            `Create ${names.given} from hyperfixation-template`,
+        ]);
+        context.io.out(`${names.given}: ${String(files.length)} file(s) in the initial commit`);
+    },
+};
+/** Every file the template fetch left, relative to the app directory, `EXCLUDED_ENTRIES` aside. */
+export async function templatedFiles(dir) {
+    const found = [];
+    const walk = async (current) => {
+        for (const entry of await readdir(current, { withFileTypes: true })) {
+            if (EXCLUDED_ENTRIES.includes(entry.name))
+                continue;
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory())
+                await walk(full);
+            else if (entry.isFile())
+                found.push(path.relative(dir, full));
+        }
+    };
+    await walk(dir);
+    return found.sort();
+}

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

@@ -0,0 +1,17 @@
+import type { Step } from "../new-cloud.js";
+import type { CloudStepContext } from "./context.js";
+/**
+ * The app's Langfuse project and a key pair for it.
+ *
+ * The project is found by name, so a cold run reuses the one it made before rather than filling
+ * the organization with duplicates. The key pair is **not** reused: Langfuse returns a secret key
+ * once, at creation, and the only copy is the state file this run may not have — so a new key is
+ * created and the old ones keep working, which costs an unused key and never an app that cannot
+ * authenticate.
+ *
+ * Creating a project needs an organization-scoped key, which is a paid-plan feature: without one
+ * the step falls back to the project key pair the operator configured, and without that to a
+ * warning. Both fallbacks record the step — an app with no tracing is a deployed app, and only
+ * the operator can decide otherwise.
+ */
+export declare const langfuseStep: Step<CloudStepContext>;

package/dist/cloud-steps/langfuse.js

@@ -0,0 +1,71 @@
+import { requireOperatorConfig } from "../config.js";
+import { LangfuseClient } from "../providers/langfuse.js";
+/** Langfuse keeps data indefinitely at 0, and any other value needs a paid entitlement. */
+const RETENTION_DAYS = 0;
+/** Said in the warning and again in the closing checklist, so neither run nor log has to be read. */
+const NOT_CONFIGURED = "Langfuse tracing is not configured: neither HF_LANGFUSE_ORG_KEY nor an " +
+    "HF_LANGFUSE_PUBLIC_KEY/HF_LANGFUSE_SECRET_KEY pair is set, so LANGFUSE_BASE_URL, " +
+    "LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY were not sent to Coolify and the app records no " +
+    "traces. To add them later, take a project's key pair from Langfuse → project settings → API " +
+    "keys, set all three in Coolify's environment for this application, and redeploy.";
+/**
+ * The app's Langfuse project and a key pair for it.
+ *
+ * The project is found by name, so a cold run reuses the one it made before rather than filling
+ * the organization with duplicates. The key pair is **not** reused: Langfuse returns a secret key
+ * once, at creation, and the only copy is the state file this run may not have — so a new key is
+ * created and the old ones keep working, which costs an unused key and never an app that cannot
+ * authenticate.
+ *
+ * Creating a project needs an organization-scoped key, which is a paid-plan feature: without one
+ * the step falls back to the project key pair the operator configured, and without that to a
+ * warning. Both fallbacks record the step — an app with no tracing is a deployed app, and only
+ * the operator can decide otherwise.
+ */
+export const langfuseStep = {
+    name: "langfuse",
+    run: async (context) => {
+        const { names } = context;
+        if ((context.config.HF_LANGFUSE_ORG_KEY ?? "") === "") {
+            await reuseOrSkip(context);
+            return;
+        }
+        const required = requireOperatorConfig(context.config, ["HF_LANGFUSE_URL", "HF_LANGFUSE_ORG_KEY"], { env: context.env });
+        const langfuse = new LangfuseClient({
+            url: required.HF_LANGFUSE_URL,
+            orgKey: required.HF_LANGFUSE_ORG_KEY,
+            fetch: context.fetch,
+        });
+        const { data } = await langfuse.listProjects();
+        const existing = data.find((project) => project.name === names.appName);
+        const projectId = existing?.id ??
+            (await langfuse.createProject({ name: names.appName, retention: RETENTION_DAYS })).id;
+        context.io.out(`${names.given}: ${existing === undefined ? "created" : "adopting"} the Langfuse project ` +
+            names.appName);
+        const key = await langfuse.createApiKey(projectId, { note: `hf new ${names.given}` });
+        await context.state.patch({
+            langfuse: { publicKey: key.publicKey, secretKey: key.secretKey },
+        });
+    },
+};
+/**
+ * The two paths without an org key: the operator's own project key pair, or nothing.
+ *
+ * No request either way — a project-scoped pair cannot list or create projects, so there is
+ * nothing to ask Langfuse that would not fail.
+ */
+async function reuseOrSkip(context) {
+    const { names, config } = context;
+    const publicKey = config.HF_LANGFUSE_PUBLIC_KEY ?? "";
+    const secretKey = config.HF_LANGFUSE_SECRET_KEY ?? "";
+    if (publicKey === "" || secretKey === "") {
+        context.io.out(`WARNING: ${names.given}: ${NOT_CONFIGURED}`);
+        context.checklist.push(NOT_CONFIGURED);
+        return;
+    }
+    // The public key names the project without being a secret, which is the only identifier this
+    // path has: nothing here may ask Langfuse what the project is called.
+    context.io.out(`${names.given}: reusing the configured Langfuse project keys (${publicKey}) — every app ` +
+        "configured with them traces into that one project");
+    await context.state.patch({ langfuse: { publicKey, secretKey } });
+}

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

@@ -0,0 +1,20 @@
+import type { Step } from "../new-cloud.js";
+import { type CloudStepContext } from "./context.js";
+/**
+ * The token reaches `git` through the child's environment alone.
+ *
+ * Not in argv, where `ps` reads it; not in the remote URL, which `git remote add` writes into
+ * `.git/config` and every later `git push` from the operator's shell would then use; and not in
+ * anything a step prints. `GIT_CONFIG_COUNT` is how git takes configuration from the environment
+ * without a file, so the header outlives neither the child nor this step.
+ */
+export declare function gitAuthEnv(token: string): Record<string, string>;
+/**
+ * The app's private GitHub repository, its first push, and both GitHub Apps on it.
+ *
+ * The cold-run question is not "is there a repository called this" but "is there a repository
+ * holding *this* app": a name someone else took answers 200 just as well, so an existing one is
+ * adopted only when its `main` is the commit the install step made. Anything else is refused with
+ * the name in the message — pushing over it is not recoverable.
+ */
+export declare const repoStep: Step<CloudStepContext>;

package/dist/cloud-steps/repo.js

@@ -0,0 +1,198 @@
+import { githubAppSlugs, requireOperatorConfig } from "../config.js";
+import { GithubClient } from "../providers/github.js";
+import { ProviderError } from "../providers/http.js";
+import { gitHead, mustRun, short, StepFailed } from "./context.js";
+/** One page of installations, and of an installation's repositories. */
+const PER_PAGE = 100;
+/**
+ * What GitHub answers a token that may not list installations.
+ *
+ * `GET /user/installations` is documented as a GitHub App user-to-server endpoint, so every
+ * classic PAT, fine-grained PAT and OAuth token — which is what `HF_GITHUB_TOKEN` is — is refused:
+ * 403 for a `gh` OAuth token, and 401/404 for the other ways a token can be told no.
+ */
+const CANNOT_LIST = new Set([401, 403, 404]);
+/**
+ * The token reaches `git` through the child's environment alone.
+ *
+ * Not in argv, where `ps` reads it; not in the remote URL, which `git remote add` writes into
+ * `.git/config` and every later `git push` from the operator's shell would then use; and not in
+ * anything a step prints. `GIT_CONFIG_COUNT` is how git takes configuration from the environment
+ * without a file, so the header outlives neither the child nor this step.
+ */
+export function gitAuthEnv(token) {
+    return {
+        GIT_CONFIG_COUNT: "1",
+        GIT_CONFIG_KEY_0: "http.extraHeader",
+        // GitHub's documented form for a token over HTTPS git; `Bearer` is the API's, not git's.
+        GIT_CONFIG_VALUE_0: "Authorization: Basic " + Buffer.from(`x-access-token:${token}`, "utf8").toString("base64"),
+    };
+}
+/**
+ * The app's private GitHub repository, its first push, and both GitHub Apps on it.
+ *
+ * The cold-run question is not "is there a repository called this" but "is there a repository
+ * holding *this* app": a name someone else took answers 200 just as well, so an existing one is
+ * adopted only when its `main` is the commit the install step made. Anything else is refused with
+ * the name in the message — pushing over it is not recoverable.
+ */
+export const repoStep = {
+    name: "repo",
+    run: async (context) => {
+        const { names } = context;
+        const required = requireOperatorConfig(context.config, ["HF_GITHUB_TOKEN", "HF_GITHUB_OWNER", "HF_GITHUB_APP_SLUGS"], { env: context.env });
+        const owner = required.HF_GITHUB_OWNER;
+        const repo = names.given;
+        const fullName = `${owner}/${repo}`;
+        const head = await gitHead(context);
+        if (head === undefined) {
+            throw new StepFailed(`${context.dir} has no commit to push: the install step has not run`);
+        }
+        const github = new GithubClient({ token: required.HF_GITHUB_TOKEN, fetch: context.fetch });
+        const existing = await getRepository(github, owner, repo);
+        let pushNeeded = true;
+        if (existing === undefined) {
+            const user = await github.getUser(owner);
+            const body = { name: repo, private: true };
+            if (user.type === "Organization")
+                await github.createOrgRepository(owner, body);
+            else
+                await github.createUserRepository(body);
+            context.io.out(`${names.given}: created the private repository ${fullName}`);
+        }
+        else {
+            const sha = await mainSha(github, owner, repo);
+            if (sha === head) {
+                pushNeeded = false;
+                context.io.out(`${names.given}: adopting ${fullName}, whose main is ${short(head)}`);
+            }
+            else if (sha === undefined) {
+                context.io.out(`${names.given}: ${fullName} exists and is empty; pushing`);
+            }
+            else {
+                throw new StepFailed(`${fullName} already exists and its main is ${short(sha)}, not this app's ` +
+                    `${short(head)}: hf new will not push over a repository it did not create. Rename ` +
+                    `it, or give the app another name.`);
+            }
+        }
+        // `set-url` rather than `add`, because a rerun finds the remote its predecessor added; the
+        // URL carries no credentials, so rewriting it is safe to repeat.
+        const url = `https://github.com/${owner}/${repo}.git`;
+        const remote = await context.exec("git", ["remote", "get-url", "origin"], {
+            cwd: context.dir,
+            capture: true,
+        });
+        await mustRun(context, "git", [
+            "remote",
+            remote.code === 0 ? "set-url" : "add",
+            "origin",
+            url,
+        ]);
+        if (pushNeeded) {
+            await mustRun(context, "git", ["push", "--set-upstream", "origin", "main"], {
+                env: gitAuthEnv(required.HF_GITHUB_TOKEN),
+            });
+        }
+        await checkAppsInstalled(context, github, githubAppSlugs(context.config), fullName);
+        await context.state.patch({ repo: fullName });
+    },
+};
+/**
+ * Every `HF_GITHUB_APP_SLUGS` entry installed on the repository, or which one is not.
+ *
+ * Coolify cannot deploy from a repository its GitHub App cannot see, and that failure otherwise
+ * surfaces as a deployment that clones nothing — so it is asserted here, by name, with the URL
+ * that fixes it.
+ *
+ * Unless the token may not ask at all, which is the usual case: then this degrades to a warning
+ * and a checklist line, because the repository has already been created and pushed and there is no
+ * second way to read a personal account's installations (organizations have
+ * `GET /orgs/{org}/installations`; personal accounts have nothing).
+ */
+async function checkAppsInstalled(context, github, slugs, fullName) {
+    let installations;
+    try {
+        installations = await allInstallations(github);
+    }
+    catch (error) {
+        if (!(error instanceof ProviderError) || !CANNOT_LIST.has(error.status))
+            throw error;
+        const note = unverifiedNote(slugs, fullName, error.status);
+        context.io.out(`WARNING: ${context.names.given}: ${note}`);
+        context.checklist.push(note);
+        return;
+    }
+    for (const slug of slugs) {
+        const installation = installations.find((candidate) => candidate.app_slug === slug);
+        if (installation === undefined) {
+            throw new StepFailed(`the GitHub App ${slug} is not installed for this token: install it on ${fullName} at ` +
+                `https://github.com/apps/${slug}/installations/new and re-run hf new`);
+        }
+        if (!(await installationReaches(github, installation.id, fullName))) {
+            throw new StepFailed(`the GitHub App ${slug} is installed but does not reach ${fullName}: add the repository ` +
+                `to it at https://github.com/apps/${slug}/installations/new and re-run hf new`);
+        }
+    }
+}
+/** The one thing left to the operator when the installations could not be listed. */
+function unverifiedNote(slugs, fullName, status) {
+    const apps = slugs
+        .map((slug) => `${slug} (https://github.com/apps/${slug}/installations/new)`)
+        .join(", ");
+    return (`the GitHub App installations on ${fullName} could not be verified with this token — ` +
+        `listing them needs a GitHub App user-to-server token and GitHub answered HTTP ` +
+        `${String(status)}. Check by hand that each of these is installed on the repository, or on ` +
+        `All repositories: ${apps}. Coolify's first deploy clones an empty repository if its app ` +
+        `cannot see this one.`);
+}
+async function allInstallations(github) {
+    const found = [];
+    for (let page = 1;; page += 1) {
+        const { total_count, installations } = await github.listInstallations({
+            per_page: PER_PAGE,
+            page,
+        });
+        found.push(...installations);
+        if (installations.length === 0 || found.length >= total_count)
+            return found;
+    }
+}
+async function installationReaches(github, installationId, fullName) {
+    for (let page = 1, seen = 0;; page += 1) {
+        const listed = await github.listInstallationRepositories(installationId, {
+            per_page: PER_PAGE,
+            page,
+        });
+        // `all` is an installation with no repository selection to check: everything the account has,
+        // now and later, which the paged list can only under-report.
+        if (listed.repository_selection === "all")
+            return true;
+        if (listed.repositories.some((candidate) => candidate.full_name === fullName))
+            return true;
+        seen += listed.repositories.length;
+        if (listed.repositories.length === 0 || seen >= listed.total_count)
+            return false;
+    }
+}
+/** The repository, or `undefined` for the 404 that covers both absent and invisible. */
+async function getRepository(github, owner, repo) {
+    try {
+        return await github.getRepository(owner, repo);
+    }
+    catch (error) {
+        if (error instanceof ProviderError && error.status === 404)
+            return undefined;
+        throw error;
+    }
+}
+/** `main`'s sha, or `undefined` for the 409 GitHub answers about a repository with no commits. */
+async function mainSha(github, owner, repo) {
+    try {
+        return (await github.getReference(owner, repo, "heads/main")).object.sha;
+    }
+    catch (error) {
+        if (error instanceof ProviderError && error.status === 409)
+            return undefined;
+        throw error;
+    }
+}

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

@@ -0,0 +1,13 @@
+import type { Step } from "../new-cloud.js";
+import { type CloudStepContext } 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 declare const sentryStep: Step<CloudStepContext>;