@wtfalch/foundry 0.48.0 → 0.50.0

package/dist/plan/stage-copy.js

@@ -0,0 +1,538 @@
+import { randomBytes } from 'node:crypto';
+import { runtimeDatabaseUrl } from './blue-green-apply.js';
+import { bgKey, stageKindOf } from './blue-green.js';
+import { withTimeout } from './call-timeout.js';
+import { dumpNow } from './database-dump.js';
+import { waitForDeploymentFinished } from './deploy-health.js';
+import { getDatabaseStarted } from './executor.js';
+import { stageGuardsReady } from './stage-guards.js';
+import { assertStageIsolated, envClass } from './stage-isolation.js';
+import { STAGE_SINK_APPLIED_SCOPE_KEY, stageMailEnv } from './stage-sink.js';
+/**
+ * Table names whose rows the exact copy leaves out (SQL structure is still restored). `*` matches any run of
+ * characters. Sessions and tokens are dropped so a copied sign-in or API token is useless on stage; the keystore
+ * and held-key tables hold ciphertext that stage must never be able to open (stage gets no production key).
+ */
+export const STAGE_COPY_EXCLUDED_TABLES = [
+    'keystore_*',
+    'keys_held_*',
+    '*session*',
+    '*token*',
+];
+/** Whether `table` is on {@link STAGE_COPY_EXCLUDED_TABLES}. Case-insensitive, like Postgres folds names. */
+export function tableExcluded(table, patterns = STAGE_COPY_EXCLUDED_TABLES) {
+    const name = table.toLowerCase();
+    return patterns.some((pattern) => {
+        const parts = pattern.toLowerCase().split('*');
+        return new RegExp(`^${parts.map((p) => p.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*')}$`).test(name);
+    });
+}
+/** Thrown before anything is touched. Fixed text and names only. */
+export class StageCopyRefusedError extends Error {
+    reason;
+    missing;
+    constructor(reason, missing = []) {
+        super(`stage copy refused: ${reason}${missing.length > 0 ? ` (${missing.join(', ')})` : ''}`);
+        this.reason = reason;
+        this.missing = missing;
+        this.name = 'StageCopyRefusedError';
+    }
+}
+/** Thrown once a run started; carries what happened so far. */
+export class StageCopyFailedError extends Error {
+    record;
+    constructor(message, record) {
+        super(`stage copy failed: ${message}`);
+        this.record = record;
+        this.name = 'StageCopyFailedError';
+    }
+}
+const DEFAULTS = {
+    callMs: 30_000,
+    restoreMs: 2_640_000,
+    deployMs: 960_000,
+    roleMs: 120_000,
+    databaseStartMs: 180_000,
+    appRunningMs: 120_000,
+    appPollMs: 2_000,
+};
+const COPY_PREFIX = (base) => `${base}-stage-db-copy-`;
+const pgNameOf = (base) => `${base}-stage-db`.replace(/-/g, '_');
+const OWNER_ENV = 'DATABASE_URL_OWNER';
+const RUNTIME_ENV = 'DATABASE_URL';
+function requireText(name, value) {
+    if (typeof value !== 'string' ||
+        value.length === 0 ||
+        [...value].some((c) => c.charCodeAt(0) < 32)) {
+        throw new TypeError(`stage copy: ${name} must be a non-empty single-line string`);
+    }
+    return value;
+}
+function positive(name, value) {
+    if (!(value > 0))
+        throw new TypeError(`stage copy: ${name} must be positive`);
+    return value;
+}
+function settings(timeouts) {
+    const t = timeouts ?? {};
+    return {
+        callMs: positive('callMs', t.callMs ?? DEFAULTS.callMs),
+        dumpMs: t.dumpMs === undefined ? undefined : positive('dumpMs', t.dumpMs),
+        restoreMs: positive('restoreMs', t.restoreMs ?? DEFAULTS.restoreMs),
+        deployMs: positive('deployMs', t.deployMs ?? DEFAULTS.deployMs),
+        roleMs: positive('roleMs', t.roleMs ?? DEFAULTS.roleMs),
+        databaseStartMs: positive('databaseStartMs', t.databaseStartMs ?? DEFAULTS.databaseStartMs),
+        appRunningMs: positive('appRunningMs', t.appRunningMs ?? DEFAULTS.appRunningMs),
+        appPollMs: positive('appPollMs', t.appPollMs ?? DEFAULTS.appPollMs),
+    };
+}
+class Run {
+    requestedBy;
+    now;
+    steps = [];
+    dumpExecutionId;
+    liveDatabaseId;
+    constructor(requestedBy, now, liveDatabaseId) {
+        this.requestedBy = requestedBy;
+        this.now = now;
+        this.liveDatabaseId = liveDatabaseId;
+    }
+    ok(step) {
+        this.steps.push({ step, outcome: 'ok' });
+    }
+    fail(step, detail) {
+        this.steps.push({ step, outcome: 'failed', detail });
+        return new StageCopyFailedError(detail, this.record());
+    }
+    record() {
+        return {
+            requestedBy: this.requestedBy,
+            at: new Date(this.now()).toISOString(),
+            liveDatabaseId: this.liveDatabaseId,
+            ...(this.dumpExecutionId ? { dumpExecutionId: this.dumpExecutionId } : {}),
+            steps: [...this.steps],
+        };
+    }
+}
+async function readStageUrls(base, cfg, appId) {
+    const envs = await withTimeout('stage copy: read the stage env', cfg.callMs, () => base.coolify.listEnvs(appId));
+    const get = (key) => envs.find((e) => e.key === key && !e.is_preview)?.value;
+    const owner = get(OWNER_ENV);
+    if (!owner)
+        throw new Error('the stage app has no owner database URL');
+    return { owner, runtime: get(RUNTIME_ENV) };
+}
+/** Waits for `running:healthy`. Called only after a new deployment finished, never on an old status. */
+async function waitHealthy(base, cfg, appId) {
+    const deadline = Date.now() + cfg.appRunningMs;
+    for (;;) {
+        const { status } = await withTimeout('stage copy: read the stage app', cfg.callMs, () => base.coolify.getApplication(appId));
+        if (status === 'running:healthy')
+            return true;
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, cfg.appPollMs));
+    }
+}
+async function stopApp(base, cfg, appId) {
+    await withTimeout('stage copy: stop the stage app', cfg.callMs, () => base.coolify.raw('POST', `/applications/${appId}/stop`));
+}
+/** Starts the stage app as a new deployment and waits for Coolify's record of it to finish. */
+async function deployApp(base, cfg, appId) {
+    await withTimeout('stage copy: deploy the stage app', cfg.deployMs, () => waitForDeploymentFinished(base.coolify, appId, {}, 'stage copy', 'the stage app stays as it was'));
+}
+async function pushUrls(base, cfg, appId, urls) {
+    const envs = [{ key: OWNER_ENV, value: urls.owner }];
+    if (urls.runtime)
+        envs.push({ key: RUNTIME_ENV, value: urls.runtime });
+    await withTimeout('stage copy: write the stage env', cfg.callMs, async () => {
+        await base.coolify.bulkUpsertEnvs(appId, envs.map((e) => ({ ...e, literal: true })));
+        if (urls.runtime)
+            return;
+        // The database the app goes back to had no runtime URL: the forward one must not stay.
+        for (const row of await base.coolify.listEnvs(appId)) {
+            if (row.key === RUNTIME_ENV && row.uuid)
+                await base.coolify.deleteEnv(appId, row.uuid);
+        }
+    });
+}
+/**
+ * Points the stage app at `to`: stop, write the two URLs, deploy anew, wait until it is healthy. When any part fails the app
+ * is pointed back at `from` the same way. `true`: stage runs on `to`. `false`: it was put back on `from` (or
+ * that could not be confirmed either; `recovered` says which).
+ */
+async function switchStage(base, cfg, appId, from, to) {
+    const attempt = async (urls) => {
+        await stopApp(base, cfg, appId);
+        await pushUrls(base, cfg, appId, urls);
+        await deployApp(base, cfg, appId);
+        return waitHealthy(base, cfg, appId);
+    };
+    try {
+        if (await attempt(to))
+            return { switched: true, recovered: true };
+    }
+    catch (error) {
+        logFailure('pointing stage at the new database', error);
+    }
+    try {
+        return { switched: false, recovered: await attempt(from) };
+    }
+    catch (error) {
+        logFailure('pointing stage back at its database', error);
+        return { switched: false, recovered: false };
+    }
+}
+/** Fixed text and the error name; the cause can echo a connection URL. */
+function logFailure(what, error) {
+    console.error(`stage copy: ${what} failed (${error instanceof Error ? error.name : 'unknown'})`);
+}
+const dbIdentity = (url) => {
+    try {
+        const u = new URL(url);
+        return `${u.hostname.toLowerCase()}:${u.port || '5432'}${u.pathname}`;
+    }
+    catch {
+        return null;
+    }
+};
+/** Whether stage's live owner URL points at this Coolify database. A database that cannot be read counts as live. */
+async function runsOn(base, cfg, uuid, liveOwnerUrl) {
+    try {
+        const { internal_db_url: url } = await withTimeout('stage copy: read a database', cfg.callMs, () => base.coolify.getDatabase(uuid));
+        const live = dbIdentity(liveOwnerUrl);
+        return url === undefined || live === null || dbIdentity(url) === live;
+    }
+    catch (error) {
+        logFailure('reading a database', error);
+        return true;
+    }
+}
+async function deleteQuietly(base, cfg, uuid) {
+    try {
+        await withTimeout('stage copy: delete a database', cfg.callMs, () => base.coolify.deleteDatabase(uuid));
+    }
+    catch (error) {
+        // The next copy deletes every database with the copy prefix that stage does not run on.
+        logFailure('deleting a database', error);
+    }
+}
+function checkInput(base) {
+    requireText('requestedBy', base.requestedBy);
+    requireText('subject.id', base.subject.id);
+    requireText('subject.base', base.subject.base);
+}
+/** The ids stage runs on, or the refusal. */
+function stageIds(base) {
+    const recorded = base.recorded();
+    const { subject } = base;
+    if (!subject.database)
+        throw new StageCopyRefusedError('no-stage-database');
+    const databaseId = recorded[bgKey.stageDatabase(subject.id)];
+    if (!databaseId)
+        throw new StageCopyRefusedError('no-stage-database');
+    const appKeyPrefix = `bg.${subject.id}.app.`;
+    const appId = Object.entries(recorded).find(([key, value]) => key.startsWith(appKeyPrefix) && key.endsWith('.stage') && value)?.[1];
+    if (!appId)
+        throw new StageCopyRefusedError('no-stage-app');
+    return { appId, databaseId };
+}
+/**
+ * Copies production's database into stage, exact except for {@link STAGE_COPY_EXCLUDED_TABLES}, on request. It
+ * refuses until the stage guards and the sink are in place, dumps production through Coolify (it never holds a
+ * production URL), restores into a new database beside stage's and points stage at it. Stage's database is
+ * recorded only once stage runs on the new one.
+ *
+ * What a failure leaves behind, by point: refusal or dump failure: nothing changed. New database made, restore
+ * or role failed: the new database is deleted, stage untouched. Switch failed: stage is pointed back at its own
+ * database and the new one deleted; if putting it back also failed the run says so (`recovered: false`) and the
+ * new database is left for the next run's sweep. Recording: the three records are written in memory and
+ * persisted once, so a crash leaves either all or none.
+ */
+export async function stageCopy(input) {
+    checkInput(input);
+    const cfg = settings(input.timeouts);
+    const { subject, coolify } = input;
+    const id = subject.id;
+    const recorded = input.recorded();
+    const guards = stageGuardsReady(recorded, id);
+    if (!guards.ready)
+        throw new StageCopyRefusedError('guards', guards.missing);
+    if (!recorded[STAGE_SINK_APPLIED_SCOPE_KEY] || !recorded[bgKey.stageSink(id)]) {
+        throw new StageCopyRefusedError('sink');
+    }
+    const production = input.production;
+    if (!production)
+        throw new StageCopyRefusedError('no-production-database');
+    for (const [name, value] of Object.entries(production))
+        requireText(`production.${name}`, value);
+    const { appId, databaseId: stageDbId } = stageIds(input);
+    if (production.databaseUuid === stageDbId) {
+        throw new StageCopyRefusedError('no-production-database');
+    }
+    if (!input.projectUuid || !input.serverUuid)
+        throw new StageCopyRefusedError('no-coolify-project');
+    const stageEnv = await withTimeout('stage copy: read the stage env', cfg.callMs, () => coolify.listEnvs(appId));
+    const wanted = stageMailEnv(input.org);
+    const have = new Map(stageEnv.filter((e) => !e.is_preview).map((e) => [e.key, e.value]));
+    if (wanted.some((e) => have.get(e.key) !== e.value)) {
+        throw new StageCopyRefusedError('stage-sink-env');
+    }
+    // Whatever was added to stage by hand (a mail token, an SMTP setting) blocks the copy; names only.
+    const violations = assertStageIsolated({
+        kind: stageKindOf(subject),
+        prod: { env: [], resources: {} },
+        stage: {
+            env: [...have].map(([name, value]) => ({ name, class: envClass(name), value })),
+            resources: {},
+        },
+        sinkMail: Object.fromEntries(wanted.map((e) => [e.key, e.value])),
+    });
+    if (violations.length > 0)
+        throw new StageCopyRefusedError('stage-isolation', violations);
+    // The database stage really runs on, whatever the records say: the sweep below never deletes it.
+    const liveOwnerUrl = have.get(OWNER_ENV);
+    if (!liveOwnerUrl)
+        throw new StageCopyRefusedError('no-stage-database');
+    const run = new Run(input.requestedBy, input.now ?? Date.now, stageDbId);
+    const pgName = pgNameOf(subject.base);
+    const runtimeRole = `${pgName}_rt`;
+    let dump;
+    try {
+        dump = await dumpNow(coolify, {
+            ...production,
+            ...(cfg.dumpMs !== undefined ? { timeoutMs: cfg.dumpMs } : {}),
+        });
+    }
+    catch (error) {
+        logFailure('dumping production', error);
+        throw run.fail('dump', 'the production dump failed');
+    }
+    run.dumpExecutionId = dump.executionId;
+    run.ok('dump');
+    // Databases an earlier run left (the kept one, a failed copy): stage never runs on them.
+    const prefix = COPY_PREFIX(subject.base);
+    const previousKept = recorded[bgKey.stageKept(id)];
+    const listed = await withTimeout('stage copy: list databases', cfg.callMs, () => coolify.listDatabases());
+    for (const database of listed) {
+        if (database.uuid === stageDbId)
+            continue;
+        if (database.name.startsWith(prefix) || database.uuid === previousKept) {
+            if (await runsOn(input, cfg, database.uuid, liveOwnerUrl))
+                continue;
+            await deleteQuietly(input, cfg, database.uuid);
+        }
+    }
+    if (previousKept) {
+        input.record(bgKey.stageKept(id), '');
+        await input.persist();
+    }
+    run.ok('drop-older');
+    const { environment } = await withTimeout('stage copy: find the environment', cfg.callMs, () => coolify.findOrCreateEnvironment(input.projectUuid, 'production'));
+    let created;
+    try {
+        created = await withTimeout('stage copy: create the database', cfg.callMs, () => coolify.createPostgresDatabase({
+            project_uuid: input.projectUuid,
+            server_uuid: input.serverUuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            name: `${prefix}${run.now().toString(36)}`,
+            postgres_db: pgName,
+            postgres_user: pgName,
+        }));
+    }
+    catch (error) {
+        logFailure('creating the database', error);
+        throw run.fail('create', 'the new database could not be made');
+    }
+    const newDbId = created.uuid;
+    let ownerUrl = created.internal_db_url;
+    input.secret?.(ownerUrl);
+    const discard = async (step, detail) => {
+        await deleteQuietly(input, cfg, newDbId);
+        throw run.fail(step, detail);
+    };
+    try {
+        const started = await withTimeout('stage copy: start the database', cfg.databaseStartMs, () => getDatabaseStarted(coolify, newDbId));
+        if (started.internal_db_url) {
+            ownerUrl = started.internal_db_url;
+            input.secret?.(ownerUrl);
+        }
+    }
+    catch (error) {
+        logFailure('starting the new database', error);
+        return discard('start-database', 'the new database did not start');
+    }
+    const abort = new AbortController();
+    let restoring = Promise.resolve();
+    let restored;
+    try {
+        restored = await withTimeout('stage copy: restore', cfg.restoreMs, () => {
+            const running = input.restore.runRestore({
+                location: dump.location,
+                targetDatabaseUrl: ownerUrl,
+                ownerRole: pgName,
+                excludeTableData: STAGE_COPY_EXCLUDED_TABLES,
+                signal: abort.signal,
+            });
+            restoring = running.catch(() => undefined);
+            return running;
+        });
+    }
+    catch (error) {
+        logFailure('restoring', error);
+        // Stop pg_restore and let it finish before the database goes: it must not write into a deleted one.
+        abort.abort();
+        const stopped = await withTimeout('stage copy: stop the restore', cfg.callMs, () => restoring.then(() => true)).catch(() => false);
+        if (!stopped)
+            throw run.fail('restore', 'the restore failed and could not be stopped');
+        return discard('restore', 'the restore failed');
+    }
+    if (restored.exitCode !== 0)
+        return discard('restore', 'the restore failed');
+    run.ok('restore');
+    const password = randomBytes(24).toString('base64url');
+    input.secret?.(password);
+    const runtimeUrl = runtimeDatabaseUrl(ownerUrl, runtimeRole, password);
+    if (!runtimeUrl)
+        return discard('runtime-role', 'the new database URL could not be read');
+    input.secret?.(runtimeUrl);
+    try {
+        const roled = await withTimeout('stage copy: runtime role', cfg.roleMs, () => input.restore.ensureRuntimeRole({
+            targetDatabaseUrl: ownerUrl,
+            runtimeRole,
+            runtimePassword: password,
+        }));
+        if (roled.exitCode !== 0)
+            return discard('runtime-role', 'the runtime role failed');
+    }
+    catch (error) {
+        logFailure('setting the runtime role', error);
+        return discard('runtime-role', 'the runtime role failed');
+    }
+    run.ok('runtime-role');
+    let from;
+    try {
+        from = await readStageUrls(input, cfg, appId);
+    }
+    catch (error) {
+        logFailure('reading the stage env', error);
+        return discard('switch', 'the stage env could not be read');
+    }
+    for (const value of [from.owner, from.runtime])
+        if (value)
+            input.secret?.(value);
+    const result = await switchStage(input, cfg, appId, from, {
+        owner: ownerUrl,
+        runtime: runtimeUrl,
+    });
+    if (!result.switched) {
+        if (result.recovered)
+            await deleteQuietly(input, cfg, newDbId);
+        throw run.fail('switch', result.recovered
+            ? 'stage did not run on the new database; it runs on its own database again'
+            : 'stage did not run on the new database, and putting it back could not be confirmed');
+    }
+    run.ok('switch');
+    input.record(bgKey.stageKept(id), stageDbId);
+    input.record(bgKey.stageDatabase(id), newDbId);
+    input.record(bgKey.stageCopy(id), `${new Date(run.now()).toISOString()}|${dump.executionId}|ok`);
+    run.liveDatabaseId = newDbId;
+    try {
+        await input.persist();
+    }
+    catch (error) {
+        // Stage runs on the new database but the records did not land. The next sweep reads stage's live
+        // database from its env, so it keeps this one.
+        logFailure('recording the new database', error);
+        throw run.fail('record', 'stage runs on the new database but recording it failed');
+    }
+    run.ok('record');
+    return run.record();
+}
+/**
+ * Puts the database stage ran on before the last copy back, and deletes the one the copy made. It mints a new
+ * runtime password for the kept database (the old one is gone from stage's env). A failure leaves stage on the
+ * database it ran on, switched back the same way a failed copy does, and records nothing.
+ */
+export async function undoStageCopy(input) {
+    checkInput(input);
+    const cfg = settings(input.timeouts);
+    const { subject, coolify } = input;
+    const id = subject.id;
+    const { appId, databaseId: currentDbId } = stageIds(input);
+    const keptId = input.recorded()[bgKey.stageKept(id)];
+    if (!keptId || keptId === currentDbId)
+        throw new StageCopyRefusedError('no-kept-database');
+    const run = new Run(input.requestedBy, input.now ?? Date.now, currentDbId);
+    const pgName = pgNameOf(subject.base);
+    const runtimeRole = `${pgName}_rt`;
+    let ownerUrl;
+    try {
+        const kept = await withTimeout('stage copy: start the kept database', cfg.databaseStartMs, () => getDatabaseStarted(coolify, keptId));
+        if (!kept.internal_db_url)
+            throw new Error('no URL');
+        ownerUrl = kept.internal_db_url;
+    }
+    catch (error) {
+        logFailure('reading the kept database', error);
+        throw new StageCopyRefusedError('no-kept-database');
+    }
+    input.secret?.(ownerUrl);
+    const password = randomBytes(24).toString('base64url');
+    input.secret?.(password);
+    const runtimeUrl = runtimeDatabaseUrl(ownerUrl, runtimeRole, password);
+    if (!runtimeUrl)
+        throw run.fail('runtime-role', 'the kept database URL could not be read');
+    input.secret?.(runtimeUrl);
+    try {
+        const roled = await withTimeout('stage copy: runtime role', cfg.roleMs, () => input.restore.ensureRuntimeRole({
+            targetDatabaseUrl: ownerUrl,
+            runtimeRole,
+            runtimePassword: password,
+        }));
+        if (roled.exitCode !== 0)
+            throw run.fail('runtime-role', 'the runtime role failed');
+    }
+    catch (error) {
+        if (error instanceof StageCopyFailedError)
+            throw error;
+        logFailure('setting the runtime role', error);
+        throw run.fail('runtime-role', 'the runtime role failed');
+    }
+    run.ok('runtime-role');
+    let from;
+    try {
+        from = await readStageUrls(input, cfg, appId);
+    }
+    catch (error) {
+        logFailure('reading the stage env', error);
+        throw run.fail('switch', 'the stage env could not be read');
+    }
+    for (const value of [from.owner, from.runtime])
+        if (value)
+            input.secret?.(value);
+    const result = await switchStage(input, cfg, appId, from, {
+        owner: ownerUrl,
+        runtime: runtimeUrl,
+    });
+    if (!result.switched) {
+        throw run.fail('switch', result.recovered
+            ? 'stage did not run on the kept database; it runs on its own database again'
+            : 'stage did not run on the kept database, and putting it back could not be confirmed');
+    }
+    run.ok('switch');
+    input.record(bgKey.stageDatabase(id), keptId);
+    input.record(bgKey.stageKept(id), '');
+    run.liveDatabaseId = keptId;
+    try {
+        await input.persist();
+    }
+    catch (error) {
+        logFailure('recording the kept database', error);
+        throw run.fail('record', 'stage runs on the kept database but recording it failed');
+    }
+    await deleteQuietly(input, cfg, currentDbId);
+    run.ok('record');
+    return run.record();
+}

