@wtfalch/foundry 0.1.0 → 0.2.0

package/dist/plan/diff.js

@@ -19,36 +19,84 @@ function resourceKey(system, kind, key) {
  * exist for every org — the issuer, mail, and chat (always provisioned at
  * level 1, per #7 "Chat", regardless of `usesDomain`). #27 adds two more,
  * in the same singleton shape: storage's spend limit on Files and AI's
- * budget. This task adds a sixth, in the same shape: the org's cms site
- * (`org.ts`'s `SiteConfig`). Everything else in `live` that none of these
- * six claim is unmanaged. The full field-by-field provisioning surface (SSO,
- * guests, calls, adopted/bespoke apps, the actual
+ * budget. T10 adds a sixth, in the same shape: the org's cms site
+ * (`org.ts`'s `SiteConfig`). #71 adds four more singleton resources, in the
+ * same shape — the org's own hosted app, its database, its Cloudflare
+ * tunnel and its Cloudflare zone (`org.ts`'s `HostingConfig`) — plus one
+ * list-shaped resource: `planIssuerApps` below emits one step per declared
+ * `hosting.issuerApps[]` entry rather than a single singleton, since an org
+ * can declare more than one ZITADEL app. #80 adds two more singletons,
+ * modeled on {@link planIssuer}: `planFilesOrganisation` and
+ * `planAiOrganisation`, each planned before its own system's limit step
+ * ({@link planStorage}, {@link planAiBudget}) so an org has somewhere for a
+ * limit to land, and AI use is switched on, before either limit is ever set.
+ * `planOwner` below adds one more singleton, in a different shape from the
+ * rest: the org's owner, invited by ZITADEL email, idempotent on the
+ * *recorded* resource id (`recordedIds`, sourced from
+ * `AppliedState.serviceIds`) rather than a live resource, since a human user
+ * is never something `live` can contain. Everything else in `live` that none
+ * of these twelve singletons and however many declared issuer apps claim is
+ * unmanaged. The full field-by-field provisioning surface (SSO, guests,
+ * calls, adopted/bespoke apps, the actual
  * Zitadel/Coolify/Cloudflare/Files/AI/cms shapes) is #20's "provision
  * Company Factory end to end", which wires real readers and executors
  * against this seam.
  */
-export function computePlanDetail(org, live) {
+export function computePlanDetail(org, live, recordedIds = {}) {
     const byKey = new Map(live.map((r) => [resourceKey(r.system, r.kind, r.key), r]));
     const claimed = new Set();
     const plannedSteps = [];
     const issuer = planIssuer(org, byKey, claimed);
     if (issuer)
         plannedSteps.push(issuer);
+    const owner = planOwner(org, recordedIds);
+    if (owner)
+        plannedSteps.push(owner);
     const mail = planMail(org, byKey, claimed);
     if (mail)
         plannedSteps.push(mail);
     const chat = planChat(org, byKey, claimed);
     if (chat)
         plannedSteps.push(chat);
+    const filesOrganisation = planFilesOrganisation(org, byKey, claimed);
+    if (filesOrganisation)
+        plannedSteps.push(filesOrganisation);
     const storage = planStorage(org, byKey, claimed);
     if (storage)
         plannedSteps.push(storage);
+    const aiOrganisation = planAiOrganisation(org, byKey, claimed);
+    if (aiOrganisation)
+        plannedSteps.push(aiOrganisation);
     const aiBudget = planAiBudget(org, byKey, claimed);
     if (aiBudget)
         plannedSteps.push(aiBudget);
     const site = planSite(org, byKey, claimed);
     if (site)
         plannedSteps.push(site);
+    // Database before app (hosting-wiring campaign): `plan-apply.ts`'s
+    // `runSteps` executes `plannedSteps` in this array order, and the app's own
+    // step (`executor.ts`'s `coolifyApp`) pushes the database's connection
+    // string into the app's environment once the database exists -- it can
+    // only do that if the database step already ran and recorded the
+    // database's resource id.
+    const database = planDatabase(org, byKey, claimed);
+    if (database)
+        plannedSteps.push(database);
+    const app = planApp(org, byKey, claimed);
+    if (app)
+        plannedSteps.push(app);
+    const tunnel = planTunnel(org, byKey, claimed);
+    if (tunnel)
+        plannedSteps.push(tunnel);
+    const zone = planZone(org, byKey, claimed);
+    if (zone)
+        plannedSteps.push(zone);
+    plannedSteps.push(...planIssuerApps(org, byKey, claimed));
+    // After the apps: the customers org is granted the project the first app
+    // step creates.
+    const customers = planCustomers(org, live, claimed, recordedIds);
+    if (customers)
+        plannedSteps.push(customers);
     // #10 (resolved): "foundry manages only what the declared org names";
     // anything left unclaimed is listed, never proposed for deletion.
     const unmanaged = live
@@ -58,13 +106,43 @@ export function computePlanDetail(org, live) {
     }));
     return { orgId: org.id, plannedSteps, unmanaged };
 }
+/**
+ * The org's own ZITADEL org (issuer), a per-org singleton like every other
+ * planner in this file, with one extra wrinkle: unlike mail/chat/site/app,
+ * there is nothing to "provision" versus "move" from the same live check --
+ * a missing live resource means the org has no ZITADEL org at all yet, which
+ * `apply` must create before anything else can act inside it (declared:
+ * `.claude/decisions-2026-09-24-executor.md`, "Executor decisions" -- "when
+ * no ZITADEL org exists, the planner now plans 'provision the org's ZITADEL
+ * org' ... the executor creates it named after the slug"). That provision
+ * step is never destructive: nothing live is touched. Once a live issuer
+ * resource exists, the original move logic applies unchanged -- moving the
+ * issuer onto or off the org's domain invalidates every passkey in the org
+ * (#7 corrections 2) and is not built in v1 (decisions file, same section:
+ * "domain verification and passkey invalidation need their own design"), so
+ * `executor.ts` throws `NotBuiltError` on it rather than run it.
+ */
 function planIssuer(org, byKey, claimed) {
     const key = resourceKey('zitadel', 'issuer', org.id);
     const live = byKey.get(key);
-    if (live)
-        claimed.add(key);
     const desiredUsesDomain = org.issuer.usesDomain;
-    const liveUsesDomain = live ? Boolean(live.config.usesDomain) : false;
+    if (!live) {
+        return {
+            action: {
+                system: 'zitadel',
+                kind: 'issuer',
+                key: org.id,
+                desired: { provision: true, usesDomain: desiredUsesDomain },
+            },
+            step: {
+                description: `provision ${org.slug}'s own ZITADEL org`,
+                destroys: false,
+                migrates: false,
+            },
+        };
+    }
+    claimed.add(key);
+    const liveUsesDomain = Boolean(live.config.usesDomain);
     if (liveUsesDomain === desiredUsesDomain)
         return null;
     const domain = org.domain ?? 'the org domain';
@@ -87,6 +165,58 @@ function planIssuer(org, byKey, claimed) {
         },
     };
 }
+/**
+ * The org's owner, invited by ZITADEL email once the org's ZITADEL org
+ * exists (goal line: "the org's owner is invited by ZITADEL email and sets a
+ * passkey — no password passes through foundry"). A per-org singleton like
+ * every other planner here, but idempotent on a different signal: the
+ * *recorded* resource id (`recordedIds['zitadel:owner:<orgId>']`, written by
+ * `plan-apply.ts`'s `runSteps` from this step's own `resourceId` — the
+ * invited user id) rather than a live resource. `ZitadelReader.listResources`
+ * (`@wtfalch/providers`' `ZitadelClient.listResources`) reads projects and
+ * grants, never a human user, so there is nothing in `live` an invited owner
+ * could ever appear as; this step neither claims nor reads from `byKey` for
+ * that reason.
+ *
+ * Ordered right after `planIssuer` in `computePlanDetail` (not after mail,
+ * chat, or any hosting step) so that on a first-ever apply — when nothing is
+ * live yet — the ZITADEL org this step's executor needs
+ * (`context.recordedIds().zitadel_org`) has already been recorded by the
+ * issuer step immediately before it in the same run: `plan-apply.ts`'s
+ * `runSteps` awaits each planned step in array order, one at a time.
+ *
+ * `desired` carries the owner's email so the executor can pass it to
+ * `ZitadelClient.inviteOrgOwner` — but the step's own `description` never
+ * does. `Plan` (the public contract `AuditLog.recordPlan`/`recordApply`
+ * store) carries only `PlanStep`, never `StepAction`, so `desired` never
+ * reaches the audit log; keeping the email out of `description` too means
+ * nothing here puts it anywhere beyond what audit already records for the
+ * org.
+ */
+function planOwner(org, recordedIds) {
+    if (!org.owner)
+        return null;
+    const key = resourceKey('zitadel', 'owner', org.id);
+    if (recordedIds[key])
+        return null; // already invited -- a re-run plans nothing.
+    return {
+        action: {
+            system: 'zitadel',
+            kind: 'owner',
+            key: org.id,
+            desired: {
+                email: org.owner.email,
+                givenName: org.owner.givenName,
+                familyName: org.owner.familyName,
+            },
+        },
+        step: {
+            description: `invite ${org.slug}'s owner by email`,
+            destroys: false,
+            migrates: false,
+        },
+    };
+}
 function planMail(org, byKey, claimed) {
     const key = resourceKey('coolify', 'mail', org.id);
     const live = byKey.get(key);
@@ -188,6 +318,92 @@ function planChat(org, byKey, claimed) {
         },
     };
 }
+/**
+ * Deduped `ai.*` permissions offered to every organisation by default
+ * (Decision, this campaign's report): the minimum set that lets an org
+ * actually run jobs against the platform's own offered models --
+ * `ai.offerings:invoke` to invoke an offering, `ai.runs:create` to submit the
+ * run itself. `ai/packages/service/src/catalogue.ts`'s five `offered: true`
+ * permissions also include the three `ai.connections:*` ones, which let an
+ * organisation bring its own provider credentials (BYOK) -- a separate,
+ * explicit opt-in this default deliberately leaves out.
+ */
+const AI_DEFAULT_OFFERS = ['ai.offerings:invoke', 'ai.runs:create'];
+/**
+ * #80: every org's own organisation on Files, a per-org singleton resource
+ * planned before {@link planStorage} -- `setQuota`/`setBudget` 404 against an
+ * org Files has never provisioned (`files/packages/sdk/src/client.ts`'s
+ * tenant routes need the row `provisionOrganisation` creates). Modeled on
+ * {@link planIssuer}: nothing to diff once it exists -- Files' own
+ * `provisionOrganisation` is safely repeatable (`executor.ts`'s
+ * `filesOrganisation` calls it every time regardless), so the only planned
+ * state is "not provisioned yet". The operator-driven `ceilingBytes`/
+ * `ceilingMicros` hard cap (`OrganisationSummary`) is never this planner's
+ * concern (`org.ts`'s `StorageConfig` doc: "a separate, operator-driven hard
+ * cap this field has no opinion on"), so provisioning always asks for an
+ * uncapped ceiling -- Decision, this campaign's report.
+ */
+function planFilesOrganisation(org, byKey, claimed) {
+    const key = resourceKey('files', 'organisation', org.id);
+    const live = byKey.get(key);
+    if (live) {
+        claimed.add(key);
+        return null;
+    }
+    return {
+        action: {
+            system: 'files',
+            kind: 'organisation',
+            key: org.id,
+            desired: { provision: true, ceilingBytes: null, ceilingMicros: null },
+        },
+        step: {
+            description: `provision ${org.slug}'s own organisation on Files`,
+            destroys: false,
+            migrates: false,
+        },
+    };
+}
+/**
+ * #80: every org's own organisation on AI, a per-org singleton resource
+ * planned before {@link planAiBudget} -- a provisioned-but-unoffered
+ * organisation holds no `ai.*` permission, so running a job is refused
+ * (foundry issue #80). Modeled on {@link planIssuer} and
+ * {@link planFilesOrganisation}: nothing to diff once it exists -- AI's own
+ * `provisionOrganisation` and `setOrganisationOffers` are both safely
+ * repeatable (`executor.ts`'s `aiOrganisation` calls both every time
+ * regardless), so the only planned state is "not provisioned yet".
+ * `AI_DEFAULT_OFFERS` is this campaign's Decision for what "AI use is
+ * switched on" means by default; `limitMicros` seeds the organisation's
+ * first budget row with whatever the org already declares (including
+ * `null` for uncapped), so a brand new org never needs a follow-up
+ * {@link planAiBudget} step just to reach its own declared default.
+ */
+function planAiOrganisation(org, byKey, claimed) {
+    const key = resourceKey('ai', 'organisation', org.id);
+    const live = byKey.get(key);
+    if (live) {
+        claimed.add(key);
+        return null;
+    }
+    return {
+        action: {
+            system: 'ai',
+            kind: 'organisation',
+            key: org.id,
+            desired: {
+                provision: true,
+                limitMicros: org.ai.limitMicros,
+                offers: [...AI_DEFAULT_OFFERS],
+            },
+        },
+        step: {
+            description: `provision ${org.slug}'s own organisation on AI and switch AI use on`,
+            destroys: false,
+            migrates: false,
+        },
+    };
+}
 /**
  * #27: the org's own spend limit on Files, a per-org singleton resource in
  * the same shape as issuer/mail/chat above. Setting a limit is a config
@@ -217,7 +433,10 @@ function planStorage(org, byKey, claimed) {
 }
 /**
  * #27: the org's own spend limit on AI, a per-org singleton resource in the
- * same shape as {@link planStorage}.
+ * same shape as {@link planStorage}. Planned after {@link planAiOrganisation}
+ * (#80), which already seeds a brand new org's first budget row from this
+ * same `org.ai.limitMicros` -- this planner only fires again once that row's
+ * live value has drifted from what is declared.
  */
 function planAiBudget(org, byKey, claimed) {
     const key = resourceKey('ai', 'budget', org.id);
@@ -300,3 +519,177 @@ function planSite(org, byKey, claimed) {
         },
     };
 }
+/**
+ * The shared on/off shape behind {@link planApp}, {@link planDatabase} and
+ * {@link planTunnel} (#71): a per-org singleton resource, keyed by the org
+ * id like {@link planMail} and {@link planSite}, with the same
+ * park-not-delete rule (#7 corrections 1) -- turning it off never deletes
+ * the org's own app, database or tunnel configuration, it parks it.
+ */
+function planHostingToggle(system, kind, desiredEnabled, org, byKey, claimed, describeProvision, describePark) {
+    const key = resourceKey(system, kind, org.id);
+    const live = byKey.get(key);
+    // A live resource is on unless it says it is parked. Providers' own
+    // configs carry no `enabled` field at all, so only a park step's
+    // explicit `enabled: false` reads as off.
+    const liveEnabled = live !== undefined && live.config.enabled !== false;
+    if (!desiredEnabled) {
+        // Nothing declared and nothing live: there is nothing to park.
+        if (!live)
+            return null;
+        claimed.add(key);
+        // Already parked: no step, or a plan would never reach empty (#14
+        // "repeat until plan returns empty") once the park step below ran.
+        if (!liveEnabled)
+            return null;
+        return {
+            action: { system, kind, key: org.id, desired: { enabled: false } },
+            step: { description: describePark(), destroys: true, migrates: false },
+        };
+    }
+    if (live)
+        claimed.add(key);
+    // Live and already enabled: matches declared, no step. Otherwise
+    // (nothing live, or live but parked) this provisions/re-provisions it.
+    if (liveEnabled)
+        return null;
+    return {
+        action: { system, kind, key: org.id, desired: { enabled: true } },
+        step: { description: describeProvision(), destroys: false, migrates: false },
+    };
+}
+/**
+ * The org's own app on Coolify (`org.ts`'s `HostingConfig.enabled`, #71), a
+ * per-org singleton resource modeled on {@link planSite}: park, not delete,
+ * on the way off (#7 corrections 1).
+ */
+function planApp(org, byKey, claimed) {
+    return planHostingToggle('coolify', 'app', org.hosting.enabled, org, byKey, claimed, () => `provision ${org.slug}'s app`, () => `park ${org.slug}'s app (stops serving; app data is retained, not deleted -- #7 corrections 1)`);
+}
+/**
+ * A Postgres database beside the org's app (`org.ts`'s
+ * `HostingConfig.database`, #71) -- `validateHosting` requires
+ * `hosting.enabled` before this can be true. Same park-not-delete shape as
+ * {@link planApp}.
+ */
+function planDatabase(org, byKey, claimed) {
+    return planHostingToggle('coolify', 'database', org.hosting.database, org, byKey, claimed, () => `provision a database for ${org.slug}'s app`, () => `park ${org.slug}'s database (data is retained, not deleted -- #7 corrections 1)`);
+}
+/**
+ * A Cloudflare tunnel reaching the org's app (`org.ts`'s
+ * `HostingConfig.tunnel`, #71) -- `validateHosting` requires
+ * `hosting.enabled` before this can be true. Same park-not-delete shape as
+ * {@link planApp}.
+ */
+function planTunnel(org, byKey, claimed) {
+    return planHostingToggle('cloudflare', 'tunnel', org.hosting.tunnel, org, byKey, claimed, () => `provision a Cloudflare tunnel for ${org.slug}'s app`, () => `park ${org.slug}'s Cloudflare tunnel (configuration is retained, not deleted -- #7 corrections 1)`);
+}
+/**
+ * The org's Cloudflare zone for its own domain (`org.ts`'s
+ * `HostingConfig.usesDomain`, #71). Unlike every other resource in this
+ * file, a zone is keyed by the domain name itself, not the org id -- a
+ * Cloudflare zone belongs to a domain, not an org. Provision-only: a plan
+ * never parks a zone, since nothing about turning `usesDomain` off says
+ * foundry should stop managing a domain the org may still own elsewhere, so
+ * a live zone under a not-`usesDomain` org is left unmanaged rather than
+ * claimed -- the same choice {@link planMail} makes for a `mode: 'off'` org.
+ */
+function planZone(org, byKey, claimed) {
+    if (!org.hosting.usesDomain || !org.domain)
+        return null;
+    const key = resourceKey('cloudflare', 'zone', org.domain);
+    const live = byKey.get(key);
+    if (live)
+        claimed.add(key);
+    if (live)
+        return null;
+    return {
+        action: {
+            system: 'cloudflare',
+            kind: 'zone',
+            key: org.domain,
+            desired: { domain: org.domain },
+        },
+        step: {
+            description: `provision a Cloudflare zone for ${org.domain}`,
+            destroys: false,
+            migrates: false,
+        },
+    };
+}
+/**
+ * The org's declared ZITADEL OIDC applications (`org.ts`'s
+ * `HostingConfig.issuerApps`, #71), each keyed by its own declared `name`
+ * rather than the org id -- an org can declare more than one. A live
+ * ZITADEL `app` resource this list does not name by `name` is left
+ * unmanaged, the same #10 rule every other resource in this file follows.
+ * There is no park for an issuer app -- ZITADEL has no notion of a
+ * disabled-but-retained OIDC client the way Coolify has a parked app or
+ * database -- so a declared `kind` that differs from the live `appType` is
+ * a destructive step (recreate), never a park, and removing an app from
+ * `issuerApps` entirely produces no step at all (nothing here deletes it;
+ * it simply stops being claimed and shows up as unmanaged next plan).
+ */
+function planIssuerApps(org, byKey, claimed) {
+    const steps = [];
+    for (const app of org.hosting.issuerApps) {
+        const key = resourceKey('zitadel', 'app', app.name);
+        const live = byKey.get(key);
+        if (live)
+            claimed.add(key);
+        const desired = { appType: app.kind };
+        if (!live) {
+            steps.push({
+                action: { system: 'zitadel', kind: 'app', key: app.name, desired },
+                step: {
+                    description: `provision the ${app.kind} ZITADEL app '${app.name}' for ${org.slug}`,
+                    destroys: false,
+                    migrates: false,
+                },
+            });
+            continue;
+        }
+        if (live.config.appType === app.kind)
+            continue;
+        steps.push({
+            action: { system: 'zitadel', kind: 'app', key: app.name, desired },
+            step: {
+                description: `recreate ZITADEL app '${app.name}' for ${org.slug} as ${app.kind} (was ${String(live.config.appType)})`,
+                destroys: true,
+                migrates: false,
+            },
+        });
+    }
+    return steps;
+}
+/**
+ * Plan gap A9: an org's customers sign in through a second ZITADEL org with
+ * self-registration on, granted the org's app project. Planned once the org
+ * declares an issuer app, since customers need an app to sign in to.
+ * Idempotent on the recorded customers org id, like `planOwner`. Once
+ * recorded, the live project grant to that org is claimed so it is not
+ * listed as unmanaged.
+ */
+function planCustomers(org, live, claimed, recordedIds) {
+    if (org.hosting.issuerApps.length === 0)
+        return null;
+    const customersOrgId = recordedIds[resourceKey('zitadel', 'customers', org.id)];
+    if (customersOrgId) {
+        for (const r of live) {
+            if (r.system === 'zitadel' &&
+                r.kind === 'project_grant' &&
+                r.config.grantedOrgId === customersOrgId) {
+                claimed.add(resourceKey(r.system, r.kind, r.key));
+            }
+        }
+        return null;
+    }
+    return {
+        action: { system: 'zitadel', kind: 'customers', key: org.id, desired: {} },
+        step: {
+            description: `provision a self-registration ZITADEL org for ${org.slug}'s customers`,
+            destroys: false,
+            migrates: false,
+        },
+    };
+}