@wtfalch/foundry 0.20.0 → 0.21.1

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

@@ -117,7 +117,7 @@ export declare const JOBS_ADMIN_TOKEN_REF = "jobs:scheduler:adminToken";
  * org's own app, reused here for the platform's one scheduler instead of once
  * per org.
  */
-type JobsCoolifyPort = Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'requireGithubApp' | 'findApplicationByName' | 'createGithubAppApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'raw' | 'bulkUpsertEnvs' | 'getApplication' | 'deploy'>;
+type JobsCoolifyPort = Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'requireGithubApp' | 'findApplicationByName' | 'createGithubAppApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'raw' | 'bulkUpsertEnvs' | 'listEnvs' | 'getApplication' | 'deploy'>;
 /**
  * Options for {@link FoundryPlatformStepExecutor}'s constructor, replacing
  * four positional arguments that shifted on every merge that added a
@@ -182,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:
@@ -261,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;
@@ -273,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
@@ -676,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";
@@ -849,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
@@ -903,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
@@ -977,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
@@ -1006,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' | 'listEnvs' | '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. */