@wtfalch/foundry 0.34.0 → 0.35.1

package/dist/plan/broker-entries.js

@@ -1,8 +1,9 @@
 import { randomUUID } from 'node:crypto';
+import { isFoundryOwnedBrokerEntryName, } from '../org.js';
 import { entryClientIdScopeKey } from './agora.js';
 import { entryHostnames } from './hostnames.js';
-import { PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, parseBrokerDeployRecord, } from './platform-diff.js';
-import { brokerDeployNeeded, brokerDeployRecordValue, missingBrokerInputs, validateBrokerAppEntry, } from './platform-providers.js';
+import { PLATFORM_ARCHON_ORG_SCOPE_KEY, PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, parseBrokerDeployRecord, } from './platform-diff.js';
+import { archonOrgConflicts, brokerDeployNeeded, brokerDeployRecordValue, missingBrokerInputs, validateBrokerAppEntry, } from './platform-providers.js';
 /**
  * F5 (https://github.com/wtfalch/foundry/issues/314): an entry with
  * `uses.auth` gets one entry in the broker's `AUTH_APPS`. The org executor has
@@ -99,6 +100,9 @@ export class PlatformBrokerPort {
     async recordedDeploy() {
         return (await this.options.store.getServiceIds())[PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY];
     }
+    async archonOrganisationId() {
+        return (await this.options.store.getServiceIds())[PLATFORM_ARCHON_ORG_SCOPE_KEY] || undefined;
+    }
     async recordDeploy(value) {
         const { leases, store } = this.options;
         const lease = await leases?.acquireMutationLease('platform', randomUUID(), 60_000);
@@ -130,6 +134,11 @@ export async function writeBrokerEntry(broker, input) {
     const { want, appKey, previous } = input;
     const label = `broker entry '${want.name}'`;
     const brokerAppId = await broker.appId();
+    // Archon's organisation holds Archon's people only: its key must be the one entry that signs in there.
+    const archonOrgId = await broker.archonOrganisationId?.();
+    if (archonOrgConflicts([want], archonOrgId).length > 0) {
+        throw new Error(`${label} would sign in Archon's own organisation, which no other entry may`);
+    }
     const env = (await broker.listEnvs()).find((e) => e.key === 'AUTH_APPS' && !e.is_preview);
     // A value that reads back empty is not an empty list: writing over it
     // would drop every hand-written entry.
@@ -154,7 +163,15 @@ export async function writeBrokerEntry(broker, input) {
         entry.name === want.name &&
         (entry.organizationId === want.organizationId ||
             (previous !== null && entry.organizationId === previous.organizationId));
-    const isReplaced = (entry) => want.replaces !== null && isObject(entry) && entry.name === want.replaces && !isOwn(entry);
+    if (want.replaces !== null && isFoundryOwnedBrokerEntryName(want.replaces)) {
+        throw new Error(`${label}: it may not replace '${want.replaces}', a broker entry foundry writes itself`);
+    }
+    // Only an entry in the same organisation: another company's entry of that name stays.
+    const isReplaced = (entry) => want.replaces !== null &&
+        isObject(entry) &&
+        entry.name === want.replaces &&
+        entry.organizationId === want.organizationId &&
+        !isOwn(entry);
     const entry = {
         ...(current.find(isOwn) ?? {}),
         organizationId: want.organizationId,

package/dist/plan/build-record.d.ts

@@ -0,0 +1,56 @@
+import type { PlanNote } from '../plan.js';
+import type { DeployAndWaitPort } from './deploy-health.js';
+/**
+ * What commit Coolify built for an app foundry deployed, and a plan note when
+ * the commit now running differs. Coolify returns no image digest for an app
+ * it built from git, so the built commit is the only thing recorded. A deploy
+ * made outside foundry (a push, a manual deploy in Coolify) shows up as a
+ * different commit.
+ */
+/** One row of Coolify's deployment history, as `CoolifyClient.listApplicationDeployments` returns it. */
+export interface BuildDeploymentRow {
+    deployment_uuid: string;
+    /** Absent on a port that builds from no git commit (the local stand-in). */
+    commit?: string;
+    status: string;
+}
+export interface BuildRecordPort {
+    listApplicationDeployments?(uuid: string, take?: number): Promise<BuildDeploymentRow[]>;
+}
+/** The scope key holding the 40 character commit of the deployment foundry started for `name`. */
+export declare function builtCommitScopeKey(name: string): string;
+/** The scope key holding the Coolify application uuid `builtCommitScopeKey(name)` was read from, so a later plan can read the live commit. */
+export declare function builtAppScopeKey(name: string): string;
+/**
+ * Records the commit of the deployment with uuid `deploymentUuid` (the one
+ * the deploy returned, not the newest row) under `built_commit_<name>`, and
+ * the application uuid under `built_app_<name>`.
+ *
+ * Best effort: a port without the list call, a failed or timed-out read, a
+ * missing row or a commit that is not 40 hex characters records nothing and
+ * returns the reason. The deploy has already succeeded, so a failure here
+ * leaves no key and the plan shows no note for this app; it never fails the
+ * step. The reason names no response body.
+ */
+export declare function recordBuiltCommit(coolify: DeployAndWaitPort, input: {
+    appId: string;
+    deploymentUuid: string;
+    name: string;
+}, record: (key: string, value: string) => void | Promise<void>): Promise<{
+    recorded: true;
+} | {
+    recorded: false;
+    reason: string;
+}>;
+/**
+ * The commit of each recorded app's latest finished deployment, keyed by
+ * app name. An app whose read fails or has no finished deployment is left
+ * out, so it gives no note.
+ */
+export declare function readLiveBuilds(coolify: BuildRecordPort | undefined, recorded: Readonly<Record<string, string>>): Promise<Record<string, string>>;
+/**
+ * One `build-drift:<name>` note per app whose live commit differs from the
+ * recorded one. An app with no recorded commit (never deployed by foundry) or
+ * no live commit gives none. The description carries 12 character shas only.
+ */
+export declare function buildDriftNotes(recorded: Readonly<Record<string, string>>, live: Readonly<Record<string, string | undefined>>): PlanNote[];

