@wtfalch/foundry 0.19.1 → 0.21.0

package/dist/plan/platform-providers.d.ts

@@ -3,6 +3,9 @@ import type { DeclaredOrg } from '../org.js';
 import type { DeclaredPlatform } from '../platform.js';
 import type { DeclaredOrgStore, PlatformStore } from '../store.js';
 import type { StepAction } from './diff.js';
+import type { AccessPort } from './edge-access.js';
+import type { DnsPort } from './edge-dns.js';
+import type { TunnelPort } from './edge-tunnels.js';
 import type { CloudflarePort, CoolifyPort, FoundryStepExecutorPorts, ZitadelPort } from './executor.js';
 import type { LiveResource, PlatformCloudflareReader, PlatformCoolifyReader } from './live.js';
 import type { PlatformStepExecutionContext, PlatformStepExecutor } from './plan-apply.js';
@@ -14,6 +17,34 @@ import { type CallsSfuPlatformDeps } from './platform-sfu.js';
  * positions, so every #167-era caller of {@link FoundryPlatformStepExecutor}
  * (zone only) keeps compiling with this third argument simply omitted.
  */
+/**
+ * F4.dns: builds the {@link DnsPort} a platform step writes its records
+ * through, given the address edge answers at on the Coolify network
+ * ({@link PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY}). The host builds it with
+ * `createEdgeDns(createEdgeClient({ baseUrl, key }).platform.dns)`, `key`
+ * being the platform key held under {@link PLATFORM_EDGE_KEY_REF}.
+ */
+export type PlatformDnsFactory = (edgeUrl: string) => DnsPort | Promise<DnsPort>;
+/**
+ * F4.tunnels: builds the {@link TunnelPort} a platform step creates, configures
+ * and reads the connector token of its tunnel through, given the same address
+ * as {@link PlatformDnsFactory}. The host builds it with
+ * `createEdgeTunnels(createEdgeClient({ baseUrl, key }).platform.tunnels)`,
+ * `key` being the platform key held under {@link PLATFORM_EDGE_KEY_REF}.
+ */
+export type PlatformTunnelsFactory = (edgeUrl: string) => PlatformTunnelPort | Promise<PlatformTunnelPort>;
+/** The tunnel calls a platform step makes; it never deletes one. */
+export type PlatformTunnelPort = Pick<TunnelPort, 'findTunnelByName' | 'createTunnel' | 'putTunnelConfig' | 'getTunnelToken'>;
+/**
+ * F4.access: builds the {@link AccessPort} a platform step finds, creates and
+ * deletes its Access app through, given the same address as
+ * {@link PlatformDnsFactory}. The host builds it with
+ * `createEdgeAccess(createEdgeClient({ baseUrl, key }).platform.access)`,
+ * `key` being the platform key held under {@link PLATFORM_EDGE_KEY_REF}.
+ */
+export type PlatformAccessFactory = (edgeUrl: string) => PlatformAccessPort | Promise<PlatformAccessPort>;
+/** The Access calls a platform step makes. */
+export type PlatformAccessPort = Pick<AccessPort, 'listAccessApps' | 'createAccessApp' | 'listAccessPolicies' | 'createAccessPolicy' | 'deleteAccessApp'>;
 /**
  * The SMTP call `provisionPlatformAuth` makes on the instance's ZITADEL.
  * `@wtfalch/providers` gains it in 0.7.2; stated here so foundry compiles
@@ -35,9 +66,11 @@ export interface PlatformZitadelSmtp {
 }
 export interface PlatformAuthDeps {
     coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'requireGithubApp' | 'createGithubAppApplication' | 'createDockerImageApplication' | 'createDockerfileApplication' | 'createPostgresDatabase' | 'getDatabase' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy' | 'raw'>;
-    cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'findTunnelByName' | 'createTunnel' | 'putTunnelConfig' | 'findDnsRecord' | 'createDnsRecord' | 'updateDnsRecord'
-    /** #197: fetches the tunnel's connector token for {@link ensureCloudflaredConnector}. */
-     | 'getTunnelToken'>;
+    /** F4.dns: every DNS record call, through edge at its recorded address (see {@link PlatformDnsFactory}). */
+    dns: PlatformDnsFactory;
+    /** F4.tunnels: every tunnel call, through edge at its recorded address (see {@link PlatformTunnelsFactory}). */
+    tunnels: PlatformTunnelsFactory;
+    cloudflare: Pick<CloudflarePort, 'findZoneByApex'>;
     /** Must target the platform's own new instance (its issuer), or `zitadelForInstance` must be set. */
     zitadel: Pick<ZitadelPort, 'findOrCreateOrg' | 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats' | 'inviteOrgOwner'> & PlatformZitadelSmtp;
     /**
@@ -149,6 +182,18 @@ export interface FoundryPlatformStepExecutorOptions {
      * planned.
      */
     backup?: PlatformBackupDeps;
