@wtfalch/foundry 0.19.1 → 0.21.0

package/dist/plan/executor.d.ts

@@ -2,7 +2,13 @@ import type { OrgMailOptions, OrgMailOrg, OrgMailResult } from '@wtfalch/email/p
 import type { DeclaredOrg, HostingBuildPack } from '../org.js';
 import type { DeclaredOrgStore } from '../store.js';
 import { type BrokerPort } from './broker-entries.js';
+import { type DeployHealthRuntime } from './deploy-health.js';
 import { type StepAction } from './diff.js';
+import { type AccessPort, type EdgePlatformAccess } from './edge-access.js';
+import { type DnsPort, type EdgePlatformDns } from './edge-dns.js';
+import { type EdgePlatformRateLimits, type RateLimitPort } from './edge-ratelimits.js';
+import { type EdgePlatformTunnels, type TunnelPort } from './edge-tunnels.js';
+import { type EdgePlatformZones, type ZonePort } from './edge-zones.js';
 import { type LoginHostBindingsPort } from './login-host.js';
 import { type MailCopyPort } from './mail-copy.js';
 import type { DestroyTarget, StepDestroyer, StepExecutionContext, StepExecutor } from './plan-apply.js';
@@ -379,6 +385,8 @@ export interface CoolifyPort {
         enabled: boolean;
         save_s3: boolean;
         s3_storage_uuid?: string;
+        /** The databases this schedule dumps, comma separated. Empty means the resource's first database. */
+        databases_to_backup?: string | null;
     }>>;
     /**
      * #257: schedules dumps of a database to the registered S3 storage --
@@ -415,8 +423,10 @@ export interface CoolifyPort {
     }>;
 }
 /**
- * The Cloudflare calls this executor makes, shaped to match
- * `@wtfalch/providers/cloudflare`'s `CloudflareClient` method-for-method.
+ * The Cloudflare zone calls the platform steps make directly, shaped to match
+ * `@wtfalch/providers/cloudflare`'s `CloudflareClient` method-for-method. They
+ * run before edge exists (edge's own step finds the apex zone), so they cannot
+ * go through edge. An org's steps use {@link ZonePort}, which does.
  */
 export interface CloudflarePort {
     findZoneByApex(domain: string): Promise<{
@@ -427,132 +437,6 @@ export interface CloudflarePort {
         id: string;
         name: string;
     }>;
-    findTunnelByName(name: string): Promise<{
-        id: string;
-        name: string;
-    } | undefined>;
-    createTunnel(name: string): Promise<{
-        id: string;
-        name: string;
-    }>;
-    putTunnelConfig(tunnelId: string, config: unknown): Promise<unknown>;
-    /**
-     * The tunnel's connector token (#197) -- a `cloudflared` container reads
-     * this at boot to dial into the tunnel. A live credential: matches
-     * `@wtfalch/providers`' `CloudflareClient.getTunnelToken` method-for-method.
-     * A caller must hand this straight to `bulkUpsertEnvs` and nowhere else --
-     * never a log, an error, a return value or a recorded scope id (see
-     * `cloudflared-connector.ts`'s `ensureCloudflaredConnector`).
-     */
-    getTunnelToken(tunnelId: string): Promise<string>;
-    /** `FoundryPlanApply.destroy`'s teardown of the org's own Cloudflare tunnel. */
-    deleteTunnel(tunnelId: string): Promise<void>;
-    /** `cloudflareAccess` finds the org's Access app by domain before creating one (#84). */
-    listAccessApps(): Promise<Array<{
-        id: string;
-        name: string;
-        domain: string;
-    }>>;
-    createAccessApp(app: {
-        name: string;
-        domain: string;
-        type: string;
-    }): Promise<{
-        id: string;
-    }>;
-    listAccessPolicies(appId: string): Promise<Array<{
-        id: string;
-        name: string;
-        include?: unknown[];
-    }>>;
-    createAccessPolicy(appId: string, policy: {
-        name: string;
-        decision: string;
-        include: unknown[];
-    }): Promise<{
-        id: string;
-    }>;
-    /**
-     * `cloudflareAccess` resolves a `kind: 'service-token'` rule's named
-     * token to its id (#246) -- the token itself is a live Cloudflare
-     * resource this package never mints; `undefined` when no token by that
-     * name exists yet.
-     */
-    findServiceTokenByName(name: string): Promise<{
-        id: string;
-    } | undefined>;
-    deleteAccessApp(appId: string): Promise<void>;
-    /**
-     * `FoundryPlanApply.destroy`'s teardown of any DNS record foundry created
-     * 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. */
-    findDnsRecord(zoneId: string, name: string, type?: string): Promise<Array<{
-        id: string;
-        type: string;
-        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;
-        content: string;
-        proxied?: boolean;
-        ttl?: number;
-        /** Required by Cloudflare for an `MX` record. */
-        priority?: number;
-    }): Promise<{
-        id: string;
-        name: string;
-        content: string;
-    }>;
-    updateDnsRecord(zoneId: string, recordId: string, rec: {
-        type: string;
-        name: string;
-        content: string;
-        proxied?: boolean;
-        ttl?: number;
-        priority?: number;
-    }): Promise<{
-        id: string;
-        name: string;
-        content: string;
-    }>;
-    /**
-     * Escape hatch (mirrors `CoolifyPort.raw`'s own precedent above) --
-     * `@wtfalch/providers` 0.5.0's `CloudflareClient` has no typed method for
-     * Health Checks or zone rulesets/rate-limiting rules
-     * (https://github.com/wtfalch/foundry/issues/43), only this public,
-     * generic `request<T>(method, path, body?, missingOkay?)`, which
-     * this port names directly rather than inventing a narrower method no real
-     * client could structurally satisfy. `cloudflareRateLimit` below is its one
-     * caller today. `missingOkay` makes a 404 resolve to `undefined` instead of
-     * throwing, matching `CloudflareClient`'s own real behavior exactly.
-     */
-    request<T>(method: string, path: string, body?: unknown, missingOkay?: boolean): Promise<T>;
 }
 /**
  * One Cloudflare Workers rate limiting binding, Cloudflare's own "simple"
@@ -569,7 +453,8 @@ export interface WorkersRateLimitBinding {
     };
 }
 /**
- * The Cloudflare Workers calls `cloudflareWorker` makes (#318, F8): deploys
+ * The Workers calls `cloudflareWorker` makes (#318, F8), served by edge's
+ * `platform.workers` through `createEdgeWorkers` (`edge-workers.ts`): deploys
  * a plain Worker from an entry's `worker` declaration and routes it on the
  * org's own zone. Optional on {@link FoundryStepExecutorPorts} -- a host
  * with no Workers rights on its Cloudflare token (the issue's own "Human
@@ -583,15 +468,13 @@ export interface WorkersRateLimitBinding {
  * package (estate DECISIONS.md, 2026-10-04, "offline.tf Worker setup" --
  * "Foundry consumes and deploys the artifact through the provider
  * boundary... No manual build step and no source checkout/bundling in
- * Foundry"). The real adapter refuses a fetched body whose digest does not
- * match. The upload itself is a multipart request Cloudflare's API wants (a
- * `metadata` part naming `main_module` and `bindings`, plus the module) --
- * `CloudflarePort.request` sends JSON only, so this port names the call
- * directly rather than forcing it through that escape hatch.
+ * Foundry"). The host hands `createEdgeWorkers` a `fetchArtifact(url, sha256)`
+ * that fetches and verifies the bytes; the adapter sends them to edge as
+ * base64 with the digest, and edge checks the digest again.
  *
  * `deleteRoute`/`deleteScript` are idempotent: deleting a route or script
  * that is already gone resolves rather than throwing, the same contract
- * `CloudflarePort.deleteDnsRecord`/`deleteAccessApp` give their own
+ * `DnsPort.deleteDnsRecord`/`deleteAccessApp` give their own
  * already-gone case via `isNotFoundError` at the call site -- here it is
  * the port's own job, since `cloudflareWorker` deletes a route or script by
  * id/name it already recorded, with nothing live to re-check first.
@@ -1373,6 +1256,37 @@ export interface EdgePort {
         secret: string;
     }>;
     revokeKey(organisationId: string, keyId: string): Promise<void>;
+    /**
+     * F4.dns: edge's platform DNS client (`createEdgeClient({ baseUrl, key
+     * }).platform.dns`), built with the same platform key that mints and
+     * revokes. Foundry reads and writes every DNS record through it.
+     */
+    dns: EdgePlatformDns;
+    /**
+     * F4.tunnels: edge's platform tunnel client (`createEdgeClient({ baseUrl,
+     * key }).platform.tunnels`), built with the same platform key. Foundry
+     * creates, configures, reads the token of and deletes every tunnel through it.
+     */
+    tunnels: EdgePlatformTunnels;
+    /**
+     * F4.access: edge's platform Access client (`createEdgeClient({ baseUrl,
+     * key }).platform.access`), built with the same platform key. Foundry
+     * finds, creates, adopts and deletes every Access app, and adds its
+     * policies, through it.
+     */
+    access: EdgePlatformAccess;
+    /**
+     * F4.ratelimits: edge's platform rate limiting client (`createEdgeClient({
+     * baseUrl, key }).platform.ratelimits`), built with the same platform key.
+     * Foundry lists, adopts and creates every rate limiting rule through it.
+     */
+    ratelimits: EdgePlatformRateLimits;
+    /**
+     * F4.zones: edge's platform zones client (`createEdgeClient({ baseUrl,
+     * key }).platform.zones`), built with the same platform key. Foundry
+     * looks up and creates every org zone through it.
+     */
+    zones: EdgePlatformZones;
     /** Refuses a label any hosting entry of `organisationId` already holds. Rerun whenever the org's own label set changes. */
     setReservedLabels(organisationId: string, labels: string[]): Promise<void>;
 }