package/dist/plan/stage-sink.d.ts

@@ -0,0 +1,37 @@
+import type { DeclaredOrg } from '../org.js';
+/**
+ * Mailpit v1.31.4, pinned by digest. `@wtfalch/foundry-local` runs the same image (`packages/local/src/sink.ts`
+ * imports {@link STAGE_SINK_IMAGE_REF}), so both use the one pin. Coolify wants the repository and the tag
+ * apart, and a tag needs a real name before `@`.
+ */
+export declare const STAGE_SINK_REPOSITORY = "axllent/mailpit";
+export declare const STAGE_SINK_TAG = "v1.31.4";
+export declare const STAGE_SINK_DIGEST = "sha256:b68349e3a014b90c5610bfb26b2ae36f3892d7b8cf25ee140c6c71c98d2fcf48";
+/** `<repository>@<digest>`, for a direct Docker pull. */
+export declare const STAGE_SINK_IMAGE_REF = "axllent/mailpit@sha256:b68349e3a014b90c5610bfb26b2ae36f3892d7b8cf25ee140c6c71c98d2fcf48";
+/** `<tag>@<digest>`, for Coolify's `docker_registry_image_tag`. */
+export declare const STAGE_SINK_IMAGE_TAG = "v1.31.4@sha256:b68349e3a014b90c5610bfb26b2ae36f3892d7b8cf25ee140c6c71c98d2fcf48";
+export declare const STAGE_SINK_SMTP_PORT = 1025;
+export declare const STAGE_SINK_HTTP_PORT = 8025;
+/** Flat org scope id: `'1'` once the sink app is deployed. Recorded after the deploy, never before. */
+export declare const STAGE_SINK_APPLIED_SCOPE_KEY = "stage_sink_applied";
+/** Flat org scope id of the sink's Coolify app: one sink per company, shared by every stage. */
+export declare const STAGE_SINK_APP_SCOPE_KEY = "stage_sink_app";
+/**
+ * Part of the structure hash of a primary server. Raise it when the sink wiring changes, so an applied
+ * structure runs once more.
+ */
+export declare const STAGE_SINK_VERSION = 1;
+type SinkOrg = Pick<DeclaredOrg, 'slug'>;
+export declare const stageSinkAppName: (org: SinkOrg) => string;
+/** The sink's HTTP address on the company's Docker network. */
+export declare const stageSinkInternalUrl: (org: SinkOrg) => string;
+/**
+ * The only mail env stage holds. `@wtfalch/mailer` 0.6.0 posts every message to `MAIL_SINK_URL` when it is set,
+ * so stage holds no mail token and no Lettermint setting.
+ */
+export declare function stageMailEnv(org: SinkOrg): Array<{
+    key: string;
+    value: string;
+}>;
+export {};