+    /**
+     * #540: dependencies for `coolify:app` keyed {@link PLATFORM_HC_KEY} --
+     * optional for the same reason as `auth`; a host that declares
+     * `platform.hc.enabled` without it gets the step reported as blocked.
+     */
+    hc?: PlatformHcDeps;
+    /**
+     * #540: dependencies for the `heartbeats:reconcile` step -- optional for
+     * the same reason as `auth`; `hc` applied with this unset gets the
+     * heartbeat checks reported as blocked rather than planned.
+     */
+    heartbeats?: PlatformHeartbeatsDeps;
 }
 /**
  * The real {@link PlatformStepExecutor} for the two steps built so far:
@@ -228,6 +273,8 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
     private readonly edge?;
     private readonly archon?;
     private readonly backup?;
+    private readonly hc?;
+    private readonly heartbeats?;
     constructor(cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'createZone'>, declaredOrgStore: Pick<DeclaredOrgStore, 'findOrgIdForZone' | 'list' | 'get'>, options?: FoundryPlatformStepExecutorOptions);
     blockedSteps(platform: DeclaredPlatform, recordedIds?: Readonly<Record<string, string>>): Promise<{
         auth?: string;
@@ -240,6 +287,9 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
         archon?: string;
         mail?: string;
         backupExecutorMissing?: boolean;
+        hc?: string;
+        heartbeatsExecutorMissing?: boolean;
+        heartbeatsApiKeyMissing?: boolean;
     }>;
     /**
      * Whether Archon's live Access policy lets through anyone but the declared
@@ -377,7 +427,11 @@ export declare function defaultStalwartForInstance(input: {
  */
 export interface PlatformMailDeps {
     coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'createDockerImageApplication' | 'createDockerfileApplication' | 'raw' | 'listStorages' | 'createPersistentStorage' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy' | 'deployAndWait'>;
-    cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'findTunnelByName' | 'createTunnel' | 'putTunnelConfig' | 'getTunnelToken' | 'findDnsRecord' | 'createDnsRecord' | 'updateDnsRecord'>;
+    /** F4.dns: every DNS record call, through edge at its recorded address (see {@link PlatformDnsFactory}). */
+    dns: PlatformDnsFactory;
+    /** F4.tunnels: every tunnel call, through edge at its recorded address (see {@link PlatformTunnelsFactory}). */
+    tunnels: PlatformTunnelsFactory;
+    cloudflare: Pick<CloudflarePort, 'findZoneByApex'>;
     /**
      * Must target the platform's own ZITADEL instance, or `zitadelForInstance`
      * must be set. `provisionPlatformMail` finds or creates a `mail` project
@@ -421,7 +475,13 @@ export interface PlatformMailRuntime {
  */
 export interface PlatformArchonDeps {
     coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'requireGithubApp' | 'createGithubAppApplication' | 'createDockerfileApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'raw' | 'bulkUpsertEnvs' | 'listEnvs' | 'deleteEnv' | 'updateApplication' | 'deploy' | 'deployAndWait'>;
-    cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'findTunnelByName' | 'createTunnel' | 'putTunnelConfig' | 'getTunnelToken' | 'findDnsRecord' | 'createDnsRecord' | 'updateDnsRecord' | 'listAccessApps' | 'createAccessApp' | 'listAccessPolicies' | 'createAccessPolicy' | 'deleteAccessApp'>;
+    /** F4.dns: every DNS record call, through edge at its recorded address (see {@link PlatformDnsFactory}). */
+    dns: PlatformDnsFactory;
+    /** F4.tunnels: every tunnel call, through edge at its recorded address (see {@link PlatformTunnelsFactory}). */
+    tunnels: PlatformTunnelsFactory;
+    /** F4.access: every Access app call, through edge at its recorded address (see {@link PlatformAccessFactory}). */
+    access: PlatformAccessFactory;
+    cloudflare: Pick<CloudflarePort, 'findZoneByApex'>;
     /** Must target the platform's own ZITADEL instance, or `zitadelForInstance` must be set. */
     zitadel: Pick<ZitadelPort, 'findOrCreateOrg' | 'findOrCreateProject' | 'createOidcApp' | 'listApps' | 'deleteApp'>;
     /** {@link PlatformAuthDeps.zitadelForInstance}, for Archon's sign-in client. */
@@ -633,6 +693,17 @@ export interface PlatformAiRuntime {
     migrateIntervalMs?: number;
     /** Tries at handing a secret to the host (default 3): the management key and the signing key both use this. */
     deliverAttempts?: number;
+    /**
+     * #543: injected for tests, against a fake runner host -- the runner's own
+     * deploy wait now does a `'ready'` probe of its `/api/health`, the same
+     * `DeployHealthRuntime.fetch` field `provisionPlatformMail`/
+     * `provisionPlatformArchon` already take. Defaults to the global `fetch`.
+     */
+    fetch?: typeof fetch;
+    /** How long to wait for the runner to answer ready (default 5 minutes). */
+    readyTimeoutMs?: number;
+    /** Pause between readiness polls (default 5 seconds). */
+    readyIntervalMs?: number;
 }
 /** The ref the AI management key is delivered under; the host's `AiOrganisationPort` adapter reads it back. */
 export declare const PLATFORM_AI_MANAGEMENT_KEY_REF = "ai:platform:managementKey";
@@ -806,6 +877,17 @@ export interface PlatformFilesRuntime {
     migrateIntervalMs?: number;
     /** Tries at handing each secret to the host (default 3). */
     deliverAttempts?: number;
+    /**
+     * #543: injected for tests, against a fake runner host -- the runner's own
+     * deploy wait now does a `'ready'` probe of its `/api/health`, same as
+     * `provisionPlatformMail`/`provisionPlatformArchon` already take. Defaults
+     * to the global `fetch`.
+     */
+    fetch?: typeof fetch;
+    /** How long to wait for the runner to answer ready (default 5 minutes). */
+    readyTimeoutMs?: number;
+    /** Pause between readiness polls (default 5 seconds). */
+    readyIntervalMs?: number;
 }
 /**
  * #171: how the host signs a files management request with the key this step
@@ -834,7 +916,11 @@ export interface PlatformEdgeRuntime {
 }
 export interface PlatformEdgeDeps {
     coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'requireGithubApp' | 'createGithubAppApplication' | 'createDockerfileApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy' | 'deployAndWait' | 'raw'>;
-    cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'findTunnelByName' | 'createTunnel' | 'putTunnelConfig' | 'getTunnelToken' | 'findDnsRecord' | 'createDnsRecord' | 'updateDnsRecord'>;
+    /** F4.dns: every DNS record call, through edge at its recorded address (see {@link PlatformDnsFactory}). */
+    dns: PlatformDnsFactory;
+    /** F4.tunnels: every tunnel call, through edge at its recorded address (see {@link PlatformTunnelsFactory}). */
+    tunnels: PlatformTunnelsFactory;
+    cloudflare: Pick<CloudflarePort, 'findZoneByApex'>;
     deliverSecret: FoundryStepExecutorPorts['deliverSecret'];
     /**
      * Reads the edge service's own Cloudflare API token back, held under
@@ -856,6 +942,30 @@ export interface PlatformEdgeDeps {
     /** Clock, sleep and fetch for the readiness wait and delivery retries; real ones by default. */
     runtime?: PlatformEdgeRuntime;
 }
+export interface PlatformHcRuntime {
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    readyTimeoutMs?: number;
+    readyIntervalMs?: number;
+}
+/**
+ * #540: dependencies for `coolify:app` keyed {@link PLATFORM_HC_KEY} -- the
+ * {@link PlatformEdgeDeps} bundling shape minus a Cloudflare token of its
+ * own: `hc` writes its tunnel and DNS record through edge the same way
+ * mail and archon do, and needs no `heldKeys`/`deliverSecret` at all --
+ * `SECRET_KEY` (Django's session-signing key) is generated once by
+ * {@link provisionPlatformHc} itself and never leaves this Coolify app.
+ */
+export interface PlatformHcDeps {
+    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'createDockerImageApplication' | 'createDockerfileApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy' | 'deployAndWait' | 'raw'>;
+    /** F4.dns: every DNS record call, through edge at its recorded address (see {@link PlatformDnsFactory}). */
+    dns: PlatformDnsFactory;
+    /** F4.tunnels: every tunnel call, through edge at its recorded address (see {@link PlatformTunnelsFactory}). */
+    tunnels: PlatformTunnelsFactory;
+    /** Clock, sleep and fetch for the readiness wait; real ones by default. */
+    runtime?: PlatformHcRuntime;
+}
 /**
  * #174: everything {@link provisionPlatformIntegrations} needs beyond
  * {@link PlatformStepExecutionContext} -- a bundle, like
@@ -930,6 +1040,91 @@ export interface PlatformBackupDeps {
     /** A cron string or one of Coolify's names (`daily`, `weekly`, ...). Default `'daily'`. */
     frequency?: string;
 }
