@wtfalch/foundry 0.1.0 → 0.3.0

package/dist/plan/executor.js

@@ -0,0 +1,1242 @@
+import { randomBytes } from 'node:crypto';
+import { URL } from 'node:url';
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+/**
+ * Thrown by name for a step this executor deliberately does not implement:
+ * 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 class NotBuiltError extends Error {
+    constructor(step, detail) {
+        super(`${step} is not built yet -- ${detail}`);
+        this.name = 'NotBuiltError';
+    }
+}
+// ---------------------------------------------------------------------------
+// Hostnames
+// ---------------------------------------------------------------------------
+/**
+ * `<slug>.oikos.host` (`../slug.ts`), or `DeclaredOrg.domain` once
+ * `hosting.usesDomain` is true — the same rule `diff.ts`'s `planApp` and
+ * `planSite` document, reused here for the org's own hosted app, its
+ * Cloudflare tunnel ingress and its ZITADEL issuer apps' redirect URIs
+ * (task brief: "Hostnames: `<slug>.oikos.host` ... or `DeclaredOrg.domain`
+ * when `hosting.usesDomain`").
+ */
+function hostnameFor(org) {
+    return org.hosting.usesDomain && org.domain ? org.domain : `${org.slug}.oikos.host`;
+}
+/**
+ * `cms.<domain>` -- the cms studio's own hostname (`cmsSite` below), apart
+ * from the public site itself at `org.domain` (used directly there). Only
+ * ever called from `cmsSite`, which only ever runs once `org.site.enabled`
+ * is true, so `org.domain` is non-null by the same `validateSite` guarantee
+ * {@link tunnelIngressHostnames}'s own doc comment cites.
+ */
+function cmsHostnameFor(org) {
+    return `cms.${org.domain}`;
+}
+/**
+ * The hostnames `cloudflareTunnel` routes to `COOLIFY_PROXY_ORIGIN`
+ * (https://github.com/wtfalch/foundry/issues/115). A site-enabled org
+ * (`org.ts`'s `SiteConfig.enabled`) has no single app hostname to reuse -- it
+ * needs both its public site at `org.domain` and its cms studio (the sign-in
+ * and editing surface, `@wtfalch/cms`) at `cms.<domain>`, so both are named
+ * here; `org.domain` is non-null in that branch, guaranteed by `org.ts`'s
+ * `validateSite` ("site.enabled requires domain"). Every other org --
+ * concretely a hosting org, whose one app hostname this served before #115
+ * ever existed -- keeps exactly the prior single-hostname behavior
+ * ({@link hostnameFor}), unchanged.
+ */
+function tunnelIngressHostnames(org) {
+    if (org.site.enabled && org.domain)
+        return [org.domain, `cms.${org.domain}`];
+    return [hostnameFor(org)];
+}
+/**
+ * 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 function healthUrls(org) {
+    if (org.hosting.enabled)
+        return [`https://${hostnameFor(org)}/api/health`];
+    if (org.site.enabled && org.domain) {
+        return [`https://${org.domain}/api/health`, `https://${cmsHostnameFor(org)}/api/health`];
+    }
+    return [];
+}
+/**
+ * The `OrgMailOrg` argument for `applyOrgMail`/`parkOrgMail`: an org with
+ * `mail.usesDomain` off has no domain of its own, so it is level 1 on
+ * `MAIL_APEX` and its mode is forced to `'hosted'` — `@wtfalch/email`'s own
+ * `resolveDomain` refuses any other mode for a domain-less org, and a
+ * level-1 `{slug}.{apex}` domain always has Stalwart's MX (foundry#7 "Mail").
+ */
+function mailOrgFor(org, usesDomain, mode) {
+    return usesDomain && org.domain
+        ? { slug: org.slug, domain: org.domain, mode }
+        : { slug: org.slug, mode: 'hosted' };
+}
+/**
+ * Every app on the Coolify box shares one Traefik reverse proxy, and Coolify
+ * itself points that proxy's routing at whatever `domains` an application
+ * declares (`coolifyApp`'s `hostnameFor(org)`) -- so a tunnel's ingress only
+ * has to reach the proxy, never a specific app container.
+ * `wtfalch/app-template`'s bootstrap (`bootstrap/steps/cf-tunnel.ts`, prior
+ * art for the exact org this file's `cloudflareTunnel` implements, cited by
+ * https://github.com/wtfalch/foundry/issues/71) names this same constant and
+ * value.
+ */
+const COOLIFY_PROXY_ORIGIN = 'http://coolify-proxy:80';
+/** The one Access policy foundry puts on its own Access app (#84). */
+const ACCESS_POLICY_NAME = 'foundry: allowed emails';
+/**
+ * The sign-in broker's own route mount (`@wtfalch/auth`'s `NextAuth`,
+ * `dist/next.d.ts`'s `handlers` doc comment: "`export const { GET, POST } =
+ * handlers` from app/auth/[...auth]/route.ts") -- every sign-in request an
+ * app built on `@wtfalch/auth` serves passes through `/auth/*`, which is
+ * what https://github.com/wtfalch/foundry/issues/43's "sign-in paths" names.
+ * `http.request.uri.path` (Cloudflare's "Path" field) is one of the two
+ * fields the Free plan allows in a rate limiting rule's expression (the
+ * other, "Verified Bot", is not needed here) -- checked against
+ * developers.cloudflare.com/waf/rate-limiting-rules/, 2026-09-26. Duplicated,
+ * not imported, in `scripts/shared-ingress.mjs`'s own constant of the same
+ * value: that file sits outside the pnpm workspace (its own top comment) and
+ * cannot import from this package.
+ */
+const SIGN_IN_PATH_EXPRESSION = 'starts_with(http.request.uri.path, "/auth/")';
+/**
+ * The rate limiting rule's fixed `description`, found before create (like
+ * `cloudflareAccess`'s app name) so a re-run after a crash reuses it instead
+ * of trying to add a second rule -- which the Free plan's one-rule-per-zone
+ * ceiling would refuse anyway (#43).
+ */
+const RATE_LIMIT_RULE_DESCRIPTION = 'foundry: rate limit sign-in paths';
+/**
+ * The Cloudflare Free plan's fixed values for a rate limiting rule's period
+ * and mitigation timeout -- the only values that plan accepts for either
+ * (developers.cloudflare.com/waf/rate-limiting-rules/, checked 2026-09-26).
+ * `characteristics: ['cf.colo.id', 'ip.src']`: the IP address is the Free
+ * plan's only counting characteristic, and the API requires `cf.colo.id`
+ * explicitly on every rule. The expression uses `starts_with`, since
+ * `matches` needs Business or above. `requests_per_period` is foundry's own
+ * choice within that ceiling, not a plan limit.
+ */
+const RATE_LIMIT_FREE_PLAN_PERIOD_SECONDS = 10;
+const RATE_LIMIT_REQUESTS_PER_PERIOD = 10;
+/**
+ * The shared standard app a level-1 org with no `bespokeAppRepo` gets
+ * deployed (gap P1, `.plans/2026-09-26-level-1-org-map.md`): one repo, the
+ * same for every such org, decided by William 2026-09-26. `coolifyApp` below
+ * names it as the git source in exactly the shape `bespokeAppRepo` itself
+ * uses (`org.ts`'s `DeclaredOrg.bespokeAppRepo: string | null`) whenever an
+ * org declares none of its own — the repo may not exist yet at decision
+ * time, and Coolify's own GitHub App create call is what will fail loudly
+ * against it, the same as any other repo name that does not exist.
+ */
+const DEFAULT_APP_REPO = 'wtfalch/hestia';
+/**
+ * The one repo `cmsSite` builds both of its apps from
+ * (https://github.com/wtfalch/cms) -- the 2026-09-25 decision this campaign
+ * implements (`.plans/2026-09-25-org-sites.md`, that repo): foundry never
+ * calls a cms admin API for the org's site, it provisions two ordinary
+ * Coolify applications from this one repo, told apart by
+ * `dockerfile_location`. `CMS_APP_DOCKERFILE` is the repo's own root
+ * `Dockerfile` (`apps/host`, single-org mode); `CMS_SITE_APP_DOCKERFILE`
+ * is `apps/site`'s own Dockerfile (the reference renderer).
+ */
+const CMS_REPO = 'wtfalch/cms';
+const CMS_APP_DOCKERFILE = 'Dockerfile';
+const CMS_SITE_APP_DOCKERFILE = 'apps/site/Dockerfile';
+/**
+ * Every app foundry deploys keeps its own logs across a redeploy, so a
+ * database outage does not also erase the only other copy of the evidence
+ * (#75). This is the exact mount path and `LOG_DIR` value lokessmie's own
+ * pilot uses (https://github.com/wtfalch/lokessmie/pull/521, verified live
+ * with Postgres stopped) — `diff.ts`'s `planApp` names this same path in its
+ * own step description, kept as a plain string there rather than importing
+ * it from this file, the same way `hostnameFor`'s hostname rule is
+ * restated rather than shared across the two files.
+ */
+const LOG_DIR = '/app/logs';
+/**
+ * The one shared Stalwart apex and MX host every org's mail lives on (#7
+ * "Mail"), the same values `@wtfalch/email`'s own README examples use for
+ * `applyOrgMail`/`parkOrgMail`'s `OrgMailOptions`.
+ */
+const MAIL_APEX = 'wtfalch.dev';
+const MAIL_HOST = 'mail.wtfalch.dev';
+/**
+ * The recorded OIDC app's `clientId` (level-1 app-env campaign, gap P2) —
+ * not a `system:kind:key` resource id (that slot already holds the app's
+ * `appId`, `zitadelApp`'s own `resourceId`) and not a secret (`deliverSecret`
+ * is for that), so a flat scope id like `zitadel_org`/`zitadel_project`
+ * above. A level-1 org declares exactly one web `issuerApps` entry for its
+ * one standard app, so one flat key is enough; an org with more than one web
+ * app would need a richer key, not built here (Finding, this campaign's
+ * report).
+ */
+const APP_CLIENT_ID_SCOPE_KEY = 'zitadel_app_client_id';
+/**
+ * `cmsSite` provisions two applications from one `cms:site` step, but
+ * `execute`'s own return value auto-records only one `resourceId`, under
+ * `cms:site:<orgId>` (`runSteps`'s own doc comment) -- the same one-step,
+ * two-resource shape `zitadelApp`/`ensureZitadelProject` already solve with
+ * a flat scope id (`zitadel_project`) alongside the per-key
+ * `zitadel:app:<key>` record. `cmsSite` returns the cms app's id as its
+ * `resourceId` (so it lands under `cms:site:<orgId>` same as any other
+ * step), and records both ids under these two flat keys instead of a
+ * `system:kind:key`-shaped one -- `recordScopeId`'s own doc comment requires
+ * a key with no `:`, precisely so a scope key can never collide with that
+ * form.
+ */
+const CMS_APP_SCOPE_KEY = 'coolify_cms_app';
+const SITE_APP_SCOPE_KEY = 'coolify_site_app';
+/**
+ * #117: the cms app's own Postgres database (`<org.slug>-cms-db`), found or
+ * created inside `cmsSite` the same way `coolifyDatabase` does for the org's
+ * own app -- but `cms:site`'s one step still auto-records only the cms app's
+ * id as its `resourceId` (see {@link CMS_APP_SCOPE_KEY}'s doc comment above),
+ * so this database's id has no `system:kind:key` slot of its own either.
+ * Recorded as a third flat scope id for the same reason: no `:`, so it can
+ * never collide with that form.
+ */
+const CMS_DATABASE_SCOPE_KEY = 'coolify_cms_database';
+/**
+ * Whether an application's own Coolify `status` (`` `running:healthy`,
+ * `exited:unhealthy` `` -- `@wtfalch/providers`' own doc comment) means it is
+ * already up, or on its way there -- `findOrCreateCmsApp`'s own check of
+ * whether a found-but-parked app still needs `start`ing (#116 review round
+ * 3, Finding 1). Only `exited`/`stopped` (Coolify's own resting-off states;
+ * `stopped` is not one this codebase has verified against a live instance,
+ * included defensively) read as off; a missing `status` defaults to on, the
+ * same "nothing says it's off" convention `planHostingToggle` (`diff.ts`)
+ * uses for the org's own app.
+ */
+function isRunningOrStarting(status) {
+    if (!status)
+        return true;
+    return !status.startsWith('exited') && !status.startsWith('stopped');
+}
+// ---------------------------------------------------------------------------
+// Executor
+// ---------------------------------------------------------------------------
+export class FoundryStepExecutor {
+    ports;
+    constructor(ports) {
+        this.ports = ports;
+    }
+    async execute(action, context) {
+        const { org } = context;
+        switch (`${action.system}:${action.kind}`) {
+            case 'zitadel:issuer':
+                return this.zitadelIssuer(action, org, context);
+            case 'zitadel:owner':
+                return this.zitadelOwner(action, org, context);
+            case 'zitadel:app':
+                return this.zitadelApp(action, org, context);
+            case 'zitadel:customers':
+                return this.zitadelCustomers(org, context);
+            case 'coolify:app':
+                return this.coolifyApp(action, org, context);
+            case 'coolify:database':
+                return this.coolifyDatabase(action, org, context);
+            case 'cloudflare:tunnel':
+                return this.cloudflareTunnel(action, org, context);
+            case 'cloudflare:zone':
+                return this.cloudflareZone(action);
+            case 'cloudflare:access':
+                return this.cloudflareAccess(org);
+            case 'cloudflare:ratelimit':
+                return this.cloudflareRateLimit(org);
+            case 'files:organisation':
+                return this.filesOrganisation(action, org);
+            case 'files:storage':
+                return this.filesStorage(action, org);
+            case 'ai:organisation':
+                return this.aiOrganisation(action, org);
+            case 'ai:budget':
+                return this.aiBudget(action, org);
+            case 'coolify:mail':
+                return this.coolifyMail(action, org);
+            case 'coolify:chat':
+                throw new NotBuiltError(`coolify:chat for ${org.slug}`, "chat's per-org Synapse+MAS has no admin API yet; tracked at https://github.com/wtfalch/chat/issues/40");
+            case 'cms:site':
+                return this.cmsSite(action, org, context);
+            default:
+                throw new Error(`FoundryStepExecutor has no dispatch for ${action.system}:${action.kind}`);
+        }
+    }
+    /**
+     * `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.
+     */
+    async cloudflareAccess(org) {
+        const domain = hostnameFor(org);
+        const name = `foundry:${org.id}`;
+        const cf = this.ports.cloudflare;
+        const onDomain = (await cf.listAccessApps()).filter((a) => a.domain === domain);
+        const foreign = onDomain.find((a) => a.name !== name);
+        if (foreign) {
+            throw new Error(`cloudflare:access for ${org.slug}: Access app '${foreign.name}' already holds ${domain}; foundry does not adopt it`);
+        }
+        const app = onDomain[0] ?? (await cf.createAccessApp({ name, domain, type: 'self_hosted' }));
+        const policies = await cf.listAccessPolicies(app.id);
+        const other = policies.find((p) => p.name !== ACCESS_POLICY_NAME);
+        if (other) {
+            throw new Error(`cloudflare:access for ${org.slug}: Access app ${app.id} has policy '${other.name}' that foundry did not create`);
+        }
+        if (policies.length === 0) {
+            await cf.createAccessPolicy(app.id, {
+                name: ACCESS_POLICY_NAME,
+                decision: 'allow',
+                include: org.hosting.accessEmails.map((email) => ({ email: { email } })),
+            });
+        }
+        return { resourceId: app.id };
+    }
+    /**
+     * `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.
+     */
+    async cloudflareRateLimit(org) {
+        if (!org.domain) {
+            throw new Error(`cloudflare:ratelimit for ${org.slug}: hosting.usesDomain is set but domain is null`);
+        }
+        const cf = this.ports.cloudflare;
+        const zone = await cf.findZoneByApex(org.domain);
+        if (!zone) {
+            throw new Error(`cloudflare:ratelimit for ${org.slug}: no Cloudflare zone found for ${org.domain} -- cloudflare:zone must provision it first`);
+        }
+        const path = `/zones/${zone.id}/rulesets/phases/http_ratelimit/entrypoint`;
+        const existing = await cf.request('GET', path, undefined, true);
+        const rules = existing?.rules ?? [];
+        const own = rules.find((r) => r.description === RATE_LIMIT_RULE_DESCRIPTION);
+        if (own)
+            return { resourceId: own.id };
+        const foreign = rules.find((r) => r.description !== RATE_LIMIT_RULE_DESCRIPTION);
+        if (foreign) {
+            throw new Error(`cloudflare:ratelimit for ${org.slug}: zone ${org.domain} already has a rate limiting rule ('${foreign.description ?? foreign.id}') foundry did not create; the Free plan allows only one rule per zone, so foundry does not adopt or replace it`);
+        }
+        const updated = await cf.request('PUT', path, {
+            rules: [
+                {
+                    description: RATE_LIMIT_RULE_DESCRIPTION,
+                    expression: SIGN_IN_PATH_EXPRESSION,
+                    action: 'block',
+                    ratelimit: {
+                        characteristics: ['cf.colo.id', 'ip.src'],
+                        period: RATE_LIMIT_FREE_PLAN_PERIOD_SECONDS,
+                        requests_per_period: RATE_LIMIT_REQUESTS_PER_PERIOD,
+                        mitigation_timeout: RATE_LIMIT_FREE_PLAN_PERIOD_SECONDS,
+                    },
+                },
+            ],
+        });
+        const created = updated.rules?.[0];
+        if (!created) {
+            throw new Error(`cloudflare:ratelimit for ${org.slug}: PUT ${path} did not return the created rule`);
+        }
+        return { resourceId: created.id };
+    }
+    // ---- zitadel --------------------------------------------------------
+    async zitadelIssuer(action, org, context) {
+        if (action.desired.provision !== true) {
+            // Moving an already-provisioned issuer onto or off the org's domain
+            // (decisions file: "domain verification and passkey invalidation need
+            // their own design" -- not built in v1).
+            throw new NotBuiltError(`zitadel:issuer move for ${org.slug}`, 'moving the issuer onto or off the org\'s own domain is not built in v1; see foundry\'s .claude/decisions-2026-09-24-executor.md, "Executor decisions"');
+        }
+        const { org: zOrg } = await this.ports.zitadel.findOrCreateOrg(org.slug);
+        context.recordScopeId('zitadel_org', zOrg.id);
+        return { resourceId: zOrg.id };
+    }
+    /**
+     * `plan/diff.ts`'s `planOwner`: invites the org's owner into its ZITADEL
+     * org by email. Never logs, returns or throws the email itself -- only the
+     * invited user id, handed back as `resourceId` so `runSteps` records it
+     * under `zitadel:owner:<orgId>`, which is exactly what makes the next
+     * `plan()` call idempotent (`planOwner` plans nothing once that key is
+     * recorded).
+     */
+    async zitadelOwner(action, org, context) {
+        const zitadelOrgId = context.recordedIds().zitadel_org;
+        if (!zitadelOrgId) {
+            throw new Error(`zitadel:owner for ${org.slug}: no ZITADEL org recorded yet -- the issuer must be provisioned first`);
+        }
+        const { userId } = await this.ports.zitadel.inviteOrgOwner(zitadelOrgId, {
+            givenName: action.desired.givenName,
+            familyName: action.desired.familyName,
+            email: action.desired.email,
+        });
+        return { resourceId: userId };
+    }
+    /**
+     * `plan/diff.ts`'s `planCustomers` (plan gap A9): the org's customers sign
+     * in through a second ZITADEL org, `<slug> customers`, with
+     * self-registration on and a grant to the org's app project. Staff stay in
+     * the org's own invite-only ZITADEL org. The space keeps the name apart from
+     * every issuer org, which is named by a slug and a slug has no spaces. Every call here is idempotent, so
+     * a re-run after a crash finishes the job.
+     */
+    async zitadelCustomers(org, context) {
+        const zitadelOrgId = context.recordedIds().zitadel_org;
+        if (!zitadelOrgId) {
+            throw new Error(`zitadel:customers for ${org.slug}: no ZITADEL org recorded yet -- the issuer must be provisioned first`);
+        }
+        const projectId = await this.ensureZitadelProject(org, zitadelOrgId, context);
+        const { org: customers } = await this.ports.zitadel.findOrCreateOrg(`${org.slug} customers`);
+        await this.ports.zitadel.allowSelfRegistration(customers.id);
+        await this.ports.zitadel.findOrCreateProjectGrant(zitadelOrgId, projectId, customers.id);
+        return { resourceId: customers.id };
+    }
+    async zitadelApp(action, org, context) {
+        const appType = action.desired.appType;
+        const recorded = context.recordedIds();
+        const zitadelOrgId = recorded.zitadel_org;
+        if (!zitadelOrgId) {
+            throw new Error(`zitadel:app '${action.key}' for ${org.slug}: no ZITADEL org recorded yet -- the issuer must be provisioned first`);
+        }
+        const projectId = await this.ensureZitadelProject(org, zitadelOrgId, context);
+        // A kind change deletes the recorded app then recreates it (task
+        // brief); the first-ever create for this key has nothing recorded, so
+        // this is a no-op then.
+        const priorAppId = recorded[`zitadel:app:${action.key}`];
+        if (priorAppId) {
+            await this.ports.zitadel.deleteApp(zitadelOrgId, projectId, priorAppId);
+        }
+        if (appType === 'api') {
+            const created = await this.ports.zitadel.createApiApp(zitadelOrgId, projectId, {
+                name: action.key,
+            });
+            // Handed off once, right here, before returning -- never in the
+            // return value, `serviceIds`, the store, a log or a thrown error (see
+            // `FoundryStepExecutorPorts.deliverSecret`'s doc comment).
+            await this.ports.deliverSecret(`zitadel:app:${org.slug}:${action.key}`, created.clientSecret);
+            return { resourceId: created.appId };
+        }
+        const hostname = hostnameFor(org);
+        // Native apps sign in via device code, with no redirect of their own
+        // (auth/scripts/provision.mjs:475-497, prior art cited in the decisions
+        // file) -- empty arrays rather than a web app's callback/logout URLs.
+        const created = await this.ports.zitadel.createOidcApp(zitadelOrgId, projectId, {
+            name: action.key,
+            appType,
+            redirectUris: appType === 'native' ? [] : [`https://${hostname}/auth/callback`],
+            postLogoutRedirectUris: appType === 'native' ? [] : [`https://${hostname}/`],
+        });
+        if (appType === 'web') {
+            // `coolifyApp`'s own `pushAppEnv` reads this to push AUTH_CLIENT_ID
+            // (level-1 app-env campaign, gap P2) -- public, not a secret, so a
+            // plain scope id, not `deliverSecret`. A native app signs in via
+            // device code with no cookie session of its own, so its clientId is
+            // never something the app's env needs.
+            context.recordScopeId(APP_CLIENT_ID_SCOPE_KEY, created.clientId);
+        }
+        return { resourceId: created.appId };
+    }
+    async ensureZitadelProject(org, zitadelOrgId, context) {
+        const recorded = context.recordedIds();
+        const existing = recorded.zitadel_project;
+        if (existing)
+            return existing;
+        const { project } = await this.ports.zitadel.findOrCreateProject(zitadelOrgId, org.slug);
+        context.recordScopeId('zitadel_project', project.id);
+        return project.id;
+    }
+    // ---- coolify ---------------------------------------------------------
+    async ensureCoolifyProject(org, context) {
+        const recorded = context.recordedIds();
+        const existing = recorded.coolify_project;
+        if (existing)
+            return existing;
+        const found = await this.ports.coolify.findProjectByName(org.slug);
+        const projectUuid = found
+            ? found.uuid
+            : (await this.ports.coolify.createProject(org.slug)).uuid;
+        context.recordScopeId('coolify_project', projectUuid);
+        return projectUuid;
+    }
+    async resolveServer() {
+        const servers = await this.ports.coolify.listServers();
+        const server = servers.find((s) => s.is_usable && s.is_reachable) ?? servers[0];
+        if (!server)
+            throw new Error('no usable Coolify server is registered on this instance');
+        return server;
+    }
+    async coolifyApp(action, org, context) {
+        if (action.desired.enabled === false) {
+            const appId = context.recordedIds()[`coolify:app:${action.key}`];
+            if (!appId) {
+                throw new Error(`coolify:app for ${org.slug}: no live app recorded, nothing to park`);
+            }
+            await this.ports.coolify.raw('POST', `/applications/${appId}/stop`);
+            return { resourceId: appId };
+        }
+        // A level-1 org with no bespoke app of its own gets the shared standard
+        // app instead (gap P1, `.plans/2026-09-26-level-1-org-map.md`), in the
+        // same repo shape `bespokeAppRepo` itself uses.
+        const appRepo = org.bespokeAppRepo ?? DEFAULT_APP_REPO;
+        const projectUuid = await this.ensureCoolifyProject(org, context);
+        const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
+        const existing = await this.ports.coolify.findApplicationByName(org.slug, {
+            environmentIds: [environment.id],
+        });
+        let appId;
+        if (existing) {
+            appId = existing.uuid;
+            // Found by name (rather than just created) is started back up if not
+            // already running or on its way there (#130, `findOrCreateCmsApp`'s
+            // own analogous fix): parking (the `enabled === false` branch above)
+            // stops the app without deleting it, so re-enabling found it here,
+            // still stopped, and it stayed stopped forever despite `apply`
+            // reporting success.
+            const live = await this.ports.coolify.getApplication(existing.uuid);
+            if (!isRunningOrStarting(live.status)) {
+                await this.ports.coolify.raw('POST', `/applications/${existing.uuid}/start`);
+            }
+        }
+        else {
+            const server = await this.resolveServer();
+            const githubApp = await this.ports.coolify.requireGithubApp();
+            const created = await this.ports.coolify.createGithubAppApplication({
+                project_uuid: projectUuid,
+                server_uuid: server.uuid,
+                environment_name: environment.name,
+                environment_uuid: environment.uuid,
+                github_app_uuid: githubApp.uuid,
+                git_repository: appRepo,
+                git_branch: org.hosting.gitBranch,
+                build_pack: org.hosting.buildPack,
+                name: org.slug,
+                domains: hostnameFor(org),
+            });
+            appId = created.uuid;
+        }
+        // The database plans before the app (`diff.ts`'s `computePlanDetail`,
+        // hosting-wiring campaign) so that, on the same apply, the database's
+        // resource id is already recorded by the time this runs -- but this also
+        // covers the database being turned on after the app already exists (the
+        // app step still ran this apply, found the app by name, and lands here).
+        if (org.hosting.database) {
+            const dbId = context.recordedIds()[`coolify:database:${action.key}`];
+            if (dbId)
+                await this.pushDatabaseUrl(appId, dbId);
+        }
+        // Every app keeps its own logs across a redeploy (#75). Unconditional,
+        // like the env push below: found by mount path before create, so a
+        // re-run (or the drift step `diff.ts`'s `planApp` plans for an app that
+        // predates this feature) never mounts a second volume. `existing` tells
+        // `ensureLogVolume` whether this app was already running before this
+        // call -- see its own doc comment for why that decides whether to
+        // restart it.
+        await this.ensureLogVolume(appId, org, Boolean(existing));
+        // The app receives whatever it needs to sign in (gap P2). Unconditional,
+        // unlike the database push above: every app has a hostname, and an
+        // upsert of the same value on a later apply is a no-op, not a change.
+        await this.pushAppEnv(appId, org, context);
+        return { resourceId: appId };
+    }
+    /**
+     * #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).
+     */
+    async ensureLogVolume(appId, org, wasAlreadyRunning) {
+        const storages = await this.ports.coolify.listStorages(appId);
+        const already = (storages.persistent_storages ?? []).some((s) => s.mount_path === LOG_DIR);
+        if (already)
+            return;
+        await this.ports.coolify.createPersistentStorage(appId, {
+            name: `${org.slug}-logs`,
+            mount_path: LOG_DIR,
+        });
+        if (wasAlreadyRunning) {
+            await this.ports.coolify.restart(appId);
+        }
+    }
+    async coolifyDatabase(action, org, context) {
+        if (action.desired.enabled === false) {
+            const dbId = context.recordedIds()[`coolify:database:${action.key}`];
+            if (!dbId) {
+                throw new Error(`coolify:database for ${org.slug}: no live database recorded, nothing to park`);
+            }
+            await this.ports.coolify.raw('POST', `/databases/${dbId}/stop`);
+            return { resourceId: dbId };
+        }
+        const existing = context.recordedIds()[`coolify:database:${action.key}`];
+        let dbId;
+        if (existing) {
+            dbId = existing;
+        }
+        else {
+            const projectUuid = await this.ensureCoolifyProject(org, context);
+            const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
+            const name = `${org.slug}-db`;
+            const found = (await this.ports.coolify.listDatabases()).find((db) => db.name === name && db.environment_id === environment.id);
+            if (found) {
+                dbId = found.uuid;
+            }
+            else {
+                const server = await this.resolveServer();
+                const dbName = org.slug.replace(/-/g, '_');
+                const created = await this.ports.coolify.createPostgresDatabase({
+                    project_uuid: projectUuid,
+                    server_uuid: server.uuid,
+                    environment_name: environment.name,
+                    environment_uuid: environment.uuid,
+                    name,
+                    postgres_db: dbName,
+                    postgres_user: dbName,
+                });
+                dbId = created.uuid;
+            }
+        }
+        // Handles the database being provisioned after the app already exists
+        // (`coolifyApp`'s own push handles the more common order, database
+        // before app on the same apply -- `diff.ts`'s `computePlanDetail`).
+        const appId = context.recordedIds()[`coolify:app:${action.key}`];
+        if (appId)
+            await this.pushDatabaseUrl(appId, dbId);
+        return { resourceId: dbId };
+    }
+    /**
+     * Pushes the database's connection string into the app's environment as
+     * `DATABASE_URL` -- never also as `DATABASE_URL_OWNER` (Decision, this
+     * campaign's report). Archon's own boot script
+     * (`archon/scripts/migrate-and-start.sh`) treats a bare `DATABASE_URL` with
+     * no `DATABASE_URL_OWNER` as "before the split": it migrates and serves as
+     * the one role it has, which is exactly what a database Coolify just
+     * created (one superuser role, no separate runtime role yet) is. Setting
+     * both to the *same* superuser URL would instead take the split branch --
+     * `db-role-guard.sh` then refuses to boot, since `DATABASE_URL_OWNER` being
+     * set means it expects `DATABASE_URL` to connect as a distinct,
+     * non-superuser runtime role (`<database>_rt`), which nothing here creates.
+     * Minting that role's own password and URL is a provisioning step of its
+     * own, not built here (Finding, this campaign's report).
+     *
+     * The connection string is a live credential
+     * (`postgres://user:password@host/db`): it is read from
+     * `CoolifyPort.getDatabase` and handed straight to `bulkUpsertEnvs` and
+     * nowhere else in this class -- never returned, never recorded in
+     * `serviceIds` (hence never in the store or an audit record), never logged,
+     * never interpolated into a thrown error.
+     */
+    async pushDatabaseUrl(appId, dbId) {
+        const db = await this.ports.coolify.getDatabase(dbId);
+        if (!db.internal_db_url)
+            return;
+        await this.ports.coolify.bulkUpsertEnvs(appId, [
+            { key: 'DATABASE_URL', value: db.internal_db_url },
+        ]);
+    }
+    /**
+     * 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).
+     */
+    async pushAppEnv(appId, org, context) {
+        const recorded = context.recordedIds();
+        const envs = [
+            { key: 'APP_URL', value: `https://${hostnameFor(org)}` },
+            // #75: read back by the package-side pino sink (not this repo's job,
+            // #75 "What belongs where") once `ensureLogVolume` has mounted the
+            // matching volume.
+            { key: 'LOG_DIR', value: LOG_DIR },
+        ];
+        const zitadelOrgId = recorded.zitadel_org;
+        if (zitadelOrgId)
+            envs.push({ key: 'AUTH_ORGANIZATION_ID', value: zitadelOrgId });
+        const clientId = recorded[APP_CLIENT_ID_SCOPE_KEY];
+        if (clientId)
+            envs.push({ key: 'AUTH_CLIENT_ID', value: clientId });
+        // The invited owner's ZITADEL user id (gap P3): the app uses it to make
+        // them its own owner in authz on first sign-in. `runSteps` records this
+        // under the same `system:kind:key` shape every step's `resourceId` uses
+        // (`zitadelOwner`'s own doc comment), not a scope id.
+        const ownerUserId = recorded[`zitadel:owner:${org.id}`];
+        if (ownerUserId)
+            envs.push({ key: 'OWNER_USER_ID', value: ownerUserId });
+        // Idempotent the same way `pushDatabaseUrl`'s credential is treated:
+        // generated once, handed straight to `bulkUpsertEnvs` and nowhere else in
+        // this class -- never returned, recorded, logged or interpolated into a
+        // thrown error.
+        const cookieSecret = await this.ensureAuthCookieSecret(appId);
+        if (cookieSecret)
+            envs.push({ key: 'AUTH_COOKIE_SECRET', value: cookieSecret });
+        await this.ports.coolify.bulkUpsertEnvs(appId, envs);
+    }
+    /**
+     * `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.
+     */
+    async ensureAuthCookieSecret(appId) {
+        const envs = await this.ports.coolify.listEnvs(appId);
+        const already = envs.some((e) => e.key === 'AUTH_COOKIE_SECRET' && !e.is_preview);
+        if (already)
+            return null;
+        return randomBytes(32).toString('base64');
+    }
+    /**
+     * `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.
+     */
+    async cmsSite(action, org, context) {
+        if (action.desired.enabled === false) {
+            const recorded = context.recordedIds();
+            const cmsAppId = recorded[CMS_APP_SCOPE_KEY];
+            const siteAppId = recorded[SITE_APP_SCOPE_KEY];
+            if (!cmsAppId && !siteAppId) {
+                throw new Error(`cms:site for ${org.slug}: no live cms/site app recorded, nothing to park`);
+            }
+            // Stops whichever of the two is recorded rather than refusing the
+            // whole step over the other -- a crash between recording the site
+            // app's id and the cms app's own (`cmsSite`'s provisioning half,
+            // above) must not leave a live app stuck running forever because park
+            // always threw first.
+            if (cmsAppId)
+                await this.ports.coolify.raw('POST', `/applications/${cmsAppId}/stop`);
+            if (siteAppId)
+                await this.ports.coolify.raw('POST', `/applications/${siteAppId}/stop`);
+            return { resourceId: cmsAppId ?? siteAppId };
+        }
+        // `validateSite` ("site.enabled requires domain") guarantees this
+        // whenever this step runs -- checked anyway, the same way
+        // `cloudflareRateLimit` above guards its own `org.domain` read, since
+        // TypeScript's `string | null` gives no static guarantee of it.
+        if (!org.domain) {
+            throw new Error(`cms:site for ${org.slug}: site.enabled is set but domain is null`);
+        }
+        const domain = org.domain;
+        const projectUuid = await this.ensureCoolifyProject(org, context);
+        const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
+        const site = await this.findOrCreateCmsApp({
+            projectUuid,
+            environment,
+            name: `${org.slug}-site`,
+            dockerfileLocation: CMS_SITE_APP_DOCKERFILE,
+            domain,
+        });
+        const cms = await this.findOrCreateCmsApp({
+            projectUuid,
+            environment,
+            name: `${org.slug}-cms`,
+            dockerfileLocation: CMS_APP_DOCKERFILE,
+            domain: cmsHostnameFor(org),
+        });
+        // Every app foundry deploys keeps its own logs (#75) -- reused as-is for
+        // both of these two, the same unconditional call `coolifyApp` makes for
+        // its own one app.
+        await this.ensureLogVolume(site.appId, org, site.existed);
+        await this.ensureLogVolume(cms.appId, org, cms.existed);
+        context.recordScopeId(SITE_APP_SCOPE_KEY, site.appId);
+        context.recordScopeId(CMS_APP_SCOPE_KEY, cms.appId);
+        // `@wtfalch/cms`'s own env contracts
+        // (https://github.com/wtfalch/cms/blob/main/apps/host/.env.example and
+        // .../apps/site/.env.example): the cms app runs in single-org mode
+        // (`CMS_ORGANISATION_ID`) and needs the site's own URL to link back to;
+        // the site app needs only the cms app's URL to read content from.
+        //
+        // Pushed here, before the database work below (#117 review round 2),
+        // rather than folded into one later `bulkUpsertEnvs` call:
+        // `ensureCmsDatabase`/`getDatabase` are deliberately left free to throw
+        // (see that section's own comment) instead of caught, so a database
+        // failure must not also cost the app these two calls already have
+        // everything they need for.
+        await this.ports.coolify.bulkUpsertEnvs(cms.appId, [
+            { key: 'APP_URL', value: `https://${cmsHostnameFor(org)}` },
+            { key: 'CMS_ORGANISATION_ID', value: org.id },
+            { key: 'CMS_SITE_URL', value: `https://${domain}` },
+        ]);
+        await this.ports.coolify.bulkUpsertEnvs(site.appId, [
+            { key: 'CMS_URL', value: `https://${cmsHostnameFor(org)}` },
+        ]);
+        // #117: the cms app's own database, split into a migration-only
+        // superuser role (`DATABASE_URL_OWNER`) and a restricted `cms_rt`
+        // runtime role (`DATABASE_URL`) -- `ensureCmsDatabase`'s and
+        // `ensureCmsRuntimeUrl`'s own doc comments. Neither call below is
+        // wrapped in a try/catch: a failure here (Coolify down, a bad response)
+        // must still fail this step, so it is visible in the apply's own output
+        // and retried on the next one, rather than silently skipped -- the two
+        // `bulkUpsertEnvs` calls above have already landed by the time either
+        // could throw.
+        const dbId = await this.ensureCmsDatabase(org, context, projectUuid, environment);
+        context.recordScopeId(CMS_DATABASE_SCOPE_KEY, dbId);
+        // Read back from Coolify's own record (`pushDatabaseUrl`'s own doc
+        // comment on why: live state, not `createPostgresDatabase`'s return
+        // value, since this run may have just found the database rather than
+        // created it) -- both values are live credentials, handed straight to
+        // `bulkUpsertEnvs` below and nowhere else in this class: never returned,
+        // recorded, logged, or interpolated into a thrown error. Its own call,
+        // separate from the two app-env calls above, since it has nothing to
+        // push once `internal_db_url` is absent.
+        const db = await this.ports.coolify.getDatabase(dbId);
+        if (db.internal_db_url) {
+            const dbEnvs = [
+                { key: 'DATABASE_URL_OWNER', value: db.internal_db_url },
+            ];
+            const runtimeUrl = await this.ensureCmsRuntimeUrl(cms.appId, db.internal_db_url);
+            if (runtimeUrl)
+                dbEnvs.push({ key: 'DATABASE_URL', value: runtimeUrl });
+            await this.ports.coolify.bulkUpsertEnvs(cms.appId, dbEnvs);
+        }
+        return { resourceId: cms.appId };
+    }
+    /**
+     * `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).
+     */
+    async ensureCmsDatabase(org, context, projectUuid, environment) {
+        const existing = context.recordedIds()[CMS_DATABASE_SCOPE_KEY];
+        if (existing)
+            return existing;
+        const name = `${org.slug}-cms-db`;
+        const found = (await this.ports.coolify.listDatabases()).find((d) => d.name === name && d.environment_id === environment.id);
+        if (found)
+            return found.uuid;
+        const server = await this.resolveServer();
+        const dbName = name.replace(/-/g, '_');
+        const created = await this.ports.coolify.createPostgresDatabase({
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            name,
+            postgres_db: dbName,
+            postgres_user: dbName,
+        });
+        return created.uuid;
+    }
+    /**
+     * `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`.
+     */
+    async ensureCmsRuntimeUrl(appId, dbInternalUrl) {
+        const envs = await this.ports.coolify.listEnvs(appId);
+        const already = envs.some((e) => e.key === 'DATABASE_URL' && !e.is_preview);
+        if (already)
+            return null;
+        let host;
+        let pathname;
+        let search;
+        try {
+            ({ host, pathname, search } = new URL(dbInternalUrl));
+        }
+        catch {
+            return null;
+        }
+        const password = randomBytes(24).toString('base64url');
+        return `postgres://cms_rt:${password}@${host}${pathname}${search}`;
+    }
+    /**
+     * `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.
+     */
+    async findOrCreateCmsApp(input) {
+        const existing = await this.ports.coolify.findApplicationByName(input.name, {
+            environmentIds: [input.environment.id],
+        });
+        if (existing) {
+            const live = await this.ports.coolify.getApplication(existing.uuid);
+            if (!isRunningOrStarting(live.status)) {
+                await this.ports.coolify.raw('POST', `/applications/${existing.uuid}/start`);
+            }
+            return { appId: existing.uuid, existed: true };
+        }
+        const server = await this.resolveServer();
+        const githubApp = await this.ports.coolify.requireGithubApp();
+        const created = await this.ports.coolify.createGithubAppApplication({
+            project_uuid: input.projectUuid,
+            server_uuid: server.uuid,
+            environment_name: input.environment.name,
+            environment_uuid: input.environment.uuid,
+            github_app_uuid: githubApp.uuid,
+            git_repository: CMS_REPO,
+            git_branch: 'main',
+            build_pack: 'dockerfile',
+            name: input.name,
+            domains: input.domain,
+            dockerfile_location: input.dockerfileLocation,
+        });
+        return { appId: created.uuid, existed: false };
+    }
+    // ---- cloudflare --------------------------------------------------------
+    async cloudflareTunnel(action, org, context) {
+        if (action.desired.enabled === false) {
+            const tunnelId = context.recordedIds()[`cloudflare:tunnel:${action.key}`];
+            if (!tunnelId) {
+                throw new Error(`cloudflare:tunnel for ${org.slug}: no live tunnel recorded, nothing to park`);
+            }
+            // Cleared, not deleted (#7 corrections 1): an ingress with only the
+            // mandatory catch-all routes nothing.
+            await this.ports.cloudflare.putTunnelConfig(tunnelId, {
+                ingress: [{ service: 'http_status:404' }],
+            });
+            return { resourceId: tunnelId };
+        }
+        const tunnelName = `${org.slug}-tunnel`;
+        const existing = await this.ports.cloudflare.findTunnelByName(tunnelName);
+        const tunnel = existing ?? (await this.ports.cloudflare.createTunnel(tunnelName));
+        // Routes each of the org's hostnames (`tunnelIngressHostnames`) to
+        // Coolify's own Traefik reverse proxy, not a per-app container address --
+        // `COOLIFY_PROXY_ORIGIN`, the same constant name and value
+        // `wtfalch/app-template`'s prior art used (`bootstrap/steps/cf-tunnel.ts`,
+        // offline.tf's bootstrap, cited by
+        // https://github.com/wtfalch/foundry/issues/71): every app on the
+        // Coolify box already gets a Traefik route from the `domains` its
+        // `coolify:app` step declared (`hostnameFor(org)`, this file's
+        // `coolifyApp`), so a cloudflared connector joined to the same Docker
+        // network only has to reach Traefik and let it route by Host header --
+        // the connector never needs to know the app's own container name or
+        // uuid. Verified evidence, not a guess (see this campaign's report);
+        // `http://<slug>:3000`, the placeholder this replaces, named a container
+        // and port no `coolify:app` step here ever configures. A site-enabled org
+        // (#115) gets one ingress entry per hostname `tunnelIngressHostnames`
+        // returns, all routed to the same proxy -- Traefik itself, not this list,
+        // is what tells the public site apart from the cms studio.
+        const ingress = tunnelIngressHostnames(org).map((hostname) => ({
+            hostname,
+            service: COOLIFY_PROXY_ORIGIN,
+        }));
+        await this.ports.cloudflare.putTunnelConfig(tunnel.id, {
+            ingress: [...ingress, { service: 'http_status:404' }],
+        });
+        return { resourceId: tunnel.id };
+    }
+    async cloudflareZone(action) {
+        const domain = action.key;
+        const existing = await this.ports.cloudflare.findZoneByApex(domain);
+        if (existing)
+            return { resourceId: existing.id };
+        const created = await this.ports.cloudflare.createZone(domain);
+        return { resourceId: created.id };
+    }
+    // ---- mail -----------------------------------------------------------
+    /**
+     * `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.
+     */
+    async coolifyMail(action, org) {
+        const mode = action.desired.mode;
+        const usesDomain = action.desired.usesDomain;
+        const options = { apex: MAIL_APEX, mailHost: MAIL_HOST };
+        if (mode === 'off') {
+            await this.ports.mail.parkOrgMail(mailOrgFor(org, usesDomain, 'hosted'), options);
+            return undefined;
+        }
+        const result = await this.ports.mail.applyOrgMail(mailOrgFor(org, usesDomain, mode), options);
+        await this.publishMailDnsRecords(org, result);
+        return { resourceId: result.domain };
+    }
+    /**
+     * 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.
+     */
+    async publishMailDnsRecords(org, result) {
+        const cf = this.ports.cloudflare;
+        const zone = await cf.findZoneByApex(result.domain);
+        if (!zone) {
+            throw new Error(`coolify:mail for ${org.slug}: no Cloudflare zone found for ${result.domain}`);
+        }
+        for (const record of result.records) {
+            const [existing] = await cf.findDnsRecord(zone.id, record.name, record.type);
+            const rec = { type: record.type, name: record.name, content: record.value };
+            if (existing) {
+                await cf.updateDnsRecord(zone.id, existing.id, rec);
+            }
+            else {
+                await cf.createDnsRecord(zone.id, rec);
+            }
+        }
+    }
+    // ---- files / ai --------------------------------------------------------
+    /**
+     * #80: provisions the org's own organisation on Files, before
+     * {@link filesStorage} can set its spend limit. `provisionOrganisation` is
+     * safely repeatable on its own (`FilesOrganisationPort`'s doc comment), so
+     * this is called every time regardless of whether it already ran --
+     * idempotent by find-or-create, not by checking `recordedIds` first.
+     */
+    async filesOrganisation(action, org) {
+        const provisioned = await this.ports.filesOrganisation.provisionOrganisation({
+            organisationId: org.id,
+            ceilingBytes: action.desired.ceilingBytes ?? null,
+            ceilingMicros: action.desired.ceilingMicros ?? null,
+        });
+        return { resourceId: provisioned.organisationId };
+    }
+    async filesStorage(action, org) {
+        const limits = this.ports.filesLimitsFor(org.id);
+        await limits.setQuota(action.desired.limitBytes ?? null);
+        await limits.setBudget(action.desired.limitMicros ?? null);
+        return { resourceId: org.id };
+    }
+    /**
+     * #80: provisions the org's own organisation on AI and switches its AI use
+     * on, before {@link aiBudget} can set its own spend limit. Both
+     * `provisionOrganisation` and `setOrganisationOffers` are safely repeatable
+     * on their own (`AiOrganisationPort`'s doc comment), so both are called
+     * every time regardless of whether they already ran.
+     */
+    async aiOrganisation(action, org) {
+        const provisioned = await this.ports.aiOrganisation.provisionOrganisation({
+            organisationId: org.id,
+            limitMicros: action.desired.limitMicros ?? null,
+        });
+        await this.ports.aiOrganisation.setOrganisationOffers(org.id, action.desired.offers ?? []);
+        return { resourceId: provisioned.organisationId };
+    }
+    async aiBudget(action, org) {
+        const limitMicros = action.desired.limitMicros ?? null;
+        if (limitMicros === null) {
+            // ai/packages/sdk/src/types.ts:134-137's UpdateBudget.limitMicros is a
+            // required string -- there is no "uncapped" this API can express yet
+            // (Finding, this campaign's report).
+            throw new Error(`ai:budget for ${org.slug}: AI's updateBudget has no uncapped representation (UpdateBudget.limitMicros is a required string); declare a numeric limit until AI's API adds one`);
+        }
+        const limits = this.ports.aiLimitsFor(org.id);
+        await limits.updateBudget({ keyId: null, limitMicros });
+        return { resourceId: org.id };
+    }
+    // ---- destroy -------------------------------------------------------------
+    /**
+     * {@link StepDestroyer.destroy}: deletes the one resource
+     * `FoundryPlanApply.destroy` names. A provider 404 (already gone) counts as
+     * deleted -- `isNotFoundError` below -- since a destroy retried after a
+     * partial failure must find an already-deleted resource a no-op, not a new
+     * error.
+     */
+    async destroy(target, context) {
+        const { org, recordedIds } = context;
+        try {
+            switch (`${target.system}:${target.kind}`) {
+                case 'cloudflare:tunnel':
+                    await this.ports.cloudflare.deleteTunnel(target.id);
+                    return;
+                case 'cloudflare:access':
+                    await this.ports.cloudflare.deleteAccessApp(target.id);
+                    return;
+                case 'coolify:app':
+                    await this.ports.coolify.deleteApplication(target.id);
+                    return;
+                case 'coolify:database':
+                    await this.ports.coolify.deleteDatabase(target.id);
+                    return;
+                case 'zitadel:app': {
+                    const zitadelOrgId = recordedIds.zitadel_org;
+                    const projectId = recordedIds.zitadel_project;
+                    if (!zitadelOrgId || !projectId) {
+                        throw new Error(`zitadel:app '${target.key}' for ${org.slug}: no ZITADEL org/project recorded, cannot delete`);
+                    }
+                    await this.ports.zitadel.deleteApp(zitadelOrgId, projectId, target.id);
+                    return;
+                }
+                case 'zitadel:project': {
+                    const zitadelOrgId = recordedIds.zitadel_org;
+                    if (!zitadelOrgId) {
+                        throw new Error(`zitadel:project for ${org.slug}: no ZITADEL org recorded, cannot delete project`);
+                    }
+                    await this.ports.zitadel.deleteProject(zitadelOrgId, target.id);
+                    return;
+                }
+                case 'zitadel:customers':
+                case 'zitadel:org':
+                    await this.ports.zitadel.deleteOrg(target.id);
+                    return;
+                default:
+                    throw new Error(`FoundryStepExecutor has no destroy dispatch for ${target.system}:${target.kind}`);
+            }
+        }
+        catch (error) {
+            if (isNotFoundError(error))
+                return;
+            throw error;
+        }
+    }
+}
+/**
+ * True for a provider's own "already gone" response, however it surfaces --
+ * `@wtfalch/providers`' `ZitadelError` carries a structured `status: number`
+ * (`zitadel.ts`), while its Coolify and Cloudflare clients throw a plain
+ * `Error` whose message embeds the HTTP status (`` `Coolify ${method} ${path}
+ * → ${status}: ${text}` ``, `` `CF ${method} ${path} → ${status}: ${msg}` ``).
+ * Ports are structural here (this file's own top comment: never import a
+ * concrete provider class), so this cannot `instanceof`-check a real error
+ * type -- it duck-types a `status` field first.
+ *
+ * A prior version fell back to scanning the *whole* message for a standalone
+ * `404` when no `status` field was present. That is unsafe: the Coolify and
+ * Cloudflare clients put the resource path -- which can contain a hex UUID
+ * -- ahead of the status in the message, so a UUID that happens to contain
+ * the digits `404` (`9a404b12-...`) made a genuine 500 read as a 404. The
+ * fallback below instead anchors to the exact position both clients put the
+ * status in: the first `→ `, after the client, method and path, and before
+ * `:`. It never scans the path or the response body.
+ */
+function isNotFoundError(error) {
+    const status = error?.status;
+    if (typeof status === 'number')
+        return status === 404;
+    const message = error instanceof Error ? error.message : String(error);
+    return /^\S+ \S+ \S+ → 404:/.test(message);
+}