@wtfalch/foundry 0.2.0 → 0.3.0

package/dist/plan/executor.d.ts

@@ -1,3 +1,4 @@
+import type { OrgMailOptions, OrgMailOrg, OrgMailResult } from '@wtfalch/email/postmaster';
 import type { DeclaredOrg, HostingBuildPack, OrgId } from '../org.js';
 import type { StepAction } from './diff.js';
 import type { DestroyTarget, StepDestroyer, StepExecutionContext, StepExecutor } from './plan-apply.js';
@@ -68,6 +69,17 @@ export interface CoolifyPort {
     }): Promise<{
         uuid: string;
     } | null>;
+    /**
+     * One application's own live status (`` `running:healthy`, `exited:unhealthy`
+     * `` -- `@wtfalch/providers`' `CoolifyApplication.status` doc comment) --
+     * `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).
+     */
+    getApplication(uuid: string): Promise<{
+        uuid: string;
+        status?: string;
+    }>;
     createGithubAppApplication(input: {
         project_uuid: string;
         server_uuid: string;
@@ -79,6 +91,8 @@ export interface CoolifyPort {
         build_pack: HostingBuildPack;
         name?: string;
         domains?: string;
+        /** Selects which of two Dockerfiles in one repo to build (`cmsSite`'s own site/cms apps). */
+        dockerfile_location?: string;
     }): Promise<{
         uuid: string;
     }>;
@@ -99,7 +113,8 @@ export interface CoolifyPort {
      * from `createPostgresDatabase`'s return value) so the app's env is wired
      * from the database's live state whether this run just created it or found
      * it already there (`coolifyApp`/`coolifyDatabase` below, hosting-wiring
-     * campaign). `internal_db_url` is `postgres://user:password@host/db` — a
+     * campaign; `cmsSite`'s own cms database, #117). `internal_db_url` is
+     * `postgres://user:password@host/db` — a
      * live credential, present in the raw Coolify API response and reachable
      * only from inside the Coolify Docker network (`@wtfalch/providers`'
      * `CoolifyClient.createPostgresDatabase` doc comment).
@@ -122,10 +137,12 @@ export interface CoolifyPort {
     /**
      * Upsert environment variables on an application in one call — used here to
      * push the database's `internal_db_url` in as the app's `DATABASE_URL`
-     * (hosting-wiring campaign). The value is a live credential: it must reach
-     * this call and nothing else — never a step's return value, `serviceIds`
-     * (hence the store), an audit record, a log or a thrown error. See
-     * `coolifyApp`'s `pushDatabaseUrl`.
+     * (hosting-wiring campaign), and, for the cms app, its `DATABASE_URL_OWNER`
+     * plus a freshly minted `DATABASE_URL` runtime-role credential (#117). Each
+     * value is a live credential: it must reach this call and nothing else —
+     * never a step's return value, `serviceIds` (hence the store), an audit
+     * record, a log or a thrown error. See `coolifyApp`'s `pushDatabaseUrl` and
+     * `cmsSite`'s `ensureCmsRuntimeUrl`.
      */
     bulkUpsertEnvs(applicationUuid: string, envs: Array<{
         key: string;
@@ -134,8 +151,50 @@ export interface CoolifyPort {
         literal?: boolean;
         multiline?: boolean;
     }>): Promise<unknown>;
+    /**
+     * Every environment variable currently on the application — read before
+     * generating `AUTH_COOKIE_SECRET` (`ensureAuthCookieSecret`, level-1
+     * app-env campaign) so that value is only ever generated once, never
+     * overwritten. Every key comes back twice (a production row and an
+     * `is_preview` duplicate, `@wtfalch/providers`' `CoolifyClient.listEnvs`
+     * doc comment), so a caller checking "does this key already exist" filters
+     * `is_preview === false` the same way a deployed-config reader must.
+     */
+    listEnvs(applicationUuid: string): Promise<Array<{
+        key: string;
+        value: string;
+        is_preview: boolean;
+    }>>;
     /** Escape hatch (`CoolifyClient.raw`) — used for stop/start, which have no typed method yet. */
     raw(method: string, path: string, body?: unknown): Promise<unknown>;
+    /**
+     * Persistent (named volume) and file storages already attached to an
+     * application (#75) — `ensureLogVolume` reads this before creating one, so
+     * a re-run never mounts a second volume at the same path.
+     */
+    listStorages(applicationUuid: string): Promise<{
+        persistent_storages?: Array<{
+            uuid: string;
+            name?: string;
+            mount_path: string;
+        }>;
+        file_storages?: Array<{
+            uuid: string;
+            mount_path: string;
+        }>;
+    }>;
+    /** Mounts a named volume on an application (#75) — `ensureLogVolume`'s create path. */
+    createPersistentStorage(applicationUuid: string, input: {
+        name: string;
+        mount_path: string;
+    }): Promise<unknown>;
+    /**
+     * Restarts the running container without a rebuild (#75) — `ensureLogVolume`
+     * calls this after mounting a volume on an app that was already running,
+     * since Coolify only binds a newly created storage into the container at
+     * its next start.
+     */
+    restart(applicationUuid: string): Promise<unknown>;
     /** `FoundryPlanApply.destroy`'s teardown of the org's own app. */
     deleteApplication(uuid: string): Promise<unknown>;
     /** `FoundryPlanApply.destroy`'s teardown of the org's own database. */
@@ -165,6 +224,31 @@ export interface CloudflarePort {
     putTunnelConfig(tunnelId: string, config: unknown): Promise<unknown>;
     /** `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;
+    }>>;
+    createAccessPolicy(appId: string, policy: {
+        name: string;
+        decision: string;
+        include: unknown[];
+    }): Promise<{
+        id: string;
+    }>;
+    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,
@@ -174,6 +258,57 @@ export interface CloudflarePort {
      * creating one.
      */
     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;
+    }>>;
+    createDnsRecord(zoneId: string, rec: {
+        type: string;
+        name: string;
+        content: string;
+        proxied?: boolean;
+        ttl?: number;
+    }): Promise<{
+        id: string;
+        name: string;
+        content: string;
+    }>;
+    updateDnsRecord(zoneId: string, recordId: string, rec: {
+        type: string;
+        name: string;
+        content: string;
+        proxied?: boolean;
+        ttl?: 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>;
+}
+/**
+ * The Stalwart calls this executor makes for one org's mail, shaped to match
+ * `@wtfalch/email/postmaster`'s `applyOrgMail`/`parkOrgMail` method-for-method
+ * with the `StalwartClient` bound, the same way {@link CloudflarePort} mirrors
+ * `CloudflareClient`.
+ */
+export interface MailPort {
+    applyOrgMail(org: OrgMailOrg, options: OrgMailOptions): Promise<OrgMailResult>;
+    parkOrgMail(org: OrgMailOrg, options: OrgMailOptions): Promise<void>;
 }
 /**
  * The ZITADEL calls this executor makes. `findOrCreateOrg`/`findOrCreateProject`
@@ -350,6 +485,7 @@ export interface FoundryStepExecutorPorts {
     coolify: CoolifyPort;
     cloudflare: CloudflarePort;
     zitadel: ZitadelPort;
+    mail: MailPort;
     /** A factory, not a flat client: Files/AI are org-scoped credentials the host resolves per org. */
     filesLimitsFor: (orgId: OrgId) => FilesOrgLimits;
     aiLimitsFor: (orgId: OrgId) => AiOrgLimits;
@@ -373,25 +509,58 @@ export interface FoundryStepExecutorPorts {
 }
 /**
  * Thrown by name for a step this executor deliberately does not implement:
- * mail and chat (no admin API exists yet in either service) and the cms
- * site (same), plus moving the issuer onto or off the org's domain (built,
- * but not in v1 — domain verification and passkey invalidation need their
- * own design). Never carries a token, secret or key (task brief: "errors
- * carry the step and the provider's status only").
+ * chat (no admin API exists yet), plus moving the issuer onto or off the
+ * org's domain (built, but not in v1 — domain verification and passkey
+ * invalidation need their own design). Never carries a token, secret or key
+ * (task brief: "errors carry the step and the provider's status only").
  */
 export declare class NotBuiltError extends Error {
     constructor(step: string, detail: string);
 }
-/** `coolify:app` needs source code to build from; `DeclaredOrg.bespokeAppRepo` is the only source this executor knows (#71, #20). */
-export declare class MissingBespokeAppRepoError extends Error {
-    constructor(slug: 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,
+ * and a site org's site app and cms app both serve `/api/health`
+ * (https://github.com/wtfalch/cms/tree/main/apps). An org that runs neither
+ * has nothing to probe. Exported so archon, which owns uptime, never repeats
+ * this file's hostname rules.
+ */
+export declare function healthUrls(org: DeclaredOrg): string[];
 export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer {
     private readonly ports;
     constructor(ports: FoundryStepExecutorPorts);
     execute(action: StepAction, context: StepExecutionContext): Promise<{
         resourceId?: string;
     } | undefined>;
+    /**
+     * `plan/diff.ts`'s `planAccess` (#84): puts the org's app hostname behind a
+     * Cloudflare Access app that lets only `hosting.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:
+     * destroy would later delete it. It also refuses when its own app carries
+     * any policy but foundry's, since that policy could let others in.
+     */
+    private cloudflareAccess;
+    /**
+     * `plan/diff.ts`'s `planRateLimit` (#43): one Cloudflare rate limiting
+     * rule, scoped to `SIGN_IN_PATH_EXPRESSION`, on the org's own Cloudflare
+     * zone -- only ever called for an own-domain org (`planRateLimit`'s own
+     * 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
+     * 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
+     * holds the hostname.
+     */
+    private cloudflareRateLimit;
     private zitadelIssuer;
     /**
      * `plan/diff.ts`'s `planOwner`: invites the org's owner into its ZITADEL
@@ -416,6 +585,28 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     private ensureCoolifyProject;
     private resolveServer;
     private coolifyApp;
+    /**
+     * #75: mounts a persistent volume at {@link LOG_DIR} on the app, unless one
+     * is already there. Found by `mount_path`, not a recorded id — no
+     * `serviceIds` entry exists for a storage the way one does for the app or
+     * database itself, and Coolify's own listing is cheap enough to check
+     * first every time, the same way `coolifyDatabase` finds its database by
+     * name before creating one. Never called from the `enabled === false`
+     * (park) branch above, so parking an app never touches its volume either.
+     *
+     * Mounting a volume on an application already running does not attach it
+     * to the live container -- Coolify only binds a storage in at the
+     * container's next start (Finding, refuted against the first version of
+     * this method: it created the storage and let a passing `listStorages`
+     * read report `hasLogVolume: true` on the very next plan, with the
+     * container itself still writing nowhere). `wasAlreadyRunning` tells this
+     * method whether `appId` names an app `coolifyApp` found already there
+     * (restart it once the volume is created) or one it just created fresh
+     * (already about to get its first deploy/start from
+     * `createGithubAppApplication`'s own instant-deploy path, so a restart
+     * here would only be a redundant extra one).
+     */
+    private ensureLogVolume;
     private coolifyDatabase;
     /**
      * Pushes the database's connection string into the app's environment as
@@ -440,8 +631,166 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * never interpolated into a thrown error.
      */
     private pushDatabaseUrl;
+    /**
+     * Pushes what the org's app needs to sign a user in through ZITADEL (gap
+     * 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.
+     *
+     * `APP_URL` and `LOG_DIR` (#75) are pushed unconditionally; every other
+     * value is pushed only once its own source step has actually recorded it
+     * (`context.recordedIds()`) -- on a first-ever apply,
+     * run one step at a time in `diff.ts`'s `computePlanDetail` order, that is
+     * `zitadel:issuer` (`AUTH_ORGANIZATION_ID`), `zitadel:owner`
+     * (`OWNER_USER_ID`, gap P3) and every `zitadel:app` step
+     * (`AUTH_CLIENT_ID`), all ordered before `coolify:app` for exactly this
+     * reason. AUTH_APP_KEY (waits on an auth broker registration API) and
+     * DATABASE_URL_OWNER (a runtime-role split not built yet, `pushDatabaseUrl`'s
+     * own doc comment) are out of scope here (task brief).
+     */
+    private pushAppEnv;
+    /**
+     * `null` once the app already has one -- `AUTH_COOKIE_SECRET` is generated
+     * only the first time (task brief), never regenerated or overwritten, so a
+     * later apply's `bulkUpsertEnvs` call simply omits the key rather than
+     * upsert a fresh value over it.
+     */
+    private ensureAuthCookieSecret;
+    /**
+     * `plan/diff.ts`'s `planSite` (#116, slicing #99's "provision the cms app,
+     * database and site app per org"): the 2026-09-25 decision
+     * (https://github.com/wtfalch/cms/blob/main/.plans/2026-09-25-org-sites.md)
+     * means foundry never calls a cms admin API for the org's site -- it
+     * provisions two ordinary Coolify applications from the one
+     * https://github.com/wtfalch/cms repo, the same way `coolifyApp` above
+     * provisions the org's own hosted app: a site app (`apps/site`, the
+     * reference renderer) at `org.domain`, built from
+     * `CMS_SITE_APP_DOCKERFILE`, and a cms app (`apps/host`, single-org mode,
+     * https://github.com/wtfalch/cms/blob/main/docs/adr/0013-one-cms-per-org.md)
+     * at {@link cmsHostnameFor}, built from the repo's own root
+     * `CMS_APP_DOCKERFILE` -- one repo, two applications, told apart by
+     * `dockerfile_location`.
+     *
+     * `action.key` is `org.id` (`planSite`'s own singleton key), so `execute`'s
+     * own auto-record has only one `resourceId` slot for this step
+     * (`cms:site:<orgId>`) -- returned here as the cms app's id, the resource
+     * this step is named for. The site app's id has no such slot, so both ids
+     * are also recorded as scope ids ({@link CMS_APP_SCOPE_KEY}/
+     * {@link SITE_APP_SCOPE_KEY}), read back by the park branch below on a
+     * later apply, when nothing gets provisioned to return one -- read
+     * independently of each other there, since a crash partway through a
+     * first-ever provision can leave only one of the two actually recorded.
+     *
+     * #117: this step also finds or creates the cms app's own Postgres
+     * database ({@link ensureCmsDatabase}) and pushes its owner and runtime
+     * connection strings ({@link ensureCmsRuntimeUrl}) onto the cms app, in the
+     * same `bulkUpsertEnvs` call as `APP_URL`/`CMS_ORGANISATION_ID`/
+     * `CMS_SITE_URL` below. The database's id is recorded as a third flat scope
+     * id ({@link CMS_DATABASE_SCOPE_KEY}), for the same reason the two app ids
+     * are: no `system:kind:key` slot of its own. Never touched from the park
+     * branch above -- parking stops the two apps only, same as #116's own
+     * destroy note; this step never parks or destroys the database.
+     */
+    private cmsSite;
+    /**
+     * `cmsSite`'s own find-or-create of a Postgres database for the cms app,
+     * modeled on `coolifyDatabase` above: `ensureCoolifyProject` (already run
+     * by `cmsSite` before this is called) and `findOrCreateEnvironment` give
+     * the project/environment this reuses, then `listDatabases` finds one
+     * already created by name before `createPostgresDatabase` makes one.
+     * Named `<org.slug>-cms-db`, distinct from `coolifyDatabase`'s own
+     * `<org.slug>-db`, so the two never collide in the same project for an org
+     * that has both.
+     *
+     * `context.recordedIds()` is checked first, the same short-circuit
+     * `coolifyDatabase` itself does not have (that step's own `resourceId` slot
+     * already covers it) -- here it is load-bearing, since this database has
+     * no `system:kind:key` slot of its own ({@link CMS_DATABASE_SCOPE_KEY}'s
+     * doc comment) and `cms:site` runs on every apply once `org.site.enabled`,
+     * not just the first.
+     *
+     * Destroying this database is out of scope here (#117, same as #116's own
+     * destroy note for the cms/site apps).
+     */
+    private ensureCmsDatabase;
+    /**
+     * `null` once the cms app already has a `DATABASE_URL` -- never rotated,
+     * the same rule `ensureAuthCookieSecret` follows for `AUTH_COOKIE_SECRET`,
+     * and for the same kind of reason: `@wtfalch/cms`'s own
+     * `apps/host/scripts/migrate.mjs` (`ensureRuntimeRole`) creates or updates
+     * the live `cms_rt` Postgres role from exactly the username/password this
+     * method mints, once, at container boot -- overwriting `DATABASE_URL` on a
+     * later apply would leave that already-created role's real password out of
+     * sync with whatever foundry hands the app next.
+     *
+     * The password is minted with `randomBytes` (the same import
+     * `ensureAuthCookieSecret` already uses) and encoded `base64url` -- `+`/`/`
+     * swapped for `-`/`_`, no `=` padding -- so it is already URL-safe in a
+     * `postgres://` URL's userinfo segment with no further percent-encoding
+     * needed. `dbInternalUrl` (`getDatabase`'s own `internal_db_url`) is parsed
+     * with `URL` for its host, path and query string; its own superuser
+     * username and password are discarded -- this mints a distinct, restricted
+     * role's own credential, never reuses the superuser's. The query string
+     * (`search`) is kept as-is and appended unchanged (#117 review round 2):
+     * a parameter there (e.g. `?sslmode=require`) is a connection requirement
+     * Coolify itself put on this database, not something specific to the
+     * superuser role, so the migration (`DATABASE_URL_OWNER`) and runtime
+     * (`DATABASE_URL`) connections must carry the same one.
+     *
+     * The password is a live credential: built here and handed straight to
+     * `cmsSite`'s own `bulkUpsertEnvs` call and nowhere else in this class --
+     * never returned, recorded, logged, or interpolated into a thrown error
+     * (the same rule `pushDatabaseUrl`'s doc comment states). That rule is why
+     * `URL`'s own parse failure is caught below rather than left to propagate:
+     * nothing here states or controls the superuser password's alphabet
+     * (Coolify's own, unlike the `cms_rt` one minted just below it), and
+     * Node's `TypeError [ERR_INVALID_URL]` on an unescaped `/`, `#` or `?` in
+     * it carries the *whole* input -- credential included -- on its own
+     * `.input` property (never in `.message`, but still reachable by a logger
+     * that inspects the error object, not just its message). Caught and
+     * turned into "skip `DATABASE_URL` for this apply" instead: `cmsSite`
+     * still pushes `DATABASE_URL_OWNER` and its other envs, and a later apply
+     * retries this once `listEnvs` still shows no `DATABASE_URL`.
+     */
+    private ensureCmsRuntimeUrl;
+    /**
+     * `cmsSite`'s own find-by-name-then-create flow for one of its two
+     * applications -- the same shape `coolifyApp` above inlines for its own,
+     * single, application, extracted here since `cmsSite` needs it twice in
+     * one step. Both of `cmsSite`'s apps share `CMS_REPO`'s own default branch
+     * (`main`) -- there is no per-org `gitBranch`/`buildPack` for this repo
+     * the way `org.hosting` carries for the org's *own* app, since the cms
+     * site is not that app.
+     *
+     * An app found by name (rather than just created) is started back up if
+     * it is not already running or on its way there (#116 review round 3,
+     * Finding 1): parking (`cmsSite`'s own `enabled: false` branch) stops both
+     * apps without deleting them, so re-enabling finds them here, still
+     * stopped, and `ProvidersCmsReader` would otherwise keep reporting
+     * `enabled: false` forever -- the plan never converging back to on.
+     * `coolifyApp`'s own analogous gap (it never restarted a found-but-stopped
+     * app either) has since closed the same way, inline in that method (#130);
+     * this method is `cmsSite`'s only caller.
+     */
+    private findOrCreateCmsApp;
     private cloudflareTunnel;
     private cloudflareZone;
+    /**
+     * `plan/diff.ts`'s `planMail`: gives an org mail, moves it between modes,
+     * or parks it on the one shared Stalwart instance (`this.ports.mail`,
+     * `@wtfalch/email/postmaster`'s `applyOrgMail`/`parkOrgMail` bound), then
+     * publishes whatever DNS records the call returns.
+     */
+    private coolifyMail;
+    /**
+     * Upserts each DNS record `applyOrgMail` says foundry must publish, found
+     * by an exact name+type match (`CloudflarePort.findDnsRecord`'s own doc
+     * comment) so update never mistakes a stale record of a different type for
+     * a match. A `DKIM` record can be absent on the first call, since Stalwart
+     * mints the key on a background task; the next apply publishes it.
+     */
+    private publishMailDnsRecords;
     /**
      * #80: provisions the org's own organisation on Files, before
      * {@link filesStorage} can set its spend limit. `provisionOrganisation` is