@wtfalch/foundry 0.1.0 → 0.3.0

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

@@ -3,7 +3,7 @@ import type { CoolifyClient } from '@wtfalch/providers/coolify';
 import type { ZitadelClient } from '@wtfalch/providers/zitadel';
 import type { OrgId } from '../org.js';
 import type { DeclaredOrgStore } from '../store.js';
-import type { CloudflareReader, CoolifyReader, LiveResource, ZitadelReader } from './live.js';
+import type { CloudflareReader, CmsReader, CoolifyReader, LiveResource, ZitadelReader } from './live.js';
 /**
  * Real `CoolifyReader`, `CloudflareReader` and `ZitadelReader` implementations
  * (`live.ts:31-45`), backed by `@wtfalch/providers`' HTTP clients instead of
@@ -22,6 +22,13 @@ import type { CloudflareReader, CoolifyReader, LiveResource, ZitadelReader } fro
  *
  * `packages/foundry/package.json` had zero `@wtfalch/*` dependencies before
  * this file; `@wtfalch/providers` is its first.
+ *
+ * Each reader also matches a live provider resource back onto the foundry
+ * resource it was created for, via {@link RecordedIds} /
+ * {@link storeRecordedIds} below, so `computePlanDetail` (`diff.ts`) treats
+ * what foundry itself provisioned as matched instead of unmanaged (#10) --
+ * see the campaign design doc,
+ * `.claude/campaign/2026-09-24-keys-and-memberships.md`, "Design for (1)".
  */
 /**
  * Resolves an estate {@link OrgId} to one provider's own scope id — a
@@ -38,19 +45,44 @@ import type { CloudflareReader, CoolifyReader, LiveResource, ZitadelReader } fro
  */
 export type ScopeResolver = (orgId: OrgId) => Promise<string | null>;
 /**
- * A {@link ScopeResolver} backed by `AppliedState.serviceIds`
- * (`../state.ts`: "one id per service ... keyed by that service's own name
- * for the org") — the one place foundry records a provider's own id for an
- * org today, through the same `DeclaredOrgStore` seam #18 built.
+ * A {@link ScopeResolver} backed by `AppliedState.serviceIds` (`../state.ts`)
+ * — the one place foundry records a provider's own id for an org today,
+ * through the same `DeclaredOrgStore` seam #18 built.
  *
- * Nothing writes a `serviceIds[serviceKey]` entry yet — that is the
- * `StepExecutor` half of #20, not built here — so every resolver built this
- * way returns `null` for every org until it does. That is the correct
- * "nothing live yet" answer: a reader passed `null` returns `[]`, which
- * `computePlanDetail` (`diff.ts`) already reads as "no live resource",
- * exactly right for an org with no Coolify project (etc.) yet.
+ * `runSteps` (`plan-apply.ts`) now writes one `serviceIds` entry per
+ * resource it creates, keyed `system:kind:key` ({@link storeRecordedIds}
+ * below reads those back), and #20's `FoundryStepExecutor` (`executor.ts`)
+ * now also calls `StepExecutionContext.recordScopeId` for `coolify_project`,
+ * `zitadel_org` and `zitadel_project`, so a resolver built with one of those
+ * three `serviceKey`s returns the real id once that step has run. A
+ * Cloudflare zone is the one scope id nothing writes yet: `executor.ts`'s
+ * `cloudflareZone` records its result only under `cloudflare:zone:<domain>`
+ * (a resource id, read back by {@link storeRecordedIds}), not under a plain
+ * `cloudflare_zone` scope key — a resolver built with that `serviceKey`
+ * still returns `null` for every org. That is the correct "nothing live yet"
+ * answer: a reader passed `null` returns `[]`, which `computePlanDetail`
+ * (`diff.ts`) already reads as "no live resource".
  */
 export declare function storeScopeResolver(store: DeclaredOrgStore, serviceKey: string): ScopeResolver;
