@wtfalch/foundry 0.61.0 → 0.63.0

package/dist/plan/blue-green.js

@@ -1,12 +1,15 @@
 import { createHash } from 'node:crypto';
 import { VERSIONS, pinnedRef } from '../bootstrap/versions.js';
-import { agoraHostnameFor } from './agora.js';
+import { kosmosOn } from '../org.js';
+import { ZITADEL_ORG_SCOPE_KEY, agoraHostnameFor } from './agora.js';
 import { bouleHostnameFor } from './boule.js';
 import { serverConnectorScopeKey } from './cloudflared-connector.js';
 import { entryHostnames, tunnelIngressHostnames, wildcardHostname } from './hostnames.js';
+import { kosmosHostnameFor } from './kosmos.js';
 import { appNameFor, appStepKey } from './platform-diff.js';
 import { remoteDatabaseAppliedFor } from './remote-database.js';
 import { buildStageEnv } from './stage-env.js';
+import { stageHostname } from './stage-guards.js';
 import { assertStageIsolated, envClass } from './stage-isolation.js';
 import { STAGE_SINK_VERSION } from './stage-sink.js';
 export const COLORS = ['blue', 'green'];
@@ -38,6 +41,8 @@ export const bgKey = {
     digest: (id, color) => `bg.${id}.digest.${color}`,
     weights: (id) => `bg.${id}.weights`,
     stage: (id) => `bg.${id}.stage`,
+    /** The last `deploy_stage`: `<ISO time>|ok|<commit>` or `<ISO time>|failed|<step>`. */
+    stageDeploy: (id) => `bg.${id}.stagedeploy`,
     window: (id) => `bg.${id}.window`,
     held: (id, digest) => `bg.${id}.held.${digest}`,
     /** The weights the load balancer on `server` was last written with. */
@@ -64,8 +69,29 @@ export const bgKey = {
     stageIsolation: (id) => `bg.${id}.stageisolation`,
     /** The id of the Access gate over the stage host: staff only, no bypass, no service-token rule. */
     stageGate: (id) => `bg.${id}.stagegate`,
+    /** The hash of the sorted email list last written to the stage gate (owners plus the people holding `releases:preview`). */
+    stageGateMembers: (id) => `bg.${id}.stagegatemembers`,
     /** `ok:<hash>` once every apply-time probe was rejected; `notrun:<names>` or `failed:<names>` otherwise. */
     stageProbes: (id) => `bg.${id}.stageprobes`,
+    /** Stage's own sign-in client: its ZITADEL app id, and its client id (public, not a secret). */
+    stageClient: (id) => `bg.${id}.stageclient`,
+    stageClientId: (id) => `bg.${id}.stageclientid`,
+    /** The held ref of stage's app key, recorded and persisted as soon as it is minted (no `:`: undelivered). */
+    stageSignInKey: (id) => `bg.${id}.stagesigninkey`,
+    /** `{name, organizationId}` of stage's broker entry, so org destroy can remove it. No key. */
+    stageBroker: (id) => `bg.${id}.stagebroker`,
+    /** `ok:<hash of the client, app and broker entry ids>` or `none`; the copy waits for it. */
+    stageSignIn: (id) => `bg.${id}.stagesignin`,
+    /** `none` (production's app uses no files, ai or jobs) or `ok:<hash>` once every service it uses is held by stage or listed absent. */
+    stageServices: (id) => `bg.${id}.stageservices`,
+    /** `ok:<hash of the ids>` or `absent:<service>:<reason>` for one service (`files`, `ai` or `jobs`). */
+    stageService: (id, service) => `bg.${id}.stage${service}`,
+    /** The id of stage's own organisation (files, ai) or project (jobs). An id, not a secret. */
+    stageServiceOrg: (id, service) => `bg.${id}.stage${service}org`,
+    /** The name stage's project or organisation was made under, when the service is deleted by name (jobs). */
+    stageServiceName: (id, service) => `bg.${id}.stage${service}name`,
+    /** `{ids, refs}` of stage's keys in that service: key ids and held refs, never a value. */
+    stageServiceKeys: (id, service) => `bg.${id}.stage${service}keys`,
     /** `applied` once the stage app holds the sink's mail env. The copy refuses without it. */
     stageSink: (id) => `bg.${id}.stagesink`,
     /** `<ISO time>|<dump execution id>|ok`, written by a finished copy of production into stage. */
@@ -165,7 +191,7 @@ export function reportingEnv(input) {
         { key: REPORTING_ENV.healthToken, value: input.healthToken },
     ];
 }
-export const BUILTIN_APPS = ['boule', 'agora'];
+export const BUILTIN_APPS = ['boule', 'agora', 'kosmos'];
 /** What foundry builds each built-in app from; `executor.ts` creates the app from the same values. */
 export const BUILTIN_APP = {
     boule: {
@@ -185,7 +211,31 @@ export const BUILTIN_APP = {
         database: false,
         reporting: false,
     },
+    kosmos: {
+        repo: 'wtfalch/kosmos',
+        dockerfile: '/Dockerfile',
+        port: 3000,
+        healthPath: '/api/health',
+        database: true,
+        reporting: true,
+    },
 };
+/** `builtinSubject`'s hostname for each built-in app, kept beside {@link BUILTIN_APP} rather than a third switch. */
+function builtinHostnameFor(org, app) {
+    if (app === 'boule')
+        return bouleHostnameFor(org);
+    if (app === 'agora')
+        return agoraHostnameFor(org);
+    return kosmosHostnameFor(org);
+}
+/**
+ * Whether `org` declares blue/green for a built-in app: Boule and Agora opt into it through their own
+ * `blueGreen` field (they already run as a single copy otherwise); kosmos has no single-copy mode -- turning
+ * it on (`org.kosmos.enabled`) always runs it blue/green, docs/adr/0001 rule 1.
+ */
+function builtinDeclaresBlueGreen(org, app) {
+    return app === 'kosmos' ? kosmosOn(org) : org[app]?.blueGreen !== undefined;
+}
 /**
  * A hosting entry that declares `blueGreen`, as a subject; `null` when it does not or cannot run.
  * `recorded` names the blue app: an app that ran before blue/green keeps its own name (see {@link liveAppNameFor}).
@@ -213,13 +263,14 @@ export function entrySubject(org, entry, recorded) {
     };
 }
 /**
- * The company's Boule or Agora as a subject; `null` when it does not declare blue/green. The running app keeps
- * its name `<slug>-<app>` and is blue, like platform-archon. Both run on the primary server only.
+ * The company's Boule, Agora or kosmos as a subject; `null` when it does not declare blue/green (see
+ * {@link builtinDeclaresBlueGreen}). The running app keeps its name `<slug>-<app>` and is blue, like
+ * platform-archon. All three run on the primary server only.
  */
 export function builtinSubject(org, app, recorded = {}) {
-    const config = org[app]?.blueGreen;
-    if (!config)
+    if (!builtinDeclaresBlueGreen(org, app))
         return null;
+    const config = org[app]?.blueGreen ?? {};
     const spec = BUILTIN_APP[app];
     const base = `${org.slug}-${app}`;
     return {
@@ -233,7 +284,7 @@ export function builtinSubject(org, app, recorded = {}) {
         buildPack: 'dockerfile',
         healthPath: spec.healthPath,
         database: spec.database,
-        hostnames: [app === 'boule' ? bouleHostnameFor(org) : agoraHostnameFor(org)],
+        hostnames: [builtinHostnameFor(org, app)],
         config,
         blueAppKey: `coolify:${app}:${org.id}`,
         dockerfileLocation: spec.dockerfile,
@@ -241,7 +292,7 @@ export function builtinSubject(org, app, recorded = {}) {
         builtin: app,
     };
 }
-/** Every blue/green subject of an org: the hosting entries that declare it, then Boule and Agora. */
+/** Every blue/green subject of an org: the hosting entries that declare it, then Boule, Agora and kosmos. */
 export function blueGreenSubjects(org, recorded) {
     const subjects = [];
     for (const entry of org.hosting.entries) {
@@ -258,7 +309,7 @@ export function blueGreenSubjects(org, recorded) {
 }
 /** Whether the org declares blue/green for any of its apps. */
 export const declaresBlueGreen = (org) => org.hosting.entries.some((entry) => entry.blueGreen) ||
-    BUILTIN_APPS.some((app) => org[app]?.blueGreen);
+    BUILTIN_APPS.some((app) => builtinDeclaresBlueGreen(org, app));
 /**
  * The Coolify name of the entry's app on the primary. A blue/green entry's app is its blue copy: the recorded
  * name; else the entry's own name when its app is already recorded (it ran before blue/green and is adopted as
@@ -410,12 +461,42 @@ export function structureHash(subject, input) {
         primary: input.primary,
         lb: VERSIONS.traefik,
         ...(input.primary ? { stageSink: STAGE_SINK_VERSION } : {}),
+        // Only a primary has a stage, and only a present guard counts: no guard hashes as before.
+        ...(input.primary && input.guards?.length ? { stageGuards: [...input.guards].sort() } : {}),
     }))
         .digest('hex')
         .slice(0, 16);
 }
-/** The kind of stage app a subject has: platform-archon, else a customer app. */
-export const stageKindOf = (subject) => subject.id === ARCHON_SUBJECT_ID ? 'archon' : 'customer';
+/**
+ * The kind of stage app a subject has: Boule and Agora by `builtin` (a hosting entry that happens to be keyed
+ * `boule` is still a customer app), platform-archon by its id, else a customer app (kosmos included: it has no lists of its own).
+ */
+export const stageKindOf = (subject) => subject.builtin === 'boule' || subject.builtin === 'agora'
+    ? subject.builtin
+    : subject.id === ARCHON_SUBJECT_ID
+        ? 'archon'
+        : 'customer';
+/**
+ * The stage guards that can be made now, by name. The names go into the applied structure hash, so a guard
+ * that becomes possible after the first apply changes the hash and plans the structure step once more.
+ */
+export function stageGuardInputs(facts) {
+    const out = [];
+    if (facts.probesPort)
+        out.push('probes');
+    if (facts.accessPort &&
+        facts.providerId &&
+        facts.domain &&
+        facts.claimValue &&
+        facts.emails > 0 &&
+        !facts.hostRuled) {
+        out.push('gate');
+    }
+    return out;
+}
+/** The guard names as the plan's `desired.guards` carries them, and back. */
+export const formatGuards = (guards) => [...guards].sort().join(',');
+export const parseGuards = (value) => typeof value === 'string' && value ? value.split(',') : [];
 /** The names stage can collide on. */
 export function stageResources(subject) {
     const database = `${subject.base}-stage-db`;
@@ -596,10 +677,22 @@ export function planBlueGreen(input) {
                 key: `bg:${id}:stage`,
             });
         }
+        // The guards that can be made now go into the applied hash: one that becomes possible after the first
+        // apply (a provider, a probe port, an owner) changes the hash and plans the structure step once more.
+        const stageHost = org.domain ? stageHostname(org.domain, id) : null;
+        const guards = stageGuardInputs({
+            probesPort: input.stageGuardPorts?.probes === true,
+            accessPort: input.stageGuardPorts?.access === true,
+            providerId: input.accessProviderId,
+            domain: org.domain,
+            claimValue: recordedIds[ZITADEL_ORG_SCOPE_KEY],
+            emails: org.owners.length,
+            hostRuled: (org.hosting.access ?? []).some((rule) => rule.hostname === stageHost),
+        });
         for (const server of targets) {
             const isPrimary = server === primary;
             const key = `${org.id}:${id}:${server}`;
-            const hash = structureHash(subject, { primary: isPrimary });
+            const hash = structureHash(subject, { primary: isPrimary, guards });
             if (!isPrimary && subject.database && !remoteDatabaseAppliedFor(recordedIds, id, server)) {
                 unmanaged.push({
                     description: `${org.slug}'s ${id} app has no blue/green copies on Coolify server ${server} yet: its database route to that server is not applied`,
@@ -624,6 +717,7 @@ export function planBlueGreen(input) {
                         primary,
                         weights: formatWeights(weights),
                         ...(input.accessProviderId ? { accessProviderId: input.accessProviderId } : {}),
+                        ...(isPrimary && guards.length > 0 ? { guards: formatGuards(guards) } : {}),
                     },
                 });
             }
@@ -722,7 +816,9 @@ export function planArchonBlueGreen(input) {
     if (!primary || !up.includes(primary)) {
         return blocked(`the primary Coolify server ${primary ?? '(none)'} is not usable and reachable`);
     }
-    const done = recorded[bgKey.applied(subject.id, primary)] === structureHash(subject, { primary: true }) &&
+    const guards = input.guards ?? [];
+    const done = recorded[bgKey.applied(subject.id, primary)] ===
+        structureHash(subject, { primary: true, guards }) &&
         recorded[bgKey.lb(subject.id, primary)] === formatWeights(weights) &&
         recorded[ARCHON_BG_ORIGIN_SCOPE_KEY] === lbOrigin(subject);
     if (done)
@@ -734,7 +830,12 @@ export function planArchonBlueGreen(input) {
             phase: 'after',
             key: subject.id,
             description: `run platform-archon as blue and green behind a load balancer on Coolify server ${primary}, then send its tunnel to the balancer`,
-            desired: { subject: subject.id, primary, weights: formatWeights(weights) },
+            desired: {
+                subject: subject.id,
+                primary,
+                weights: formatWeights(weights),
+                ...(guards.length > 0 ? { guards: formatGuards(guards) } : {}),
+            },
         },
     };
 }

package/dist/plan/boule.d.ts

@@ -154,7 +154,7 @@ export declare const registrarWanted: (org: Pick<DeclaredOrg, "customers" | "bou
 /** The broker's base as Boule calls it: `@wtfalch/auth`'s own `brokerUrl` default, `<issuer>/api`. */
 export declare const registrarUrl: (issuer: string) => string;
 /** The env names `desiredBouleEnv` can write, so the live reader knows which to read back. */
-export declare const BOULE_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ISSUER", "AUTH_ORGANIZATION_ID", "AUTH_CLIENT_ID", "BOULE_ORG_NAME", "AUTHZ_BOOTSTRAP_OPERATOR", "AUTHZ_FIRST_OWNER", "ARCHON_URL", "MAIL_FROM", "LETTERMINT_API_TOKEN", "AUTHZ_PEER_PASSWORD_OPERATOR", "ARCHON_BRIDGE_SECRET", "OWNER_SEED_SECRET", "ARCHON_ORG_ID", "ARCHON_CREDENTIAL", "CUSTOMERS_ORGANISATION_ID", "CUSTOMERS_DIRECTORY_CREDENTIAL", "TEST_CUSTOMERS_ORGANISATION_ID", "CUSTOMER_GRANTS", "SIGNIN_UPSTREAM", "AUTH_REGISTRAR_URL", "AUTH_REGISTRAR_KEY"];
+export declare const BOULE_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ISSUER", "AUTH_ORGANIZATION_ID", "AUTH_CLIENT_ID", "BOULE_ORG_NAME", "AUTHZ_BOOTSTRAP_OPERATOR", "AUTHZ_FIRST_OWNER", "ARCHON_URL", "MAIL_FROM", "LETTERMINT_API_TOKEN", "AUTHZ_PEER_PASSWORD_OPERATOR", "ARCHON_BRIDGE_SECRET", "OWNER_SEED_SECRET", "NATIVE_BUILD_KEY", "ARCHON_ORG_ID", "ARCHON_CREDENTIAL", "CUSTOMERS_ORGANISATION_ID", "CUSTOMERS_DIRECTORY_CREDENTIAL", "TEST_CUSTOMERS_ORGANISATION_ID", "CUSTOMER_GRANTS", "SIGNIN_UPSTREAM", "AUTH_REGISTRAR_URL", "AUTH_REGISTRAR_KEY"];
 /**
  * The env vars an org's Boule app should carry, and every input still missing
  * to build them. Callers that write must refuse on a non-empty `missing`: a

package/dist/plan/boule.js

@@ -1,3 +1,4 @@
+import { NATIVE_BUILD_KEY_ENV } from '../native-build.js';
 import { DEFAULT_NO_REPLY_LOCAL_PART, appsOn, ownerMailboxes, } from '../org.js';
 import { ZITADEL_ORG_SCOPE_KEY } from './agora.js';
 import { SIGN_IN_UPSTREAM_ENV, inAppHostApplied, signInUpstream, staleSignInUpstream, } from './sign-in.js';
@@ -176,6 +177,7 @@ export const BOULE_MANAGED_ENV_KEYS = [
     BOULE_PEER_PASSWORD_ENV,
     BOULE_BRIDGE_SECRET_ENV,
     BOULE_OWNER_SEED_SECRET_ENV,
+    NATIVE_BUILD_KEY_ENV,
     BOULE_ARCHON_ORG_ID_ENV,
     BOULE_ARCHON_CREDENTIAL_ENV,
     BOULE_CUSTOMERS_ORG_ENV,

package/dist/plan/broker-entries.d.ts

@@ -178,3 +178,12 @@ export declare function writeBrokerEntry(broker: BrokerPort, input: {
     invalidForeign: string[];
     replaced: string | null;
 }>;
+/**
+ * Takes one entry (and so its key) out of the broker's `AUTH_APPS`, matched by name and organisation, and
+ * deploys the broker when the list changed. Every other entry is copied back as it was. An entry that is
+ * already gone writes nothing. Errors name the entry, never a key.
+ */
+export declare function removeBrokerEntry(broker: BrokerPort, input: {
+    name: string;
+    organizationId: string;
+}): Promise<boolean>;

package/dist/plan/broker-entries.js

@@ -373,3 +373,32 @@ export async function writeBrokerEntry(broker, input) {
         replaced: replaced.length > 0 ? JSON.stringify(replaced) : null,
     };
 }
+/**
+ * Takes one entry (and so its key) out of the broker's `AUTH_APPS`, matched by name and organisation, and
+ * deploys the broker when the list changed. Every other entry is copied back as it was. An entry that is
+ * already gone writes nothing. Errors name the entry, never a key.
+ */
+export async function removeBrokerEntry(broker, input) {
+    const label = `broker entry '${input.name}'`;
+    const env = (await broker.listEnvs()).find((e) => e.key === 'AUTH_APPS' && !e.is_preview);
+    if (!env?.value)
+        return false;
+    let parsed;
+    try {
+        parsed = JSON.parse(env.value);
+    }
+    catch {
+        throw new Error(`${label}: the broker's AUTH_APPS is not JSON, so nothing was removed`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error(`${label}: the broker's AUTH_APPS is not a JSON array, so nothing was removed`);
+    }
+    const next = parsed.filter((entry) => !(isObject(entry) &&
+        entry.name === input.name &&
+        entry.organizationId === input.organizationId));
+    if (next.length === parsed.length)
+        return false;
+    await broker.setAuthApps(JSON.stringify(next));
+    await broker.deploy();
+    return true;
+}

package/dist/plan/deploy-health.js

@@ -142,10 +142,17 @@ async function matchesHealth(fetchImpl, health) {
         const response = await fetchImpl(health.url, {
             signal: AbortSignal.timeout(HEALTH_REQUEST_TIMEOUT_MS),
         });
-        if (!response.ok)
+        if (!response.ok) {
+            // #760: an unread body left undici's parser paused when the socket
+            // ended, throwing an uncaught assertion in the host. Every answer this
+            // function does not go on to consume gets cancelled here.
+            await response.body?.cancel();
             return false;
-        if (health.kind === 'ready')
+        }
+        if (health.kind === 'ready') {
+            await response.body?.cancel();
             return true;
+        }
         const body = await response.json().catch(() => undefined);
         const value = body && typeof body === 'object'
             ? body[health.field ?? 'version']

package/dist/plan/desktop-callback.js

@@ -1,6 +1,7 @@
 import { agoraHostnameFor } from './agora.js';
 import { bouleHostnameFor } from './boule.js';
 import { appHostname, cmsStudioHostnameFor, entryHostnames } from './hostnames.js';
+import { kosmosHostnameFor } from './kosmos.js';
 import { workspaceAuthEntryOf, workspaceClientHosts } from './workspace-client.js';
 /**
  * #339: the desktop app signs in through the company's web app, so every
@@ -36,7 +37,9 @@ export function signInRedirectUris(org, appKey) {
                     ? cmsStudioHostnameFor(org)
                     : appKey === 'boule'
                         ? bouleHostnameFor(org)
-                        : appHostname(org),
+                        : appKey === 'kosmos'
+                            ? kosmosHostnameFor(org)
+                            : appHostname(org),
             ];
     return [
         ...hosts.map((host) => `https://${host}/auth/callback`),

package/dist/plan/diff.d.ts

@@ -150,6 +150,11 @@ export interface PlanOrgOptions {
     blueGreenServers?: readonly BlueGreenServer[];
     /** The company's stage mail sink is recorded and its live app is stopped or gone. */
     stageSinkDown?: boolean;
+    /** Which stage-guard ports the host has ({@link PlanBlueGreenInput.stageGuardPorts}). */
+    stageGuardPorts?: {
+        probes: boolean;
+        access: boolean;
+    };
 }
 export interface PlanDetail {
     orgId: OrgId;