@wtfalch/foundry 0.4.0 → 0.5.0

package/dist/plan/agora.d.ts

@@ -0,0 +1,77 @@
+import type { DeclaredOrg, OrgId } from '../org.js';
+/**
+ * #164: what both the planner (`diff.ts`) and the executor (`executor.ts`)
+ * need to agree on for an org's Agora -- the hostname, the values the host
+ * supplies, and the env vars those produce -- so the plan can compare the
+ * live app with exactly what the executor would write.
+ */
+/**
+ * `AppliedState.serviceIds` scope keys `desiredAgoraEnv` reads:
+ * `zitadel_org` is `executor.ts`'s `ensureZitadelProject`/`zitadelIssuer`
+ * scope id, `agora_client_id` the fixed `agora` ZITADEL client's `clientId`
+ * (recorded by `executor.ts`'s `zitadelApp`).
+ */
+export declare const ZITADEL_ORG_SCOPE_KEY = "zitadel_org";
+export declare const AGORA_CLIENT_ID_SCOPE_KEY = "agora_client_id";
+/**
+ * The accent every org's Agora wears until orgs choose their own: the house
+ * theme's `--accent` (`@wtfalch/house`, `HOUSE_THEMES['good-company']` in
+ * `design/packages/house/src/themes.ts`, the default theme
+ * `HOUSE_DEFAULT_THEME`). Agora's config parser requires `theme.accent` as a
+ * hex colour (`agora/apps/agora/src/agoras.ts`). Restated here rather than
+ * imported: `packages/foundry` carries no `@wtfalch/house` dependency.
+ */
+export declare const AGORA_THEME_ACCENT = "#B23A0C";
+/**
+ * Provider-side values only the host can supply, like every other provider
+ * value `FoundryStepExecutorPorts` carries. As of #177, `plan-apply.ts`'s
+ * `FoundryPlanApply` derives these itself from the applied platform
+ * (`platform-org.ts`'s `agoraHostValuesFromPlatform`) whenever a host wires
+ * one in and supplies no `AgoraHostPort` of its own -- an explicit `agora`
+ * port still overrides that, unchanged. `null` means the value is not
+ * available yet. The first three are required by Agora's config parser
+ * (`agoras.ts`: `issuer`, `mailProjectId`, `messagingProjectId`);
+ * `mailUpstream`/`filesUpstream` are the mail/files servers' internal
+ * addresses, optional -- unset, `AGORA_MAIL_UPSTREAM`/`AGORA_FILES_UPSTREAM`
+ * are not pushed and Agora answers 502 on those routes rather than serving
+ * anything wrong (`executor.ts`'s `coolifyAgora` doc comment).
+ */
+export interface AgoraHostValues {
+    issuer: string | null;
+    mailProjectId: string | null;
+    messagingProjectId: string | null;
+    mailUpstream: string | null;
+    filesUpstream: string | null;
+}
+export interface AgoraHostPort {
+    valuesFor(orgId: OrgId): Promise<AgoraHostValues>;
+}
+/** No host values at all: what an absent port means. */
+export declare const NO_AGORA_HOST_VALUES: AgoraHostValues;
+/** What the plan reads from the host: its values, or why it could not get them. */
+export type AgoraHostReading = AgoraHostValues | {
+    error: string;
+};
+/** Reads the port once for a plan. An absent port, or one that throws, is a blocked Agora, never a failed plan. */
+export declare function readAgoraHost(port: AgoraHostPort | undefined, orgId: OrgId): Promise<AgoraHostReading>;
+/** The host values Agora cannot be configured without, by name -- the ones `host` lacks. */
+export declare function agoraHostMissing(host: AgoraHostValues): string[];
+/**
+ * `agora.<domain>` when the org has a domain, `<slug>-agora.oikos.host`
+ * otherwise (the 2026-09-24 layout, foundry#14; `../slug.ts`'s
+ * `AGORA_SUFFIX` reserves the collision).
+ */
+export declare function agoraHostnameFor(org: DeclaredOrg): string;
+/**
+ * The env vars an org's Agora app should carry, and every input still
+ * missing to build them. `AGORA_CONFIG` is present only when `missing` is
+ * empty; callers that write must refuse on a non-empty `missing`.
+ * `AGORA_MAIL_UPSTREAM` is present only when mail is on and the host supplies
+ * an address.
+ */
+export declare function desiredAgoraEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, host: AgoraHostValues): {
+    env: Record<string, string>;
+    missing: string[];
+};
+/** The desired env keys the live app lacks or holds a different value for. Extra live keys are ignored. */
+export declare function agoraEnvDrift(desired: Readonly<Record<string, string>>, live: Readonly<Record<string, string>>): string[];