package/dist/plan/stage-sink.js

@@ -0,0 +1,33 @@
+/**
+ * Mailpit v1.31.4, pinned by digest. `@wtfalch/foundry-local` runs the same image (`packages/local/src/sink.ts`
+ * imports {@link STAGE_SINK_IMAGE_REF}), so both use the one pin. Coolify wants the repository and the tag
+ * apart, and a tag needs a real name before `@`.
+ */
+export const STAGE_SINK_REPOSITORY = 'axllent/mailpit';
+export const STAGE_SINK_TAG = 'v1.31.4';
+export const STAGE_SINK_DIGEST = 'sha256:b68349e3a014b90c5610bfb26b2ae36f3892d7b8cf25ee140c6c71c98d2fcf48';
+/** `<repository>@<digest>`, for a direct Docker pull. */
+export const STAGE_SINK_IMAGE_REF = `${STAGE_SINK_REPOSITORY}@${STAGE_SINK_DIGEST}`;
+/** `<tag>@<digest>`, for Coolify's `docker_registry_image_tag`. */
+export const STAGE_SINK_IMAGE_TAG = `${STAGE_SINK_TAG}@${STAGE_SINK_DIGEST}`;
+export const STAGE_SINK_SMTP_PORT = 1025;
+export const STAGE_SINK_HTTP_PORT = 8025;
+/** Flat org scope id: `'1'` once the sink app is deployed. Recorded after the deploy, never before. */
+export const STAGE_SINK_APPLIED_SCOPE_KEY = 'stage_sink_applied';
+/** Flat org scope id of the sink's Coolify app: one sink per company, shared by every stage. */
+export const STAGE_SINK_APP_SCOPE_KEY = 'stage_sink_app';
+/**
+ * Part of the structure hash of a primary server. Raise it when the sink wiring changes, so an applied
+ * structure runs once more.
+ */
+export const STAGE_SINK_VERSION = 1;
+export const stageSinkAppName = (org) => `${org.slug}-stage-sink`;
+/** The sink's HTTP address on the company's Docker network. */
+export const stageSinkInternalUrl = (org) => `http://${stageSinkAppName(org)}:${STAGE_SINK_HTTP_PORT}`;
+/**
+ * The only mail env stage holds. `@wtfalch/mailer` 0.6.0 posts every message to `MAIL_SINK_URL` when it is set,
+ * so stage holds no mail token and no Lettermint setting.
+ */
+export function stageMailEnv(org) {
+    return [{ key: 'MAIL_SINK_URL', value: stageSinkInternalUrl(org) }];
+}