+/**
+ * Resolves an estate {@link OrgId} to the provider ids this org's applied
+ * state has recorded for one reader's `system`, inverted so a reader can
+ * look a live resource's own id up directly: the provider's id -> the
+ * foundry `kind:key` it was recorded under.
+ *
+ * Backed by the same `AppliedState.serviceIds` {@link storeScopeResolver}
+ * reads, but a different slice of it: `plan-apply.ts`'s `runSteps` records a
+ * completed step's `resourceId` under `serviceIds[`${system}:${kind}:${key}`]`
+ * (`../state.ts`'s doc comment; design:
+ * `.claude/campaign/2026-09-24-keys-and-memberships.md`, "Design for (1)").
+ * Only entries in that three-part form, for this `system`, are kept — a
+ * scope id (`coolify_project`, etc.) has no `:` in it and is filtered out
+ * rather than mistaken for a resource id. `key` is rejoined with `:` rather
+ * than taken as a single segment because it is not always the org id: a
+ * declared ZITADEL app is keyed by its own name (#71), not `orgId`.
+ */
+export type RecordedIds = (orgId: OrgId) => Promise<Record<string, string>>;
+export declare function storeRecordedIds(store: DeclaredOrgStore, system: LiveResource['system']): RecordedIds;
 /**
  * Backed by `@wtfalch/providers/coolify`'s `CoolifyClient.listResources`: a
  * Coolify project's environments and in-scope applications (v1 scope — see
@@ -59,7 +91,8 @@ export declare function storeScopeResolver(store: DeclaredOrgStore, serviceKey:
 export declare class ProvidersCoolifyReader implements CoolifyReader {
     private readonly client;
     private readonly resolveScope;
-    constructor(client: CoolifyClient, resolveScope: ScopeResolver);
+    private readonly resolveRecordedIds;
+    constructor(client: CoolifyClient, resolveScope: ScopeResolver, resolveRecordedIds: RecordedIds);
     listResources(orgId: OrgId): Promise<LiveResource[]>;
 }
 /**
@@ -70,7 +103,8 @@ export declare class ProvidersCoolifyReader implements CoolifyReader {
 export declare class ProvidersCloudflareReader implements CloudflareReader {
     private readonly client;
     private readonly resolveScope;
-    constructor(client: CloudflareClient, resolveScope: ScopeResolver);
+    private readonly resolveRecordedIds;
+    constructor(client: CloudflareClient, resolveScope: ScopeResolver, resolveRecordedIds: RecordedIds);
     listResources(orgId: OrgId): Promise<LiveResource[]>;
 }
 /**
@@ -81,6 +115,60 @@ export declare class ProvidersCloudflareReader implements CloudflareReader {
 export declare class ProvidersZitadelReader implements ZitadelReader {
     private readonly client;
     private readonly resolveScope;
-    constructor(client: ZitadelClient, resolveScope: ScopeResolver);
+    private readonly resolveRecordedIds;
+    constructor(client: ZitadelClient, resolveScope: ScopeResolver, resolveRecordedIds: RecordedIds);
+    listResources(orgId: OrgId): Promise<LiveResource[]>;
+}
+/**
+ * Backed by the same `@wtfalch/providers/coolify`'s `CoolifyClient.listResources`
+ * call {@link ProvidersCoolifyReader} makes, not a real cms admin API --
+ * `executor.ts`'s `cmsSite` (#116) provisions the org's cms app and site app
+ * as two ordinary Coolify applications in the *same* Coolify project the
+ * org's own hosted app would use (`ensureCoolifyProject`), so this reader
+ * resolves that project's scope the same way, then finds the two
+ * applications this org recorded there -- by the flat scope ids `cmsSite`
+ * records them under (`coolify_cms_app`/`coolify_site_app`, `executor.ts`'s
+ * `CMS_APP_SCOPE_KEY`/`SITE_APP_SCOPE_KEY` -- restated here rather than
+ * imported, the same way `hostnameFor`'s hostname rule is restated across
+ * files rather than shared), matched by id the same way every other reader
+ * in this file matches a recorded resource, never by name.
+ *
+ * Without this reader nothing ever reports a live `cms:site:<orgId>`
+ * resource, so `diff.ts`'s `planSite` sees `!live` forever and re-plans
+ * "provision a cms site" on every apply even after one has already
+ * succeeded -- #116 review Finding 1, breaking #14's "repeat until plan
+ * returns empty" invariant.
+ *
+ * `planSite` reads this resource's `config.enabled`/`config.usesDomain` with
+ * plain truthiness (`Boolean(live.config.enabled)`), unlike
+ * `planHostingToggle`'s own `!== false` convention for the org's *own* app
+ * -- so, unlike {@link ProvidersCoolifyReader}, which only ever passes
+ * Coolify's raw fields through untouched, this reader has to synthesize an
+ * explicit `enabled` boolean itself, or the plan would never converge in
+ * either direction. Both apps must exist and count as up, or on their way
+ * there ({@link isRunningApplication}), for `enabled` to be `true`; not
+ * found, or found but actually stopped, reads as `false`, which is what
+ * lets a later park step's own live check (`!live.config.enabled`) settle
+ * once both apps have actually stopped.
+ * `usesDomain` is always `true`: `validateSite` ("site.enabled requires
+ * site.usesDomain") guarantees it whenever this resource can exist at all.
+ *
+ * Nothing recorded yet (no Coolify project scope, or either app id still
+ * unrecorded -- `cmsSite`'s own doc comment: a crash partway through a first
+ * apply can leave only one recorded) or either application missing from
+ * Coolify's own listing reads as "nothing live" (`[]`), the same "not
+ * provisioned yet" answer `computePlanDetail` already knows how to plan
+ * against. A failing `client.listResources` call is not caught here, the
+ * same way it is not caught in `ProvidersCoolifyReader`/
+ * `ProvidersCloudflareReader`/`ProvidersZitadelReader` either -- only a
+ * bolt-on *extra* read (`withLogVolumeConfig`'s own doc comment) gets a
+ * try/catch, and this call is this reader's entire job, not an extra.
+ */
+export declare class ProvidersCmsReader implements CmsReader {
+    private readonly client;
+    private readonly resolveProjectScope;
+    private readonly resolveCmsAppId;
+    private readonly resolveSiteAppId;
+    constructor(client: CoolifyClient, resolveProjectScope: ScopeResolver, resolveCmsAppId: ScopeResolver, resolveSiteAppId: ScopeResolver);
     listResources(orgId: OrgId): Promise<LiveResource[]>;
 }