package/dist/plan/build-record.js

@@ -0,0 +1,109 @@
+const BUILT_COMMIT_PREFIX = 'built_commit_';
+const BUILT_APP_PREFIX = 'built_app_';
+const FULL_SHA = /^[0-9a-f]{40}$/;
+/** Coolify's own client has a request timeout; this bounds the whole read so a stuck call cannot hold a deploy step. */
+const LIST_TIMEOUT_MS = 15_000;
+const SHORT_SHA_LENGTH = 12;
+/** The scope key holding the 40 character commit of the deployment foundry started for `name`. */
+export function builtCommitScopeKey(name) {
+    return `${BUILT_COMMIT_PREFIX}${name}`;
+}
+/** The scope key holding the Coolify application uuid `builtCommitScopeKey(name)` was read from, so a later plan can read the live commit. */
+export function builtAppScopeKey(name) {
+    return `${BUILT_APP_PREFIX}${name}`;
+}
+async function withTimeout(work, label) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label} timed out`)), LIST_TIMEOUT_MS);
+    });
+    try {
+        return await Promise.race([work, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Records the commit of the deployment with uuid `deploymentUuid` (the one
+ * the deploy returned, not the newest row) under `built_commit_<name>`, and
+ * the application uuid under `built_app_<name>`.
+ *
+ * Best effort: a port without the list call, a failed or timed-out read, a
+ * missing row or a commit that is not 40 hex characters records nothing and
+ * returns the reason. The deploy has already succeeded, so a failure here
+ * leaves no key and the plan shows no note for this app; it never fails the
+ * step. The reason names no response body.
+ */
+export async function recordBuiltCommit(coolify, input, record) {
+    if (!coolify.listApplicationDeployments) {
+        return { recorded: false, reason: 'the Coolify port cannot list deployments' };
+    }
+    let rows;
+    try {
+        rows = await withTimeout(coolify.listApplicationDeployments(input.appId), 'deployment list');
+    }
+    catch (error) {
+        const reason = error instanceof Error && error.message.endsWith('timed out')
+            ? error.message
+            : 'the deployment list failed';
+        return { recorded: false, reason };
+    }
+    const row = rows.find((candidate) => candidate.deployment_uuid === input.deploymentUuid);
+    if (!row)
+        return { recorded: false, reason: 'the deployment is not in the list' };
+    if (!row.commit || !FULL_SHA.test(row.commit))
+        return { recorded: false, reason: 'the deployment has no git commit' };
+    await record(builtCommitScopeKey(input.name), row.commit);
+    await record(builtAppScopeKey(input.name), input.appId);
+    return { recorded: true };
+}
+/**
+ * The commit of each recorded app's latest finished deployment, keyed by
+ * app name. An app whose read fails or has no finished deployment is left
+ * out, so it gives no note.
+ */
+export async function readLiveBuilds(coolify, recorded) {
+    const live = {};
+    const list = coolify?.listApplicationDeployments?.bind(coolify);
+    if (!list)
+        return live;
+    for (const [key, appId] of Object.entries(recorded)) {
+        if (!key.startsWith(BUILT_APP_PREFIX) || !appId)
+            continue;
+        try {
+            const rows = await withTimeout(list(appId), 'deployment list');
+            const finished = rows.find((row) => row.status === 'finished');
+            if (finished?.commit && FULL_SHA.test(finished.commit)) {
+                live[key.slice(BUILT_APP_PREFIX.length)] = finished.commit;
+            }
+        }
+        catch (error) {
+            // Unreadable now: no live value, so no note for this app. The next plan reads again.
+            void error;
+        }
+    }
+    return live;
+}
+/**
+ * One `build-drift:<name>` note per app whose live commit differs from the
+ * recorded one. An app with no recorded commit (never deployed by foundry) or
+ * no live commit gives none. The description carries 12 character shas only.
+ */
+export function buildDriftNotes(recorded, live) {
+    const notes = [];
+    for (const [key, recordedSha] of Object.entries(recorded)) {
+        if (!key.startsWith(BUILT_COMMIT_PREFIX))
+            continue;
+        const name = key.slice(BUILT_COMMIT_PREFIX.length);
+        const liveSha = live[name];
+        if (!recordedSha || !liveSha || liveSha === recordedSha)
+            continue;
+        notes.push({
+            key: `build-drift:${name}`,
+            service: name,
+            description: `${name}: running build ${liveSha.slice(0, SHORT_SHA_LENGTH)} differs from the recorded ${recordedSha.slice(0, SHORT_SHA_LENGTH)}`,
+        });
+    }
+    return notes.sort((a, b) => a.key.localeCompare(b.key));
+}

package/dist/plan/calls-matrix.js

@@ -1,5 +1,5 @@
 import { generateKeyPairSync, randomBytes } from 'node:crypto';
-import { VERSIONS } from '../bootstrap/versions.js';
+import { VERSIONS, pinnedRef } from '../bootstrap/versions.js';
 /**
  * The calls Matrix stack (#128, part 1 of 2 -- see that issue's "If this
  * passes about 800 changed lines, split it" note): pure config generation
@@ -59,8 +59,8 @@ export const MAS_PORT = 8080;
  */
 export function masDockerfile() {
     return [
-        `FROM busybox:${VERSIONS.busybox} AS busybox`,
-        `FROM ${MAS_IMAGE}`,
+        `FROM busybox:${pinnedRef('busybox')} AS busybox`,
+        `FROM ghcr.io/element-hq/matrix-authentication-service:${pinnedRef('mas')}`,
         'COPY --from=busybox /bin/busybox /busybox',
         'CMD ["server", "--config", "/config/config.yaml"]',
         `HEALTHCHECK --interval=15s --timeout=5s --start-period=30s --retries=3 CMD ["/busybox", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:${MAS_PORT}/health"]`,

package/dist/plan/cloudflared-connector.js

@@ -1,4 +1,4 @@
-import { VERSIONS } from '../bootstrap/versions.js';
+import { VERSIONS, pinnedRef } from '../bootstrap/versions.js';
 import { isNotFoundError } from './executor.js';
 /**
  * #197: the pinned `cloudflared` image, the same release tag as
@@ -24,7 +24,7 @@ export const CLOUDFLARED_METRICS_PORT = 20241;
  */
 export function cloudflaredDockerfile() {
     return [
-        `FROM ${CLOUDFLARED_IMAGE_REF}`,
+        `FROM cloudflare/cloudflared:${pinnedRef('cloudflared')}`,
         `CMD ["tunnel", "--no-autoupdate", "--metrics", "0.0.0.0:${CLOUDFLARED_METRICS_PORT}", "run"]`,
         `HEALTHCHECK --interval=15s --timeout=5s --start-period=30s --retries=3 CMD ["cloudflared", "tunnel", "--metrics", "127.0.0.1:${CLOUDFLARED_METRICS_PORT}", "ready"]`,
         '',

package/dist/plan/company-backups.d.ts

@@ -0,0 +1,31 @@
+import type { DeclaredOrg } from '../org.js';
+import type { UnmanagedItem } from '../plan.js';
+import type { DraftStep } from './diff.js';
+/**
+ * F6: the Postgres databases of a company that get a nightly backup, and the
+ * recorded id each one's uuid sits under. The keys are second, documented
+ * copies of the constants in `executor.ts` and `platform-providers.ts` (the
+ * way `PLATFORM_BACKUP_DATABASE_SCOPE_KEYS` copies the platform's): a renamed
+ * key shows up as a database the planner no longer sees, and the test in
+ * `platform-providers.backup.test.ts` plans every name here from a recorded id.
+ * `app` is the hosting entry's database, recorded as a resource id.
+ */
+export declare function companyDatabaseKeys(org: Pick<DeclaredOrg, 'id'>): Readonly<Record<string, string>>;
+/** What every recorded-id key of a company database's backup schedule starts with. */
+export declare const BACKUP_SCOPE_PREFIX = "backup_";
+/** The recorded-id key a company database's backup schedule uuid is stored under. */
+export declare function backupScopeKey(db: string): string;
+/** The databases an upgrade of `service` can migrate, by the names in {@link companyDatabaseKeys}. Empty: not coverable here. */
+export declare function databasesForService(service: string): readonly string[] | 'all';
+/**
+ * One `coolify:backup:<orgSlug>:<db>` step per company database that has a
+ * recorded uuid and no recorded backup yet. `storageUuid` undefined means the
+ * host did not wire backups, so nothing is planned and nothing is said; null
+ * means the platform's backup storage is not registered, so each database is
+ * reported as blocked instead (rule 2). A company that runs its own mail
+ * server carries a note that the Stalwart volume has no Postgres to dump.
+ */
+export declare function planCompanyBackups(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, storageUuid: string | null | undefined): {
+    steps: DraftStep[];
+    blocked: UnmanagedItem[];
+};

package/dist/plan/company-backups.js

@@ -0,0 +1,101 @@
+import { ownsServices } from '../org.js';
+import { BOULE_DATABASE_SCOPE_KEY } from './boule.js';
+import { CHAT_REKEY_MAS_DB_SCOPE_KEY, CHAT_REKEY_SYNAPSE_DB_SCOPE_KEY } from './executor.js';
+/**
+ * F6: the Postgres databases of a company that get a nightly backup, and the
+ * recorded id each one's uuid sits under. The keys are second, documented
+ * copies of the constants in `executor.ts` and `platform-providers.ts` (the
+ * way `PLATFORM_BACKUP_DATABASE_SCOPE_KEYS` copies the platform's): a renamed
+ * key shows up as a database the planner no longer sees, and the test in
+ * `platform-providers.backup.test.ts` plans every name here from a recorded id.
+ * `app` is the hosting entry's database, recorded as a resource id.
+ */
+export function companyDatabaseKeys(org) {
+    return {
+        app: `coolify:database:${org.id}`,
+        cms: 'coolify_cms_database',
+        auth: 'coolify_platform_auth_database',
+        files: 'coolify_platform_files_database',
+        jobs: 'coolify_jobs_database',
+        chat: 'coolify_chat_service_database',
+        calls: 'coolify_calls_service_database',
+        synapse: 'coolify_calls_synapse_database',
+        mas: 'coolify_calls_mas_database',
+        chat_synapse: 'coolify_chat_synapse_database',
+        chat_mas: 'coolify_chat_mas_database',
+        boule: BOULE_DATABASE_SCOPE_KEY,
+        chat_rekey_synapse: CHAT_REKEY_SYNAPSE_DB_SCOPE_KEY,
+        chat_rekey_mas: CHAT_REKEY_MAS_DB_SCOPE_KEY,
+    };
+}
+/** What every recorded-id key of a company database's backup schedule starts with. */
+export const BACKUP_SCOPE_PREFIX = 'backup_';
+/** The recorded-id key a company database's backup schedule uuid is stored under. */
+export function backupScopeKey(db) {
+    return `${BACKUP_SCOPE_PREFIX}${db}`;
+}
+/** The databases an upgrade of `service` can migrate, by the names in {@link companyDatabaseKeys}. Empty: not coverable here. */
+export function databasesForService(service) {
+    switch (service) {
+        case 'zitadel':
+            return ['auth'];
+        case 'files':
+            return ['files'];
+        case 'jobs':
+            return ['jobs'];
+        case 'synapse':
+            return ['synapse', 'chat_synapse'];
+        case 'mas':
+            return ['mas', 'chat_mas'];
+        case 'postgres':
+            return 'all';
+        default:
+            return [];
+    }
+}
+/**
+ * One `coolify:backup:<orgSlug>:<db>` step per company database that has a
+ * recorded uuid and no recorded backup yet. `storageUuid` undefined means the
+ * host did not wire backups, so nothing is planned and nothing is said; null
+ * means the platform's backup storage is not registered, so each database is
+ * reported as blocked instead (rule 2). A company that runs its own mail
+ * server carries a note that the Stalwart volume has no Postgres to dump.
+ */
+export function planCompanyBackups(org, recordedIds, storageUuid) {
+    const steps = [];
+    const blocked = [];
+    if (storageUuid === undefined)
+        return { steps, blocked };
+    for (const [db, key] of Object.entries(companyDatabaseKeys(org))) {
+        const databaseId = recordedIds[key];
+        if (!databaseId || recordedIds[backupScopeKey(db)])
+            continue;
+        if (!storageUuid) {
+            blocked.push({
+                description: `${org.slug}'s ${db} database backup is blocked, not planned: the platform's backup storage is not registered yet`,
+                key: `backup-blocked:${org.slug}:${db}`,
+            });
+            continue;
+        }
+        steps.push({
+            action: {
+                system: 'coolify',
+                kind: 'backup',
+                key: `${org.slug}:${db}`,
+                desired: { databaseId, database: db, storageUuid },
+            },
+            step: {
+                description: `schedule a nightly backup of ${org.slug}'s ${db} database to the platform's backup bucket`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    if (ownsServices(org)) {
+        blocked.push({
+            description: `${org.slug}'s mail server keeps its data on a volume, not in Postgres: no backup covers it yet`,
+            key: 'backup-not-covered:mail',
+        });
+    }
+    return { steps, blocked };
+}

package/dist/plan/deploy-health.d.ts

@@ -69,6 +69,12 @@ export interface DeployAndWaitPort {
         deploymentUuid: string;
         status: string;
     }>;
+    /** Present on a real client; `build-record.ts` reads it to record the built commit. */
+    listApplicationDeployments?(uuid: string, take?: number): Promise<Array<{
+        deployment_uuid: string;
+        commit?: string;
+        status: string;
+    }>>;
 }
 /**
  * How a call site proves the new version is the one that answers (or that
@@ -114,7 +120,9 @@ export interface DeployHealthRuntime {
  * with no such ordering constraint calls {@link waitForNewDeployment}
  * instead, never this plus {@link waitForHealthyVersion} by hand.
  */
-export declare function waitForDeploymentFinished(coolify: DeployAndWaitPort, appId: string, runtime: DeployHealthRuntime, label: string, appliedRefDescription: string): Promise<void>;
+export declare function waitForDeploymentFinished(coolify: DeployAndWaitPort, appId: string, runtime: DeployHealthRuntime, label: string, appliedRefDescription: string): Promise<{
+    deploymentUuid: string;
+}>;
 /**
  * Phase 2 alone: the health check named by `health.kind`, with no deploy and
  * no Coolify polling -- see {@link waitForDeploymentFinished}'s own doc
@@ -133,4 +141,6 @@ export declare function waitForHealthyVersion(appId: string, health: DeployHealt
  * what is still live so a caller's error is actionable without the helper
  * itself knowing any step's scope keys.
  */
-export declare function waitForNewDeployment(coolify: DeployAndWaitPort, appId: string, health: DeployHealthCheck, runtime: DeployHealthRuntime, sleep: (ms: number) => Promise<void>, label: string, appliedRefDescription: string): Promise<void>;
+export declare function waitForNewDeployment(coolify: DeployAndWaitPort, appId: string, health: DeployHealthCheck, runtime: DeployHealthRuntime, sleep: (ms: number) => Promise<void>, label: string, appliedRefDescription: string): Promise<{
+    deploymentUuid: string;
+}>;

package/dist/plan/deploy-health.js

@@ -93,6 +93,7 @@ export async function waitForDeploymentFinished(coolify, appId, runtime, label,
     if (status !== DEPLOYMENT_SUCCEEDED) {
         throw new Error(`${label}: the deployment (${deploymentUuid}) of ${appId} did not finish (status: ${status}); ${appliedRefDescription}. Apply again`);
     }
+    return { deploymentUuid };
 }
 /**
  * Phase 2 alone: the health check named by `health.kind`, with no deploy and
@@ -132,8 +133,9 @@ export async function waitForHealthyVersion(appId, health, runtime, sleep, label
  * itself knowing any step's scope keys.
  */
 export async function waitForNewDeployment(coolify, appId, health, runtime, sleep, label, appliedRefDescription) {
-    await waitForDeploymentFinished(coolify, appId, runtime, label, appliedRefDescription);
+    const { deploymentUuid } = await waitForDeploymentFinished(coolify, appId, runtime, label, appliedRefDescription);
     await waitForHealthyVersion(appId, health, runtime, sleep, label, appliedRefDescription);
+    return { deploymentUuid };
 }
 async function matchesHealth(fetchImpl, health) {
     try {

package/dist/plan/destinations.d.ts

@@ -0,0 +1,73 @@
+import type { CoolifyPort } from './executor.js';
+/** The Docker network of the server's default destination: everything on the platform side. */
+export declare const PLATFORM_NETWORK = "coolify";
+/**
+ * Whether a customer company gets its own `co-<slug>` network. Off for go-live: every company shares the
+ * platform network, because Archon (on it) calls each company's files, mail admin and jobs at internal
+ * addresses and Coolify cannot put Archon on a second network. Per-company networks return after go-live,
+ * once a design lists every call that crosses the split. `let` so tests can turn it on.
+ */
+export declare let COMPANY_NETWORKS: boolean;
+/** Test-only: turns the per-company networks on or off. */
+export declare function setCompanyNetworksForTests(on: boolean): void;
+/** A company runs on the platform network: the owner always, a customer while {@link COMPANY_NETWORKS} is off. */
+export declare function onPlatformNetwork(ownerCompany: boolean | undefined): boolean;
+/** Coolify's destination name for a company, so a listing says who owns it. */
+export declare const COMPANY_DESTINATION_NAME_PREFIX = "foundry:";
+/** Docker's default address pools give about 30 user networks; stop a little short. */
+export declare const DEFAULT_MAX_DESTINATIONS = 25;
+/** The company's own Docker network: `co-<slug>`. */
+export declare function companyNetworkName(slug: string): string;
+/** Refuses a name Docker or this module cannot take; the message names no value. */
+export declare function validateNetworkName(network: unknown): string;
+/** A server already holds as many networks as the capacity gate allows. */
+export declare class DestinationCapacityError extends Error {
+    readonly limit: number;
+    constructor(limit: number);
+}
+type DestinationRaw = Pick<CoolifyPort, 'raw'>;
+/** The uuid of the server's destination on `network`, or undefined. Creates nothing. */
+export declare function findDestination(coolify: DestinationRaw, serverUuid: string, network: string): Promise<string | undefined>;
+/**
+ * The uuid of the server's destination on `network`; creates it when absent.
+ * Coolify makes the Docker network and attaches its proxy to it when the
+ * destination is created. Each call has a 60 second timeout. A create that
+ * fails (Coolify answers 409 when the network already exists) is followed by
+ * one more listing; found there, that uuid is used, so two runs at once and a
+ * re-run after a crash converge on one destination. `maxDestinations` stops a
+ * create on a server that already holds that many (`DestinationCapacityError`,
+ * before anything is created).
+ */
+export declare function ensureDestination(coolify: DestinationRaw, serverUuid: string, network: string, options?: {
+    name?: string;
+    maxDestinations?: number;
+}): Promise<string>;
+type PlacedPort = Partial<Pick<CoolifyPort, 'createGithubAppApplication' | 'createDockerImageApplication' | 'createDockerfileApplication' | 'createPostgresDatabase'>>;
+/**
+ * The Coolify port with `destination_uuid` added to the four create calls
+ * (the other calls pass through). `resolve` gives the destination of the
+ * input's `server_uuid`; it runs once per server for this port. A create that
+ * already names a destination keeps it. A `resolve` that gives nothing leaves
+ * the create as it was. Composes with `limited`: `limited(placed(port, ...))`.
+ */
+export declare function placed<C extends PlacedPort>(coolify: C, resolve: (serverUuid: string) => Promise<string | undefined>): C;
+/**
+ * `placed` on the platform's destination (Docker network `coolify`) of each
+ * server. Once a server has a company destination, a create without
+ * `destination_uuid` is refused by Coolify, so every platform create names the
+ * default one. A server whose listing has no `coolify` destination, and a port
+ * with no `raw`, get the create unchanged.
+ */
+export declare function placedOnPlatform<C extends PlacedPort & {
+    raw?: CoolifyPort['raw'];
+}>(coolify: C): C;
+/**
+ * `placed`, with the destination chosen by the step now running: `scope` gives a key (the company) and
+ * the resolver for it, or nothing, and a create then goes out as it was. One `placed` wrapper is made
+ * per key, so its answers are never shared between companies.
+ */
+export declare function placedByScope<C extends PlacedPort>(coolify: C, scope: () => {
+    key: string;
+    resolve: (serverUuid: string) => Promise<string | undefined>;
+} | undefined): C;
+export {};