@wtfalch/foundry 0.8.0 → 0.10.0

package/dist/plan/executor.d.ts

@@ -1,6 +1,7 @@
 import type { OrgMailOptions, OrgMailOrg, OrgMailResult } from '@wtfalch/email/postmaster';
 import type { DeclaredOrg, HostingBuildPack } from '../org.js';
 import type { DeclaredOrgStore } from '../store.js';
+import { type BrokerPort } from './broker-entries.js';
 import type { StepAction } from './diff.js';
 import { type LoginHostBindingsPort } from './login-host.js';
 import { type MailCopyPort } from './mail-copy.js';
@@ -97,6 +98,19 @@ export interface CoolifyPort {
         domains?: string;
         /** Selects which of two Dockerfiles in one repo to build (`cmsSite`'s own site/cms apps). */
         dockerfile_location?: string;
+        /** The port the app listens on (`HostingEntry.port`). */
+        ports_exposes?: string;
+        /** `false` for an internal entry: Coolify makes no domain for it. */
+        autogenerate_domain?: boolean;
+        /** The folder a `static` entry serves (`HostingEntry.folder`). */
+        publish_directory?: string;
+        /** Whether a push to `git_branch` deploys (`HostingEntry.autoDeploy`). */
+        is_auto_deploy_enabled?: boolean;
+        /**
+         * The app's folder in the repo (`HostingEntry.folder`). Coolify's create
+         * endpoint takes it; `@wtfalch/providers` forwards the body as it is.
+         */
+        base_directory?: string;
     }): Promise<{
         uuid: string;
     }>;
