@wtfalch/foundry 0.9.0 → 0.11.0

package/dist/plan/executor.d.ts

@@ -1,6 +1,10 @@
 import type { OrgMailOptions, OrgMailOrg, OrgMailResult } from '@wtfalch/email/postmaster';
 import type { DeclaredOrg, HostingBuildPack } from '../org.js';
-import type { DeclaredOrgStore } from '../store.js';
+import type { UnmanagedItem } from '../plan.js';
+import type { Adoption, AdoptionStore, DeclaredOrgStore } from '../store.js';
+import { type IngressRoute } from './adopt.js';
+import type { AdoptionVault } from './adoption-vault.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 +101,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;
     }>;
@@ -167,9 +184,13 @@ export interface CoolifyPort {
      * `is_preview === false` the same way a deployed-config reader must.
      */
     listEnvs(applicationUuid: string): Promise<Array<{
+        uuid?: string;
         key: string;
         value: string;
         is_preview: boolean;
+        is_buildtime?: boolean;
+        is_literal?: boolean;
+        is_multiline?: boolean;
     }>>;
     /** Escape hatch (`CoolifyClient.raw`) — used for stop/start, which have no typed method yet. */
     raw(method: string, path: string, body?: unknown): Promise<unknown>;
@@ -316,12 +337,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 --
@@ -358,6 +387,18 @@ export interface CloudflarePort {
         name: string;
     }>;
     putTunnelConfig(tunnelId: string, config: unknown): Promise<unknown>;
+    /**
+     * #312: the tunnel's live configuration, `config` null for a tunnel never
+     * configured. Matches `@wtfalch/providers`' `CloudflareClient.getTunnelConfig`.
+     * `cloudflareTunnel` reads it on every apply of an adopted tunnel, to merge
+     * its routes into the live ingress list rather than overwrite it.
+     */
+    getTunnelConfig(tunnelId: string): Promise<{
+        config: {
+            ingress: IngressRoute[];
+            [field: string]: unknown;
+        } | null;
+    }>;
     /**
      * The tunnel's connector token (#197) -- a `cloudflared` container reads
      * this at boot to dial into the tunnel. A live credential: matches
@@ -577,14 +618,17 @@ export interface MailPort {
      * (#162). The host implements this with `@wtfalch/email/postmaster`'s own
      * `createMailbox`, resolving `org`'s domain to a `domainId` the same way
      * `applyOrgMail` does -- that function already refuses a duplicate `local`
-     * on the resolved domain, so this port method never has to. `ensureOwnerMailbox`
+     * on the resolved domain, so this port method never has to. `options` is
+     * the same `{ apex, mailHost }` `applyOrgMail`/`parkOrgMail` take, needed
+     * for the same reason: `@wtfalch/email/postmaster`'s `createMailbox` takes
+     * it to resolve the shared mail apex (#335). `ensureOwnerMailbox`
      * and `ensureRoleMailboxes` (#230) below are this executor's callers, and each checks its own recorded scope
      * id first, so a second apply never calls this at all.
      */
     createMailbox(org: OrgMailOrg, mailbox: {
         address: string;
         name: string;
-    }): Promise<void>;
+    }, options: OrgMailOptions): Promise<void>;
     /**
      * Upserts this org's own outbound relay route on Stalwart (#149): an
      * `MtaRoute` through Lettermint, restricted to `org`'s domain, keyed by
@@ -1134,6 +1178,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
@@ -1156,6 +1207,17 @@ export interface FoundryStepExecutorPorts {
      * passes the same store instance it constructs `FoundryPlanApply` with.
      */
     declaredOrgStore: Pick<DeclaredOrgStore, 'findOrgIdForZone'>;
