@wtfalch/foundry 0.49.0 → 0.50.1

package/dist/index.d.ts

@@ -31,6 +31,11 @@ export { COMPANY_DESTINATION_NAME_PREFIX, COMPANY_NETWORKS, DEFAULT_MAX_DESTINAT
 export { AdoptRefusedError } from './plan/index.js';
 export { DumpError, dumpNow } from './plan/index.js';
 export type { DatabaseDump } from './plan/index.js';
+export { STAGE_SINK_APPLIED_SCOPE_KEY, STAGE_SINK_IMAGE_REF, stageMailEnv, stageSinkAppName, } from './plan/index.js';
+export { STAGE_COPY_EXCLUDED_TABLES, StageCopyFailedError, StageCopyRefusedError, stageCopy, tableExcluded, undoStageCopy, } from './plan/index.js';
+export type { StageCopyInput, StageCopyPort, StageCopyProduction, StageCopyRunRecord, UndoStageCopyInput, } from './plan/index.js';
+export { StageRestoreError, StageRestoreRefusedError, createStageCopyPort, execRunner, } from './plan/index.js';
+export type { Runner, StageCopyPortDeps } from './plan/index.js';
 export { InvalidMigrationConfirmationError, ORG_POSTGRES_MIGRATION_CONFIRMED_SCOPE_KEY, OrgPostgresMigrationBackupMissingError, OrgPostgresMigrationNotConfirmedError, } from './plan/index.js';
 export type { OrgPostgresMigrationConfirmation } from './plan/index.js';
 export { NetworkMoveBackupMissingError, UpgradeBackupMissingError } from './plan/index.js';

package/dist/index.js

@@ -19,6 +19,9 @@ export { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryAudit
 export { COMPANY_DESTINATION_NAME_PREFIX, COMPANY_NETWORKS, DEFAULT_MAX_DESTINATIONS, DestinationCapacityError, PLATFORM_NETWORK, companyNetworkName, ensureDestination, findDestination, placed, placedOnPlatform, validateNetworkName, } from './plan/index.js';
 export { AdoptRefusedError } from './plan/index.js';
 export { DumpError, dumpNow } from './plan/index.js';
+export { STAGE_SINK_APPLIED_SCOPE_KEY, STAGE_SINK_IMAGE_REF, stageMailEnv, stageSinkAppName, } from './plan/index.js';
+export { STAGE_COPY_EXCLUDED_TABLES, StageCopyFailedError, StageCopyRefusedError, stageCopy, tableExcluded, undoStageCopy, } from './plan/index.js';
+export { StageRestoreError, StageRestoreRefusedError, createStageCopyPort, execRunner, } from './plan/index.js';
 export { InvalidMigrationConfirmationError, ORG_POSTGRES_MIGRATION_CONFIRMED_SCOPE_KEY, OrgPostgresMigrationBackupMissingError, OrgPostgresMigrationNotConfirmedError, } from './plan/index.js';
 export { NetworkMoveBackupMissingError, UpgradeBackupMissingError } from './plan/index.js';
 export { createEdgeAccess, createEdgeDns, edgeDnsRecordOwners, createEdgeRateLimits, createEdgeTunnels, createEdgeWorkers, createEdgeZones, } from './plan/index.js';

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

@@ -59,6 +59,7 @@ export async function applyArchonBlueGreen(run) {
         logDir: run.logDir,
         isRunning: run.isRunning,
         adoptRunningBlue: true,
+        stageSink: { slug: 'platform' },
         actionsKey: async () => {
             const key = await mintActionsKey({
                 id,

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

@@ -7,6 +7,8 @@ import { type StageGuardDeps } from './stage-guards.js';
 /** The Coolify calls this module makes. */
 type Coolify = Pick<CoolifyPort, 'findApplicationByName' | 'getApplication' | 'createGithubAppApplication' | 'createDockerfileApplication' | 'updateApplication' | 'bulkUpsertEnvs' | 'listEnvs' | 'deploy' | 'deployAndWait' | 'listStorages' | 'createPersistentStorage' | 'createFileStorage' | 'updateFileStorage' | 'requireGithubApp' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'raw'> & {
     listApplicationDeployments?: CoolifyPort['listApplicationDeployments'];
+    /** Needed by the stage mail sink; a host without it gets no sink, so no stage mail env. */
+    createDockerImageApplication?: CoolifyPort['createDockerImageApplication'];
 };
 export interface BlueGreenApplyDeps {
     coolify: Coolify;
@@ -47,6 +49,13 @@ export interface BlueGreenApplyDeps {
      * guard unrecorded ("not run", never passed), so `stageGuardsReady` stays false and the copy does not start.
      */
     stageGuards?: StageGuardDeps;
+    /**
+     * The company the stage mail sink belongs to (its name is `<slug>-stage-sink`). Absent: no sink is made and
+     * stage holds no mail env at all, so the copy stays refused.
+     */
+    stageSink?: {
+        slug: string;
+    };
 }
 /** What writing a balancer's config needs; {@link BlueGreenApplyDeps} and the release runner both have it. */
 export interface LbConfigDeps {

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

@@ -1,13 +1,18 @@
 import { randomBytes } from 'node:crypto';
 import { ACTIONS_KEY_ENV, COLORS, LB_CONFIG_PATH, bgKey, colorAppName, colorBackend, formatWeights, lbAppName, lbDockerfile, parseWeights, prodResources, renderLbConfig, reportingEnv, stageAppName, stageAppUrl, stageKindOf, stageResources, structureHash, } from './blue-green.js';
 import { recordBuiltCommit } from './build-record.js';
+import { withTimeout } from './call-timeout.js';
 import { ensureConnectorsOnServers } from './cloudflared-connector.js';
 import { waitForNewDeployment } from './deploy-health.js';
+import { commandHealthCheckSettings, wgetProbe } from './health-check-settings.js';
 import { ENTRY_CONTAINER_LABELS } from './proxy-labels.js';
 import { remoteDatabaseAddress, remoteDatabaseHost } from './remote-database.js';
 import { buildStageEnv } from './stage-env.js';
 import { buildStageProbes, runStageProbes, stageProbesRecord, } from './stage-guards.js';
 import { assertStageIsolated, envClass, stageIsolationHash, } from './stage-isolation.js';
+import { STAGE_SINK_APPLIED_SCOPE_KEY, STAGE_SINK_APP_SCOPE_KEY, STAGE_SINK_HTTP_PORT, STAGE_SINK_IMAGE_TAG, STAGE_SINK_REPOSITORY, stageMailEnv, stageSinkAppName, } from './stage-sink.js';
+/** How long one Coolify call of the sink may take. */
+const SINK_CALL_TIMEOUT_MS = 30_000;
 /** 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. */
@@ -80,8 +85,15 @@ export async function applyBlueGreenServer(deps, subject, server) {
     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)
+    if (isPrimary) {
+        const sinkReady = await ensureStageSink(deps, subject, server.uuid);
         await ensureStage(deps, subject, server.uuid);
+        if (!sinkReady) {
+            // The planner plans this step again while the state is `blocked:`; ensureStage may have written `ok`.
+            deps.record(bgKey.stageState(id), 'blocked:sink');
+            await deps.persist();
+        }
+    }
     deps.record(bgKey.applied(id, server.uuid), structureHash(subject, { primary: isPrimary }));
     await deps.persist();
 }
@@ -301,6 +313,69 @@ async function ensureLoadBalancer(deps, subject, serverUuid, name, isPrimary) {
     }
     return lbId;
 }
+/**
+ * One Mailpit app per company beside stage, shared by every stage of the company. It is checked against the live
+ * app on every run: one that is stopped or gone is deployed again. `stage_sink_applied` is recorded only after
+ * the sink deploys; a failure clears it, logs fixed text and the error name, and returns false. Production's
+ * structure goes on (stage then holds no mail env and the copy stays refused).
+ */
+async function ensureStageSink(deps, subject, serverUuid) {
+    const org = deps.stageSink;
+    if (!org)
+        return true;
+    const { coolify } = deps;
+    const name = stageSinkAppName(org);
+    try {
+        let appId = deps.recorded()[STAGE_SINK_APP_SCOPE_KEY];
+        let created = false;
+        if (!appId) {
+            appId = (await withTimeout('stage sink: find the app', SINK_CALL_TIMEOUT_MS, () => coolify.findApplicationByName(name, { environmentIds: [deps.environment.id] })))?.uuid;
+        }
+        if (!appId) {
+            const createImageApp = coolify.createDockerImageApplication;
+            if (!createImageApp)
+                throw new Error('the host cannot create an image app');
+            appId = (await withTimeout('stage sink: create the app', SINK_CALL_TIMEOUT_MS, () => createImageApp.call(coolify, {
+                project_uuid: deps.projectUuid,
+                server_uuid: serverUuid,
+                environment_name: deps.environment.name,
+                environment_uuid: deps.environment.uuid,
+                docker_registry_image_name: STAGE_SINK_REPOSITORY,
+                docker_registry_image_tag: STAGE_SINK_IMAGE_TAG,
+                ports_exposes: String(STAGE_SINK_HTTP_PORT),
+                name,
+                description: `mail sink for ${subject.base}'s stage`,
+                instant_deploy: false,
+            }))).uuid;
+            created = true;
+        }
+        // Recorded before anything else is written, so a later failure never leaves an app nothing points at.
+        if (deps.recorded()[STAGE_SINK_APP_SCOPE_KEY] !== appId) {
+            deps.record(STAGE_SINK_APP_SCOPE_KEY, appId);
+            await deps.persist();
+        }
+        if (created) {
+            await withTimeout('stage sink: set the app up', SINK_CALL_TIMEOUT_MS, () => coolify.updateApplication(appId, {
+                custom_internal_name: name,
+                ...commandHealthCheckSettings(wgetProbe(STAGE_SINK_HTTP_PORT, '/livez')),
+            }));
+        }
+        await ensureDeployed(deps, appId, name);
+    }
+    catch (error) {
+        console.error(`${deps.label}: the stage mail sink failed (${error instanceof Error ? error.name : 'unknown'}); stage gets no mail env`);
+        if (deps.recorded()[STAGE_SINK_APPLIED_SCOPE_KEY]) {
+            deps.record(STAGE_SINK_APPLIED_SCOPE_KEY, '');
+            await deps.persist();
+        }
+        return false;
+    }
+    if (!deps.recorded()[STAGE_SINK_APPLIED_SCOPE_KEY]) {
+        deps.record(STAGE_SINK_APPLIED_SCOPE_KEY, '1');
+        await deps.persist();
+    }
+    return true;
+}
 /** The stage app and its own empty database, on the primary. Its env comes from the allowlist, never from a copy of the live app's. */
 async function ensureStage(deps, subject, serverUuid) {
     const { coolify } = deps;
@@ -368,6 +443,12 @@ async function ensureStage(deps, subject, serverUuid) {
         deps.secret(key);
         stageEnv.push({ key: ACTIONS_KEY_ENV, value: key, buildTime: true });
     }
+    // The sink's mail env, only once the sink app is deployed. Before that stage holds no mail env at all.
+    const sinkApplied = deps.stageSink && deps.recorded()[STAGE_SINK_APPLIED_SCOPE_KEY];
+    const mail = deps.stageSink && sinkApplied ? stageMailEnv(deps.stageSink) : [];
+    const stageHas = new Map((await coolify.listEnvs(appId)).filter((e) => !e.is_preview).map((e) => [e.key, e.value]));
+    const mailChanged = mail.some((e) => stageHas.get(e.key) !== e.value);
+    stageEnv.push(...mail);
     const stageSurface = {
         env: stageEnv.map((e) => ({ name: e.key, class: envClass(e.key), value: e.value })),
         resources: stageResources(subject),
@@ -382,6 +463,7 @@ async function ensureStage(deps, subject, serverUuid) {
             internalHosts: Object.values(prodResources(subject)),
         },
         stage: stageSurface,
+        sinkMail: Object.fromEntries(mail.map((e) => [e.key, e.value])),
     });
     if (violations.length > 0) {
         // Stage fails closed for itself: nothing is written to it, production's structure goes on.
@@ -423,11 +505,13 @@ async function ensureStage(deps, subject, serverUuid) {
         return;
     }
     await upsertEnv(deps, appId, stageEnv);
+    if (mail.length > 0)
+        deps.record(bgKey.stageSink(subject.id), 'applied');
     deps.record(bgKey.stageIsolation(subject.id), isolationHash);
     deps.record(bgKey.stageProbes(subject.id), probes.value);
     await deps.persist();
     const live = await coolify.getApplication(appId);
-    if (live.status === undefined || !deps.isRunning(live.status)) {
+    if (mailChanged || live.status === undefined || !deps.isRunning(live.status)) {
         // Stage is a test copy: a failed build or health check must not fail production's structure apply.
         // The next apply retries it (the plan keeps the step while the state is `unhealthy`).
         let built;

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

@@ -54,6 +54,12 @@ export declare const bgKey: {
     stageGate: (id: string) => string;
     /** `ok:<hash>` once every apply-time probe was rejected; `notrun:<names>` or `failed:<names>` otherwise. */
     stageProbes: (id: string) => string;
+    /** `applied` once the stage app holds the sink's mail env. The copy refuses without it. */
+    stageSink: (id: string) => string;
+    /** `<ISO time>|<dump execution id>|ok`, written by a finished copy of production into stage. */
+    stageCopy: (id: string) => string;
+    /** The Coolify database stage ran on before the last copy, kept for `undoStageCopy` until the next copy. */
+    stageKept: (id: string) => string;
 };
 /** The three env names the reporting health read uses (contract C1). */
 export declare const REPORTING_ENV: {
@@ -263,6 +269,8 @@ export interface PlanBlueGreenInput {
     appPlanned: (entryKey: string) => boolean;
     /** The platform's recorded Access provider, which the stage gate requires. Absent: no gate is made. */
     accessProviderId?: string | null;
+    /** The company's stage mail sink is recorded and its live app is stopped or gone (read from Coolify at plan time). */
+    stageSinkDown?: boolean;
 }
 /**
  * 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

@@ -8,6 +8,7 @@ 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';
+import { STAGE_SINK_VERSION } from './stage-sink.js';
 export const COLORS = ['blue', 'green'];
 /** The name of `base`'s copy in `color`: `<base>-blue`. */
 export function colorAppName(base, color) {
@@ -62,6 +63,12 @@ export const bgKey = {
     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`,
+    /** `applied` once the stage app holds the sink's mail env. The copy refuses without it. */
+    stageSink: (id) => `bg.${id}.stagesink`,
+    /** `<ISO time>|<dump execution id>|ok`, written by a finished copy of production into stage. */
+    stageCopy: (id) => `bg.${id}.stagecopy`,
+    /** The Coolify database stage ran on before the last copy, kept for `undoStageCopy` until the next copy. */
+    stageKept: (id) => `bg.${id}.stagekept`,
 };
 /** The three env names the reporting health read uses (contract C1). */
 export const REPORTING_ENV = {
@@ -324,6 +331,7 @@ export function structureHash(subject, input) {
         database: subject.database,
         primary: input.primary,
         lb: VERSIONS.traefik,
+        ...(input.primary ? { stageSink: STAGE_SINK_VERSION } : {}),
     }))
         .digest('hex')
         .slice(0, 16);
@@ -498,6 +506,12 @@ export function planBlueGreen(input) {
                 key: `bg:${id}:stage`,
             });
         }
+        else if (stageState === 'blocked:sink' || input.stageSinkDown === true) {
+            unmanaged.push({
+                description: `${org.slug}'s ${id} app: the stage mail sink is not running; stage gets no mail env and the copy is refused`,
+                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)})`,
@@ -516,7 +530,10 @@ export function planBlueGreen(input) {
                 continue;
             }
             // A stage that was not healthy is retried by running the structure again.
-            const stageRetry = isPrimary && (stageState === 'unhealthy' || stageState?.startsWith('blocked:') === true);
+            const stageRetry = isPrimary &&
+                (stageState === 'unhealthy' ||
+                    stageState?.startsWith('blocked:') === true ||
+                    input.stageSinkDown === true);
             if (recordedIds[bgKey.applied(id, server)] !== hash || stageRetry) {
                 steps.push({
                     kind: 'bluegreen',

package/dist/plan/call-timeout.d.ts

@@ -0,0 +1,6 @@
+/** A failed outside call: fixed text and the label, never the cause (it can echo a credential). */
+export declare class CallError extends Error {
+    constructor(message: string);
+}
+/** Runs one outside call under a timeout. Any failure becomes a {@link CallError} with fixed text. */
+export declare function withTimeout<T>(label: string, timeoutMs: number, call: () => Promise<T>): Promise<T>;

package/dist/plan/call-timeout.js

@@ -0,0 +1,27 @@
+/** A failed outside call: fixed text and the label, never the cause (it can echo a credential). */
+export class CallError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CallError';
+    }
+}
+/** Runs one outside call under a timeout. Any failure becomes a {@link CallError} with fixed text. */
+export async function withTimeout(label, timeoutMs, call) {
+    let timer;
+    try {
+        return await Promise.race([
+            call(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new CallError(`${label}: no answer within ${timeoutMs / 1000} seconds`)), timeoutMs);
+            }),
+        ]);
+    }
+    catch (error) {
+        if (error instanceof CallError)
+            throw error;
+        throw new CallError(`${label}: the call failed`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/plan/diff.d.ts

@@ -136,6 +136,8 @@ export interface PlanOrgOptions {
     backupStorageUuid?: string | null;
     /** Every Coolify server the host lists, for blue/green (`plan/blue-green.ts`). Absent: the host cannot list them. */
     blueGreenServers?: readonly BlueGreenServer[];
+    /** The company's stage mail sink is recorded and its live app is stopped or gone. */
+    stageSinkDown?: boolean;
 }
 export interface PlanDetail {
     orgId: OrgId;

package/dist/plan/diff.js

@@ -491,6 +491,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
         servers: options.blueGreenServers,
         canHoldSecrets: platformReadiness.canHoldSecrets === true,
         accessProviderId: platformReadiness.accessProviderId ?? null,
+        ...(options.stageSinkDown ? { stageSinkDown: true } : {}),
         appPlanned: (entryKey) => plannedSteps.some((p) => p.action.system === 'coolify' &&
             p.action.kind === 'app' &&
             p.action.key === appStepKey(org, entryKey)),

package/dist/plan/executor.d.ts

@@ -2374,6 +2374,8 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * blue copy is not recorded. The health token is only read here, never minted.
      */
     releaseHost(org: DeclaredOrg, subject: BlueGreenSubject, context: ReleaseContext, renew: () => Promise<void>): ReleaseHost | null;
+    /** Whether the stage mail sink app is stopped or gone, read live. A failed read throws; the caller reads that as up. */
+    stageSinkDown(appId: string): Promise<boolean>;
     /** Every server Coolify lists with whether it is usable and reachable, for the planner. */
     blueGreenServers(): Promise<BlueGreenServer[]>;
     /**

package/dist/plan/executor.js

@@ -2905,6 +2905,17 @@ export class FoundryStepExecutor {
             label: `coolify:release:${subject.id}`,
         });
     }
+    /** Whether the stage mail sink app is stopped or gone, read live. A failed read throws; the caller reads that as up. */
+    async stageSinkDown(appId) {
+        try {
+            return !isRunningOrStarting((await this.ports.coolify.getApplication(appId)).status);
+        }
+        catch (error) {
+            if (isNotFoundError(error))
+                return true;
+            throw error;
+        }
+    }
     /** Every server Coolify lists with whether it is usable and reachable, for the planner. */
     async blueGreenServers() {
         return (await this.ports.coolify.listServers()).map((s) => ({
@@ -3014,6 +3025,7 @@ export class FoundryStepExecutor {
             logDir: LOG_DIR,
             isRunning: isRunningOrStarting,
             stageGuards: this.stageGuards(org, subject, recorded(), action.desired.accessProviderId),
+            stageSink: { slug: org.slug },
         };
         if (action.kind === 'bluegreen-lb') {
             await applyBlueGreenWeights(deps, subject, { uuid: serverUuid, primaryUuid });
@@ -9324,9 +9336,21 @@ export class FoundryStepExecutor {
                     }
                     return;
                 }
-                case 'coolify:bg-database':
+                case 'coolify:bg-database': {
+                    // Copies of production (`<base>-stage-db-copy-*`) are never all recorded; they go with the org.
+                    const all = await this.ports.coolify.listDatabases();
+                    const name = all.find((d) => d.uuid === target.id)?.name;
+                    const base = name ? /^(.+)-stage-db(?:-copy-.+)?$/.exec(name)?.[1] : undefined;
+                    if (base) {
+                        for (const d of all) {
+                            if (d.uuid !== target.id && d.name.startsWith(`${base}-stage-db-copy-`)) {
+                                await this.ports.coolify.deleteDatabase(d.uuid);
+                            }
+                        }
+                    }
                     await this.ports.coolify.deleteDatabase(target.id);
                     return;
+                }
                 case 'coolify:database':
                     await this.ports.coolify.deleteDatabase(target.id);
                     return;

package/dist/plan/index.d.ts

@@ -41,6 +41,11 @@ export { createZitadelOrgMetadata } from './zitadel-org-metadata.js';
 export { createZitadelProjectRoles } from './zitadel-project-roles.js';
 export { DumpError, dumpNow } from './database-dump.js';
 export type { DatabaseDump } from './database-dump.js';
+export { STAGE_SINK_APPLIED_SCOPE_KEY, STAGE_SINK_IMAGE_REF, STAGE_SINK_SMTP_PORT, stageMailEnv, stageSinkAppName, stageSinkInternalUrl, } from './stage-sink.js';
+export { STAGE_COPY_EXCLUDED_TABLES, StageCopyFailedError, StageCopyRefusedError, stageCopy, tableExcluded, undoStageCopy, } from './stage-copy.js';
+export type { StageCopyInput, StageCopyPort, StageCopyProduction, StageCopyRefusalReason, StageCopyRunRecord, UndoStageCopyInput, } from './stage-copy.js';
+export { StageRestoreError, StageRestoreRefusedError, createStageCopyPort, execRunner, } from './stage-copy-port.js';
+export type { Runner, StageCopyPortDeps } from './stage-copy-port.js';
 export type { CallsSfuConnection, CallsSfuConnectionPort, CallsSfuKeysPort, CallsSfuSshConnector, CallsSfuPlatformDeps, } from './platform-sfu.js';
 export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep, callsSfuAppliedFingerprint, } from './platform-sfu.js';
 export type { MailCopyJob, MailCopyPort, MailCopyStepResult } from './mail-copy.js';

package/dist/plan/index.js

@@ -26,6 +26,9 @@ export { createZitadelProjectRoles } from './zitadel-project-roles.js';
 // implements over held keys and its own SSH client, the same shape the rest
 // of `platform-providers.ts` uses for Cloudflare.
 export { DumpError, dumpNow } from './database-dump.js';
+export { STAGE_SINK_APPLIED_SCOPE_KEY, STAGE_SINK_IMAGE_REF, STAGE_SINK_SMTP_PORT, stageMailEnv, stageSinkAppName, stageSinkInternalUrl, } from './stage-sink.js';
+export { STAGE_COPY_EXCLUDED_TABLES, StageCopyFailedError, StageCopyRefusedError, stageCopy, tableExcluded, undoStageCopy, } from './stage-copy.js';
+export { StageRestoreError, StageRestoreRefusedError, createStageCopyPort, execRunner, } from './stage-copy-port.js';
 export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep, callsSfuAppliedFingerprint, } from './platform-sfu.js';
 export { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, MissingMailCopyAccountsError, MissingMailCopySourceTokenError, MissingMailCopyStalwartTokenError, parseMailCopyCompleted, runMailCopyStep, } from './mail-copy.js';
 export { ProvidersAiReader, ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeLoginHostResolver, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';

package/dist/plan/plan-apply.d.ts

@@ -219,6 +219,8 @@ export interface StepExecutor {
         usable: boolean;
         reachable: boolean;
     }>>;
+    /** Whether the company's stage mail sink app (by Coolify id) is stopped or gone, read live. Optional: an executor without it reads the sink as up. */
+    stageSinkDown?(appId: string): Promise<boolean>;
     /**
      * The release runner's outside calls for one blue/green entry (`plan/release-host.ts`); `null` while its blue
      * copy is not recorded. Optional: an executor without it runs no release.

package/dist/plan/plan-apply.js

@@ -1313,6 +1313,10 @@ export class FoundryPlanApply {
         const blueGreenServers = declaresBlueGreen(org) && this.executor.blueGreenServers
             ? await this.executor.blueGreenServers().catch(() => undefined)
             : undefined;
+        const sinkId = recorded.stage_sink_app;
+        const stageSinkDown = sinkId && recorded.stage_sink_applied && declaresBlueGreen(org) && this.executor.stageSinkDown
+            ? await this.executor.stageSinkDown(sinkId).catch(() => false)
+            : false;
         const detail = computePlanDetail(org, live, applied?.serviceIds ?? {}, agoraHost, this.jobsScheduler, platformReadiness, {
             loginHostBindings: this.loginHostBindings,
             loginHostClientOrganizations: this.loginHostClientOrganizations,
@@ -1343,6 +1347,7 @@ export class FoundryPlanApply {
             customersDirectory: this.executor.customersDirectoryAvailable?.() ?? false,
             bouleArchonCredential: this.executor.bouleArchonCredentialAvailable?.() ?? false,
             ...(blueGreenServers ? { blueGreenServers } : {}),
+            ...(stageSinkDown ? { stageSinkDown } : {}),
             ...(blueGreenServers && org.hosting.entries.some((e) => e.blueGreen && e.database)
                 ? {
                     remoteDatabase: remoteDatabaseFactsFrom({
@@ -2137,9 +2142,9 @@ function destroyStepDescriptions(targets) {
         'delete the declared org',
     ];
 }
-/** Scope keys of the Coolify apps blue/green made: `bg.<entry>.app.<server>.<part>`, a database sidecar, a connector on another server. */
-const BLUE_GREEN_APP_KEY = /^(bg\.[^.:]+\.app\.[^.:]+\.[a-z]+|bgdb\.[^.:]+\.sidecar\.[^.:]+|cloudflare_tunnel_connector_app\.[^.:]+)$/;
-const BLUE_GREEN_DATABASE_KEY = /^bg\.[^.:]+\.stagedb$/;
+/** Scope keys of the Coolify apps blue/green made: `bg.<entry>.app.<server>.<part>`, a database sidecar, a connector on another server, the company's stage mail sink (`stage_sink_app`). */
+const BLUE_GREEN_APP_KEY = /^(bg\.[^.:]+\.app\.[^.:]+\.[a-z]+|bgdb\.[^.:]+\.sidecar\.[^.:]+|cloudflare_tunnel_connector_app\.[^.:]+|stage_sink_app)$/;
+const BLUE_GREEN_DATABASE_KEY = /^bg\.[^.:]+\.(stagedb|stagekept)$/;
 /** Stage's Access gate (`bg.<entry>.stagegate`), and the database route's Cloudflare parts: its Access app, its service token (also one minted and never delivered) and its DNS record (recorded as the route). */
 const BLUE_GREEN_EDGE_KEYS = [
     [/^bgdb\.[^.:]+\.access$/, 'bg-access'],

package/dist/plan/platform-providers.js

@@ -4016,8 +4016,8 @@ async function switchOnArchonIdTokenUserinfo(context, deps) {
     try {
         done = await zitadel.updateOidcAppIdTokenUserinfoAssertion(orgId, projectId, appId);
     }
-    catch {
-        throw new Error(`platform:archon: switching on user info in the ID token failed for the sign-in client ${appId}`);
+    catch (error) {
+        throw new Error(`platform:archon: switching on user info in the ID token failed for the sign-in client ${appId}${zitadelRefusal(error)}`);
     }
     // A client that answers every property (`packages/local`) resolves to something else: no marker.
     if (typeof done !== 'boolean')
@@ -4052,13 +4052,29 @@ async function updateArchonPostLogoutUris(context, deps) {
     try {
         await zitadel.updateOidcAppPostLogoutRedirectUris(orgId, projectId, appId, uris);
     }
-    catch {
-        throw new Error(`platform:archon: updating the post-logout addresses failed for the sign-in client ${appId}`);
+    catch (error) {
+        throw new Error(`platform:archon: updating the post-logout addresses failed for the sign-in client ${appId}${zitadelRefusal(error)}`);
     }
     context.recordScopeId(PLATFORM_ARCHON_POST_LOGOUT_APPLIED_SCOPE_KEY, postLogoutAppliedValue(appId, uris));
     await context.persist?.();
     return {};
 }
+/**
+ * What ZITADEL answered, for an error about one of Archon's sign-in client repairs: its HTTP status,
+ * gRPC code and own message (ZITADEL's error ids, never a token or a request body), capped. Empty for
+ * anything that is not a ZITADEL answer, so a network failure names no cause it cannot vouch for.
+ */
+function zitadelRefusal(error) {
+    if (!(error instanceof Error) || error.name !== 'ZitadelError')
+        return '';
+    const { status, code } = error;
+    const parts = [
+        typeof status === 'number' ? `HTTP ${status}` : '',
+        typeof code === 'number' ? `code ${code}` : '',
+    ];
+    const said = error.message.slice(0, 200);
+    return ` (ZITADEL answered ${[...parts.filter(Boolean), said].join(', ')})`;
+}
 /**
  * #339: registers `/auth/desktop/callback` on Archon's sign-in client
  * (`zitadel:desktop-callback` keyed {@link PLATFORM_ARCHON_KEY}), keeping the
@@ -4089,8 +4105,8 @@ async function registerArchonDesktopCallback(context, deps) {
             await zitadel.updateOidcAppRedirectUris(orgId, projectId, appId, union);
         }
     }
-    catch {
-        throw new Error(`platform:archon: registering the desktop callback failed for the sign-in client ${appId}`);
+    catch (error) {
+        throw new Error(`platform:archon: registering the desktop callback failed for the sign-in client ${appId}${zitadelRefusal(error)}`);
     }
     context.recordScopeId(PLATFORM_ARCHON_DESKTOP_CALLBACK_APPLIED_SCOPE_KEY, appId);
     await context.persist?.();

package/dist/plan/stage-copy-port.d.ts

@@ -0,0 +1,62 @@
+import type { DatabaseDump } from './database-dump.js';
+import { type StageCopyPort } from './stage-copy.js';
+/** Thrown before anything is run or fetched. Fixed text: never the URL it refused. */
+export declare class StageRestoreRefusedError extends Error {
+    constructor(reason: string);
+}
+/** Thrown when a step of the restore failed. Fixed text only: the cause can echo a connection URL. */
+export declare class StageRestoreError extends Error {
+    constructor(step: string);
+}
+export interface RunResult {
+    exitCode: number;
+    stdout: string;
+}
+/** Runs a program with exactly `env` (nothing inherited) and kills it after `timeoutMs`. */
+export type Runner = (command: string, args: readonly string[], options: {
+    env: Readonly<Record<string, string>>;
+    timeoutMs: number;
+    /** Kills the program when aborted. */
+    signal?: AbortSignal;
+}) => Promise<RunResult>;
+/** The default {@link Runner}: `execFile`, stderr dropped, no shell. */
+export declare const execRunner: Runner;
+export interface StageCopyPortTimeouts {
+    /** Saving the dump from the backup bucket. Default 10 minutes. */
+    fetchMs?: number;
+    /** Reading the dump's table of contents. Default 2 minutes. */
+    listMs?: number;
+    /** `pg_restore`. Default 30 minutes. */
+    restoreMs?: number;
+    /** Creating or syncing the runtime role. Default 2 minutes. */
+    roleMs?: number;
+}
+export interface StageCopyPortDeps {
+    /** Every connection URL production's database answers at. A target on the same host, port and database is refused. */
+    productionUrls: () => Promise<readonly string[]>;
+    /** Saves the dump from the backup bucket to a local file; `remove` deletes it. */
+    fetchDump: (location: DatabaseDump['location'], signal?: AbortSignal) => Promise<{
+        path: string;
+        remove: () => Promise<void>;
+    }>;
+    run?: Runner;
+    /** Default: `@wtfalch/db/runtime-role`'s `ensureRuntimeRole`. */
+    ensureRole?: (options: {
+        ownerUrl: string;
+        runtimeUrl: string;
+        log: () => void;
+    }) => Promise<unknown>;
+    timeouts?: StageCopyPortTimeouts;
+}
+/** The table of contents of a dump without the data of the excluded tables. */
+export declare function filterToc(toc: string, patterns: readonly string[]): {
+    list: string;
+    excluded: number;
+};
+/**
+ * The concrete {@link StageCopyPort}. It restores a dump into a stage database and sets up that database's runtime
+ * role, and refuses any target that is not a stage database or that is production's. Connection settings reach
+ * the programs as `PG*` env, never as arguments. Every outside call has a timeout, and an error carries fixed text
+ * only.
+ */
+export declare function createStageCopyPort(deps: StageCopyPortDeps): StageCopyPort;