@wtfalch/foundry 0.42.1 → 0.43.0

package/dist/plan/blue-green-apply.js

@@ -0,0 +1,360 @@
+import { randomBytes } from 'node:crypto';
+import { COLORS, LB_CONFIG_PATH, bgKey, colorAppName, colorBackend, formatWeights, lbAppName, lbDockerfile, parseWeights, renderLbConfig, reportingEnv, stageAppName, structureHash, } from './blue-green.js';
+import { recordBuiltCommit } from './build-record.js';
+import { ensureConnectorsOnServers } from './cloudflared-connector.js';
+import { waitForNewDeployment } from './deploy-health.js';
+import { ENTRY_CONTAINER_LABELS } from './proxy-labels.js';
+import { remoteDatabaseAddress, remoteDatabaseHost } from './remote-database.js';
+/** Env names whose value is a credential: registered before they are copied. */
+const SECRETISH = /(KEY|SECRET|TOKEN|PASSWORD|DATABASE_URL)/;
+/** The env names that name the database. */
+const DATABASE_ENV = new Set(['DATABASE_URL', 'DATABASE_URL_OWNER']);
+/** Replaces the host in a connection URL; `null` when it is not one. Never throws a value. */
+export function withDatabaseHost(url, host) {
+    const match = /^([a-z][a-z0-9+.-]*:\/\/[^@/?#]*@)([^/?#]*)(.*)$/i.exec(url);
+    return match ? `${match[1]}${host}${match[3]}` : null;
+}
+/** `postgres://user:password@host/db` for a stage runtime role: the password is minted by the caller. */
+export function runtimeDatabaseUrl(ownerUrl, role, password) {
+    const match = /^([a-z][a-z0-9+.-]*:\/\/)[^:@/]*:[^@/]*@(.*)$/i.exec(ownerUrl);
+    return match ? `${match[1]}${role}:${password}@${match[2]}` : null;
+}
+const noDeploy = { kind: 'deployment-only' };
+/**
+ * Applies one server's blue/green structure for `subject`: green (and blue, off the primary) beside the
+ * primary's blue, the balancer with the recorded weights, and on the primary the stage app. Every color
+ * gets the primary blue's env (the database host rewritten off the primary) and its three reporting
+ * values. A failure halfway leaves the apps already made, recorded by id; the next run finds them and
+ * does the rest. Nothing is recorded as applied until every part is done.
+ */
+export async function applyBlueGreenServer(deps, subject, server) {
+    const { coolify } = deps;
+    const id = subject.id;
+    const isPrimary = server.uuid === server.primaryUuid;
+    const weights = parseWeights(deps.recorded()[bgKey.weights(id)]);
+    if (!weights)
+        throw new Error(`${deps.label}: the recorded weights are not valid`);
+    const ids = {};
+    if (isPrimary)
+        ids.blue = deps.primaryBlueAppId;
+    const sourceEnv = await coolify.listEnvs(deps.primaryBlueAppId);
+    const token = await deps.healthToken();
+    for (const color of COLORS) {
+        const name = isPrimary && color === 'blue' ? subject.primaryBlueName : colorAppName(subject.base, color);
+        if (!ids[color]) {
+            ids[color] = await ensureGitApp(deps, subject, {
+                key: bgKey.app(id, server.uuid, color),
+                name,
+                server: server.uuid,
+                branch: subject.branch,
+                autoDeploy: false,
+            });
+        }
+        const appId = ids[color];
+        const copied = isPrimary && color === 'blue' ? [] : copiedEnv(deps, subject, sourceEnv, server);
+        const release = deps.recorded()[bgKey.digest(id, color)];
+        const reporting = reportingEnv({ color, release, healthToken: token });
+        // A running color reads its reporting env at start: when it changed, the color restarts before the
+        // tunnel can move to it.
+        const reportingChanged = await reportingEnvDiffers(deps, appId, reporting);
+        await upsertEnv(deps, appId, [...copied, ...reporting]);
+        await ensureDeployed(deps, appId, name, reportingChanged);
+    }
+    const lbName = lbAppName(subject.base);
+    const lbId = await ensureLoadBalancer(deps, subject, server.uuid, lbName, isPrimary);
+    await writeLbConfig(deps, subject, { uuid: server.uuid, isPrimary }, lbId, weights);
+    if (isPrimary)
+        await ensureStage(deps, subject, server.uuid);
+    deps.record(bgKey.applied(id, server.uuid), structureHash(subject, { primary: isPrimary }));
+    await deps.persist();
+}
+/** Writes the balancer's config with the recorded weights and records them for this server. */
+export async function applyBlueGreenWeights(deps, subject, server) {
+    const weights = parseWeights(deps.recorded()[bgKey.weights(subject.id)]);
+    if (!weights)
+        throw new Error(`${deps.label}: the recorded weights are not valid`);
+    const lbId = deps.recorded()[bgKey.app(subject.id, server.uuid, 'lb')];
+    if (!lbId)
+        throw new Error(`${deps.label}: the load balancer on this server is not recorded`);
+    await writeLbConfig(deps, subject, { uuid: server.uuid, isPrimary: server.uuid === server.primaryUuid }, lbId, weights);
+}
+async function writeLbConfig(deps, subject, server, lbId, weights) {
+    const onPrimary = server.isPrimary;
+    let pinKey = deps.recorded()[bgKey.pinKey(subject.id)];
+    if (!pinKey) {
+        pinKey = randomBytes(32).toString('hex');
+        deps.record(bgKey.pinKey(subject.id), pinKey);
+        await deps.persist();
+    }
+    const content = renderLbConfig({
+        weights,
+        pinKey,
+        backends: {
+            blue: [colorBackend(subject, 'blue', onPrimary)],
+            green: [colorBackend(subject, 'green', onPrimary)],
+        },
+    });
+    const storages = await deps.coolify.listStorages(lbId);
+    const found = storages.file_storages?.find((s) => s.mount_path === LB_CONFIG_PATH);
+    if (found)
+        await deps.coolify.updateFileStorage(lbId, found.uuid, content);
+    else
+        await deps.coolify.createFileStorage(lbId, { mount_path: LB_CONFIG_PATH, content });
+    deps.record(bgKey.lb(subject.id, server.uuid), formatWeights(weights));
+    await deps.persist();
+}
+/** The primary blue's env for another color: the database host swapped when the server is not the primary. */
+function copiedEnv(deps, subject, source, server) {
+    const sidecar = server.uuid === server.primaryUuid
+        ? null
+        : remoteDatabaseHost(subject.base, server.uuid, server.primaryUuid);
+    const dbHost = sidecar ? remoteDatabaseAddress(sidecar) : null;
+    const out = [];
+    for (const env of source) {
+        if (env.is_preview || env.value === undefined || env.key.startsWith('REPORTING_'))
+            continue;
+        let value = env.value;
+        if (dbHost && DATABASE_ENV.has(env.key)) {
+            const swapped = withDatabaseHost(value, dbHost);
+            if (swapped === null) {
+                throw new Error(`${deps.label}: ${env.key} is not a connection URL, so its host was not changed`);
+            }
+            value = swapped;
+        }
+        if (SECRETISH.test(env.key))
+            deps.secret(value);
+        out.push({ key: env.key, value });
+    }
+    return out;
+}
+/** Whether the app's env holds a different value for any of the reporting names. */
+async function reportingEnvDiffers(deps, appId, wanted) {
+    const have = await deps.coolify.listEnvs(appId);
+    return wanted.some((w) => have.find((e) => e.key === w.key && !e.is_preview)?.value !== w.value);
+}
+async function upsertEnv(deps, appId, envs) {
+    try {
+        await deps.coolify.bulkUpsertEnvs(appId, envs.map((e) => ({ ...e, literal: true })));
+    }
+    catch {
+        // A Coolify error can echo the request body, which holds credentials.
+        throw new Error(`${deps.label}: writing env to app ${appId} failed`);
+    }
+}
+/** The git app for one color or the stage: recorded id first, then by name, then created. */
+async function ensureGitApp(deps, subject, input) {
+    const { coolify } = deps;
+    const isStatic = subject.buildPack === 'static';
+    const settings = {
+        ports_exposes: String(subject.port),
+        git_branch: input.branch,
+        is_preview_deployments_enabled: false,
+        ...(subject.folder === null ? {} : { base_directory: `/${subject.folder}` }),
+    };
+    const recorded = deps.recorded()[input.key];
+    if (recorded) {
+        try {
+            await coolify.getApplication(recorded);
+            await coolify.updateApplication(recorded, settings);
+            return recorded;
+        }
+        catch (error) {
+            if (!isNotFound(error))
+                throw error;
+        }
+    }
+    const found = await coolify.findApplicationByName(input.name, {
+        environmentIds: [deps.environment.id],
+    });
+    if (found) {
+        await coolify.updateApplication(found.uuid, settings);
+        deps.record(input.key, found.uuid);
+        await deps.persist();
+        return found.uuid;
+    }
+    const githubApp = await coolify.requireGithubApp();
+    const created = await coolify.createGithubAppApplication({
+        is_preview_deployments_enabled: false,
+        project_uuid: deps.projectUuid,
+        server_uuid: input.server,
+        environment_name: deps.environment.name,
+        environment_uuid: deps.environment.uuid,
+        github_app_uuid: githubApp.uuid,
+        git_repository: subject.repo,
+        git_branch: input.branch,
+        build_pack: subject.buildPack,
+        name: input.name,
+        autogenerate_domain: false,
+        ports_exposes: isStatic ? '80' : String(subject.port),
+        is_auto_deploy_enabled: input.autoDeploy,
+        base_directory: subject.folder === null ? undefined : `/${subject.folder}`,
+    });
+    // Recorded before anything else is written, so a later failure never leaves an app nothing points at.
+    deps.record(input.key, created.uuid);
+    await deps.persist();
+    await coolify.updateApplication(created.uuid, {
+        custom_internal_name: input.name,
+        custom_labels: Buffer.from(ENTRY_CONTAINER_LABELS).toString('base64'),
+        health_check_enabled: true,
+        health_check_path: subject.healthPath,
+        health_check_port: String(subject.port),
+    });
+    await mountLogVolume(deps, created.uuid, input.name);
+    return created.uuid;
+}
+async function mountLogVolume(deps, appId, name) {
+    const storages = await deps.coolify.listStorages(appId);
+    if ((storages.persistent_storages ?? []).some((s) => s.mount_path === deps.logDir))
+        return;
+    await deps.coolify.createPersistentStorage(appId, {
+        name: `${name}-logs`,
+        mount_path: deps.logDir,
+    });
+}
+/** Deploys a color that is new or not running, and waits for Coolify's deployment to finish. */
+async function ensureDeployed(deps, appId, name, redeploy = false) {
+    const live = await deps.coolify.getApplication(appId);
+    if (!redeploy && live.status !== undefined && deps.isRunning(live.status))
+        return null;
+    return waitForNewDeployment(deps.coolify, appId, noDeploy, deps.runtime, deps.sleep, `${deps.label} ${name}`, `${name} stays as it was`);
+}
+async function ensureLoadBalancer(deps, subject, serverUuid, name, isPrimary) {
+    const { coolify } = deps;
+    const key = bgKey.app(subject.id, serverUuid, 'lb');
+    let lbId = deps.recorded()[key];
+    if (lbId) {
+        try {
+            await coolify.getApplication(lbId);
+        }
+        catch (error) {
+            if (!isNotFound(error))
+                throw error;
+            lbId = undefined;
+        }
+    }
+    if (!lbId) {
+        const found = await coolify.findApplicationByName(name, {
+            environmentIds: [deps.environment.id],
+        });
+        lbId = found?.uuid;
+    }
+    let created = false;
+    if (!lbId) {
+        const made = await coolify.createDockerfileApplication({
+            project_uuid: deps.projectUuid,
+            server_uuid: serverUuid,
+            environment_name: deps.environment.name,
+            environment_uuid: deps.environment.uuid,
+            dockerfile: lbDockerfile(subject.port),
+            name,
+            description: `load balancer for ${subject.base}`,
+            instant_deploy: false,
+            autogenerate_domain: false,
+        });
+        lbId = made.uuid;
+        created = true;
+    }
+    deps.record(key, lbId);
+    await deps.persist();
+    if (created) {
+        await coolify.updateApplication(lbId, {
+            custom_internal_name: name,
+            custom_labels: Buffer.from(ENTRY_CONTAINER_LABELS).toString('base64'),
+            ports_exposes: String(subject.port),
+            // The Dockerfile's own HEALTHCHECK, as the cloudflared connector does.
+            health_check_enabled: false,
+        });
+        // The config is mounted before the first start, so Traefik never starts without a file.
+        await writeLbConfig(deps, subject, { uuid: serverUuid, isPrimary }, lbId, parseWeights(deps.recorded()[bgKey.weights(subject.id)]));
+    }
+    const live = await coolify.getApplication(lbId);
+    if (created || live.status === undefined || !deps.isRunning(live.status)) {
+        await waitForNewDeployment(coolify, lbId, noDeploy, deps.runtime, deps.sleep, `${deps.label} ${name}`, `${name} stays as it was`);
+    }
+    return lbId;
+}
+/** The stage app and its own empty database, on the primary. Holds no env from the live app. */
+async function ensureStage(deps, subject, serverUuid) {
+    const { coolify } = deps;
+    const name = stageAppName(subject.base);
+    const appId = await stageAppId(deps, subject, name, serverUuid);
+    const envs = [{ key: 'LOG_DIR', value: deps.logDir }];
+    if (subject.database) {
+        const dbName = `${subject.base}-stage-db`;
+        const pgName = dbName.replace(/-/g, '_');
+        let dbId = deps.recorded()[bgKey.stageDatabase(subject.id)];
+        if (!dbId) {
+            const existing = (await coolify.listDatabases()).find((d) => d.name === dbName && d.environment_id === deps.environment.id);
+            dbId =
+                existing?.uuid ??
+                    (await coolify.createPostgresDatabase({
+                        project_uuid: deps.projectUuid,
+                        server_uuid: serverUuid,
+                        environment_name: deps.environment.name,
+                        environment_uuid: deps.environment.uuid,
+                        name: dbName,
+                        postgres_db: pgName,
+                        postgres_user: pgName,
+                    })).uuid;
+            deps.record(bgKey.stageDatabase(subject.id), dbId);
+            await deps.persist();
+        }
+        const db = await coolify.getDatabase(dbId);
+        if (db.internal_db_url) {
+            deps.secret(db.internal_db_url);
+            envs.push({ key: 'DATABASE_URL_OWNER', value: db.internal_db_url });
+            const have = (await coolify.listEnvs(appId)).find((e) => e.key === 'DATABASE_URL' && !e.is_preview);
+            if (!have) {
+                const password = randomBytes(24).toString('base64url');
+                deps.secret(password);
+                const runtime = runtimeDatabaseUrl(db.internal_db_url, `${pgName}_rt`, password);
+                if (runtime) {
+                    deps.secret(runtime);
+                    envs.push({ key: 'DATABASE_URL', value: runtime });
+                }
+            }
+        }
+    }
+    // Stage never holds the live app's keys or secrets: its env is the log directory and its own database.
+    await upsertEnv(deps, appId, envs);
+    const live = await coolify.getApplication(appId);
+    if (live.status === undefined || !deps.isRunning(live.status)) {
+        const built = await waitForNewDeployment(coolify, appId, noDeploy, deps.runtime, deps.sleep, `${deps.label} ${name}`, `${name} stays as it was`);
+        await recordBuiltCommit(coolify, { appId, deploymentUuid: built.deploymentUuid, name: subject.id }, (key, value) => {
+            if (key.startsWith('built_commit_'))
+                deps.record(bgKey.stage(subject.id), value);
+        });
+    }
+}
+async function stageAppId(deps, subject, name, serverUuid) {
+    return ensureGitApp(deps, subject, {
+        key: bgKey.app(subject.id, serverUuid, 'stage'),
+        name,
+        server: serverUuid,
+        branch: subject.branch,
+        autoDeploy: true,
+    });
+}
+function isNotFound(error) {
+    const status = error?.status;
+    return status === 404;
+}
+/** A connector for the org's tunnel on each given server; the primary's is the existing one. */
+export async function applyBlueGreenConnectors(input) {
+    await ensureConnectorsOnServers({
+        coolify: input.coolify,
+        tunnels: input.tunnels,
+        tunnelId: input.tunnelId,
+        baseAppName: input.baseAppName,
+        baseScopeKey: input.baseScopeKey,
+        primaryUuid: input.primaryUuid,
+        serverUuids: input.serverUuids,
+        projectUuid: input.projectUuid,
+        environment: input.environment,
+        recorded: input.recorded(),
+        record: async (key, appId) => {
+            input.record(key, appId);
+            await input.persist();
+        },
+    });
+}

package/dist/plan/blue-green.d.ts

@@ -0,0 +1,223 @@
+import type { BlueGreenConfig, DeclaredOrg, HostingEntry } from '../org.js';
+/**
+ * Blue/green releases (docs/adr/0001-blue-green-releases.md). A color is a property any app can have
+ * ({@link Colored}), not something only a hosting entry has: platform-archon uses the same code path
+ * ({@link BlueGreenSubject}).
+ */
+export type Color = 'blue' | 'green';
+export declare const COLORS: readonly Color[];
+/** Anything that runs as one color. */
+export interface Colored {
+    color: Color;
+}
+/** The name of `base`'s copy in `color`: `<base>-blue`. */
+export declare function colorAppName(base: string, color: Color): string;
+export declare const lbAppName: (base: string) => string;
+export declare const stageAppName: (base: string) => string;
+/** The color a name carries, or `null`. */
+export declare function colorOfName(name: string): Color | null;
+export type Weights = Record<Color, number>;
+/** Live blue until a release moves it. */
+export declare const DEFAULT_WEIGHTS = "blue:100,green:0";
+/** `blue:95,green:5`. Whole percentages that sum to 100, so a typo cannot send traffic nowhere. */
+export declare function parseWeights(raw: string | undefined): Weights | null;
+export declare const formatWeights: (w: Weights) => string;
+/** The scope keys of a blue/green subject (contract C3). `.` separated, no `:`. */
+export declare const bgKey: {
+    live: (id: string) => string;
+    digest: (id: string, color: Color) => string;
+    weights: (id: string) => string;
+    stage: (id: string) => string;
+    window: (id: string) => string;
+    held: (id: string, digest: string) => string;
+    /** The weights the load balancer on `server` was last written with. */
+    lb: (id: string, server: string) => string;
+    /** The hash of the structure (apps, balancer, stage) last applied on `server`. */
+    applied: (id: string, server: string) => string;
+    /** The Coolify app of one part (`blue`, `green`, `lb`, `stage`) on `server`. */
+    app: (id: string, server: string, part: string) => string;
+    /** The cloudflared connector app of the tunnel on a non-primary `server`. */
+    connector: (id: string, server: string) => string;
+    stageDatabase: (id: string) => string;
+    /** The Coolify name of the blue app on the primary: the adopted single app's name, or `<base>-blue`. */
+    blueName: (id: string) => string;
+    /** The pin key of the balancer's header routers. Not a credential: it only pins a color. */
+    pinKey: (id: string) => string;
+};
+/** The three env names the reporting health read uses (contract C1). */
+export declare const REPORTING_ENV: {
+    readonly color: "REPORTING_COLOR";
+    readonly release: "REPORTING_RELEASE";
+    readonly healthToken: "REPORTING_HEALTH_TOKEN";
+};
+/** The held-key name of an entry's health token (`sharedSecretRef(org.id, name)`): one mint per entry. */
+export declare const healthTokenName: (id: string) => string;
+/** What a color's container gets for the reporting health read. The release is left out until a digest is known. */
+export declare function reportingEnv(input: {
+    color: Color;
+    release: string | undefined;
+    healthToken: string;
+}): Array<{
+    key: string;
+    value: string;
+}>;
+/**
+ * Everything the blue/green code needs to know about the app it runs. A hosting entry makes one
+ * ({@link entrySubject}); platform-archon makes one with {@link archonSubject} in `platform-providers.ts`.
+ */
+export interface BlueGreenSubject {
+    /** The scope-key id: the entry key, or `platform-archon`. No `:` or `.`. */
+    id: string;
+    /** The base name: colors are `<base>-blue`, the balancer `<base>-lb`. */
+    base: string;
+    /** The Coolify name of the blue copy on the primary server. Entries: `<base>-blue`. */
+    primaryBlueName: string;
+    port: number;
+    repo: string;
+    folder: string | null;
+    branch: string;
+    buildPack: string;
+    healthPath: string;
+    /** Whether the app has a database (its URLs are copied to the other colors). */
+    database: boolean;
+    /** The hostnames the tunnel routes to the balancer. */
+    hostnames: string[];
+    config: BlueGreenConfig;
+}
+/**
+ * A hosting entry that declares `blueGreen`, as a subject; `null` when it does not or cannot run.
+ * `recorded` names the blue app: an app that ran before blue/green keeps its own name (see {@link liveAppNameFor}).
+ */
+export declare function entrySubject(org: DeclaredOrg, entry: HostingEntry, recorded?: Readonly<Record<string, string>>): BlueGreenSubject | null;
+/**
+ * The Coolify name of the entry's app on the primary. A blue/green entry's app is its blue copy: the recorded
+ * name; else the entry's own name when its app is already recorded (it ran before blue/green and is adopted as
+ * blue, never renamed); else `<base>-blue` for an entry with no app yet.
+ */
+export declare function liveAppNameFor(org: DeclaredOrg, entry: HostingEntry, recorded?: Readonly<Record<string, string>>): string;
+/** Whether the balancer on the primary is written and the structure applied: the tunnel may move to it. */
+export declare function balancerApplied(id: string, recorded: Readonly<Record<string, string>>, primaryUuid: string | undefined): boolean;
+/** The origin the tunnel routes a subject's names to: its balancer, reached on each server's own network. */
+export declare function lbOrigin(subject: Pick<BlueGreenSubject, 'base' | 'port'>): string;
+export interface BlueGreenServer {
+    uuid: string;
+    usable: boolean;
+    reachable: boolean;
+}
+/** Usable and reachable servers in the order Coolify lists them, and the uuids of the rest. */
+export declare function splitServers(all: readonly BlueGreenServer[]): {
+    up: string[];
+    down: string[];
+};
+/** The scope key of the org's primary server (`COOLIFY_SERVER_SCOPE_KEY` in `executor.ts`). */
+export declare const PRIMARY_SERVER_SCOPE_KEY = "coolify_server";
+/** The sticky cookie that keeps a user on one color. */
+export declare const LB_COOKIE_NAME = "bg_color";
+/** A request with this header goes to the named color whatever the weights; the release runner checks a color with it. */
+export declare const LB_COLOR_HEADER = "X-Foundry-Color";
+/** A pinned request also carries this header with the entry's pin key, so a stranger cannot pin a color. */
+export declare const LB_PIN_HEADER = "X-Foundry-Pin";
+export declare const LB_CONFIG_PATH = "/etc/traefik/dynamic/lb.yml";
+/**
+ * The balancer's inline Dockerfile: a pinned Traefik with a file provider watching one directory.
+ * Weights are never in here, so a weight change is a config write and never a redeploy.
+ */
+export declare function lbDockerfile(port: number): string;
+/** The traefik tag the balancer runs, for a test that keeps the pin and the Dockerfile equal. */
+export declare const LB_IMAGE_REF: string;
+/**
+ * The balancer's dynamic config: two weighted services and a sticky cookie. A color at weight 0 is left out
+ * of the weighted list, because Traefik sends a request that carries a sticky cookie to the named service
+ * whatever its weight, which would keep a rolled-back user on the failed color. The weights are in the first
+ * line, so a reader sees both numbers. `backends` are the URLs of each color's containers, one per server.
+ */
+export declare function renderLbConfig(input: {
+    weights: Weights;
+    backends: Record<Color, string[]>;
+    pinKey: string;
+}): string;
+/**
+ * The URL of one color's container on its own server's network. On the primary, blue is the app that was
+ * already there, under its own name; every other color is `<base>-<color>`.
+ */
+export declare const colorBackend: (subject: Pick<BlueGreenSubject, "base" | "port" | "primaryBlueName">, color: Color, onPrimary: boolean) => string;
+export interface UnmanagedLine {
+    description: string;
+    key: string;
+}
+export interface BlueGreenPlanStep {
+    kind: 'bluegreen' | 'bluegreen-lb' | 'bluegreen-connector';
+    /** `before`: ahead of the tunnel step, so its route finds a running balancer. `after`: needs the tunnel. */
+    phase: 'before' | 'after';
+    key: string;
+    description: string;
+    desired: Record<string, unknown>;
+}
+/** A short hash of what decides the shape of a server's apps, so a change replans the server. */
+export declare function structureHash(subject: BlueGreenSubject, input: {
+    primary: boolean;
+}): string;
+/** Hostnames of the tunnel that no blue/green entry serves; a connector on a second server cannot answer them. */
+export declare function namesNotBlueGreen(org: DeclaredOrg): string[];
+export interface PlanBlueGreenInput {
+    org: DeclaredOrg;
+    recordedIds: Readonly<Record<string, string>>;
+    /** Every Coolify server the host reports. `undefined`: the host cannot list them. */
+    servers: readonly BlueGreenServer[] | undefined;
+    /** The host's executor can hold a secret (the health token). */
+    canHoldSecrets: boolean;
+    /** The entry's app step is planned in this run (it makes the blue copy this step copies from). */
+    appPlanned: (entryKey: string) => boolean;
+}
+/**
+ * Plans the blue/green parts of an org: per usable server, one structure step (the apps, the balancer, the
+ * stage on the primary) when the recorded shape differs, else one balancer-config step when only the weights
+ * differ. A server that is down is skipped and reported in `unmanaged`. Pure: reads nothing but its input.
+ */
+export declare function planBlueGreen(input: PlanBlueGreenInput): {
+    steps: BlueGreenPlanStep[];
+    unmanaged: UnmanagedLine[];
+};
+/** The scope-key id, base name and port platform-archon runs under. */
+export declare const ARCHON_SUBJECT_ID = "platform-archon";
+/** https://github.com/wtfalch/archon: one Dockerfile at its root, `runner` stage on port 3000. */
+export declare const ARCHON_REPO = "wtfalch/archon";
+/**
+ * platform-archon as a blue/green subject: the same type a hosting entry makes. Its running app keeps its
+ * name and serves as the blue copy, because renaming its container would take its sign-in and tunnel down
+ * mid-apply; green and the balancer are new apps beside it.
+ */
+export declare function archonSubject(platform: {
+    archon: {
+        enabled: boolean;
+        hostname: string;
+        gitRef: string;
+        blueGreen?: BlueGreenConfig;
+    };
+}, repo: string): BlueGreenSubject | null;
+/**
+ * Where the tunnel sends a subject's names: its balancer once the structure on the primary is applied (the
+ * balancer's config written and every part running), else the app as before. Pointing the tunnel at a balancer
+ * that does not exist or does not answer yet would take the site down.
+ */
+export declare function tunnelOriginFor(subject: Pick<BlueGreenSubject, 'id' | 'base' | 'port'> | null, recorded: Readonly<Record<string, string>>, primaryUuid: string | undefined, fallback: string): string;
+/** The origin the archon step last wrote to the tunnel through {@link tunnelOriginFor}, recorded by the platform step. */
+export declare const ARCHON_BG_ORIGIN_SCOPE_KEY = "archon_bluegreen_origin";
+/**
+ * Plans the one platform step that runs platform-archon on the blue/green path: the structure on the primary
+ * server, the balancer's weights, and the tunnel's move to the balancer. It plans nothing until archon's app and
+ * tunnel are recorded, because the step copies the app's env and moves that tunnel. Archon runs on the primary
+ * only: the platform has no database route to another server.
+ */
+export declare function planArchonBlueGreen(input: {
+    platform: Parameters<typeof archonSubject>[0];
+    repo: string;
+    recorded: Readonly<Record<string, string>>;
+    /** Every Coolify server; `undefined`: the host cannot list them. */
+    servers: readonly BlueGreenServer[] | undefined;
+    /** Why the executor cannot run it (no way to hold the health token), or absent. */
+    executorBlocked?: string | undefined;
+}): {
+    step: BlueGreenPlanStep | null;
+    unmanaged: UnmanagedLine[];
+};