@wtfalch/foundry 0.66.0 → 0.68.0

package/dist/plan/diff.js

@@ -3,6 +3,8 @@ import { NATIVE_BUILD_KEY_ENV } from '../native-build.js';
 import { APP_ENTRY_KEY, ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, appsOn, companyGithubFor, heldEnvRef, kosmosOn, mainEntry, ownerMailboxRecorded, ownerMailboxes, ownerNameProblem, ownsServices, } from '../org.js';
 import { entryHasDatabase } from '../worker-app-config.js';
 import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_DEPLOYED_SCOPE_KEY, CHAT_CALLS_APPLIED_SCOPE_KEY, CHAT_CALLS_TOKEN_SCOPE_KEY, CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, NO_AGORA_HOST_VALUES, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostMissing, agoraHostnameFor, callsServiceHasName, callsServiceHasTokenEnv, callsTokenEnvMovedMessage, callsTokenHostFrom, chatCallsApplied, chatHasUpstreams, desiredAgoraEnv, entryClientIdScopeKey, withRecordedMessagingProject, } from './agora.js';
+import { planAnalyticsBoule } from './analytics-boule.js';
+import { analyticsEnvDrift, analyticsWanted, desiredAnalyticsEnv } from './analytics.js';
 import { planAppsDbRoute } from './apps-db-route.js';
 import { planAppsZones } from './apps-zones.js';
 import { bgKey, planBlueGreen, } from './blue-green.js';
@@ -16,6 +18,7 @@ import { DESKTOP_AUTH_HOME, planDesktopAuth } from './desktop-auth.js';
 import { planDesktopCallbacks } from './desktop-callback.js';
 import { onPlatformNetwork } from './destinations.js';
 import { planEntryAiKeys } from './entry-ai-key.js';
+import { planEntryAnalyticsKeys } from './entry-analytics-key.js';
 import { planEntryAudit } from './entry-audit.js';
 import { CUSTOMER_GRANTS_ENV, CUSTOMER_GRANTS_WRITTEN_SCOPE_KEY, customerGrantsEntries, customerGrantsShapeMatches, customerGrantsToDrop, wantedCustomerGrants, } from './entry-customer-grants.js';
 import { planEdgeReservedLabels, planEdgeSlug, planEntryEdgeKeys } from './entry-edge-key.js';
