@wtfalch/foundry 0.47.0 → 0.48.0

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

@@ -1,4 +1,5 @@
 import type { BlueGreenConfig, DeclaredOrg, HostingEntry } from '../org.js';
+import { type StageKind } from './stage-isolation.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
@@ -38,11 +39,21 @@ export declare const bgKey: {
     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;
+    /** The held ref of the server actions key, recorded and persisted as soon as it is minted (no `:`: undelivered). */
+    actionsKey: (id: string) => string;
     stageDatabase: (id: string) => string;
+    /** `ok`, `unhealthy` (build or health check failed) or `blocked:<reason names>` (a guard refused; stage was not written to). */
+    stageState: (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 hash of the stage env name set and resource set that passed the isolation check. */
+    stageIsolation: (id: string) => string;
+    /** The id of the Access gate over the stage host: staff only, no bypass, no service-token rule. */
+    stageGate: (id: string) => string;
+    /** `ok:<hash>` once every apply-time probe was rejected; `notrun:<names>` or `failed:<names>` otherwise. */
+    stageProbes: (id: string) => string;
 };
 /** The three env names the reporting health read uses (contract C1). */
 export declare const REPORTING_ENV: {
@@ -50,6 +61,30 @@ export declare const REPORTING_ENV: {
     readonly release: "REPORTING_RELEASE";
     readonly healthToken: "REPORTING_HEALTH_TOKEN";
 };
+/** Next.js server action ids differ between builds unless every color is built with the same key. */
+export declare const ACTIONS_KEY_ENV = "NEXT_SERVER_ACTIONS_ENCRYPTION_KEY";
+/** The held-key name of a subject's server actions key: one mint per subject, shared by blue and green only. */
+export declare const actionsKeyName: (id: string) => string;
+/**
+ * One mint of the server actions key (CLAUDE.md, Platform steps, rule 1). The key goes to the held store, then its
+ * ref is recorded under {@link bgKey.actionsKey} and persisted, and only then is it returned for any env. A later
+ * apply reuses the held key; when the ref is recorded but the key is no longer held it stops, never mints again.
+ * The error names the ref only.
+ */
+export declare function mintActionsKey(input: {
+    id: string;
+    ref: string;
+    recorded: () => Readonly<Record<string, string>>;
+    record: (key: string, value: string) => void;
+    persist: () => Promise<void>;
+    heldKeys: {
+        resolve(ref: string): Promise<string | null>;
+        put(ref: string, value: string): Promise<void>;
+    };
+    generate: () => string;
+    /** Registers the value for redaction before it is written anywhere. */
+    secret: (value: string) => void;
+}): Promise<string>;
 /** 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. */
@@ -83,12 +118,54 @@ export interface BlueGreenSubject {
     /** The hostnames the tunnel routes to the balancer. */
     hostnames: string[];
     config: BlueGreenConfig;
+    /** The scope key that records the Coolify app of the blue copy (the app the subject runs as today). */
+    blueAppKey: string;
+    /** The Dockerfile in the repo, when it is not the root one. */
+    dockerfileLocation?: string;
+    /**
+     * Whether the app serves the reporting health read. A static app does not: its release uses hard fails only
+     * (address check, crash loop) and moves up by time.
+     */
+    reporting: boolean;
+    /** Set for Boule and Agora, which are not hosting entries. */
+    builtin?: BuiltinApp;
 }
+/** The apps foundry runs for every company, which can declare blue/green (`org.boule`, `org.agora`). */
+export type BuiltinApp = 'boule' | 'agora';
+export declare const BUILTIN_APPS: readonly BuiltinApp[];
+/** What foundry builds each built-in app from; `executor.ts` creates the app from the same values. */
+export declare const BUILTIN_APP: {
+    readonly boule: {
+        readonly repo: "wtfalch/boule";
+        readonly dockerfile: "/Dockerfile";
+        readonly port: 3000;
+        readonly healthPath: "/api/health";
+        readonly database: true;
+        readonly reporting: true;
+    };
+    readonly agora: {
+        readonly repo: "wtfalch/agora";
+        readonly dockerfile: "/apps/agora/Dockerfile";
+        readonly port: 8080;
+        readonly healthPath: "/";
+        readonly database: false;
+        readonly reporting: false;
+    };
+};
 /**
  * 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 company's Boule or Agora as a subject; `null` when it does not declare blue/green. The running app keeps
+ * its name `<slug>-<app>` and is blue, like platform-archon. Both run on the primary server only.
+ */
+export declare function builtinSubject(org: DeclaredOrg, app: BuiltinApp, recorded?: Readonly<Record<string, string>>): BlueGreenSubject | null;
+/** Every blue/green subject of an org: the hosting entries that declare it, then Boule and Agora. */
+export declare function blueGreenSubjects(org: DeclaredOrg, recorded?: Readonly<Record<string, string>>): BlueGreenSubject[];
+/** Whether the org declares blue/green for any of its apps. */
+export declare const declaresBlueGreen: (org: DeclaredOrg) => boolean;
 /**
  * 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
@@ -147,8 +224,11 @@ export interface UnmanagedLine {
 }
 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';
+    /**
+     * `before`: ahead of the tunnel step, so its route finds a running balancer. `after`: needs the tunnel.
+     * `last`: after Boule's and Agora's own steps, which make the blue app a built-in subject copies.
+     */
+    phase: 'before' | 'after' | 'last';
     key: string;
     description: string;
     desired: Record<string, unknown>;
@@ -157,6 +237,19 @@ export interface BlueGreenPlanStep {
 export declare function structureHash(subject: BlueGreenSubject, input: {
     primary: boolean;
 }): string;
+/** The kind of stage app a subject has: platform-archon, else a customer app. */
+export declare const stageKindOf: (subject: Pick<BlueGreenSubject, "id">) => StageKind;
+/** The names stage can collide on. */
+export declare function stageResources(subject: BlueGreenSubject): Record<string, string>;
+/** The names of the subject's live parts: stage must equal none of them. */
+export declare function prodResources(subject: BlueGreenSubject): Record<string, string>;
+/** The address of a stage app inside its network: it has no hostname. */
+export declare const stageAppUrl: (subject: Pick<BlueGreenSubject, "base" | "port">) => string;
+/**
+ * The violations of stage isolation that need no live values: the stage env names the builder gives, and the
+ * names stage and the org's other apps hold. Names only.
+ */
+export declare function stagePlanViolations(subject: BlueGreenSubject, otherApps: readonly string[]): 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 {
@@ -168,6 +261,8 @@ export interface PlanBlueGreenInput {
     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;
+    /** The platform's recorded Access provider, which the stage gate requires. Absent: no gate is made. */
+    accessProviderId?: string | null;
 }
 /**
  * Plans the blue/green parts of an org: per usable server, one structure step (the apps, the balancer, the

package/dist/plan/blue-green.js

@@ -1,9 +1,13 @@
 import { createHash } from 'node:crypto';
 import { VERSIONS, pinnedRef } from '../bootstrap/versions.js';
+import { agoraHostnameFor } from './agora.js';
+import { bouleHostnameFor } from './boule.js';
 import { serverConnectorScopeKey } from './cloudflared-connector.js';
 import { entryHostnames, tunnelIngressHostnames, wildcardHostname } from './hostnames.js';
 import { appNameFor, appStepKey } from './platform-diff.js';
 import { remoteDatabaseAppliedFor } from './remote-database.js';
+import { buildStageEnv } from './stage-env.js';
+import { assertStageIsolated, envClass } from './stage-isolation.js';
 export const COLORS = ['blue', 'green'];
 /** The name of `base`'s copy in `color`: `<base>-blue`. */
 export function colorAppName(base, color) {
@@ -43,11 +47,21 @@ export const bgKey = {
     app: (id, server, part) => `bg.${id}.app.${server}.${part}`,
     /** The cloudflared connector app of the tunnel on a non-primary `server`. */
     connector: (id, server) => `bg.${id}.connector.${server}`,
+    /** The held ref of the server actions key, recorded and persisted as soon as it is minted (no `:`: undelivered). */
+    actionsKey: (id) => `bg.${id}.actionskey`,
     stageDatabase: (id) => `bg.${id}.stagedb`,
+    /** `ok`, `unhealthy` (build or health check failed) or `blocked:<reason names>` (a guard refused; stage was not written to). */
+    stageState: (id) => `bg.${id}.stagestate`,
     /** The Coolify name of the blue app on the primary: the adopted single app's name, or `<base>-blue`. */
     blueName: (id) => `bg.${id}.bluename`,
     /** The pin key of the balancer's header routers. Not a credential: it only pins a color. */
     pinKey: (id) => `bg.${id}.pinkey`,
+    /** The hash of the stage env name set and resource set that passed the isolation check. */
+    stageIsolation: (id) => `bg.${id}.stageisolation`,
+    /** The id of the Access gate over the stage host: staff only, no bypass, no service-token rule. */
+    stageGate: (id) => `bg.${id}.stagegate`,
+    /** `ok:<hash>` once every apply-time probe was rejected; `notrun:<names>` or `failed:<names>` otherwise. */
+    stageProbes: (id) => `bg.${id}.stageprobes`,
 };
 /** The three env names the reporting health read uses (contract C1). */
 export const REPORTING_ENV = {
@@ -55,6 +69,32 @@ export const REPORTING_ENV = {
     release: 'REPORTING_RELEASE',
     healthToken: 'REPORTING_HEALTH_TOKEN',
 };
+/** Next.js server action ids differ between builds unless every color is built with the same key. */
+export const ACTIONS_KEY_ENV = 'NEXT_SERVER_ACTIONS_ENCRYPTION_KEY';
+/** The held-key name of a subject's server actions key: one mint per subject, shared by blue and green only. */
+export const actionsKeyName = (id) => `server-actions-key-${id}`;
+/**
+ * One mint of the server actions key (CLAUDE.md, Platform steps, rule 1). The key goes to the held store, then its
+ * ref is recorded under {@link bgKey.actionsKey} and persisted, and only then is it returned for any env. A later
+ * apply reuses the held key; when the ref is recorded but the key is no longer held it stops, never mints again.
+ * The error names the ref only.
+ */
+export async function mintActionsKey(input) {
+    const held = await input.heldKeys.resolve(input.ref);
+    if (held) {
+        input.secret(held);
+        return held;
+    }
+    if (input.recorded()[bgKey.actionsKey(input.id)]) {
+        throw new Error(`server actions key ${input.ref} was minted but is no longer held; restore the held value`);
+    }
+    const key = input.generate();
+    input.secret(key);
+    await input.heldKeys.put(input.ref, key);
+    input.record(bgKey.actionsKey(input.id), input.ref);
+    await input.persist();
+    return key;
+}
 /** The held-key name of an entry's health token (`sharedSecretRef(org.id, name)`): one mint per entry. */
 export const healthTokenName = (id) => `reporting-health-${id}`;
 /** What a color's container gets for the reporting health read. The release is left out until a digest is known. */
@@ -65,6 +105,27 @@ export function reportingEnv(input) {
         { key: REPORTING_ENV.healthToken, value: input.healthToken },
     ];
 }
+export const BUILTIN_APPS = ['boule', 'agora'];
+/** What foundry builds each built-in app from; `executor.ts` creates the app from the same values. */
+export const BUILTIN_APP = {
+    boule: {
+        repo: 'wtfalch/boule',
+        dockerfile: '/Dockerfile',
+        port: 3000,
+        healthPath: '/api/health',
+        database: true,
+        reporting: true,
+    },
+    agora: {
+        repo: 'wtfalch/agora',
+        dockerfile: '/apps/agora/Dockerfile',
+        // Equal to `AGORA_APP_PORTS_EXPOSES` (a test holds them together); importing it here would be a cycle.
+        port: 8080,
+        healthPath: '/',
+        database: false,
+        reporting: false,
+    },
+};
 /**
  * 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}).
@@ -87,8 +148,57 @@ export function entrySubject(org, entry, recorded) {
         database: entry.database,
         hostnames: entryHostnames(org, entry),
         config: entry.blueGreen,
+        blueAppKey: `coolify:app:${appStepKey(org, entry.key)}`,
+        reporting: true,
     };
 }
+/**
+ * The company's Boule or Agora as a subject; `null` when it does not declare blue/green. The running app keeps
+ * its name `<slug>-<app>` and is blue, like platform-archon. Both run on the primary server only.
+ */
+export function builtinSubject(org, app, recorded = {}) {
+    const config = org[app]?.blueGreen;
+    if (!config)
+        return null;
+    const spec = BUILTIN_APP[app];
+    const base = `${org.slug}-${app}`;
+    return {
+        id: app,
+        base,
+        primaryBlueName: recorded[bgKey.blueName(app)] ?? base,
+        port: spec.port,
+        repo: spec.repo,
+        folder: null,
+        branch: 'main',
+        buildPack: 'dockerfile',
+        healthPath: spec.healthPath,
+        database: spec.database,
+        hostnames: [app === 'boule' ? bouleHostnameFor(org) : agoraHostnameFor(org)],
+        config,
+        blueAppKey: `coolify:${app}:${org.id}`,
+        dockerfileLocation: spec.dockerfile,
+        reporting: spec.reporting,
+        builtin: app,
+    };
+}
+/** Every blue/green subject of an org: the hosting entries that declare it, then Boule and Agora. */
+export function blueGreenSubjects(org, recorded) {
+    const subjects = [];
+    for (const entry of org.hosting.entries) {
+        const subject = entrySubject(org, entry, recorded);
+        if (subject)
+            subjects.push(subject);
+    }
+    for (const app of BUILTIN_APPS) {
+        const subject = builtinSubject(org, app, recorded);
+        if (subject)
+            subjects.push(subject);
+    }
+    return subjects;
+}
+/** Whether the org declares blue/green for any of its apps. */
+export const declaresBlueGreen = (org) => org.hosting.entries.some((entry) => entry.blueGreen) ||
+    BUILTIN_APPS.some((app) => org[app]?.blueGreen);
 /**
  * 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
@@ -218,6 +328,59 @@ export function structureHash(subject, input) {
         .digest('hex')
         .slice(0, 16);
 }
+/** The kind of stage app a subject has: platform-archon, else a customer app. */
+export const stageKindOf = (subject) => subject.id === ARCHON_SUBJECT_ID ? 'archon' : 'customer';
+/** The names stage can collide on. */
+export function stageResources(subject) {
+    const database = `${subject.base}-stage-db`;
+    return {
+        app: stageAppName(subject.base),
+        ...(subject.database ? { database, databaseName: database.replace(/-/g, '_') } : {}),
+    };
+}
+/** The names of the subject's live parts: stage must equal none of them. */
+export function prodResources(subject) {
+    return {
+        blue: subject.primaryBlueName,
+        green: colorAppName(subject.base, 'green'),
+        lb: lbAppName(subject.base),
+        base: subject.base,
+    };
+}
+/** The address of a stage app inside its network: it has no hostname. */
+export const stageAppUrl = (subject) => `http://${stageAppName(subject.base)}:${subject.port}`;
+/**
+ * The violations of stage isolation that need no live values: the stage env names the builder gives, and the
+ * names stage and the org's other apps hold. Names only.
+ */
+export function stagePlanViolations(subject, otherApps) {
+    const { env } = buildStageEnv({
+        kind: stageKindOf(subject),
+        appUrl: stageAppUrl(subject),
+        logDir: '',
+        database: subject.database
+            ? [
+                { key: 'DATABASE_URL_OWNER', value: '' },
+                { key: 'DATABASE_URL', value: '' },
+            ]
+            : [],
+        prod: [],
+        existing: [],
+        mint: () => '',
+    });
+    const stage = {
+        env: env.map((e) => ({ name: e.key, class: envClass(e.key) })),
+        resources: stageResources(subject),
+    };
+    const prod = {
+        env: [],
+        resources: {
+            ...prodResources(subject),
+            ...Object.fromEntries(otherApps.map((name, i) => [`other${i}`, name])),
+        },
+    };
+    return assertStageIsolated({ kind: stageKindOf(subject), prod, stage });
+}
 /** Hostnames of the tunnel that no blue/green entry serves; a connector on a second server cannot answer them. */
 export function namesNotBlueGreen(org) {
     const served = new Set();
@@ -232,6 +395,11 @@ export function namesNotBlueGreen(org) {
                 served.add(wildcard);
         }
     }
+    for (const subject of blueGreenSubjects(org)) {
+        if (subject.builtin)
+            for (const name of subject.hostnames)
+                served.add(name);
+    }
     return tunnelIngressHostnames(org).filter((name) => !served.has(name));
 }
 const MAX_NAME = 63;
@@ -246,21 +414,25 @@ export function planBlueGreen(input) {
     const { org, recordedIds } = input;
     const steps = [];
     const unmanaged = [];
-    for (const entry of org.hosting.entries) {
-        const subject = entrySubject(org, entry, recordedIds);
-        if (!subject)
-            continue;
+    for (const subject of blueGreenSubjects(org, recordedIds)) {
+        const entry = org.hosting.entries.find((e) => e.key === subject.id);
+        const builtin = subject.builtin !== undefined;
         const id = subject.id;
         const blocked = (why, part = 'blocked') => unmanaged.push({
             description: `${org.slug}'s ${id} app blue/green is blocked, not planned: ${why}`,
             key: `bg:${id}:${part}`,
         });
-        if (entry.buildPack === 'dockercompose')
+        if (entry?.buildPack === 'dockercompose')
             continue;
         if (colorAppName(subject.base, 'green').length > MAX_NAME) {
             blocked('its app name is too long for the green copy; shorten the slug or the entry key');
             continue;
         }
+        const stageViolations = stagePlanViolations(subject, org.hosting.entries.filter((e) => e.key !== subject.id).map((e) => appNameFor(org, e)));
+        if (stageViolations.length > 0) {
+            blocked(`its stage would not be isolated from production (${stageViolations.join(', ')})`, 'stageisolation');
+            continue;
+        }
         if (!input.servers) {
             blocked('the host cannot list Coolify servers');
             continue;
@@ -274,8 +446,14 @@ export function planBlueGreen(input) {
             blocked(`the recorded weights are not 'blue:<n>,green:<n>' summing to 100`, 'weights');
             continue;
         }
-        if (!recordedIds[`coolify:app:${appStepKey(org, id)}`] && !input.appPlanned(id)) {
-            blocked('its blue copy is not recorded and no app step is planned to make it');
+        if (builtin && !org.domain) {
+            blocked('its address is on the shared tunnel, which cannot route to a balancer; give the company a domain');
+            continue;
+        }
+        if (!recordedIds[subject.blueAppKey] && (builtin || !input.appPlanned(id))) {
+            blocked(builtin
+                ? 'its app is not recorded yet; apply the company once first'
+                : 'its blue copy is not recorded and no app step is planned to make it');
             continue;
         }
         const { up, down } = splitServers(input.servers);
@@ -285,13 +463,13 @@ export function planBlueGreen(input) {
             blocked(`the primary Coolify server ${primary ?? '(none)'} is not usable and reachable`);
             continue;
         }
-        for (const uuid of down) {
+        for (const uuid of builtin ? [] : down) {
             unmanaged.push({
                 description: `${org.slug}'s ${id} app has no blue/green copies on Coolify server ${uuid}: the server is not usable or not reachable right now`,
                 key: `bg:${id}:down:${uuid}`,
             });
         }
-        const others = up.filter((uuid) => uuid !== primary);
+        const others = builtin ? [] : up.filter((uuid) => uuid !== primary);
         const unrouted = namesNotBlueGreen(org);
         const useOthers = others.length > 0 && unrouted.length === 0;
         if (others.length > 0 && !useOthers) {
@@ -313,6 +491,19 @@ export function planBlueGreen(input) {
                 }
             }
         }
+        const stageState = recordedIds[bgKey.stageState(id)];
+        if (stageState === 'unhealthy') {
+            unmanaged.push({
+                description: `${org.slug}'s ${id} app: stage is not healthy yet`,
+                key: `bg:${id}:stage`,
+            });
+        }
+        else if (stageState?.startsWith('blocked:')) {
+            unmanaged.push({
+                description: `${org.slug}'s ${id} app: stage is blocked and was not written to (${stageState.slice('blocked:'.length)})`,
+                key: `bg:${id}:stage`,
+            });
+        }
         for (const server of targets) {
             const isPrimary = server === primary;
             const key = `${org.id}:${id}:${server}`;
@@ -324,19 +515,27 @@ export function planBlueGreen(input) {
                 });
                 continue;
             }
-            if (recordedIds[bgKey.applied(id, server)] !== hash) {
+            // A stage that was not healthy is retried by running the structure again.
+            const stageRetry = isPrimary && (stageState === 'unhealthy' || stageState?.startsWith('blocked:') === true);
+            if (recordedIds[bgKey.applied(id, server)] !== hash || stageRetry) {
                 steps.push({
                     kind: 'bluegreen',
-                    phase: 'before',
+                    phase: builtin ? 'last' : 'before',
                     key,
                     description: `run ${org.slug}'s ${id} app as blue and green behind a load balancer on Coolify server ${server}${isPrimary ? ', with a stage copy' : ''}`,
-                    desired: { entry: id, server, primary, weights: formatWeights(weights) },
+                    desired: {
+                        entry: id,
+                        server,
+                        primary,
+                        weights: formatWeights(weights),
+                        ...(input.accessProviderId ? { accessProviderId: input.accessProviderId } : {}),
+                    },
                 });
             }
             else if (recordedIds[bgKey.lb(id, server)] !== formatWeights(weights)) {
                 steps.push({
                     kind: 'bluegreen-lb',
-                    phase: 'before',
+                    phase: builtin ? 'last' : 'before',
                     key,
                     description: `set ${org.slug}'s ${id} app traffic to ${formatWeights(weights)} on Coolify server ${server}`,
                     desired: { entry: id, server, primary, weights: formatWeights(weights) },
@@ -374,6 +573,8 @@ export function archonSubject(platform, repo) {
         database: true,
         hostnames: [archon.hostname],
         config: archon.blueGreen,
+        blueAppKey: ARCHON_APP_RECORD,
+        reporting: true,
     };
 }
 /**

package/dist/plan/database-dump.d.ts

@@ -0,0 +1,37 @@
+import type { CoolifyPort } from './executor.js';
+/** The dump {@link dumpNow} started, and where it is saved. */
+export interface DatabaseDump {
+    /** Coolify's uuid of the execution this call started. */
+    executionId: string;
+    location: {
+        /** The S3 storage (`platform-backups`) the dump was saved to. */
+        storageUuid: string;
+        /** The dump's file as Coolify records it: its path in that storage's bucket. */
+        filename: string;
+    };
+}
+/** An error of {@link dumpNow}: fixed text and the database's key, never a Coolify message, uuid or body. */
+export declare class DumpError extends Error {
+    constructor(message: string);
+}
+/**
+ * Takes a fresh dump of one database now and returns where it is saved. Coolify has no
+ * run-now route: `PATCH /databases/{uuid}/backups/{backup}` with `backup_now: true` queues the
+ * schedule's job, so the dump goes through the database's existing schedule. The execution it
+ * started is the first one not listed before the call; an older one is never returned. Every
+ * failure is an error naming `databaseKey`, never a uuid, a Coolify message or a body. Nothing is
+ * retried. The dump is subject to the schedule's own retention.
+ */
+export declare function dumpNow(coolify: Pick<CoolifyPort, 'listDatabaseBackups' | 'raw'> & Partial<Pick<CoolifyPort, 'listDatabaseBackupExecutions'>>, input: {
+    /** The database's name in `companyDatabaseKeys`, e.g. `app.shop`. Goes into every error. */
+    databaseKey: string;
+    databaseUuid: string;
+    /** The uuid of the database's schedule. */
+    backupUuid: string;
+    /** The registered `platform-backups` storage the schedule saves to. */
+    storageUuid: string;
+    /** Milliseconds to wait for the dump to finish. Default: 10 minutes. */
+    timeoutMs?: number;
+    /** Milliseconds between two reads of the executions. Default: 3 seconds. */
+    intervalMs?: number;
+}): Promise<DatabaseDump>;

package/dist/plan/database-dump.js

@@ -0,0 +1,101 @@
+const DUMP_NOW_TIMEOUT_MS = 600_000;
+const DUMP_NOW_INTERVAL_MS = 3_000;
+const DUMP_CALL_TIMEOUT_MS = 30_000;
+/** An error of {@link dumpNow}: fixed text and the database's key, never a Coolify message, uuid or body. */
+export class DumpError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DumpError';
+    }
+}
+async function dumpCall(label, call) {
+    let timer;
+    try {
+        return await Promise.race([
+            call(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new DumpError(`dump of ${label}: Coolify did not answer within ${DUMP_CALL_TIMEOUT_MS / 1000} seconds`)), DUMP_CALL_TIMEOUT_MS);
+            }),
+        ]);
+    }
+    catch (error) {
+        if (error instanceof DumpError)
+            throw error;
+        throw new DumpError(`dump of ${label}: a Coolify call failed`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function dumpExecutions(coolify, label, databaseUuid, backupUuid) {
+    const body = await dumpCall(label, () => coolify.listDatabaseBackupExecutions
+        ? coolify.listDatabaseBackupExecutions(databaseUuid, backupUuid)
+        : coolify.raw('GET', `/databases/${databaseUuid}/backups/${backupUuid}/executions`));
+    const rows = Array.isArray(body) ? body : body?.executions;
+    if (!Array.isArray(rows)) {
+        throw new DumpError(`dump of ${label}: Coolify's executions had an unexpected shape`);
+    }
+    return rows.map((row) => {
+        const r = row;
+        if (!r || typeof r.uuid !== 'string' || typeof r.status !== 'string') {
+            throw new DumpError(`dump of ${label}: Coolify's executions had an unexpected shape`);
+        }
+        return {
+            uuid: r.uuid,
+            status: r.status,
+            ...(typeof r.filename === 'string' ? { filename: r.filename } : {}),
+        };
+    });
+}
+/**
+ * Takes a fresh dump of one database now and returns where it is saved. Coolify has no
+ * run-now route: `PATCH /databases/{uuid}/backups/{backup}` with `backup_now: true` queues the
+ * schedule's job, so the dump goes through the database's existing schedule. The execution it
+ * started is the first one not listed before the call; an older one is never returned. Every
+ * failure is an error naming `databaseKey`, never a uuid, a Coolify message or a body. Nothing is
+ * retried. The dump is subject to the schedule's own retention.
+ */
+export async function dumpNow(coolify, input) {
+    const { databaseKey: label, databaseUuid, backupUuid, storageUuid } = input;
+    for (const [name, value] of Object.entries({
+        databaseKey: label,
+        databaseUuid,
+        backupUuid,
+        storageUuid,
+    })) {
+        if (typeof value !== 'string' || value.length === 0) {
+            throw new DumpError(`dump: ${name} must be a non-empty string`);
+        }
+    }
+    const timeoutMs = input.timeoutMs ?? DUMP_NOW_TIMEOUT_MS;
+    const intervalMs = input.intervalMs ?? DUMP_NOW_INTERVAL_MS;
+    if (!(timeoutMs > 0) || !(intervalMs > 0)) {
+        throw new DumpError(`dump of ${label}: timeoutMs and intervalMs must be positive`);
+    }
+    const schedule = (await dumpCall(label, () => coolify.listDatabaseBackups(databaseUuid))).find((s) => s.uuid === backupUuid);
+    if (!schedule || schedule.enabled === false || !schedule.save_s3) {
+        throw new DumpError(`dump of ${label}: its schedule is missing, disabled or does not save to S3`);
+    }
+    if (schedule.s3_storage_uuid !== undefined && schedule.s3_storage_uuid !== storageUuid) {
+        throw new DumpError(`dump of ${label}: its schedule saves to another storage than the backup bucket`);
+    }
+    const before = new Set((await dumpExecutions(coolify, label, databaseUuid, backupUuid)).map((e) => e.uuid));
+    await dumpCall(label, () => coolify.raw('PATCH', `/databases/${databaseUuid}/backups/${backupUuid}`, { backup_now: true }));
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const started = (await dumpExecutions(coolify, label, databaseUuid, backupUuid)).find((e) => !before.has(e.uuid));
+        if (started?.status === 'success') {
+            if (!started.filename) {
+                throw new DumpError(`dump of ${label}: Coolify recorded no file for the finished dump`);
+            }
+            return { executionId: started.uuid, location: { storageUuid, filename: started.filename } };
+        }
+        if (started && started.status !== 'running') {
+            throw new DumpError(`dump of ${label} failed`);
+        }
+        if (Date.now() >= deadline) {
+            throw new DumpError(`dump of ${label}: no finished dump within ${Math.round(timeoutMs / 1000)} seconds`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+}

package/dist/plan/diff.js

@@ -490,6 +490,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         recordedIds,
         servers: options.blueGreenServers,
         canHoldSecrets: platformReadiness.canHoldSecrets === true,
+        accessProviderId: platformReadiness.accessProviderId ?? null,
         appPlanned: (entryKey) => plannedSteps.some((p) => p.action.system === 'coolify' &&
             p.action.kind === 'app' &&
             p.action.key === appStepKey(org, entryKey)),
@@ -566,6 +567,8 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const boule = planBoule(org, byKey, claimed, recordedIds, authIssuer, options.otherSlugs ?? [], options.archonUrl ?? null, platformReadiness, bouleCredentials.wants);
     if (boule.step)
         plannedSteps.push(boule.step);
+    // Boule's and Agora's blue/green: after their own steps, which make the app it copies.
+    plannedSteps.push(...blueGreen.steps.filter((x) => x.phase === 'last').map(blueGreenDraft()));
     // Boule owners, after the Boule step: needs the app deployed and the seeding secret in its env.
     const bouleOwners = planBouleOwners(org, recordedIds, (byKey.get(resourceKey('coolify', 'boule', org.id))?.config.env ?? null));
     if (bouleOwners.seed.length > 0) {