+/** One check as self-hosted Healthchecks' own Management API reports it. */
+export interface HeartbeatCheck {
+    id: string;
+    name: string;
+    pingUrl: string;
+}
+/**
+ * #540: the heartbeat server's own Management API -- a project API key in a
+ * header, `POST /api/v3/checks/` with `name`/`unique: ['name']` to upsert a
+ * check idempotently by name, `GET /api/v3/checks/` to list every one,
+ * `DELETE /api/v3/checks/<uuid>` to remove one -- restated here as the port
+ * `provisionPlatformHeartbeats` plans and provisions against, never a real
+ * HTTP client: this package never connects itself (`README.md`), so the
+ * host implements this against its own running `hc` instance and its own
+ * project API key, the same seam every other real I/O in this file crosses.
+ */
+export interface HeartbeatsPort {
+    listChecks(): Promise<HeartbeatCheck[]>;
+    /** Creates a check named `name`, or returns the existing one of that name -- the Management API's own upsert. */
+    createCheck(name: string): Promise<HeartbeatCheck>;
+    /**
+     * #540 round 2: pauses a check (`POST /api/v3/checks/<uuid>/pause/`) so it
+     * reads "paused" rather than "down" while nothing actually pings it yet --
+     * both the uptime Worker's own check and every backup check (see this
+     * file's own doc comment on `PlatformHeartbeatsDeps` for why). Sending a
+     * check a ping resumes it automatically (Healthchecks' own documented
+     * behaviour), so foundry never has to call the reverse of this: once a
+     * real pinger exists, the check un-pauses itself on its first ping.
+     * `provisionPlatformHeartbeats` calls this exactly once, right after
+     * `createCheck`, and never again on a check it merely finds already live
+     * -- a check already being pinged, or one an operator unpaused by hand,
+     * must never be paused again by a reconcile run.
+     */
+    pauseCheck(id: string): Promise<void>;
+    deleteCheck(id: string): Promise<void>;
+}
+/**
+ * #540: dependencies for the `heartbeats:reconcile` step
+ * (`platform-diff.ts`'s `planHeartbeats`).
+ *
+ * #540 round 2: `resolve` is new. It guards only the *delete* half of
+ * {@link provisionPlatformHeartbeats} -- a live check is only ever deleted
+ * when foundry itself holds a ping URL for its exact name
+ * (`heartbeatCheckUrlRef`, `platform-diff.ts`), proof this run or an
+ * earlier one created it. Without that guard, a hand-made check sharing
+ * foundry's naming scheme (an operator's own `uptime-worker`, say, made
+ * before foundry ever ran) could be deleted the moment that name was not
+ * yet desired -- a backup service with no recorded database yet is in
+ * `provisionPlatformHeartbeats`'s own `ownedNames` but not `desiredSet`.
+ * `resolve` is never consulted on the *create* half: a check already live
+ * under a desired name is always treated as foundry's, the way it always
+ * was, and (the round-2 fix for a second bug) its ping address is now
+ * always re-saved rather than only on the create that first makes it live
+ * -- see `put`'s own doc comment below for why that half carries no
+ * adoption risk the way deleting does.
+ *
+ * `put` records a check's own ping URL -- on every create, and (new this
+ * round) on every run that finds a desired check already live, not only
+ * the run that created it. Before this fix, a save that failed once, or a
+ * run that died between create and save, or a host that wired `heldKeys`
+ * only after the original create, lost that address for good: the next run
+ * found the check already live and never saved anything, despite this very
+ * doc comment already claiming the step "can simply ask the live check
+ * again." Required whenever an address actually needs saving -- optional
+ * only so a host without one still compiles, in which case nothing here
+ * can ever be created or re-confirmed, and the step throws rather than
+ * silently drop an address: CLAUDE.md platform-step rule 1 is written for a
+ * minted credential, not a ping URL (a lost one is simply re-asked from the
+ * live check, never re-minted), but the rule's "never silently lose it"
+ * half applies just as well here.
+ *
+ * Both fields are optional only so a host without either still compiles;
+ * while `PlatformHeartbeatsDeps` is wired at all, `FoundryPlatformStepExecutor
+ * .blockedSteps`'s own `heartbeatsApiKeyMissing` check blocks the step
+ * until a project API key is held under {@link PLATFORM_HC_API_KEY_REF}, so
+ * the live Healthchecks calls below are never reached with nothing behind
+ * them.
+ */
+export interface PlatformHeartbeatsDeps {
+    heartbeats: HeartbeatsPort;
+    heldKeys?: {
+        resolve(ref: string): Promise<string | null>;
+        put?(ref: string, value: string): Promise<void>;
+    };
+}
 /**
  * The real {@link PlatformCloudflareReader}: the platform's apex zone as
  * `planApexZone` expects to see it, and nothing else. The zone's DNS records
@@ -959,7 +1154,7 @@ export declare class ProvidersPlatformCloudflareReader implements PlatformCloudf
 export declare class ProvidersPlatformCoolifyReader implements PlatformCoolifyReader {
     private readonly client;
     private readonly platformStore;
-    constructor(client: Pick<CoolifyPort, 'getApplication' | 'getDatabase' | 'listDatabaseBackups'>, platformStore: Pick<PlatformStore, 'getServiceIds'>);
+    constructor(client: Pick<CoolifyPort, 'getApplication' | 'getDatabase' | 'listDatabaseBackups' | 'raw'>, platformStore: Pick<PlatformStore, 'getServiceIds'>);
     listResources(): Promise<LiveResource[]>;
 }
 /** Scope id (no `:`): the share domains the runner's Coolify `domains` was last set to, comma-joined. */