package/dist/store/postgres.js

@@ -1,5 +1,5 @@
 import { and, asc, desc, eq, inArray, isNull, ne, sql } from 'drizzle-orm';
-import { APP_ENTRY_KEY, DEFAULT_MAIL_APPS, DEFAULT_NO_REPLY_LOCAL_PART, refuseBuiltinBlueGreen, refuseCustomers, refuseHosting, validateBlueGreen, validateBuyerIdentity, validateCalls, validateDomain, validateDomainClaim, validateMail, validateOwners, validateServices, validateSignIn, validateSite, validateVersionPin, } from '../org.js';
+import { APP_ENTRY_KEY, DEFAULT_MAIL_APPS, DEFAULT_NO_REPLY_LOCAL_PART, normalizeHostingRepos, refuseBuiltinBlueGreen, refuseCustomers, refuseHosting, validateBlueGreen, validateBuyerIdentity, validateCalls, validateDomain, validateDomainClaim, validateMail, validateOwners, validateServices, validateSignIn, validateSite, validateVersionPin, } from '../org.js';
 import { hostingNames } from '../plan/locked-hostnames.js';
 import { findNameClashes, nameClashMessage } from '../plan/org-names.js';
 import { validatePlatform } from '../platform.js';
@@ -176,6 +176,7 @@ function rowToOrg(row) {
             issuerApps: row.hostingIssuerApps,
             entries: row.hostingEntries.map((entry) => storedEntryToEntry(entry, row.hostingUsesDomain)),
             gateLimit: row.hostingGateLimit,
+            repos: row.hostingRepos,
         },
         sso: { enabled: row.ssoEnabled },
         guests: { enabled: row.guestsEnabled },
