@wtfalch/foundry 0.7.1 → 0.9.0

package/dist/plan/executor.d.ts

@@ -282,6 +282,59 @@ export interface CoolifyPort {
      * deploy` method-for-method.
      */
     deploy(uuid: string, force?: boolean): Promise<unknown>;
+    /**
+     * #257: every S3-compatible storage registered for the team -- matches
+     * `CoolifyClient.listS3Storages` method-for-method. `provisionPlatformBackup`
+     * (`platform-providers.ts`) uses this to find the platform's shared R2
+     * bucket by name before registering a second one.
+     */
+    listS3Storages(): Promise<Array<{
+        uuid: string;
+        name: string;
+        bucket: string;
+        endpoint: string;
+        is_usable?: boolean;
+    }>>;
+    /**
+     * #257: registers a bucket as a Coolify team S3 storage -- matches
+     * `CoolifyClient.createS3Storage` method-for-method.
+     */
+    createS3Storage(input: {
+        name: string;
+        description?: string;
+        endpoint: string;
+        bucket: string;
+        region: string;
+        key: string;
+        secret: string;
+        is_usable?: boolean;
+    }): Promise<{
+        uuid: string;
+    }>;
+    /**
+     * #257: the scheduled backups of one database -- matches
+     * `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.
+     */
+    listDatabaseBackups(databaseUuid: string): Promise<Array<{
+        uuid: string;
+        frequency: string;
+        enabled: boolean;
+        save_s3: boolean;
+    }>>;
+    /**
+     * #257: schedules dumps of a database to the registered S3 storage --
+     * matches `CoolifyClient.createDatabaseBackup` method-for-method.
+     */
+    createDatabaseBackup(databaseUuid: string, input: {
+        frequency: string;
+        enabled?: boolean;
+        save_s3?: boolean;
+        s3_storage_uuid?: string;
+    }): Promise<{
+        uuid: string;
+    }>;
 }
 /**
  * The Cloudflare calls this executor makes, shaped to match
@@ -344,11 +397,8 @@ export interface CloudflarePort {
     deleteAccessApp(appId: string): Promise<void>;
     /**
      * `FoundryPlanApply.destroy`'s teardown of any DNS record foundry created
-     * for the org. Nothing in this executor creates or records one yet (Finding,
-     * this campaign's report: no `cloudflare:dns` resource kind exists in
-     * `diff.ts`/`executor.ts` today), so `destroy` has no dispatch target for
-     * it either -- this port method exists ready for whichever step starts
-     * creating one.
+     * for the org -- `destroy`'s `cloudflare:tunnel` case uses it to remove
+     * every CNAME {@link publishTunnelDnsRecords} published (#236).
      */
     deleteDnsRecord(zoneId: string, recordId: string): Promise<void>;
     /** `coolify:mail`'s lookup of an existing MX/TXT record before upserting it, filtered by type so a stale record of a different type is never mistaken for a match. */
@@ -358,6 +408,27 @@ export interface CloudflarePort {
         content: string;
         name: string;
     }>>;