+    /**
+     * #311: where an adoption keeps the env values of the live app it takes
+     * over. Optional with `adoptionStore`: without both, the planner reports
+     * adoption as blocked and plans no `coolify:adopt` step
+     * (`FoundryPlanApplyOptions`).
+     */
+    adoptionVault?: AdoptionVault;
+    /** #311: the rows that hold the non-secret part of each snapshot. */
+    adoptionStore?: AdoptionStore;
+    /** #311: the clock of a snapshot's `takenAt`; the host passes `FoundryPlanApply`'s own. Defaults to the real clock. */
+    now?: () => Date;
 }
 /**
  * Thrown by name for a step this executor deliberately does not implement:
@@ -1326,6 +1388,49 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     private ensureZitadelProject;
     private ensureCoolifyProject;
     private resolveServer;
+    /** The live app Coolify holds under `uuid`. The error names the id only (rule 6). */
+    private readLiveApp;
+    /** The live ingress routes of the adopted tunnel `id`. The error names the id only (rule 6). */
+    private readAdoptedIngress;
+    /**
+     * #311: for each adopted resource, the lines its `coolify:adopt` step shows
+     * (a setting with old value beside new; an env var by name only) and what
+     * is blocked. Read from the live app on every plan. No value of an env var
+     * leaves this method (rule 6).
+     */
+    adoptionReport(org: DeclaredOrg, recorded: Readonly<Record<string, string>>): Promise<{
+        details: Record<string, string[]>;
+        blocked: UnmanagedItem[];
+        withheld: string[];
+    }>;
+    /**
+     * #311: puts each adopted app back as its snapshot recorded it, touching
+     * only what foundry writes: the settings it patches and the env names it
+     * owns (an edit a person made to anything else stays). Owned names the
+     * snapshot has are written back with its value and flags; owned names it
+     * lacks are deleted; preview rows are left alone. Every vault entry and
+     * live read happens first, so a missing entry or a row that cannot be
+     * deleted refuses before any Coolify write. Errors name ids only, and the
+     * vault's env values go to `bulkUpsertEnvs` and nowhere else (rule 6).
+     */
+    restoreAdoption(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, rows: readonly Adoption[]): Promise<{
+        envDeleted: string[];
+        tokenLeft: string[];
+    }>;
+    /**
+     * #311: records what a live app or database looked like before foundry
+     * first writes to it, in this order: the env values to the vault, the
+     * non-secret settings to the row, then both read back and compared. The
+     * step writes nothing to Coolify, so a snapshot that fails stops the apply
+     * before any later step does. Every error names ids only (rule 6).
+     */
+    private coolifyAdopt;
+    /** #311: whether the resource was adopted: its row is `adopted` or `confirmed`, or `id` is a declared adopt uuid. */
+    private isAdopted;
+    /** #311: refuses to manage as foundry's own a resource whose row protects its key and whose declaration has no `adopt`. */
+    private refuseTakeover;
+    /** #311: refuses to write to a declared adopt uuid that has no active snapshot. */
+    private requireSnapshot;
     private coolifyApp;
     /**
      * #75: mounts a persistent volume at {@link LOG_DIR} on the app, unless one
@@ -1401,6 +1506,21 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * 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
@@ -1774,6 +1894,24 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     /** `deliverSecret`, tried up to {@link JOBS_DELIVERY_ATTEMPTS} times; true once one attempt succeeds. */
     private deliverWithRetry;
     private cloudflareTunnel;
+    /**
+     * Runs `call`; for an adopted resource a failure that is not one of this
+     * file's own messages (which name hostnames and record types only) is
+     * replaced by `label`, because a client's error text carries response
+     * bodies (rule 6, #312).
+     */
+    private guarded;
+    /**
+     * #312: writes the org's routes into the adopted tunnel's LIVE ingress list
+     * (`mergeIngress`), not the snapshot, so a route a person added since is
+     * kept too. The declared names go into the tunnel row's `written` only after
+     * the write that carried them succeeded, so a crash in between leaves a
+     * route taken as foreign and kept. Writes nothing when the merged list is the
+     * live one. Errors name the tunnel id and the operation only.
+     */
+    private mergeAdoptedIngress;
+    /** #312: replaces the `settings` of an adoption row, read fresh so no other key is lost. The state and `takenAt` stay. */
+    private updateAdoptionSettings;
     /**
      * #236: when this tunnel's DNS was last published under a domain that
      * differs from the one `org` now declares, deletes every CNAME in the