package/dist/plan/agora.js

@@ -0,0 +1,127 @@
+/**
+ * #164: what both the planner (`diff.ts`) and the executor (`executor.ts`)
+ * need to agree on for an org's Agora -- the hostname, the values the host
+ * supplies, and the env vars those produce -- so the plan can compare the
+ * live app with exactly what the executor would write.
+ */
+/**
+ * `AppliedState.serviceIds` scope keys `desiredAgoraEnv` reads:
+ * `zitadel_org` is `executor.ts`'s `ensureZitadelProject`/`zitadelIssuer`
+ * scope id, `agora_client_id` the fixed `agora` ZITADEL client's `clientId`
+ * (recorded by `executor.ts`'s `zitadelApp`).
+ */
+export const ZITADEL_ORG_SCOPE_KEY = 'zitadel_org';
+export const AGORA_CLIENT_ID_SCOPE_KEY = 'agora_client_id';
+/**
+ * The accent every org's Agora wears until orgs choose their own: the house
+ * theme's `--accent` (`@wtfalch/house`, `HOUSE_THEMES['good-company']` in
+ * `design/packages/house/src/themes.ts`, the default theme
+ * `HOUSE_DEFAULT_THEME`). Agora's config parser requires `theme.accent` as a
+ * hex colour (`agora/apps/agora/src/agoras.ts`). Restated here rather than
+ * imported: `packages/foundry` carries no `@wtfalch/house` dependency.
+ */
+export const AGORA_THEME_ACCENT = '#B23A0C';
+/** No host values at all: what an absent port means. */
+export const NO_AGORA_HOST_VALUES = {
+    issuer: null,
+    mailProjectId: null,
+    messagingProjectId: null,
+    mailUpstream: null,
+    filesUpstream: null,
+};
+/** Reads the port once for a plan. An absent port, or one that throws, is a blocked Agora, never a failed plan. */
+export async function readAgoraHost(port, orgId) {
+    if (!port)
+        return NO_AGORA_HOST_VALUES;
+    try {
+        return await port.valuesFor(orgId);
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** The host values Agora cannot be configured without, by name -- the ones `host` lacks. */
+export function agoraHostMissing(host) {
+    const missing = [];
+    if (!host.issuer)
+        missing.push('issuer');
+    if (!host.mailProjectId)
+        missing.push('mailProjectId');
+    if (!host.messagingProjectId)
+        missing.push('messagingProjectId');
+    return missing;
+}
+/**
+ * `agora.<domain>` when the org has a domain, `<slug>-agora.oikos.host`
+ * otherwise (the 2026-09-24 layout, foundry#14; `../slug.ts`'s
+ * `AGORA_SUFFIX` reserves the collision).
+ */
+export function agoraHostnameFor(org) {
+    return org.domain ? `agora.${org.domain}` : `${org.slug}-agora.oikos.host`;
+}
+/**
+ * The env vars an org's Agora app should carry, and every input still
+ * missing to build them. `AGORA_CONFIG` is present only when `missing` is
+ * empty; callers that write must refuse on a non-empty `missing`.
+ * `AGORA_MAIL_UPSTREAM` is present only when mail is on and the host supplies
+ * an address.
+ */
+export function desiredAgoraEnv(org, recorded, host) {
+    const env = { AGORA_CANONICAL_HOST: agoraHostnameFor(org) };
+    const zitadelOrgId = recorded[ZITADEL_ORG_SCOPE_KEY];
+    const clientId = recorded[AGORA_CLIENT_ID_SCOPE_KEY];
+    const missing = [];
+    if (!zitadelOrgId)
+        missing.push('zitadelOrgId');
+    if (!clientId)
+        missing.push('clientId');
+    missing.push(...agoraHostMissing(host));
+    if (missing.length === 0) {
+        env.AGORA_CONFIG = JSON.stringify({
+            name: org.displayName,
+            theme: { accent: AGORA_THEME_ACCENT },
+            issuer: host.issuer,
+            clientId,
+            organisationId: zitadelOrgId,
+            mailProjectId: host.mailProjectId,
+            messagingProjectId: host.messagingProjectId,
+        });
+    }
+    if (org.mail.mode !== 'off' && host.mailUpstream) {
+        env.AGORA_MAIL_UPSTREAM = host.mailUpstream;
+    }
+    // Files is always on for every org (#80), unlike mail -- no mode to gate
+    // this on, only whether the host supplies an address at all (#177).
+    if (host.filesUpstream) {
+        env.AGORA_FILES_UPSTREAM = host.filesUpstream;
+    }
+    return { env, missing };
+}
+function stable(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stable).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const entries = Object.entries(value).sort(([a], [b]) => a < b ? -1 : 1);
+        return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stable(v)}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function sameEnvValue(key, desired, live) {
+    if (key !== 'AGORA_CONFIG')
+        return desired === live;
+    try {
+        return stable(JSON.parse(desired)) === stable(JSON.parse(live));
+    }
+    catch {
+        return false;
+    }
+}
+/** The desired env keys the live app lacks or holds a different value for. Extra live keys are ignored. */
+export function agoraEnvDrift(desired, live) {
+    return Object.entries(desired)
+        .filter(([key, value]) => {
+        const liveValue = live[key];
+        return liveValue === undefined || !sameEnvValue(key, value, liveValue);
+    })
+        .map(([key]) => key);
+}

package/dist/plan/cloudflared-connector.d.ts

@@ -0,0 +1,70 @@
+import type { CloudflarePort, CoolifyPort } from './executor.js';
+/**
+ * #197: the pinned `cloudflared` image, the same release tag as
+ * `scripts/shared-ingress.mjs`'s and `calls-sfu.ts`'s own
+ * `CLOUDFLARED_IMAGE_REF`. A test in each keeps the three equal.
+ */
+export declare const CLOUDFLARED_IMAGE_REF = "cloudflare/cloudflared:2026.9.3";
+/**
+ * The inline Dockerfile a docker-image `cloudflared` app needs, copied from
+ * `scripts/shared-ingress.mjs`'s `cloudflaredDockerfile()`: the published
+ * image's own `CMD` is `version`, and Coolify's `start_command` is ignored
+ * for image-based applications, so the run command has to be stated in a
+ * Dockerfile's `CMD` instead. `TUNNEL_TOKEN` is never baked in here; it
+ * reaches the container only via `bulkUpsertEnvs`, as an environment
+ * variable `cloudflared` reads at boot.
+ */
+export declare function cloudflaredDockerfile(): string;
+/**
+ * #197: ensure one `cloudflared` connector app exists in Coolify for a
+ * tunnel, with the current token, deployed if needed. Decision: one connector
+ * per platform tunnel, so each tunnel-owning platform step (auth, mail,
+ * archon) calls this once with its own app name and scope key.
+ */
+export interface EnsureCloudflaredConnectorInput {
+    coolify: Pick<CoolifyPort, 'findApplicationByName' | 'getApplication' | 'createDockerfileApplication' | 'bulkUpsertEnvs' | 'listEnvs' | 'deploy'>;
+    cloudflare: Pick<CloudflarePort, 'getTunnelToken'>;
+    /** The Cloudflare tunnel this connector dials into (already created and configured by the caller). */
+    tunnelId: string;
+    /** Fixed name, found before created -- so a second apply reuses this app rather than making a second one. */
+    appName: string;
+    projectUuid: string;
+    environment: {
+        id: number;
+        name: string;
+        uuid: string;
+    };
+    /** Called only when the app must be created -- never on the found-by-name or found-by-id paths. */
+    resolveServer: () => Promise<{
+        uuid: string;
+    }>;
+    /**
+     * The app's uuid from a prior run's recorded scope id, or `null`. When
+     * given, it is trusted over a by-name lookup, so a renamed or
+     * duplicate-named app never causes a second create. A recorded uuid whose
+     * app no longer exists (not found) falls through to find-by-name, then create.
+     */
+    recordedConnectorAppId: string | null;
+    /**
+     * Called with the app's uuid as soon as it is created or found by name,
+     * before the token fetch, env write and deploy. The caller records and
+     * persists it there, so a later failure never leaves an app nothing points at.
+     */
+    recordAppId: (appId: string) => Promise<void>;
+}
+/**
+ * Finds or creates the one Coolify app that runs `cloudflared` for
+ * {@link EnsureCloudflaredConnectorInput.tunnelId}, writes its tunnel token as
+ * `TUNNEL_TOKEN` (a literal env var) when the token is new or changed, and
+ * deploys it when it was just created, its token changed, or it is not
+ * explicitly running (a missing status counts as not running, so a run that
+ * failed after the env write is repaired by the next one). `CLAUDE.md` rule 4.
+ *
+ * The token is a credential (`CLAUDE.md` rule 6): it goes to `bulkUpsertEnvs`
+ * and nowhere else. A failed write throws an error that names the app only,
+ * with no cause, because a Coolify error can echo the request body.
+ */
+export declare function ensureCloudflaredConnector(input: EnsureCloudflaredConnectorInput): Promise<{
+    appId: string;
+    deployed: boolean;
+}>;

package/dist/plan/cloudflared-connector.js

@@ -0,0 +1,106 @@
+import { isNotFoundError } from './executor.js';
+/**
+ * #197: the pinned `cloudflared` image, the same release tag as
+ * `scripts/shared-ingress.mjs`'s and `calls-sfu.ts`'s own
+ * `CLOUDFLARED_IMAGE_REF`. A test in each keeps the three equal.
+ */
+export const CLOUDFLARED_IMAGE_REF = 'cloudflare/cloudflared:2026.9.3';
+/**
+ * The inline Dockerfile a docker-image `cloudflared` app needs, copied from
+ * `scripts/shared-ingress.mjs`'s `cloudflaredDockerfile()`: the published
+ * image's own `CMD` is `version`, and Coolify's `start_command` is ignored
+ * for image-based applications, so the run command has to be stated in a
+ * Dockerfile's `CMD` instead. `TUNNEL_TOKEN` is never baked in here; it
+ * reaches the container only via `bulkUpsertEnvs`, as an environment
+ * variable `cloudflared` reads at boot.
+ */
+export function cloudflaredDockerfile() {
+    return `FROM ${CLOUDFLARED_IMAGE_REF}\nCMD ["tunnel", "--no-autoupdate", "run"]\n`;
+}
+/**
+ * Finds or creates the one Coolify app that runs `cloudflared` for
+ * {@link EnsureCloudflaredConnectorInput.tunnelId}, writes its tunnel token as
+ * `TUNNEL_TOKEN` (a literal env var) when the token is new or changed, and
+ * deploys it when it was just created, its token changed, or it is not
+ * explicitly running (a missing status counts as not running, so a run that
+ * failed after the env write is repaired by the next one). `CLAUDE.md` rule 4.
+ *
+ * The token is a credential (`CLAUDE.md` rule 6): it goes to `bulkUpsertEnvs`
+ * and nowhere else. A failed write throws an error that names the app only,
+ * with no cause, because a Coolify error can echo the request body.
+ */
+export async function ensureCloudflaredConnector(input) {
+    const { coolify, cloudflare } = input;
+    const liveStatus = async (uuid) => {
+        try {
+            return { found: true, status: (await coolify.getApplication(uuid)).status };
+        }
+        catch (error) {
+            if (isNotFoundError(error))
+                return { found: false };
+            throw error;
+        }
+    };
+    let appId = null;
+    let status;
+    let justCreated = false;
+    if (input.recordedConnectorAppId) {
+        const live = await liveStatus(input.recordedConnectorAppId);
+        if (live.found) {
+            appId = input.recordedConnectorAppId;
+            status = live.status;
+        }
+    }
+    if (!appId) {
+        const found = await coolify.findApplicationByName(input.appName, {
+            environmentIds: [input.environment.id],
+        });
+        if (found) {
+            const live = await liveStatus(found.uuid);
+            if (live.found) {
+                appId = found.uuid;
+                status = live.status;
+            }
+        }
+    }
+    if (!appId) {
+        const server = await input.resolveServer();
+        const created = await coolify.createDockerfileApplication({
+            project_uuid: input.projectUuid,
+            server_uuid: server.uuid,
+            environment_name: input.environment.name,
+            environment_uuid: input.environment.uuid,
+            dockerfile: cloudflaredDockerfile(),
+            name: input.appName,
+            description: 'cloudflared connector for this platform tunnel (#197)',
+            instant_deploy: false,
+        });
+        appId = created.uuid;
+        justCreated = true;
+    }
+    if (appId !== input.recordedConnectorAppId)
+        await input.recordAppId(appId);
+    const token = await cloudflare.getTunnelToken(input.tunnelId);
+    const tokenChanged = justCreated || (await tunnelTokenDiffers(coolify, appId, token));
+    if (tokenChanged) {
+        try {
+            await coolify.bulkUpsertEnvs(appId, [{ key: 'TUNNEL_TOKEN', value: token, literal: true }]);
+        }
+        catch {
+            throw new Error(`cloudflared connector ${input.appName}: writing TUNNEL_TOKEN failed`);
+        }
+    }
+    // Only a connector that is up or on its way up is left alone; a missing,
+    // stopped, crash-looping or degraded one is deployed.
+    const upOrStarting = Boolean(status?.startsWith('running') || status?.startsWith('starting'));
+    const deployed = justCreated || tokenChanged || !upOrStarting;
+    if (deployed) {
+        await coolify.deploy(appId);
+    }
+    return { appId, deployed };
+}
+/** Whether the app's live `TUNNEL_TOKEN` is missing or differs from the token just fetched. */
+async function tunnelTokenDiffers(coolify, appId, token) {
+    const live = (await coolify.listEnvs(appId)).find((e) => e.key === 'TUNNEL_TOKEN' && !e.is_preview);
+    return !live || live.value !== token;
+}

package/dist/plan/diff.d.ts

@@ -1,6 +1,8 @@
 import type { DeclaredOrg, OrgId } from '../org.js';
 import type { Plan, PlanStep, UnmanagedItem } from '../plan.js';
+import { type AgoraHostReading } from './agora.js';
 import type { LiveResource } from './live.js';
+import { type OrgPlatformReadiness } from './platform-org.js';
 /**
  * What a {@link StepExecutor} (see `plan-apply.ts`) needs to actually make a
  * step true, alongside the public {@link PlanStep} an operator reads.
@@ -60,12 +62,27 @@ export declare function toPlan(detail: PlanDetail): Plan;
  * by default unlike chat's own: {@link planCalls}, the org's own calls
  * Matrix stack (`org.ts`'s `CallsConfig.enabled`). #145 adds one more,
  * planned right after it and gated on the same flag: {@link planCallsService},
- * the calls service itself (`wtfalch/calls`'s `packages/service`). Everything
- * else in `live` that none of these fifteen singletons and however many
+ * the calls service itself (`wtfalch/calls`'s `packages/service`). #164 adds
+ * two more, unconditionally -- no `DeclaredOrg` field gates either, since
+ * every org's own Agora is always on: {@link planAgoraClient}, a fixed
+ * ZITADEL web client named `agora` (modeled on {@link planCmsClient}), and
+ * {@link planAgora}, the Agora itself as a Coolify app (modeled on
+ * {@link planSite}, minus the park branch -- foundry never deletes an
+ * Agora). #173 adds one more, gated on `org.hosting.enabled` like
+ * {@link planApp} itself: {@link planJobsRegistration}, registering the org's
+ * app with the platform's jobs scheduler, idempotent on the *recorded*
+ * resource id like {@link planOwner} rather than a live resource, since
+ * nothing in `live` can report a scheduler registration (no reader exists for
+ * it). Everything
+ * else in `live` that none of these eighteen singletons and however many
  * declared issuer apps claim is unmanaged. The full field-by-field provisioning surface (SSO,
  * guests, calls on the org's own domain, 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 declare function computePlanDetail(org: DeclaredOrg, live: LiveResource[], recordedIds?: Readonly<Record<string, string>>): PlanDetail;
+export declare function computePlanDetail(org: DeclaredOrg, live: LiveResource[], recordedIds?: Readonly<Record<string, string>>, agoraHost?: AgoraHostReading, jobsAvailable?: boolean, platformReadiness?: OrgPlatformReadiness): PlanDetail;
+/** Restated from `executor.ts`, the same rule: the id of an ai key minted but not delivered. */
+export declare const AI_KEY_UNDELIVERED_SCOPE_KEY = "ai_key_undelivered";
+/** Restated from `executor.ts`, the same rule: the id of a jobs project registered but not delivered. */
+export declare const JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY = "jobs_registration_undelivered";