package/dist/plan/providers-readers.js

@@ -1,15 +1,21 @@
 /**
- * A {@link ScopeResolver} backed by `AppliedState.serviceIds`
- * (`../state.ts`: "one id per service ... keyed by that service's own name
- * for the org") — the one place foundry records a provider's own id for an
- * org today, through the same `DeclaredOrgStore` seam #18 built.
+ * A {@link ScopeResolver} backed by `AppliedState.serviceIds` (`../state.ts`)
+ * — the one place foundry records a provider's own id for an org today,
+ * through the same `DeclaredOrgStore` seam #18 built.
  *
- * Nothing writes a `serviceIds[serviceKey]` entry yet — that is the
- * `StepExecutor` half of #20, not built here — so every resolver built this
- * way returns `null` for every org until it does. That is the correct
- * "nothing live yet" answer: a reader passed `null` returns `[]`, which
- * `computePlanDetail` (`diff.ts`) already reads as "no live resource",
- * exactly right for an org with no Coolify project (etc.) yet.
+ * `runSteps` (`plan-apply.ts`) now writes one `serviceIds` entry per
+ * resource it creates, keyed `system:kind:key` ({@link storeRecordedIds}
+ * below reads those back), and #20's `FoundryStepExecutor` (`executor.ts`)
+ * now also calls `StepExecutionContext.recordScopeId` for `coolify_project`,
+ * `zitadel_org` and `zitadel_project`, so a resolver built with one of those
+ * three `serviceKey`s returns the real id once that step has run. A
+ * Cloudflare zone is the one scope id nothing writes yet: `executor.ts`'s
+ * `cloudflareZone` records its result only under `cloudflare:zone:<domain>`
+ * (a resource id, read back by {@link storeRecordedIds}), not under a plain
+ * `cloudflare_zone` scope key — a resolver built with that `serviceKey`
+ * still returns `null` for every org. That is the correct "nothing live yet"
+ * answer: a reader passed `null` returns `[]`, which `computePlanDetail`
+ * (`diff.ts`) already reads as "no live resource".
  */
 export function storeScopeResolver(store, serviceKey) {
     return async (orgId) => {
@@ -20,6 +26,110 @@ export function storeScopeResolver(store, serviceKey) {
         return applied?.serviceIds[serviceKey] || null;
     };
 }
+export function storeRecordedIds(store, system) {
+    return async (orgId) => {
+        const applied = await store.getAppliedState(orgId);
+        const recorded = {};
+        if (!applied)
+            return recorded;
+        for (const [resourceKey, providerId] of Object.entries(applied.serviceIds)) {
+            const [keySystem, kind, ...rest] = resourceKey.split(':');
+            if (keySystem !== system || kind === undefined || rest.length === 0)
+                continue;
+            recorded[providerId] = `${kind}:${rest.join(':')}`;
+        }
+        return recorded;
+    };
+}
+/**
+ * Maps each live resource whose own id is one `recorded` names onto the
+ * foundry `kind`/`key` it was recorded under, keeping `config` exactly as
+ * the provider gave it (design doc, "Design for (1)": "the reader then maps
+ * each provider resource whose `key` equals a recorded provider id onto the
+ * recorded foundry `kind` and `key`"). A resource nothing recorded passes
+ * through unchanged, so `computePlanDetail` (`diff.ts`) still reports it
+ * unmanaged (#10) rather than this boundary guessing at a match.
+ *
+ * `dropUnrecordedKinds` names kinds that are dropped outright instead of
+ * passed through when unrecorded. Cloudflare's `tunnel` is the one case: a
+ * tunnel is account-wide, so an unrecorded one belongs to some other org,
+ * not this one, and every org's plan would otherwise report the same
+ * foreign tunnel as unmanaged.
+ */
+function applyRecordedIds(resources, recorded, dropUnrecordedKinds = new Set()) {
+    const mapped = [];
+    for (const resource of resources) {
+        const foundryKey = recorded[resource.key];
+        if (!foundryKey) {
+            if (!dropUnrecordedKinds.has(resource.kind))
+                mapped.push(resource);
+            continue;
+        }
+        const separator = foundryKey.indexOf(':');
+        mapped.push({
+            ...resource,
+            kind: foundryKey.slice(0, separator),
+            key: foundryKey.slice(separator + 1),
+        });
+    }
+    return mapped;
+}
+/** Cloudflare tunnels this org has not recorded are dropped — see {@link applyRecordedIds}. */
+const CLOUDFLARE_DROP_UNRECORDED = new Set(['tunnel']);
+/**
+ * The persistent-storage mount path #75 requires on every app foundry
+ * deploys, and the exact string `executor.ts`'s own `LOG_DIR` constant holds
+ * -- restated here rather than imported the same way `executor.ts` restates
+ * `diff.ts`'s hostname rule, since neither file in `plan/` imports another's
+ * private constants.
+ */
+const LOG_DIR = '/app/logs';
+/**
+ * #75: whether the org's own recorded app already carries the durable log
+ * directory `executor.ts`'s `ensureLogVolume` creates -- an extra
+ * `listStorages` read, by the application's own provider uuid
+ * (`resource.key`, still the raw Coolify uuid at this point -- called
+ * *before* {@link applyRecordedIds} below overwrites `key` with the foundry
+ * key it was recorded under, or `listStorages` would be asked for a
+ * "storages" listing of the org id instead of the application). Gated on
+ * `recorded` mapping this exact uuid onto foundry's `app` kind (the same map
+ * {@link applyRecordedIds} itself reads), not just `resource.kind ===
+ * 'application'`, so this never fires for some other application in the same
+ * project, nor for the project's own database uuid.
+ *
+ * This lets `diff.ts`'s `planApp` notice a live app that predates this
+ * feature and plan the missing volume, the same way `LiveResource.config`
+ * (`live.ts`) already carries whatever a planner needs to diff against.
+ * `hasLogDir`'s env var itself is not read back here: `executor.ts`'s
+ * `coolifyApp` always pushes `LOG_DIR` in the same step that mounts the
+ * volume, so the volume's own presence is the one signal this reader needs
+ * (Decision: reading `listEnvs` too would only catch a volume manually
+ * removed after the env was pushed by hand, which #75's own "no app is
+ * configured by hand" rules out).
+ *
+ * `listStorages` is one extra, unrelated-to-the-plan's-real-purpose read
+ * bolted onto every org's plan (#75), so a failure of this one call --
+ * Coolify briefly unreachable, a 5xx, anything `CoolifyClient` throws on a
+ * non-2xx -- must not abort the whole org's plan the way an unhandled
+ * rejection here would (Finding, refuted against the first version of this
+ * function: it had no try/catch at all). Caught and treated the same as
+ * "nothing has checked this app yet": the resource passes through
+ * unchanged, `hasLogVolume` stays absent, and `diff.ts`'s `planApp` already
+ * reads a missing `hasLogVolume` as compliant rather than drift.
+ */
+async function withLogVolumeConfig(client, resource, recorded) {
+    if (resource.kind !== 'application' || !recorded[resource.key]?.startsWith('app:')) {
+        return resource;
+    }
+    try {
+        const storages = await client.listStorages(resource.key);
+        const hasLogVolume = (storages.persistent_storages ?? []).some((s) => s.mount_path === LOG_DIR);
+        return { ...resource, config: { ...resource.config, hasLogVolume } };
+    }
+    catch {
+        return resource;
+    }
+}
 /** `@wtfalch/providers`' own `LiveResource` (`resource.ts`) has no `system` field — foundry's adds it at this boundary. */
 function toFoundryResources(system, resources) {
     return resources.map((r) => ({ system, kind: r.kind, key: r.key, config: r.config }));
@@ -32,15 +142,22 @@ function toFoundryResources(system, resources) {
 export class ProvidersCoolifyReader {
     client;
     resolveScope;
-    constructor(client, resolveScope) {
+    resolveRecordedIds;
+    constructor(client, resolveScope, resolveRecordedIds) {
         this.client = client;
         this.resolveScope = resolveScope;
+        this.resolveRecordedIds = resolveRecordedIds;
     }
     async listResources(orgId) {
         const projectUuid = await this.resolveScope(orgId);
         if (!projectUuid)
             return [];
-        return toFoundryResources('coolify', await this.client.listResources(projectUuid));
+        const [resources, recorded] = await Promise.all([
+            this.client.listResources(projectUuid),
+            this.resolveRecordedIds(orgId),
+        ]);
+        const withLogConfig = await Promise.all(toFoundryResources('coolify', resources).map((r) => withLogVolumeConfig(this.client, r, recorded)));
+        return applyRecordedIds(withLogConfig, recorded);
     }
 }
 /**
@@ -51,15 +168,24 @@ export class ProvidersCoolifyReader {
 export class ProvidersCloudflareReader {
     client;
     resolveScope;
-    constructor(client, resolveScope) {
+    resolveRecordedIds;
+    constructor(client, resolveScope, resolveRecordedIds) {
         this.client = client;
         this.resolveScope = resolveScope;
+        this.resolveRecordedIds = resolveRecordedIds;
     }
     async listResources(orgId) {
         const zoneId = await this.resolveScope(orgId);
         if (!zoneId)
             return [];
-        return toFoundryResources('cloudflare', await this.client.listResources(zoneId));
+        const [resources, recorded] = await Promise.all([
+            this.client.listResources(zoneId),
+            this.resolveRecordedIds(orgId),
+        ]);
+        // A zone needs no mapping: its key is already the zone name, which is
+        // foundry's own zone key (`diff.ts`'s `planZone`), so it never matches a
+        // recorded provider id and always passes through unchanged.
+        return applyRecordedIds(toFoundryResources('cloudflare', resources), recorded, CLOUDFLARE_DROP_UNRECORDED);
     }
 }
 /**
@@ -70,14 +196,117 @@ export class ProvidersCloudflareReader {
 export class ProvidersZitadelReader {
     client;
     resolveScope;
-    constructor(client, resolveScope) {
+    resolveRecordedIds;
+    constructor(client, resolveScope, resolveRecordedIds) {
         this.client = client;
         this.resolveScope = resolveScope;
+        this.resolveRecordedIds = resolveRecordedIds;
     }
     async listResources(orgId) {
         const zitadelOrgId = await this.resolveScope(orgId);
         if (!zitadelOrgId)
             return [];
-        return toFoundryResources('zitadel', await this.client.listResources(zitadelOrgId));
+        const [resources, recorded] = await Promise.all([
+            this.client.listResources(zitadelOrgId),
+            this.resolveRecordedIds(orgId),
+        ]);
+        return applyRecordedIds(toFoundryResources('zitadel', resources), recorded);
+    }
+}
+/**
+ * Whether an application counts as up, or on its way there, from its own
+ * Coolify `status` (`` `running:healthy`, `running:unknown`,
+ * `exited:unhealthy` `` -- `CoolifyClient`'s own `CoolifyApplication.status`
+ * doc comment). Anything except `exited`/`stopped` (Coolify's own
+ * resting-off states; `stopped` is not one this codebase has verified
+ * against a live instance, included defensively) reads as still on --
+ * concretely, `starting:*`/`restarting:*` right after `cmsSite` (re)creates
+ * or starts an app both count as on too, not just `running:*`, or a status
+ * read moments after that call would misreport `enabled: false` and cause a
+ * spurious re-plan (#116 review round 3, Finding 2, mirroring
+ * `executor.ts`'s own `isRunningOrStarting`, restated here rather than
+ * imported the same way `hostnameFor`'s hostname rule is). A missing
+ * `status` defaults to on too, the same "nothing says it's off" convention
+ * `planHostingToggle` (`diff.ts`) uses for the org's own app.
+ */
+function isRunningApplication(resource) {
+    const status = resource.config.status;
+    if (!status)
+        return true;
+    return (typeof status === 'string' && !status.startsWith('exited') && !status.startsWith('stopped'));
+}
+/**
+ * Backed by the same `@wtfalch/providers/coolify`'s `CoolifyClient.listResources`
+ * call {@link ProvidersCoolifyReader} makes, not a real cms admin API --
+ * `executor.ts`'s `cmsSite` (#116) provisions the org's cms app and site app
+ * as two ordinary Coolify applications in the *same* Coolify project the
+ * org's own hosted app would use (`ensureCoolifyProject`), so this reader
+ * resolves that project's scope the same way, then finds the two
+ * applications this org recorded there -- by the flat scope ids `cmsSite`
+ * records them under (`coolify_cms_app`/`coolify_site_app`, `executor.ts`'s
+ * `CMS_APP_SCOPE_KEY`/`SITE_APP_SCOPE_KEY` -- restated here rather than
+ * imported, the same way `hostnameFor`'s hostname rule is restated across
+ * files rather than shared), matched by id the same way every other reader
+ * in this file matches a recorded resource, never by name.
+ *
+ * Without this reader nothing ever reports a live `cms:site:<orgId>`
+ * resource, so `diff.ts`'s `planSite` sees `!live` forever and re-plans
+ * "provision a cms site" on every apply even after one has already
+ * succeeded -- #116 review Finding 1, breaking #14's "repeat until plan
+ * returns empty" invariant.
+ *
+ * `planSite` reads this resource's `config.enabled`/`config.usesDomain` with
+ * plain truthiness (`Boolean(live.config.enabled)`), unlike
+ * `planHostingToggle`'s own `!== false` convention for the org's *own* app
+ * -- so, unlike {@link ProvidersCoolifyReader}, which only ever passes
+ * Coolify's raw fields through untouched, this reader has to synthesize an
+ * explicit `enabled` boolean itself, or the plan would never converge in
+ * either direction. Both apps must exist and count as up, or on their way
+ * there ({@link isRunningApplication}), for `enabled` to be `true`; not
+ * found, or found but actually stopped, reads as `false`, which is what
+ * lets a later park step's own live check (`!live.config.enabled`) settle
+ * once both apps have actually stopped.
+ * `usesDomain` is always `true`: `validateSite` ("site.enabled requires
+ * site.usesDomain") guarantees it whenever this resource can exist at all.
+ *
+ * Nothing recorded yet (no Coolify project scope, or either app id still
+ * unrecorded -- `cmsSite`'s own doc comment: a crash partway through a first
+ * apply can leave only one recorded) or either application missing from
+ * Coolify's own listing reads as "nothing live" (`[]`), the same "not
+ * provisioned yet" answer `computePlanDetail` already knows how to plan
+ * against. A failing `client.listResources` call is not caught here, the
+ * same way it is not caught in `ProvidersCoolifyReader`/
+ * `ProvidersCloudflareReader`/`ProvidersZitadelReader` either -- only a
+ * bolt-on *extra* read (`withLogVolumeConfig`'s own doc comment) gets a
+ * try/catch, and this call is this reader's entire job, not an extra.
+ */
+export class ProvidersCmsReader {
+    client;
+    resolveProjectScope;
+    resolveCmsAppId;
+    resolveSiteAppId;
+    constructor(client, resolveProjectScope, resolveCmsAppId, resolveSiteAppId) {
+        this.client = client;
+        this.resolveProjectScope = resolveProjectScope;
+        this.resolveCmsAppId = resolveCmsAppId;
+        this.resolveSiteAppId = resolveSiteAppId;
+    }
+    async listResources(orgId) {
+        const projectUuid = await this.resolveProjectScope(orgId);
+        if (!projectUuid)
+            return [];
+        const [cmsAppId, siteAppId] = await Promise.all([
+            this.resolveCmsAppId(orgId),
+            this.resolveSiteAppId(orgId),
+        ]);
+        if (!cmsAppId || !siteAppId)
+            return [];
+        const resources = await this.client.listResources(projectUuid);
+        const cmsApp = resources.find((r) => r.kind === 'application' && r.key === cmsAppId);
+        const siteApp = resources.find((r) => r.kind === 'application' && r.key === siteAppId);
+        if (!cmsApp || !siteApp)
+            return [];
+        const enabled = isRunningApplication(cmsApp) && isRunningApplication(siteApp);
+        return [{ system: 'cms', kind: 'site', key: orgId, config: { enabled, usesDomain: true } }];
     }
 }

package/dist/provision.d.ts

@@ -0,0 +1,56 @@
+import type { CoolifyPort } from './plan/executor.js';
+export declare const PROJECT_NAME = "foundry";
+export declare const ENVIRONMENT_NAME = "production";
+export declare const DATABASE_NAME = "foundry";
+/**
+ * The Coolify calls provisioning needs, on top of `plan/executor.ts`'s own
+ * `CoolifyPort` (reused by reference below rather than restated): `listEnvironments`,
+ * which `CoolifyPort` has no read-only equivalent for (`findOrCreateEnvironment`
+ * creates on a miss). A real `CoolifyClient` already has both, so this is
+ * still satisfied with no adapter.
+ */
+export interface ProvisionCoolifyPort extends Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'listDatabases' | 'createPostgresDatabase'> {
+    listEnvironments(projectUuid: string): Promise<Array<{
+        id: number;
+        uuid: string;
+        name: string;
+    }>>;
+}
+export interface ProvisionPlan {
+    projectExists: boolean;
+    project?: {
+        uuid: string;
+    };
+    environmentExists: boolean;
+    environment?: {
+        id: number;
+        uuid: string;
+        name: string;
+    };
+    databaseExists: boolean;
+    database?: {
+        uuid: string;
+        name: string;
+        environment_id?: number;
+    };
+}
+/**
+ * Read-only: works out what `applyProvision` would need to do to make the
+ * `PROJECT_NAME`/`ENVIRONMENT_NAME`/`DATABASE_NAME` database exist, without
+ * creating anything. Mirrors `plan/executor.ts`'s `coolifyDatabase` step --
+ * find the database by name scoped to the environment's numeric
+ * `environment_id`, the same care about environment scoping
+ * `findApplicationByName`'s doc comment explains (an unscoped name match
+ * risks a false positive against a same-named database in a different
+ * environment).
+ */
+export declare function planProvision(coolify: ProvisionCoolifyPort): Promise<ProvisionPlan>;
+/**
+ * Makes `plan` true: creates whatever `planProvision` found missing.
+ * A no-op read (returns `plan.database`) when the database already exists,
+ * so calling this twice never creates a second one.
+ */
+export declare function applyProvision(coolify: ProvisionCoolifyPort, plan: ProvisionPlan): Promise<{
+    uuid: string;
+    name: string;
+}>;

package/dist/provision.js

@@ -0,0 +1,69 @@
+// #R2 (map gap: foundry's own Postgres, two commands): find-or-create the
+// Postgres database `scripts/foundry-db-provision.mjs` migrates into.
+// Project, environment and database names are fixed here rather than taken
+// as input -- one foundry install, one project -- so there is nothing to
+// mistype on the command line.
+export const PROJECT_NAME = 'foundry';
+export const ENVIRONMENT_NAME = 'production';
+export const DATABASE_NAME = 'foundry';
+/**
+ * Read-only: works out what `applyProvision` would need to do to make the
+ * `PROJECT_NAME`/`ENVIRONMENT_NAME`/`DATABASE_NAME` database exist, without
+ * creating anything. Mirrors `plan/executor.ts`'s `coolifyDatabase` step --
+ * find the database by name scoped to the environment's numeric
+ * `environment_id`, the same care about environment scoping
+ * `findApplicationByName`'s doc comment explains (an unscoped name match
+ * risks a false positive against a same-named database in a different
+ * environment).
+ */
+export async function planProvision(coolify) {
+    const project = await coolify.findProjectByName(PROJECT_NAME);
+    if (!project) {
+        return { projectExists: false, environmentExists: false, databaseExists: false };
+    }
+    const environments = await coolify.listEnvironments(project.uuid);
+    const environment = environments.find((e) => e.name === ENVIRONMENT_NAME);
+    if (!environment) {
+        return { projectExists: true, project, environmentExists: false, databaseExists: false };
+    }
+    const databases = await coolify.listDatabases();
+    const database = databases.find((db) => db.name === DATABASE_NAME && db.environment_id === environment.id);
+    return {
+        projectExists: true,
+        project,
+        environmentExists: true,
+        environment,
+        databaseExists: Boolean(database),
+        database,
+    };
+}
+/**
+ * Makes `plan` true: creates whatever `planProvision` found missing.
+ * A no-op read (returns `plan.database`) when the database already exists,
+ * so calling this twice never creates a second one.
+ */
+export async function applyProvision(coolify, plan) {
+    if (plan.databaseExists && plan.database)
+        return plan.database;
+    const project = plan.projectExists && plan.project ? plan.project : await coolify.createProject(PROJECT_NAME);
+    const environment = plan.environmentExists && plan.environment
+        ? plan.environment
+        : (await coolify.findOrCreateEnvironment(project.uuid, ENVIRONMENT_NAME)).environment;
+    const servers = await 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.');
+    // `createPostgresDatabase` also returns `internal_db_url` -- a live
+    // credential -- which is deliberately never read off this result: only
+    // `uuid` (and the `name` we already know) leaves this function.
+    const created = await coolify.createPostgresDatabase({
+        project_uuid: project.uuid,
+        server_uuid: server.uuid,
+        environment_name: environment.name,
+        environment_uuid: environment.uuid,
+        name: DATABASE_NAME,
+        postgres_db: DATABASE_NAME,
+        postgres_user: DATABASE_NAME,
+    });
+    return { uuid: created.uuid, name: DATABASE_NAME };
+}

package/dist/slug.d.ts

@@ -1,21 +1,3 @@
-/**
- * The declared org's slug: a pure validator, no I/O, no store access.
- *
- * Decided in https://github.com/wtfalch/foundry/issues/28, forced by the
- * level-1 apex `oikos.host` being live: Cloudflare's free-tier Universal SSL
- * covers a single wildcard level, so every level-1 org's hostnames are flat
- * (`acme.oikos.host`, `acme-stage.oikos.host`, `acme-pr-12.oikos.host`).
- * That makes the slug a live hostname from the moment the org exists — #7
- * only froze it once the org had mail, which is too late: by then the
- * hostname is already serving. This validator runs at creation, not at
- * first use (#28 "Done when").
- *
- * Kept separate from `org.ts` and `store/postgres.ts` so it can be called
- * from both without either depending on the other: `store/postgres.ts`
- * calls it on `create` and `update` (#28), and anything that needs to
- * pre-validate a slug before it ever reaches the store — the operator page,
- * one day — can import it too.
- */
 /** The flattened set {@link validateSlug} checks a candidate slug against. */
 export declare const RESERVED_SLUGS: ReadonlySet<string>;
 /**
@@ -36,3 +18,15 @@ export interface SlugRejection {
  * needs one reason reported.
  */
 export declare function validateSlug(slug: string): SlugRejection | null;
+/**
+ * The slug for a new org, derived from its first display name (William,
+ * 2026-09-26): "Good Company" becomes `good-company`, and `good-company.oikos.host`
+ * is its address. When that slug is taken, reserved or has an environment
+ * suffix, a short random suffix is added: `bruh-7k3q`. The display name stays
+ * separate, so an org can rename itself without moving its address.
+ *
+ * An offensive name is refused outright, by the same check the sign-in broker
+ * runs on usernames (https://github.com/wtfalch/foundry/issues/103, N1b). A
+ * name that could pass as infra (`admin`, `help`) only costs the slug a suffix.
+ */
+export declare function slugFromName(name: string, slugTaken: (slug: string) => Promise<boolean>, suffix?: () => string): Promise<string>;