@wtfalch/foundry 0.17.0 → 0.17.1

package/dist/plan/executor.d.ts

@@ -2,7 +2,7 @@ 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 { StepAction } from './diff.js';
+import { type StepAction } from './diff.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';
@@ -80,11 +80,25 @@ export interface CoolifyPort {
      * `findOrCreateCmsApp`'s own check of whether an app it found by name
      * (rather than just created) needs starting again (#116 review round 3,
      * Finding 1).
+     *
+     * #480: also the rolling-update/health-check settings `updateApplication`
+     * patches on `platform:archon` (`is_consistent_container_name_enabled`,
+     * `custom_network_aliases`, `health_check_enabled`), so a drift check can
+     * tell a setting changed back by hand from one this run already applied.
+     * `is_consistent_container_name_enabled` comes back nested under
+     * `settings`, not at the top level -- confirmed against live Coolify
+     * 4.3.23 (PR #482 review); `custom_network_aliases` and
+     * `health_check_enabled` are both top-level there.
      */
     getApplication(uuid: string): Promise<{
         uuid: string;
         status?: string;
         custom_labels?: string | null;
+        settings?: {
+            is_consistent_container_name_enabled?: boolean;
+        };
+        custom_network_aliases?: string | null;
+        health_check_enabled?: boolean;
     }>;
     createGithubAppApplication(input: {
         project_uuid: string;
@@ -535,6 +549,72 @@ export interface CloudflarePort {
      */
     request<T>(method: string, path: string, body?: unknown, missingOkay?: boolean): Promise<T>;
 }
+/**
+ * One Cloudflare Workers rate limiting binding, Cloudflare's own "simple"
+ * shape -- the metadata part {@link WorkersPort.uploadScript} sends beside
+ * the module (#318).
+ */
+export interface WorkersRateLimitBinding {
+    type: 'ratelimit';
+    name: string;
+    namespace_id: string;
+    simple: {
+        limit: number;
+        period: number;
+    };
+}
+/**
+ * The Cloudflare Workers calls `cloudflareWorker` makes (#318, F8): deploys
+ * a plain Worker from an entry's `edge` 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
+ * steps": the token needs them added first) wires none, and the planner
+ * reports every `edge` entry blocked instead of planning a step that would
+ * throw (`FoundryPlanApplyOptions.edgeWorkers`).
+ *
+ * `uploadScript` takes the *declared artifact reference*, not bytes:
+ * fetching `artifactUrl` and verifying it against `artifactSha256` happens
+ * behind this port, never in `cloudflareWorker` or anywhere else in this
+ * 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.
+ *
+ * `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
+ * 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.
+ */
+export interface WorkersPort {
+    /** Whether a script named `name` already exists -- checked only on an entry's first-ever apply, so `cloudflareWorker` can refuse to overwrite a script it did not create instead of PUTting over it by its deterministic name. */
+    scriptExists(name: string): Promise<boolean>;
+    uploadScript(input: {
+        name: string;
+        artifactUrl: string;
+        artifactSha256: string;
+        compatibilityDate: string;
+        bindings?: WorkersRateLimitBinding[];
+    }): Promise<void>;
+    /** The script name currently bound to `pattern` in `zoneId`, or `undefined` for no route there. */
+    findRoute(zoneId: string, pattern: string): Promise<{
+        id: string;
+        script: string;
+    } | undefined>;
+    /** Creates the route if absent; `cloudflareWorker` only calls this once `findRoute` has confirmed the pattern is foundry's own or unclaimed. */
+    createRoute(zoneId: string, pattern: string, script: string): Promise<{
+        id: string;
+    }>;
+    /** A no-op, not a throw, when `routeId` is already gone. */
+    deleteRoute(zoneId: string, routeId: string): Promise<void>;
+    /** A no-op, not a throw, when `name` is already gone. */
+    deleteScript(name: string): Promise<void>;
+}
 /**
  * One DNS record a Lettermint domain's own response says must be published --
  * `purpose` is Lettermint's own label (`return_path`, `dmarc`, `dkim_legacy`,
@@ -1257,6 +1337,37 @@ export interface AiOrganisationPort {
         limitMicros: string;
     }): Promise<unknown>;
 }
+/**
+ * #317 (F7): the names service's own management API
+ * (https://github.com/wtfalch/names, live on main, offering `mintKey`,
+ * `revokeKey` and `setReservedLabels`) -- this port states the shape this
+ * executor assumes of it. `organisationId` is the org itself: unlike
+ * `AiOrganisationPort.mintNestedKey`, names takes no separate minter key
+ * id, so `namesEntryKey` mints directly below the org. A real adapter
+ * wiring this port into `platform-providers.ts` is tracked separately
+ * (https://github.com/wtfalch/archon/issues/339).
+ */
+export interface NamesPort {
+    /**
+     * `domain` is required: names's own `mintKey` refuses a request without a
+     * lowercase hostname and binds the key to it
+     * (`wtfalch/names`'s `packages/service/src/keys.ts`) -- `namesEntryKey`
+     * passes `org.domain`, which `validateEntryNames` already requires before
+     * `uses.names` is accepted.
+     */
+    mintKey(input: {
+        organisationId: string;
+        domain: string;
+        name: string;
+        expiresDays: number;
+    }): Promise<{
+        id: string;
+        secret: string;
+    }>;
+    revokeKey(organisationId: string, keyId: string): Promise<void>;
+    /** 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>;
+}
 /**
  * #173: the jobs scheduler's own admin API
  * (https://github.com/wtfalch/jobs, "The admin API", jobs#62), authenticated
@@ -1325,6 +1436,15 @@ export interface FoundryStepExecutorPorts {
     /** Flat, not a factory: `organisationId` is an explicit argument on every method of both ports (see each port's own doc comment; #177 dropped the `filesLimitsFor`/`aiLimitsFor` factories this used to need). */
     filesOrganisation?: FilesOrganisationPort;
     aiOrganisation?: AiOrganisationPort;
+    /**
+     * #317 (F7): mints an entry's names key -- see {@link NamesPort}'s own
+     * doc comment. Optional the same way `jobsScheduler` is: a host with no
+     * names service deployed builds the executor without one, and tells the
+     * planner so (`FoundryPlanApplyOptions.names`), which then reports each
+     * entry's `uses.names` step as blocked instead of planning one that would
+     * throw.
+     */
+    names?: NamesPort;
     /**
      * #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
@@ -1347,6 +1467,13 @@ export interface FoundryStepExecutorPorts {
      * `FoundryPlanApplyOptions.broker`).
      */
     broker?: BrokerPort;
+    /**
+     * #318: deploys and routes an entry's `edge` Worker -- see
+     * {@link WorkersPort}'s own doc comment. Optional the same way `broker` is:
+     * without it the plan reports each `edge` entry blocked (the host also
+     * sets `FoundryPlanApplyOptions.edgeWorkers`).
+     */
+    workers?: WorkersPort;
     /**
      * Hands a just-minted, one-time secret (today: an API app's
      * `clientSecret`) to the host, immediately after the provider returns it
@@ -1490,6 +1617,49 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * holds the hostname.
      */
     private cloudflareRateLimit;
+    /**
+     * `plan/diff.ts`'s `planEdgeWorkers` (#318, F8): deploys one entry's
+     * `edge` Worker and routes it on the org's own zone. Throws by name
+     * without a {@link WorkersPort}, the same `jobsRegistration` shape --
+     * `planEdgeWorkers` reports the step blocked instead while the host has
+     * none, so this only fires against a stale plan. The route is checked
+     * before upload: a foreign route already on the pattern is refused, never
+     * adopted or replaced (`cloudflareAccess`'s own precedent for a foreign
+     * resource on the same name), so a Worker is never deployed only to find
+     * nothing can route to it.
+     *
+     * Order on apply: record (and persist) the uploaded name and clear the
+     * retired marker, upload, record the pending route, create the route only
+     * if needed, delete any *previous* route this entry recorded on its own
+     * zone, then record the new route id/zone/pattern and the applied
+     * declaration last -- every crash point leaves a recorded trace that
+     * retire and destroy can clean up (#318 re-review), and per CLAUDE.md's
+     * "Declared changes apply" nothing is marked done until the
+     * live state actually matches it.
+     */
+    private cloudflareWorker;
+    /**
+     * The zone id a recorded route lives in, or `undefined` only when that
+     * zone is *positively* gone -- its apex resolves to no zone, or to a
+     * different zone than the one recorded (#318 re-review). Reads the zone
+     * recorded beside the route, never `org.domain`: the route id and its
+     * zone are always recorded together (the apply branch below writes both
+     * in the same batch, and the pending-route marker carries its own zone
+     * too), so a route id with no zone recorded cannot happen within this
+     * feature -- and re-resolving from `org.domain` as a fallback would risk
+     * looking up the *new* zone after a domain change and leaving the route
+     * live on the old one, the exact bug a recorded-per-route zone exists to
+     * avoid (#318 re-review).
+     */
+    private liveEdgeZone;
+    /** Deletes the route an interrupted apply was creating, if `findRoute` shows it exists, points at that apply's script, and is not `keepRouteId`. */
+    private deletePendingEdgeRoute;
+    /**
+     * Retire and destroy share this: delete the recorded route on its own
+     * zone, then any route an interrupted apply created but never recorded,
+     * then the script. Records nothing -- the caller does.
+     */
+    private teardownEdgeWorker;
     private zitadelIssuer;
     /**
      * `plan/diff.ts`'s `planOwner`: invites the org's owner into its ZITADEL
@@ -1761,6 +1931,22 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * comment), never logged, never interpolated into a thrown error -- the
      * same discipline `pushDatabaseUrl`'s doc comment states for a database's
      * own connection string.
+     *
+     * #491: none of the above applies to the org whose mail domain is the
+     * platform's own apex -- it shares the platform's existing Lettermint
+     * project (`platformLettermintProjectId`, from `DeclaredPlatform.mail`)
+     * instead of minting a `<slug>-app` one, and this method never creates or
+     * deletes a project for it. `platformApex`/`platformLettermintProjectId`
+     * come straight off this step's own `desired`, the same "the executor
+     * writes exactly what the plan showed" rule `coolifyMail` already follows
+     * for its own `apex`/`mailHost` -- the caller (`coolifyApp`) refuses a
+     * `desired` missing the `platformApex` key outright as a stale plan --
+     * checked here, after the no-op-until-a-mail-domain-exists return just
+     * below, rather than unconditionally at the call site: every other
+     * `coolify:app` concern (hostnames, ports, settings, the sign-in env...)
+     * has nothing to do with Lettermint and must keep working the moment a
+     * mail domain was never even recorded for this org, the same as before
+     * this field existed (review round 2, finding 3).
      */
     private ensureAppLettermintMail;
     /**
@@ -1796,6 +1982,12 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * it the same way the app step does, rather than assuming it already
      * exists -- the domain must never end up unrestricted, whichever step gets
      * there first.
+     *
+     * #491: this org's own `<slug>-relay` project is unaffected by whether it
+     * is the platform's own org -- only the domain restriction
+     * (`platformApex`/`platformLettermintProjectId`, forwarded to
+     * {@link ensureLettermintDomainRestriction}) and the delete loop below
+     * (which must never delete the platform's own project) change.
      */
     private ensureOrgLettermintRelay;
     /**
@@ -1818,6 +2010,21 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * unrestricted domain cannot verify and cannot send, whichever project
      * owns it (post-#140 review finding, restated here rather than only at
      * the one call site it used to have).
+     *
+     * #491: `platformApex`/`platformLettermintProjectId` cover both callers at
+     * once -- when `mailDomain` is the platform's own apex, the platform's
+     * project id is always folded into the restriction, so a plan that shares
+     * the platform's project (rather than minting a `<slug>-app` one) never
+     * ends up restricting that org's domain to nothing. A no-op for every
+     * other org's domain, since `mailDomain` never matches `platformApex` there.
+     * Review round 2, finding 4: a declared id that is not among `allProjects`
+     * (a mistype, or the project was deleted in Lettermint) is refused rather
+     * than folded in anyway -- that would restrict the apex to whatever *is*
+     * live (the relay project, say) plus an id naming nothing, which excludes
+     * the real platform project from its own domain exactly as completely as
+     * never restricting it at all. Centralised here rather than duplicated at
+     * each caller, since both {@link ensureAppLettermintMail} and
+     * {@link ensureOrgLettermintRelay} reach the apex through this one method.
      */
     private ensureLettermintDomainRestriction;
     /**
@@ -2356,6 +2563,13 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * domain recorded) and on a same-domain re-apply (compared
      * case-insensitively, the same rule {@link findExactLettermintDomain}
      * applies to the lookup itself).
+     *
+     * #491 review: also a no-op when the previous domain is the platform's own
+     * apex -- an org that moves its mail *off* that domain (`usesDomain` flips,
+     * or `org.domain` changes) must never delete it here, the same protection
+     * {@link parkLettermintMail} already gives the apex on a move to `off`.
+     * `planMail` only blocks a move *onto* the apex (no project id yet); a move
+     * away from it reaches this method with nothing to block it otherwise.
      */
     private deleteStaleLettermintDomain;
     /**
@@ -2398,6 +2612,10 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * A no-op until a previous apply recorded {@link MAIL_DOMAIN_SCOPE_KEY}:
      * nothing was ever provisioned for an org whose mail went straight from
      * never-applied to off.
+     *
+     * #491: when `mailDomain` is the platform's own apex, this must never
+     * delete the platform's own project (the delete loop skips it by id) or
+     * the platform's own domain (returns before the domain lookup/delete).
      */
     private parkLettermintMail;
     /**
@@ -2497,6 +2715,22 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * new key.
      */
     private revokeEntryKey;
+    /**
+     * F7 (#317): mints one entry's names key directly below the org (names
+     * takes no separate minter key id, unlike ai/files), writes `NAMES_URL`
+     * and `NAMES_API_KEY` to the entry's app env, then restarts it. Retires
+     * the key when `uses.names` is removed. Follows the "one mint" rule
+     * (CLAUDE.md "Platform steps"): the id is recorded as undelivered and
+     * persisted before delivery is attempted, so a crash or a failed write
+     * never leads to a second mint -- `planEntryNamesKeys` blocks instead.
+     */
+    private namesEntryKey;
+    /**
+     * F7 (#317): `plan/entry-names-key.ts`'s `planNamesReservedLabels` --
+     * tells the names service every label this org's own entries already
+     * hold, so names refuses a customer claiming one of them.
+     */
+    private namesReservedLabels;
     /**
      * F6b: mints or renews the org's own files key, or revokes the ones a
      * renewal replaced. The key is minted below the files organisation's owner