+    /**
+     * #236: `destroy`'s `cloudflare:tunnel` case and
+     * {@link FoundryStepExecutor.deleteStaleTunnelDnsRecords} each fall back to
+     * this for a domain recorded before
+     * {@link CLOUDFLARE_TUNNEL_DNS_HOSTNAMES_SCOPE_KEY} existed, with no
+     * hostname list to look up instead -- the one case left that must still
+     * see every CNAME in the zone, not one matched by name. Round 3: this is
+     * no longer either caller's normal path, since the real adapter
+     * (`@wtfalch/providers`' `cloudflare.ts`) asks for one page of 100 and
+     * never walks `result_info.total_pages`, so a zone with more records than
+     * that would silently lose everything past the first page.
+     */
+    listDnsRecords(zoneId: string, opts?: {
+        type?: string;
+        name?: string;
+    }): Promise<Array<{
+        id: string;
+        type: string;
+        content: string;
+        name: string;
+    }>>;
     createDnsRecord(zoneId: string, rec: {
         type: string;
         name: string;
@@ -620,22 +691,56 @@ export interface ZitadelPort {
     }>;
     deleteApp(orgId: string, projectId: string, appId: string): Promise<void>;
     /**
-     * `zitadelApp`'s kind-change path reads this to find an app a prior,
+     * `zitadelApp`'s kind-change path reads `apps` to find an app a prior,
      * lost-response create already made under the new name, before calling
      * `createOidcApp`/`createApiApp` again and orphaning that one under the
-     * same name. Matches `@wtfalch/providers/zitadel`'s `ZitadelClient.
-     * listApps` return shape exactly, so that client satisfies this port with
-     * no adapter -- it does not carry `clientId`/`clientSecret` (that provider
+     * same name -- it does not carry `clientId`/`clientSecret` (that provider
      * method never parses either, and a secret is minted once, on creation,
      * never handed back again), which is why the reuse path below cannot
      * re-deliver either one.
-     */
-    listApps(orgId: string, projectId: string): Promise<Array<{
-        id: string;
-        name: string;
-        appType: 'web' | 'native' | 'api';
-        state: string;
-    }>>;
+     *
+     * `loginBaseUri` and `complete` are `zitadelLoginHost`'s own #274
+     * additions, neither satisfied by the real (unpublished-ahead-of-pin)
+     * `@wtfalch/providers` `ZitadelClient.listApps` yet -- {@link
+     * adaptZitadelListApps} below is the adapter for both until a tracked
+     * change lands (https://github.com/wtfalch/providers/issues/29):
+     *
+     * - `loginBaseUri`: each app's current ZITADEL Login V2 base URI, used to
+     *   decide whether a host a company-login-host change left behind is
+     *   still in use -- rather than guessing from which apps this step itself
+     *   repointed. Three states, not two (#274 fix round 4): a `string` is
+     *   the URI itself; `null` means this call *read* the app and it has
+     *   never had one set -- common, and never a reason to keep a host
+     *   pending; `undefined` means this call could not read the field at all
+     *   (every app, through {@link adaptZitadelListApps}, until the tracked
+     *   change above lands) and is the only one of the three
+     *   `zitadelLoginHost` fails a pending host closed over. Collapsing
+     *   "confirmed unset" into "unreadable" would never let a host clear once
+     *   an app with no login flow of its own existed, forever, even after the
+     *   tracked change lands and genuinely-unset apps start reporting `null`.
+     *   The real client's own `_search` response parsing (`appFrom`)
+     *   deliberately reads only enough of each app to classify its kind,
+     *   "everything else... ignored on purpose".
+     * - `complete`: whether this call read every one of ZITADEL's own result
+     *   pages, not only the first -- the real client's `_search` call sends
+     *   no `query.offset`/`limit` yet, so {@link adaptZitadelListApps} reports
+     *   `false` until that lands. #274 fix round 3: a result count alone can
+     *   never answer this (any threshold guessed at the boundary between
+     *   "every app fit on one page" and "the page was cut off" is
+     *   indistinguishable from the server's own page size, which nothing here
+     *   is told), so `zitadelLoginHost` treats `complete: false` as "cannot
+     *   safely tell" rather than trusting however many apps did come back.
+     */
+    listApps(orgId: string, projectId: string): Promise<{
+        apps: Array<{
+            id: string;
+            name: string;
+            appType: 'web' | 'native' | 'api';
+            state: string;
+            loginBaseUri?: string | null;
+        }>;
+        complete: boolean;
+    }>;
     /**
      * The org-owner flow (goal line): find-or-create the human user by email in
      * the org, then have ZITADEL email them an invite to set up a passkey.
@@ -779,6 +884,17 @@ export interface ZitadelPort {
     ensureTrustedDomain(domain: string): Promise<{
         added: boolean;
     }>;
+    /**
+     * #274: removes a host from the ZITADEL instance's trusted domains
+     * (`@wtfalch/providers`' `ZitadelClient.deleteTrustedDomain`) -- the old
+     * host a company login host change or an org destroy leaves behind, which
+     * {@link ensureTrustedDomain} only ever adds to, never removes from. No
+     * idempotency wrapper on the real client's own side (matching `deleteApp`/
+     * `deleteOrg`/`deleteProject`): a host already gone throws the same
+     * `status`-bearing not-found `isNotFoundError` catches everywhere else in
+     * this package.
+     */
+    deleteTrustedDomain(domain: string): Promise<void>;
     /**
      * #267: moves an already-created app's Login V2 base URI, read-modify-
      * write (`@wtfalch/providers`' `ZitadelClient.updateOidcAppLoginBaseUri`).
@@ -787,6 +903,36 @@ export interface ZitadelPort {
      */
     updateOidcAppLoginBaseUri(orgId: string, projectId: string, appId: string, loginBaseUri: string): Promise<void>;
 }
+/**
+ * #274 fix round 4: bridges `@wtfalch/providers`' real `ZitadelClient.
+ * listApps` -- a plain array, with no `loginBaseUri` or completeness signal
+ * -- into {@link ZitadelPort.listApps}'s own shape, so a host wiring that
+ * real client in satisfies this port without reaching into `executor.ts`
+ * itself to build the wrapper by hand. `complete: false` on every call:
+ * the real client's own `_search` request has no pagination on it yet
+ * (https://github.com/wtfalch/providers/issues/29), so this adapter cannot
+ * promise it read more than one page. `loginBaseUri` comes back `undefined`
+ * for every app for the identical reason -- the real client does not read
+ * it back at all yet, not "read it back as absent" -- which is exactly the
+ * state `zitadelLoginHost`'s fail-closed rule exists for: every pending
+ * host stays pending until the tracked change above lands and this adapter
+ * (or its replacement) can start reporting `string | null` for real.
+ */
+export declare function adaptZitadelListApps(client: {
+    listApps(orgId: string, projectId: string): Promise<ZitadelListAppsRawApp[]>;
+}): ZitadelPort['listApps'];
+/**
+ * The real `@wtfalch/providers` `ZitadelClient.listApps`' own return shape
+ * (its `ZitadelApp`) -- restated rather than imported, the same rule this
+ * package's doc comments already follow wherever a provider type is cited
+ * without a runtime dependency on the package that owns it existing yet.
+ */
+export interface ZitadelListAppsRawApp {
+    id: string;
+    name: string;
+    appType: 'web' | 'native' | 'api';
+    state: string;
+}
 /**
  * Provisions one org's organisation on Files (#80), matching
  * `files/packages/sdk/src/client.ts:136-145`'s
@@ -1052,7 +1198,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:
@@ -1095,6 +1241,66 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * domains, writes zitadel-login's binding, then repoints the apps whose
      * client id that binding holds. Apps created later are not in it yet:
      * the next run replans (`diff.ts`'s `planLoginHost`) and moves them.
+     *
+     * #274: when the org's host has moved (`recorded[key]`, the *previous*
+     * run's resourceId, differs from this run's `host`), also removes every
+     * host that is no longer the org's current one from both places --
+     * `ensureTrustedDomain` and `upsertBinding` above only ever add, so
+     * without this an old host stays trusted and bound forever, and a later
+     * org that reuses the old slug inherits it unasked.
+     *
+     * #274 fix round 2: this always returns `host` -- the *current* desired
+     * host -- as its `resourceId`, never an old one, however many of its
+     * removals are still outstanding. Fix round 1 returned `previousHost`
+     * while a removal was skipped, banking on `planLoginHost` replanning the
+     * whole step off that mismatch alone; that loses track of the *new* host
+     * the moment a second host change moves `previousHost` on again (A -> B
+     * skipped, then B -> C: A's own removal has nothing left recording it was
+     * ever owed). `LOGIN_HOST_PENDING_REMOVAL_SCOPE_KEY`
+     * (`pendingRemovalHosts`/`pendingRemovalState`, `login-host.ts`) is the
+     * durable record instead -- every host still awaiting removal, independent
+     * of which one is current -- and `planLoginHost` replans the step whenever
+     * it is non-empty, not only when the current host itself differs.
+     *
+     * Whether a host is still "in use" is decided from each live app's actual
+     * ZITADEL Login V2 base URI (`ZitadelPort.listApps`' `loginBaseUri`), not
+     * from `boundAppIds` membership: fix round 1 skipped removal only while an
+     * app outside `boundAppIds` existed, but `boundAppIds` is deliberately
+     * narrower than "every live app" (it excludes `native`/`api` apps and any
+     * `web` app without a recorded client id yet) and a host can safely be
+     * removed even while such an app exists, so long as nothing is actually
+     * pointed at it. Removing by the wrong signal either breaks sign-in (an
+     * app repointed is not the same fact as an app with no client id yet) or
+     * strands a host forever (an org with a `native`/`api` app would never
+     * satisfy "every live app bound").
+     *
+     * #274 fix round 3, four more defects fix round 2 left:
+     *
+     * 1. The *current* host is excluded from the candidates for removal.
+     *    Without this, A -> B (A pending, not yet safe) -> A deletes the host
+     *    this very call just (re-)trusted and bound: a host already in
+     *    `LOGIN_HOST_PENDING_REMOVAL_SCOPE_KEY` from an earlier run can be
+     *    exactly the one the org's host is moving back to.
+     * 2. Fail closed on missing information, rather than ever reading
+     *    "nothing uses it" off of one: an app whose `loginBaseUri` cannot be
+     *    read at all (`undefined` -- which, until a real adapter is wired per
+     *    `ZitadelPort.listApps`'s own doc comment, is every app, every call)
+     *    means every pending host stays pending this run, not just the ones a
+     *    narrower check happened to miss.
+     * 3. Same fail-closed rule for `listApps`' own `complete` flag: an
+     *    incomplete read (today, always, for the identical reason) means the
+     *    set of apps this call saw could be missing one still pointed at a
+     *    pending host, so nothing is removed off of it either.
+     * 4. A base URI compares after lowercasing and trimming its trailing
+     *    `/` (`normalizedLoginBaseUri`) -- ZITADEL's own value and the one
+     *    this step constructs are not guaranteed to agree on case or a
+     *    trailing slash, and a comparison that is case- or slash-sensitive
+     *    both ways can report "in use" as "not" by accident.
+     * 5. Each live app's base URI is read as of *after* this call's own
+     *    repoint loop above, not the stale value `listApps` returned before
+     *    it: a bound app this very call just repointed away from a pending
+     *    host must not hold that host pending for one more run only because
+     *    the snapshot taken before the repoint still named it.
      */
     private zitadelLoginHost;
     /**
@@ -1178,7 +1384,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
@@ -1191,7 +1397,7 @@ 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;
@@ -1568,6 +1774,105 @@ 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;
+    /**
+     * #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
+     * *old* domain's zone that points at this tunnel, so a domain switch
+     * never leaves the old domain still answering for it. Takes the previous
+     * domain and hostnames as plain arguments rather than reading them off
+     * `context` itself (round 3): `cloudflareTunnel` reads the old values
+     * before calling either this or `publishTunnelDnsRecords`, and (round 4
+     * finding 3) does not record the new domain/hostnames until *after* this
+     * method has returned, so a crash here still sees the old domain on retry.
+     * A no-op when the old zone itself is already gone.
+     *
+     * `previousHostnames` (round 3) is {@link CLOUDFLARE_TUNNEL_DNS_HOSTNAMES_SCOPE_KEY}'s
+     * recorded list, looked up one by one instead of a zone-wide
+     * `listDnsRecords` -- the real adapter's version of that call asks for one
+     * page and never walks the rest. A domain change recorded before that key
+     * existed falls back to the old zone-wide pass, the one case where no
+     * hostname list was ever written to look up instead.
+     *
+     * `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;
+    /**
+     * #236: upserts a proxied CNAME to this tunnel for each of
+     * `tunnelIngressHostnames(org)` that actually belongs to `domain`'s own
+     * zone -- a hosting app still served off the shared `*.oikos.host`
+     * wildcard tunnel (`scripts/shared-ingress.mjs`) can appear in that list
+     * alongside `agora.<domain>` (#164's unconditional Agora hostname) when
+     * `hosting.usesDomain` is off, and `<slug>.oikos.host` is not this org's
+     * zone to touch.
+     *
+     * Checks every hostname for a conflicting record *before* writing any
+     * (round 2 finding: a conflict found only partway through a hostname-by-
+     * hostname pass left earlier hostnames written but the domain never
+     * recorded -- an orphaned partial write). An existing A or AAAA record,
+     * or a CNAME already pointed anywhere but this tunnel or (round 3) its own
+     * immediately prior tunnel id, blocks the whole step with a named
+     * conflict rather than being adopted or replaced, the same do-not-adopt
+     * policy {@link cloudflareZone} itself follows for the zone. A CNAME
+     * already pointed at this tunnel is left alone, so a second apply changes
+     * nothing. The caller ({@link cloudflareTunnel}) records the domain and the
+     * returned hostname list as scope ids only once this method -- and, on a
+     * domain change, the old domain's own cleanup -- has returned successfully
+     * (round 4 finding 3), so a crash mid-write is recovered by re-running
+     * this same idempotent step, never silently skipped.
+     *
+     * 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 --
+     * {@link cloudflareTunnel} hands the *whole* old domain to
+     * {@link deleteStaleTunnelDnsRecords} for that case instead). A name in it
+     * that the org's current config no longer produces is dropped from
+     * `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 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, 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;
     /**
      * `plan/diff.ts`'s `planZone`: finds or creates the Cloudflare zone for the
      * org's own domain. Refuses to adopt a zone the store already records