@@ -316,12 +330,20 @@ export interface CoolifyPort {
      * `CoolifyClient.listDatabaseBackups` method-for-method.
      * `provisionPlatformBackup` reads this to decide whether a database
      * already has an enabled, `save_s3` schedule before creating a second one.
+     * `s3_storage_uuid` (#257 fix round 3) is the field a replaced storage's
+     * repoint compares against -- Coolify's "Update database backup" operation
+     * (https://coolify.io/docs/api-reference/api/operations/update-database-backup)
+     * documents it as a field of the same scheduled-backup resource this list
+     * returns, but the list endpoint's own response has not been checked
+     * against a live instance, so it is optional here rather than assumed
+     * present.
      */
     listDatabaseBackups(databaseUuid: string): Promise<Array<{
         uuid: string;
         frequency: string;
         enabled: boolean;
         save_s3: boolean;
+        s3_storage_uuid?: string;
     }>>;
     /**
      * #257: schedules dumps of a database to the registered S3 storage --
@@ -1134,6 +1156,13 @@ export interface FoundryStepExecutorPorts {
      * or repointed without the binding.
      */
     loginHostBindings?: LoginHostBindingsPort;
+    /**
+     * F5: the broker's `AUTH_APPS`, where an entry with `uses.auth` gets its own
+     * entry. Optional the same way `loginHostBindings` is: without it the plan
+     * reports each broker entry blocked (the host also sets
+     * `FoundryPlanApplyOptions.broker`).
+     */
+    broker?: BrokerPort;
     /**
      * Hands a just-minted, one-time secret (today: an API app's
      * `clientSecret`) to the host, immediately after the provider returns it
@@ -1198,7 +1227,7 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     } | undefined>;
     /**
      * `plan/diff.ts`'s `planAccess` (#84): puts the org's app hostname behind a
-     * Cloudflare Access app that lets only `hosting.accessEmails` through.
+     * Cloudflare Access app that lets only the `app` entry's `accessEmails` through.
      * foundry names its Access app `foundry:<orgId>` and reuses only an app with
      * that name, so a re-run after a crash does not duplicate it. It refuses,
      * rather than adopt, when another Access app already holds the hostname:
@@ -1384,7 +1413,7 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * P2, `.plans/2026-09-26-level-1-org-map.md`) -- a second `bulkUpsertEnvs`
      * call rather than folding into `pushDatabaseUrl`'s, since this one runs
      * unconditionally (`coolifyApp`) where that one runs only once
-     * `hosting.database` is declared and provisioned.
+     * the `app` entry's `database` is declared and provisioned.
      *
      * `APP_URL` and `LOG_DIR` (#75) are pushed unconditionally; every other
      * value is pushed only once its own source step has actually recorded it
@@ -1397,10 +1426,25 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * is its own design question, left out of #204's own "How" rather than
      * guessed) is out of scope here (task brief). `DATABASE_URL_OWNER`/
      * `DATABASE_URL` are pushed by `pushDatabaseUrl` instead, not here --
-     * that call runs only once `hosting.database` is declared and
+     * that call runs only once the `app` entry's `database` is declared and
      * provisioned, where this one is unconditional (#239).
      */
     private pushAppEnv;
+    /**
+     * F5: the app's `AUTH_APP_KEY`, minted once and only when the app has none
+     * of at least 32 characters (the broker refuses a shorter one). `null` once
+     * it has one: the app's env is where the key lives, and
+     * `coolifyBrokerEntry` reads it back from there. It goes to this env and
+     * the broker's, nowhere else.
+     */
+    private ensureAuthAppKey;
+    /**
+     * `plan/diff.ts`'s `planBrokerEntries` (F5): the entry's `AUTH_APPS` entry,
+     * written by `writeBrokerEntry` with the key `pushAppEnv` put in the app's
+     * env. Records what it wrote (never the key) and any foreign entry the
+     * broker would drop.
+     */
+    private coolifyBrokerEntry;
     /**
      * `null` once the app already has one -- `AUTH_COOKIE_SECRET` is generated
      * only the first time (task brief), never regenerated or overwritten, so a
@@ -1793,15 +1837,27 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * existed falls back to the old zone-wide pass, the one case where no
      * hostname list was ever written to look up instead.
      *
-     * `previousTunnelId` (round 4 finding 1): the old domain's CNAMEs were
-     * published under whatever tunnel id was live the *last* time this step
-     * recorded that domain, which is `previousTunnelId`, not necessarily
-     * `tunnelId` -- a tunnel recreated under the same name
-     * (`findTunnelByName` returning a new id) in the same apply that also
-     * changes the domain leaves the old domain's records pointed at the old
-     * id. Matching only `tunnelId`'s target left them live forever. Both
-     * targets are checked so this stays a no-op once a retry has already
-     * moved the old domain onto the new id.
+     * `previousIds` (round 4 finding 1, round 6 finding 2): the old domain's
+     * CNAMEs were published under whatever tunnel id was live the *last*
+     * time this step recorded that domain, which may be any id this step has
+     * ever replaced, not necessarily `tunnelId` -- a tunnel recreated under
+     * the same name (`findTunnelByName` returning a new id), possibly more
+     * than once with no successful publish in between, in the same apply
+     * that also changes the domain leaves the old domain's records pointed
+     * at an old id. Matching only `tunnelId`'s target left them live
+     * forever; matching only the single most recent previous id (round 4)
+     * still missed an older one two unresolved recreates back. Every target
+     * is checked so this stays a no-op once a retry has already moved the
+     * old domain onto the current id.
+     *
+     * Round 6 finding 1: once `previousHostnames` is non-empty, every name in
+     * it has now been looked up -- deleted (its CNAME matched one of
+     * `dnsTargets`), left alone (found but foreign), or never found at all
+     * (already gone) -- so none of them needs tracking under `previousDomain`
+     * in {@link CLOUDFLARE_TUNNEL_DNS_TRACKED_SCOPE_KEY} any longer; dropped
+     * from that set accordingly. The zone-wide fallback path (no recorded
+     * hostnames) never added entries of its own to begin with, so there is
+     * nothing of this domain's left in that set either way.
      */
     private deleteStaleTunnelDnsRecords;
     /**
@@ -1828,13 +1884,15 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * (round 4 finding 3), so a crash mid-write is recovered by re-running
      * this same idempotent step, never silently skipped.
      *
-     * Round 3: `previousTunnelId` is the tunnel id this same step recorded
-     * last time it ran (`cloudflareTunnel`'s own `cloudflare:tunnel:<key>`
-     * resource id, read before `tunnel` above is computed for this run) -- a
-     * tunnel Cloudflare shows as recreated under the same name
-     * (`findTunnelByName` returning a new id for `<slug>-tunnel`) leaves every
-     * CNAME still pointed at the *old* id. That is this org's own stale
-     * record, not a foreign one, so it is repointed rather than refused.
+     * Round 3, round 6 finding 2: `previousIds` is every tunnel id this same
+     * step has ever replaced (`cloudflareTunnel`'s own accumulated set,
+     * captured before `tunnel` above is computed for this run) -- a tunnel
+     * Cloudflare shows as recreated under the same name (`findTunnelByName`
+     * returning a new id for `<slug>-tunnel`), possibly more than once with
+     * no successful publish in between, leaves every CNAME still pointed at
+     * one of those old ids. That is this org's own stale record, not a
+     * foreign one, so it is repointed rather than refused, whichever of
+     * `previousIds` it still names.
      *
      * Round 4 finding 2: `previousHostnames` is this domain's own previously
      * recorded hostname list (empty when the domain just changed --
@@ -1844,17 +1902,19 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * `hostnames` below but was never cleaned up before this round: its CNAME
      * stayed live and its name stayed in the recorded list forever, because
      * only a domain *change* ever ran cleanup. Each dropped name's CNAME is
-     * deleted here when it still points at this tunnel or its immediately
-     * prior id; a name already gone, or now pointed at something foreign, is
-     * simply left out of the returned list -- nothing here is this method's to
-     * reclaim or report as a conflict.
+     * deleted here when it still points at this tunnel or any of
+     * `previousIds`; a name already gone, or now pointed at something
+     * foreign, is simply left out of the returned list -- nothing here is
+     * this method's to reclaim or report as a conflict.
      *
-     * Round 5 finding 1: `context` is used only to record
-     * {@link CLOUDFLARE_TUNNEL_DNS_PENDING_DOMAIN_SCOPE_KEY}/
-     * {@link CLOUDFLARE_TUNNEL_DNS_PENDING_HOSTNAMES_SCOPE_KEY} after each
-     * individual CNAME write below succeeds, so a crash or a thrown conflict
-     * partway through never leaves an already-created CNAME out of every
-     * recorded list -- `destroy` checks this pending pair too.
+     * Round 5 finding 1, round 6 finding 1: `context` is used to add every
+     * hostname this call confirms correct (settled, created or repointed) to
+     * {@link CLOUDFLARE_TUNNEL_DNS_TRACKED_SCOPE_KEY} as soon as it is
+     * confirmed, and to drop a dropped hostname from it once that hostname's
+     * own CNAME is resolved one way or another -- additively, alongside
+     * whatever other domains that shared set already names, never
+     * overwriting them. `destroy` and {@link deleteStaleTunnelDnsRecords}
+     * both read this set.
      */
     private publishTunnelDnsRecords;
     /**