@@ -1420,7 +1334,6 @@ export interface PlatformOrgPortSource {
 }
 export interface FoundryStepExecutorPorts {
     coolify: CoolifyPort;
-    cloudflare: CloudflarePort;
     zitadel: ZitadelPort;
     mail: MailPort;
     lettermint: LettermintPort;
@@ -1455,6 +1368,31 @@ export interface FoundryStepExecutorPorts {
      * throw.
      */
     edge?: EdgePort;
+    /**
+     * F4.dns: overrides the DNS calls, which otherwise go through `edge.dns`
+     * (see {@link EdgePort.dns}). Kept for a host or a test that supplies its own.
+     */
+    dns?: DnsPort;
+    /**
+     * F4.tunnels: overrides the tunnel calls, which otherwise go through
+     * `edge.tunnels` (see {@link EdgePort.tunnels}). Kept for a host or a test that supplies its own.
+     */
+    tunnels?: TunnelPort;
+    /**
+     * F4.access: overrides the Access calls, which otherwise go through
+     * `edge.access` (see {@link EdgePort.access}). Kept for a host or a test that supplies its own.
+     */
+    access?: AccessPort;
+    /**
+     * F4.ratelimits: overrides the rate limiting rule calls, which otherwise go through
+     * `edge.ratelimits` (see {@link EdgePort.ratelimits}). Kept for a host or a test that supplies its own.
+     */
+    ratelimits?: RateLimitPort;
+    /**
+     * F4.zones: overrides the zone calls, which otherwise go through
+     * `edge.zones` (see {@link EdgePort.zones}). Kept for a host or a test that supplies its own.
+     */
+    zones?: ZonePort;
     /**
      * #177: builds the files, AI and jobs ports from the platform's addresses
      * and held keys. A port set above overrides it (tests); with neither, the
@@ -1516,6 +1454,17 @@ export interface FoundryStepExecutorPorts {
      * passes the same store instance it constructs `FoundryPlanApply` with.
      */
     declaredOrgStore: Pick<DeclaredOrgStore, 'findOrgIdForZone'>;
+    /**
+     * #543: clock, sleep and `fetch` for the health-check wait every company
+     * app's own redeploy now goes through (`deploy-health.ts`'s
+     * `waitForNewDeployment`) -- the same override shape `platform-providers.ts`'s
+     * own `PlatformMailDeps.runtime`/`PlatformArchonDeps.runtime` already take,
+     * here on one shared port instead of one per platform step since this
+     * executor is the one class every company-app step runs through. Optional:
+     * without it, {@link defaultSleep} (plain `setTimeout`) and the real
+     * `fetch`/`Date.now` are used.
+     */
+    runtime?: DeployHealthRuntime;
 }
 /**
  * Thrown by name for a step this executor deliberately does not implement:
@@ -1527,6 +1476,26 @@ export interface FoundryStepExecutorPorts {
 export declare class NotBuiltError extends Error {
     constructor(step: string, detail: string);
 }
+/**
+ * `cms.<domain>` -- the cms studio's own hostname (`cmsSite` below), apart
+ * from the public site itself at `org.domain` (used directly there). Called
+ * from `cmsSite` and from `zitadelApp` for the fixed `cms` client (#139),
+ * both of which only run once `org.site.enabled` is true, so `org.domain`
+ * is non-null by the same `validateSite` guarantee
+ * {@link tunnelIngressHostnames}'s own doc comment cites.
+ */
+export declare function cmsHostnameFor(org: DeclaredOrg): string;
+/**
+ * #145's "Decided" (2026-09-27): the calls service's own public hostname.
+ * `calls.usesDomain: false` (or no `domain`) is served flat, like
+ * `<slug>-stage.oikos.host` and `<slug>-pr-<n>.oikos.host` (`../slug.ts`) --
+ * the shared tunnel's wildcard `*.oikos.host` DNS record already reaches it,
+ * so nothing changes in `scripts/shared-ingress.mjs`. `calls.usesDomain: true`
+ * gets `calls.<domain>` instead, on its own per-org tunnel
+ * ({@link tunnelIngressHostnames}), the same subdomain-of-the-org's-own-domain
+ * shape {@link cmsHostnameFor} uses for `cms.<domain>`.
+ */
+export declare function callsHostnameFor(org: DeclaredOrg): string;
 /**
  * The health URLs an outside prober should call for this org (#43): one per
  * app foundry runs for it. A hosting org's app answers at its own hostname,
@@ -1579,6 +1548,12 @@ export declare const databaseStartWait: {
 };
 export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer {
     private readonly ports;
+    private edgeDns;
+    private edgeTunnels;
+    private edgeAccess;
+    private edgeRateLimits;
+    private edgeZones;
+    private edgeWriteSlot;
     constructor(ports: FoundryStepExecutorPorts);
     execute(action: StepAction, context: StepExecutionContext): Promise<{
         resourceId?: string;
@@ -1615,12 +1590,10 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * gate), so `org.domain` is set and that zone is the org's alone, never
      * shared with another org the way `oikos.host` is.
      *
-     * Rate limiting rules attach to a zone's `http_ratelimit` phase entry
-     * point ruleset, one `GET`/`PUT` pair per zone (`@wtfalch/providers` 0.5.0
-     * has no typed method for either -- `CloudflarePort.request`'s own doc
-     * comment) -- so "find by name" here means reading that one ruleset's
-     * `rules[]` and matching `RATE_LIMIT_RULE_DESCRIPTION`, the same shape
-     * `cloudflareAccess` above finds its own Access app by name. The Free
+     * Rate limiting rules go through edge (`RateLimitPort`) -- so "find by
+     * name" here means listing the zone's rules and matching
+     * `RATE_LIMIT_RULE_DESCRIPTION`, the same shape `cloudflareAccess` above
+     * finds its own Access app by name. The Free
      * plan allows exactly one rule per zone, so a rule already there under a
      * different description is refused, never adopted or replaced, mirroring
      * `cloudflareAccess`'s own refusal when a foreign Access app already
@@ -2419,6 +2392,36 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     /** #177: the host's own port when it supplies one, else the platform's, built from its address and held key. */
     private filesPort;
     private aiPort;
+    /**
+     * Every DNS record call runs through edge (`edge.dns`, the platform
+     * credential), adopting live records before it first changes them. `dns` on
+     * the ports is a seam for a host or test that supplies its own {@link DnsPort}.
+     */
+    private dnsPort;
+    /**
+     * Every tunnel call runs through edge (`edge.tunnels`, the platform
+     * credential), adopting a live tunnel before it first configures, reads the
+     * token of or deletes it. Shares edge's write slot with {@link dnsPort}.
+     */
+    private tunnelPort;
+    /**
+     * Every Access call runs through edge (`edge.access`, the platform
+     * credential), adopting a live app before it first adds a policy to or
+     * deletes it. Shares edge's write slot with {@link dnsPort}.
+     */
+    private accessPort;
+    /**
+     * Every rate limiting rule call runs through edge (`edge.ratelimits`, the
+     * platform credential), adopting the live rule before it first creates it.
+     * Shares edge's write slot with {@link dnsPort}.
+     */
+    private rateLimitPort;
+    /**
+     * Every zone lookup and create runs through edge (`edge.zones`, the
+     * platform credential), adopting a live zone before it first creates it.
+     * Shares edge's write slot with {@link dnsPort}.
+     */
+    private zonePort;
     private jobsPort;
     private jobsRegistration;
     /** `deliverSecret`, tried up to {@link JOBS_DELIVERY_ATTEMPTS} times; true once one attempt succeeds. */
@@ -2647,7 +2650,7 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * a record someone proxied by hand is put back. An `MX` record carries the
      * priority it was given, which Cloudflare requires.
      *
-     * Found by an exact name+type match (`CloudflarePort.findDnsRecord`'s own
+     * Found by an exact name+type match (`DnsPort.findDnsRecord`'s own
      * doc comment) so a stale record of a different type is never taken for a
      * match. A name can hold several `TXT` records (an apex often holds a site
      * verification beside SPF), so a `TXT` record only replaces one that