@@ -241,6 +242,7 @@ function orgToRow(org) {
         hostingIssuerApps: org.hosting.issuerApps,
         hostingEntries: org.hosting.entries,
         hostingGateLimit: org.hosting.gateLimit,
+        hostingRepos: normalizeHostingRepos(org.hosting.repos),
         ssoEnabled: org.sso.enabled,
         guestsEnabled: org.guests.enabled,
         soloEnabled: org.solo.enabled,
@@ -569,7 +571,16 @@ export function createPostgresDeclaredOrgStore(db) {
             // just be re-litigating a write this update isn't making.
             if (patch.slug !== undefined && patch.slug !== current.slug)
                 requireValidSlug(patch.slug);
-            const next = { ...current, ...patch, id: current.id, version: current.version };
+            const merged = {
+                ...current,
+                ...patch,
+                id: current.id,
+                version: current.version,
+            };
+            const next = {
+                ...merged,
+                hosting: { ...merged.hosting, repos: normalizeHostingRepos(merged.hosting.repos) },
+            };
             requireValidDomain(next.domain);
             requireValidLimits(next);
             requireValidBuyer(next);

package/dist/store/schema.d.ts

@@ -692,6 +692,25 @@ export declare const declaredOrgs: import("drizzle-orm/pg-core").PgTableWithColu
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        hostingRepos: import("drizzle-orm/pg-core").PgColumn<{
+            name: "hosting_repos";
+            tableName: "foundry_declared_orgs";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: string[];
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: string[];
+        }>;
         ssoEnabled: import("drizzle-orm/pg-core").PgColumn<{
             name: "sso_enabled";
             tableName: "foundry_declared_orgs";