@@ -568,6 +571,7 @@ export function computePlanDetail(declaredOrg, live, recordedIds = {}, agoraHost
         servers: options.blueGreenServers,
         canHoldSecrets: platformReadiness.canHoldSecrets === true,
         accessProviderId: platformReadiness.accessProviderId ?? null,
+        ownerOrgId: platformReadiness.platformOwnerOrgId,
         ...(options.stageSinkDown ? { stageSinkDown: true } : {}),
         ...(options.stageGuardPorts ? { stageGuardPorts: options.stageGuardPorts } : {}),
         appPlanned: (entryKey) => plannedSteps.some((p) => p.action.system === 'coolify' &&
@@ -723,6 +727,14 @@ export function computePlanDetail(declaredOrg, live, recordedIds = {}, agoraHost
     const kosmos = planKosmos(org, byKey, claimed, recordedIds, authIssuer, options.otherSlugs ?? []);
     if (kosmos.step)
         plannedSteps.push(kosmos.step);
+    // The company's analytics backend, only while something uses it (an entry's `uses.analytics`, or Boule's
+    // apps); never parked once made. Before the site keys and Boule's env, which need its operator key.
+    const analytics = planAnalyticsBackend(org, byKey, claimed, recordedIds, options.otherSlugs ?? []);
+    if (analytics.step)
+        plannedSteps.push(analytics.step);
+    plannedSteps.push(...planAnalyticsBoule(org, recordedIds, plannedSteps));
+    const entryAnalyticsKeys = planEntryAnalyticsKeys(org, recordedIds, plannedSteps, options.analyticsPort ?? false);
+    plannedSteps.push(...entryAnalyticsKeys.steps);
     // Boule's, Agora's and kosmos's blue/green: after their own steps, which make the app it copies.
     plannedSteps.push(...blueGreen.steps.filter((x) => x.phase === 'last').map(blueGreenDraft()));
     // Boule owners, after the Boule step: needs the app deployed and the seeding secret in its env.
@@ -995,6 +1007,9 @@ export function computePlanDetail(declaredOrg, live, recordedIds = {}, agoraHost
     }
     if (kosmos.blocked)
         unmanaged.push({ description: kosmos.blocked, key: 'coolify:kosmos' });
+    if (analytics.blocked)
+        unmanaged.push({ description: analytics.blocked, key: 'coolify:analytics' });
+    unmanaged.push(...entryAnalyticsKeys.blocked);
     // Same for an ai key minted but never delivered: planning a new mint would
     // orphan a second live key.
     if (aiKey.blocked)
@@ -3212,6 +3227,78 @@ function planKosmos(org, byKey, claimed, recordedIds, issuer, otherSlugs) {
         blocked: null,
     };
 }
+/**
+ * The company's analytics backend: a per-org singleton keyed by the org id under its own `analytics` kind, built
+ * from https://github.com/wtfalch/analytics's root Dockerfile (`executor.ts`'s `coolifyAnalytics`) with a
+ * database of its own. Planned only while `analyticsWanted(org)`; once live it is kept and never parked. A live
+ * app is planned again when its `APP_URL` or `AUTH_ORGANIZATION_ID` is missing or different. It needs no
+ * sign-in client and no issuer; only the company's sign-in organisation id (recorded by an earlier step).
+ */
+function planAnalyticsBackend(org, byKey, claimed, recordedIds, otherSlugs) {
+    const key = resourceKey('coolify', 'analytics', org.id);
+    const live = byKey.get(key);
+    if (live)
+        claimed.add(key);
+    if (!analyticsWanted(org))
+        return { step: null, blocked: null };
+    const tooLong = [
+        [`${org.slug}-analytics`, 'the analytics host label and app name'],
+        [`${org.slug}_analytics_db_rt`, 'the analytics database role'],
+    ].filter(([name]) => name.length > 63);
+    if (tooLong.length > 0) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s analytics backend is blocked, not planned: ${tooLong.map(([n, what]) => `${what} '${n}' is over 63 characters`).join(', ')}; shorten the slug`,
+        };
+    }
+    if (otherSlugs.includes(`${org.slug}-analytics`)) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s analytics backend is blocked, not planned: another declared org has the slug '${org.slug}-analytics', which is this backend's hostname`,
+        };
+    }
+    // `coolifyAnalytics` writes nothing without the sign-in organisation, so the step waits for it here.
+    const { env, missing } = desiredAnalyticsEnv(org, recordedIds);
+    if (missing.length > 0) {
+        return {
+            step: null,
+            blocked: `${org.slug}'s analytics backend is blocked, not planned: the company's sign-in organisation is not recorded yet`,
+        };
+    }
+    const action = {
+        system: 'coolify',
+        kind: 'analytics',
+        key: org.id,
+        desired: {},
+    };
+    if (!live) {
+        return {
+            step: {
+                action,
+                step: {
+                    description: `provision ${org.slug}'s analytics backend`,
+                    destroys: false,
+                    migrates: false,
+                },
+            },
+            blocked: null,
+        };
+    }
+    const drift = analyticsEnvDrift(env, (live.config.env ?? {}));
+    if (drift.length === 0)
+        return { step: null, blocked: null };
+    return {
+        step: {
+            action,
+            step: {
+                description: `update ${org.slug}'s analytics backend config (${drift.join(', ')} missing or different)`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: null,
+    };
+}
 /**
  * C3: which credentials the org's Boule is given, and why one is not. Archon's credential goes to every
  * Boule the host can mint it for; the customers directory credential only while `customers.enabled`. Each

package/dist/plan/entry-analytics-key.d.ts

@@ -0,0 +1,35 @@
+import type { DeclaredOrg } from '../org.js';
+import type { DraftStep } from './diff.js';
+/**
+ * `uses.analytics` on a server entry: one site key of its own at the company's analytics backend, minted
+ * through `POST /v1/site-keys` with the operator key and written as `ANALYTICS_URL` and `ANALYTICS_SITE_KEY` to
+ * the entry's env. The backend shows the secret once, so this follows rule 1 of CLAUDE.md "Platform steps":
+ *
+ * 1. the key's id is recorded as `analytics_key_undelivered.<entry>` and persisted before the env is written;
+ * 2. the env write is tried 3 times with the same secret; the id is the main id `analytics:key:<orgId>:<entry>`
+ *    and the applied marker only after it worked, and the undelivered marker is cleared then;
+ * 3. a marker left behind (every try failed) is reported blocked and never minted again.
+ *
+ * A Worker app entry is skipped: Boule installs its keys per copy. The entry's stage gets its own key through
+ * `plan/stage-services.ts` (service `analytics`, environment `stage`), so the two differ. Removing
+ * `uses.analytics` or the entry plans the retire form: revoke the key, take both env names away.
+ */
+export declare const entryAnalyticsUndeliveredScopeKey: (entryKey: string) => string;
+/** The address the entry's env was last written with; a change rewrites the address only. */
+export declare const entryAnalyticsAppliedScopeKey: (entryKey: string) => string;
+/** The id of a key that was revoked, so a stale main id is not revoked again. */
+export declare const entryAnalyticsRetiredScopeKey: (entryKey: string) => string;
+export declare const ENTRY_ANALYTICS_KEY_DELIVERY_ATTEMPTS = 3;
+/** The name the backend knows the key by; its site derives from it. */
+export declare const entryAnalyticsKeyName: (org: Pick<DeclaredOrg, "slug">, entryKey: string) => string;
+/** The stage copy's key name: the backend reads the `-stage` suffix as the stage environment. */
+export declare const stageAnalyticsKeyName: (org: Pick<DeclaredOrg, "slug">, entryKey: string) => string;
+type Blocked = Array<{
+    description: string;
+    key: string;
+}>;
+export declare function planEntryAnalyticsKeys(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], analyticsPort: boolean): {
+    steps: DraftStep[];
+    blocked: Blocked;
+};
+export {};

package/dist/plan/entry-analytics-key.js

@@ -0,0 +1,134 @@
+import { analyticsUrlFor } from './analytics.js';
+import { appStepKey } from './platform-diff.js';
+/**
+ * `uses.analytics` on a server entry: one site key of its own at the company's analytics backend, minted
+ * through `POST /v1/site-keys` with the operator key and written as `ANALYTICS_URL` and `ANALYTICS_SITE_KEY` to
+ * the entry's env. The backend shows the secret once, so this follows rule 1 of CLAUDE.md "Platform steps":
+ *
+ * 1. the key's id is recorded as `analytics_key_undelivered.<entry>` and persisted before the env is written;
+ * 2. the env write is tried 3 times with the same secret; the id is the main id `analytics:key:<orgId>:<entry>`
+ *    and the applied marker only after it worked, and the undelivered marker is cleared then;
+ * 3. a marker left behind (every try failed) is reported blocked and never minted again.
+ *
+ * A Worker app entry is skipped: Boule installs its keys per copy. The entry's stage gets its own key through
+ * `plan/stage-services.ts` (service `analytics`, environment `stage`), so the two differ. Removing
+ * `uses.analytics` or the entry plans the retire form: revoke the key, take both env names away.
+ */
+export const entryAnalyticsUndeliveredScopeKey = (entryKey) => `analytics_key_undelivered.${entryKey}`;
+/** The address the entry's env was last written with; a change rewrites the address only. */
+export const entryAnalyticsAppliedScopeKey = (entryKey) => `analytics_key_applied.${entryKey}`;
+/** The id of a key that was revoked, so a stale main id is not revoked again. */
+export const entryAnalyticsRetiredScopeKey = (entryKey) => `analytics_key_retired.${entryKey}`;
+export const ENTRY_ANALYTICS_KEY_DELIVERY_ATTEMPTS = 3;
+/** The name the backend knows the key by; its site derives from it. */
+export const entryAnalyticsKeyName = (org, entryKey) => `${org.slug}-${entryKey}-analytics`;
+/** The stage copy's key name: the backend reads the `-stage` suffix as the stage environment. */
+export const stageAnalyticsKeyName = (org, entryKey) => `${org.slug}-${entryKey}-stage-analytics`;
+const servesKey = (entry) => entry.uses?.analytics === true && !entry.workerApp && entry.live !== false;
+export function planEntryAnalyticsKeys(org, recordedIds, plannedSteps, analyticsPort) {
+    const steps = [];
+    const blocked = [];
+    if (!org.hosting.enabled)
+        return { steps, blocked };
+    const planned = (system, kind, key) => plannedSteps.some((p) => p.action.system === system && p.action.kind === kind && p.action.key === key);
+    const wanted = new Map(org.hosting.entries.filter(servesKey).map((e) => [e.key, e]));
+    const mainPrefix = `analytics:key:${org.id}:`;
+    // Keys whose entry stopped using analytics or is gone: a delivered key (main id) or one minted and never
+    // delivered (undelivered marker), so the retire clears the marker and the entry can mint again later.
+    const undeliveredPrefix = entryAnalyticsUndeliveredScopeKey('');
+    const retiring = new Set();
+    for (const [name, id] of Object.entries(recordedIds)) {
+        if (!id)
+            continue;
+        const prefix = name.startsWith(mainPrefix)
+            ? mainPrefix
+            : name.startsWith(undeliveredPrefix)
+                ? undeliveredPrefix
+                : null;
+        if (!prefix)
+            continue;
+        const entryKey = name.slice(prefix.length);
+        if (wanted.has(entryKey) ||
+            retiring.has(entryKey) ||
+            recordedIds[entryAnalyticsRetiredScopeKey(entryKey)] === id) {
+            continue;
+        }
+        retiring.add(entryKey);
+        const key = `${mainPrefix}${entryKey}`;
+        if (!analyticsPort) {
+            blocked.push({
+                description: `${org.slug}'s ${entryKey} analytics key is not revoked, not planned: the host supplies no analytics port`,
+                key,
+            });
+        }
+        else if (!recordedIds[`coolify:analytics:${org.id}`]) {
+            blocked.push({
+                description: `${org.slug}'s ${entryKey} analytics key is not revoked, not planned: the analytics backend is not recorded`,
+                key,
+            });
+        }
+        else {
+            steps.push({
+                action: {
+                    system: 'analytics',
+                    kind: 'key',
+                    key: `${org.id}:${entryKey}`,
+                    desired: { mode: 'retire' },
+                },
+                step: {
+                    description: `revoke ${org.slug}'s ${entryKey} analytics key and take ANALYTICS_* out of its env: the entry no longer uses analytics`,
+                    destroys: true,
+                    migrates: false,
+                },
+            });
+        }
+    }
+    for (const entry of wanted.values()) {
+        const stepKey = appStepKey(org, entry.key);
+        const key = `analytics:key:${stepKey}`;
+        const at = `${org.slug}'s ${entry.key} analytics key`;
+        const block = (why) => blocked.push({ description: `${at} is blocked: ${why}`, key });
+        const url = analyticsUrlFor(org);
+        const undelivered = recordedIds[entryAnalyticsUndeliveredScopeKey(entry.key)];
+        if (undelivered) {
+            block(`key ${undelivered} was minted but never written to the app, and the backend shows a key once; remove the recorded id ${entryAnalyticsUndeliveredScopeKey(entry.key)} to mint a new key, which replaces that one`);
+            continue;
+        }
+        const live = recordedIds[key] &&
+            recordedIds[entryAnalyticsRetiredScopeKey(entry.key)] !== recordedIds[key];
+        if (live && recordedIds[entryAnalyticsAppliedScopeKey(entry.key)] === url)
+            continue;
+        if (!analyticsPort) {
+            block('the host supplies no analytics port');
+            continue;
+        }
+        if (!recordedIds[`coolify:analytics:${org.id}`] && !planned('coolify', 'analytics', org.id)) {
+            block("the company's analytics backend is not recorded or planned yet");
+            continue;
+        }
+        if (!recordedIds[`coolify:app:${stepKey}`] && !planned('coolify', 'app', stepKey)) {
+            block("the entry's app is not recorded yet");
+            continue;
+        }
+        steps.push({
+            action: {
+                system: 'analytics',
+                kind: 'key',
+                key: stepKey,
+                desired: {
+                    mode: live ? 'url' : 'mint',
+                    name: entryAnalyticsKeyName(org, entry.key),
+                    analyticsUrl: url,
+                },
+            },
+            step: {
+                description: live
+                    ? `write the analytics address to ${org.slug}'s ${entry.key} env`
+                    : `mint ${at}, write ANALYTICS_URL and ANALYTICS_SITE_KEY to its env, restart the app`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    return { steps, blocked };
+}

package/dist/plan/executor.d.ts

@@ -2,6 +2,7 @@ import type { OrgMailOptions, OrgMailOrg, OrgMailResult } from '@wtfalch/email/p
 import { type CallsSfuUrls } from '../calls-sfu.js';
 import type { DeclaredOrg, HostingBuildPack, OrgId } from '../org.js';
 import type { DeclaredOrgStore } from '../store.js';
+import { type AnalyticsPort } from './analytics.js';
 import { type BlueGreenServer, type BlueGreenSubject } from './blue-green.js';
 import { type BouleOwnerSeed } from './boule.js';
 import { type BrokerPort } from './broker-entries.js';
@@ -1841,6 +1842,8 @@ export interface FoundryStepExecutorPorts {
     workerAppKeys?: KeysCustodyPort;
     /** F7: the keys service's per-company registrar. Without it the plan reports Boule's registrar key blocked (the host also sets `FoundryPlanApplyOptions.keysRegistrarUrl`). */
     keysRegistrar?: KeysRegistrarPort;
+    /** The company's analytics backend operator API: mints and revokes site keys. Without it the plan reports each `uses.analytics` key blocked (the host also sets `FoundryPlanApplyOptions.analyticsPort`). */
+    analytics?: AnalyticsPort;
     /**
      * C3: mints the credential an org's Boule reaches Archon with (org-scoped; `orgs:request` and
      * `orgs:read` for that org). Archon implements it. Every call rotates the credential (the old secret
@@ -2020,6 +2023,10 @@ export declare const BOULE_PORT = 3000;
 export declare const KOSMOS_REPO = "wtfalch/kosmos";
 export declare const KOSMOS_APP_DOCKERFILE = "/Dockerfile";
 export declare const KOSMOS_PORT = 3000;
+/** The company's analytics backend (https://github.com/wtfalch/analytics): root Dockerfile, serves on 3000, migrates in its own start script. */
+export declare const ANALYTICS_REPO = "wtfalch/analytics";
+export declare const ANALYTICS_APP_DOCKERFILE = "/Dockerfile";
+export declare const ANALYTICS_PORT = 3000;
 export declare const LOG_DIR = "/app/logs";
 /** The company's Coolify destination (its Docker network `co-<slug>`), recorded when its first resource is created. */
 export declare const COOLIFY_DESTINATION_SCOPE_KEY = "coolify_destination";
@@ -3425,6 +3432,35 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * shape {@link coolifyAgora}'s own doc comment explains.
      */
     private coolifyBoule;
+    /**
+     * `plan/diff.ts`'s `planAnalyticsBackend`: the company's analytics backend as one more Coolify application
+     * from https://github.com/wtfalch/analytics's root Dockerfile ({@link ANALYTICS_REPO}), with a database of its
+     * own, shaped like {@link coolifyKosmos}. Its start script migrates as the owner role and then serves as the
+     * runtime role, so `pushDatabaseUrl` gives it both URLs. It needs no sign-in client: it reads only
+     * `AUTH_ORGANIZATION_ID` (the tenant id derives from it), `APP_URL` and the operator key.
+     *
+     * `ANALYTICS_OPERATOR_KEY` is made once here (`mintIfAbsent`) and written only to this app's env. No outside
+     * service shows it once, so no undelivered marker is needed: a failed write leaves nothing live to mint twice.
+     * Steps that call the backend's operator API read it back from this env.
+     *
+     * A brand new app is deployed once ({@link ANALYTICS_DEPLOYED_SCOPE_KEY}), as for Boule (#504).
+     */
+    private coolifyAnalytics;
+    /** The backend's operator key, read from its own env. Fixed text when the backend or the key is not there. */
+    private analyticsOperatorKey;
+    /**
+     * C2 `coolify:analytics-boule` (`plan/analytics-boule.ts`): the backend's address and operator key into
+     * Boule's env, then Boule restarts. `analytics_boule_applied` is recorded last. Retire takes both names away.
+     */
+    private analyticsBoule;
+    /**
+     * `plan/entry-analytics-key.ts`: one server entry's site key (CLAUDE.md "Platform steps" rule 1). Mint: the
+     * key's id is recorded as undelivered and persisted before anything is written; the env write is tried 3
+     * times with the same secret; the applied address and the cleared marker come last; every try failing leaves
+     * the marker, and the error names the id only. `url` rewrites the address. Retire revokes the key and the
+     * env names. The operator key is read from the backend's env and never recorded.
+     */
+    private analyticsEntryKey;
     /**
      * `plan/diff.ts`'s `planKosmos`: provisions the org's own kosmos
      * (https://github.com/wtfalch/kosmos) as one more Coolify application, from