@wtfalch/foundry 0.66.0 → 0.67.0

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

package/dist/plan/executor.js

@@ -9,6 +9,8 @@ import { NATIVE_BUILD_KEY_ENV } from '../native-build.js';
 import { AI_ENTRY_PERMISSIONS, APPS_DOMAIN, APP_ENTRY_KEY, FILES_ENTRY_PERMISSIONS, FULL_COMMIT_SHA, ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, appsOn, companyGithubFor, filesCollectionEnvName, heldEnvRef, isLiveEntry, isMainEntry, kosmosOn, mainEntry, ownerMailboxRecorded, ownerMailboxes, ownsServices, sharedSecretRef, } from '../org.js';
 import { adoptedKeysUnreadable, parseAdoptSnapshot } from './adopt.js';
 import { AGORA_ACTIVATED_ENV_SCOPE_KEY, AGORA_APP_PORTS_EXPOSES, AGORA_CLIENT_ID_SCOPE_KEY, AGORA_DEPLOYED_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_DEPLOYED_SCOPE_KEY, CALLS_SERVICE_NAME_SCOPE_KEY, CALLS_SERVICE_PORT, CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY, CHAT_CALLS_APPLIED_SCOPE_KEY, CHAT_CALLS_TOKEN_SCOPE_KEY, CHAT_CALLS_TOKEN_UNDELIVERED_SCOPE_KEY, CHAT_INTROSPECTION_SCOPE_KEY, CHAT_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CHAT_SERVICE_URL_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, DESKTOP_AUTH_PORT, ENTRY_CLIENT_ID_SCOPE_PREFIX, ZITADEL_MESSAGING_PROJECT_SCOPE_KEY, ZITADEL_ORG_SCOPE_KEY, agoraEnvDrift, agoraEnvRevision, agoraHostnameFor, callsIntrospectionAppName, callsServiceHasName, callsServiceInternalName, callsTokenEnvMarker, callsTokenEnvMovedMessage, chatCallsApplied, chatHasUpstreams, chatIntrospectionAppName, desiredAgoraEnv, desktopAuthInternalName, entryClientIdScopeKey, } from './agora.js';
+import { ANALYTICS_BOULE_APPLIED_SCOPE_KEY, ANALYTICS_BOULE_ENV_NAMES, analyticsBouleMarker, } from './analytics-boule.js';
+import { ANALYTICS_DATABASE_SCOPE_KEY, ANALYTICS_DEPLOYED_SCOPE_KEY, ANALYTICS_OPERATOR_KEY_ENV, analyticsEnvDrift, analyticsHostnameFor, analyticsUrlFor, desiredAnalyticsEnv, } from './analytics.js';
 import { APPS_DATABASE_ADMIN_URL_ENV, applyAppsDbRoute, retireAppsDbRoute, } from './apps-db-route.js';
 import { APPS_ZONES_APPLIED_SCOPE_KEY, applyAppsZones, retireAppsZones } from './apps-zones.js';
 import { applyBlueGreenConnectors, applyBlueGreenServer, applyBlueGreenWeights, applyWorkspaceServer, } from './blue-green-apply.js';
@@ -38,6 +40,7 @@ import { createEdgeRateLimits, } from './edge-ratelimits.js';
 import { createEdgeTunnels } from './edge-tunnels.js';
 import { createEdgeZones } from './edge-zones.js';
 import { AI_ENTRY_KEY_DAYS, AI_ENTRY_RENEW_WINDOW_DAYS, entryAiAppliedScopeKey, entryAiClampedScopeKey, entryAiExpiresScopeKey, entryAiPendingExpiresScopeKey, entryAiRetiredScopeKey, entryAiUndeliveredScopeKey, entryAiUnrevokedScopeKey, entryAiWebhookPendingScopeKey, entryAiWrittenScopeKey, parseIdList, } from './entry-ai-key.js';
+import { ENTRY_ANALYTICS_KEY_DELIVERY_ATTEMPTS, entryAnalyticsAppliedScopeKey, entryAnalyticsRetiredScopeKey, entryAnalyticsUndeliveredScopeKey, stageAnalyticsKeyName, } from './entry-analytics-key.js';
 import { applyEntryAudit } from './entry-audit.js';
 import { CUSTOMER_GRANTS_CREDENTIAL_ENV, CUSTOMER_GRANTS_ENV, CUSTOMER_GRANTS_WRITTEN_SCOPE_KEY, customerGrantsEntries, customerGrantsJson, customerGrantsMintedScopeKey, customerGrantsRef, customerGrantsToDrop, ensureCustomerGrantsCredential, wantedCustomerGrants, } from './entry-customer-grants.js';
 import { BOULE_EDGE_ENTRY_KEY, EDGE_ENTRY_KEY_DAYS, EDGE_RESERVED_LABELS_APPLIED_SCOPE_KEY, EDGE_SLUG_APPLIED_SCOPE_KEY, ENTRY_EDGE_KEY_DELIVERY_ATTEMPTS, bouleEdgeKeyWanted, edgeKeyAppRecordKey, edgeKeyDomain, entryEdgeMintedAtScopeKey, entryEdgeRetiredScopeKey, entryEdgeUndeliveredScopeKey, } from './entry-edge-key.js';
@@ -404,6 +407,10 @@ export const BOULE_PORT = 3000;
 export const KOSMOS_REPO = 'wtfalch/kosmos';
 export const KOSMOS_APP_DOCKERFILE = '/Dockerfile';
 export 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 const ANALYTICS_REPO = 'wtfalch/analytics';
+export const ANALYTICS_APP_DOCKERFILE = '/Dockerfile';
+export const ANALYTICS_PORT = 3000;
 /**
  * Every app foundry deploys keeps its own logs across a redeploy, so a
  * database outage does not also erase the only other copy of the evidence
@@ -969,6 +976,8 @@ function limitProfileOf(action) {
             return LIMITS.boule;
         case 'coolify:kosmos':
             return LIMITS.kosmos;
+        case 'coolify:analytics':
+            return LIMITS.analytics;
         case 'coolify:broker-registrar':
             return LIMITS.brokerEntry;
         case 'coolify:keys-registrar':
@@ -1404,6 +1413,12 @@ export class FoundryStepExecutor {
                 return this.bouleBrokerEntry(org, context);
             case 'coolify:kosmos':
                 return this.coolifyKosmos(action, org, context);
+            case 'coolify:analytics':
+                return this.coolifyAnalytics(action, org, context);
+            case 'coolify:analytics-boule':
+                return this.analyticsBoule(action, org, context);
+            case 'analytics:key':
+                return this.analyticsEntryKey(action, org, context);
             case 'coolify:broker-registrar':
                 return this.brokerRegistrar(org, context);
             case 'coolify:keys-registrar':
@@ -3831,8 +3846,34 @@ export class FoundryStepExecutor {
                     : { id: registered.id, name: projectName };
             },
         };
+        const analytics = {
+            held: held('analytics'),
+            available: async () => canHold &&
+                Boolean(this.ports.analytics) &&
+                Boolean(context.recordedIds()[`coolify:analytics:${org.id}`]) &&
+                entry?.uses?.analytics === true,
+            create: async () => {
+                const port = this.ports.analytics;
+                if (!port)
+                    throw new Error('no analytics port');
+                const operatorKey = await this.analyticsOperatorKey(org, context);
+                const name = stageAnalyticsKeyName(org, subject.id);
+                const minted = await port.mintSiteKey({
+                    baseUrl: analyticsUrlFor(org),
+                    operatorKey,
+                    name,
+                    environment: 'stage',
+                });
+                return {
+                    id: minted.id,
+                    name,
+                    keyIds: [minted.id],
+                    secrets: [{ env: 'ANALYTICS_SITE_KEY', value: minted.secret }],
+                };
+            },
+        };
         const prodJobsProjectId = context.recordedIds()[`jobs:registration:${org.id}`];
-        return { files, ai, jobs, ...(prodJobsProjectId ? { prodJobsProjectId } : {}) };
+        return { files, ai, jobs, analytics, ...(prodJobsProjectId ? { prodJobsProjectId } : {}) };
     }
     /**
      * Stage's own sign-in (`plan/stage-signin.ts`): a client named `<production client>-stage` on production's
@@ -7859,6 +7900,254 @@ export class FoundryStepExecutor {
         this.recordSignInEnvLive(context, 'boule', bouleHostnameFor(org), env);
         return { resourceId: app.appId };
     }
+    // ---- analytics backend ----------------------------------------------------
+    /**
+     * `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).
+     */
+    async coolifyAnalytics(_action, org, context) {
+        const { env, missing } = desiredAnalyticsEnv(org, context.recordedIds());
+        if (missing.length > 0) {
+            throw new Error(`the analytics backend for ${org.slug} cannot be configured: missing ${missing.join(', ')}. Nothing was written.`);
+        }
+        const projectUuid = await this.ensureCoolifyProject(org, context);
+        const { environment } = await this.ports.coolify.findOrCreateEnvironment(projectUuid, 'production');
+        const name = `${org.slug}-analytics`;
+        const dbName = `${org.slug}-analytics-db`.replace(/-/g, '_');
+        const dbId = await this.ensureCallsDatabase(org, context, projectUuid, environment, `${org.slug}-analytics-db`, dbName, ANALYTICS_DATABASE_SCOPE_KEY);
+        context.recordScopeId(ANALYTICS_DATABASE_SCOPE_KEY, dbId);
+        const server = await this.resolveServer(org, context);
+        const githubApp = await this.ports.coolify.requireGithubApp();
+        const app = await this.findOrCreateCallsApp(name, environment.id, () => this.ports.coolify.createGithubAppApplication({
+            is_preview_deployments_enabled: false,
+            project_uuid: projectUuid,
+            server_uuid: server.uuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            github_app_uuid: githubApp.uuid,
+            git_repository: ANALYTICS_REPO,
+            git_branch: 'main',
+            build_pack: 'dockerfile',
+            name,
+            domains: coolifyTunnelDomains([analyticsHostnameFor(org)]),
+            dockerfile_location: ANALYTICS_APP_DOCKERFILE,
+        }));
+        await this.ensureLogVolume(app.appId, org, app.existed);
+        await this.ports.coolify.updateApplication(app.appId, {
+            ...healthCheckSettings('/api/health', ANALYTICS_PORT),
+            ...(await this.routedLabels(name, analyticsHostnameFor(org), ANALYTICS_PORT)),
+        });
+        const liveEnv = Object.fromEntries((await this.ports.coolify.listEnvs(app.appId))
+            .filter((e) => !e.is_preview)
+            .map((e) => [e.key, e.value]));
+        const envChanged = analyticsEnvDrift(env, liveEnv).length > 0;
+        const envs = Object.entries(env).map(([key, value]) => ({ key, value }));
+        const operatorKey = await this.mintIfAbsent(app.appId, ANALYTICS_OPERATOR_KEY_ENV, 32);
+        if (operatorKey) {
+            this.handledSecrets.add(operatorKey);
+            envs.push({ key: ANALYTICS_OPERATOR_KEY_ENV, value: operatorKey });
+        }
+        try {
+            await this.ports.coolify.bulkUpsertEnvs(app.appId, envs);
+        }
+        catch (error) {
+            if (!operatorKey)
+                throw error;
+            throw new Error(redactSecrets(error instanceof Error ? error.message : String(error), [operatorKey]));
+        }
+        const dbPush = await this.pushDatabaseUrl(app.appId, dbId, dbName);
+        if (!dbPush.pushed) {
+            throw new Error(`the analytics backend for ${org.slug}: its database has no internal_db_url yet -- retry this apply once Coolify reports one`);
+        }
+        if (!context.recordedIds()[ANALYTICS_DEPLOYED_SCOPE_KEY]) {
+            const runtime = this.ports.runtime ?? {};
+            const built = await waitForNewDeployment(this.ports.coolify, app.appId, publicHealthCheck(org, context.recordedIds(), analyticsHostnameFor(org), '/api/health'), runtime, runtime.sleep ?? defaultSleep, 'coolify:analytics', `${org.slug}'s analytics backend stays at its previous deploy`);
+            await recordBuiltCommit(this.ports.coolify, { appId: app.appId, deploymentUuid: built.deploymentUuid, name: 'analytics' }, (key, value) => context.recordScopeId(key, value));
+            context.recordScopeId(ANALYTICS_DEPLOYED_SCOPE_KEY, '1');
+        }
+        else if (app.existed && (envChanged || operatorKey !== null || dbPush.changed)) {
+            await this.ports.coolify.restart(app.appId);
+        }
+        return { resourceId: app.appId };
+    }
+    /** The backend's operator key, read from its own env. Fixed text when the backend or the key is not there. */
+    async analyticsOperatorKey(org, context) {
+        const appId = context.recordedIds()[`coolify:analytics:${org.id}`];
+        if (!appId)
+            throw new Error(`the analytics backend for ${org.slug} is not recorded yet`);
+        const rows = await this.ports.coolify.listEnvs(appId);
+        const key = rows.find((e) => e.key === ANALYTICS_OPERATOR_KEY_ENV && !e.is_preview)?.value;
+        if (!key)
+            throw new Error(`the analytics backend for ${org.slug} has no operator key yet`);
+        this.handledSecrets.add(key);
+        return key;
+    }
+    /**
+     * 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.
+     */
+    async analyticsBoule(action, org, context) {
+        const at = `coolify:analytics-boule for ${org.slug}`;
+        const recorded = context.recordedIds();
+        const bouleId = recorded[`coolify:boule:${org.id}`];
+        if (!bouleId)
+            throw new Error(`${at}: Boule is not recorded yet`);
+        if (action.desired.mode === 'retire') {
+            const rows = await this.ports.coolify.listEnvs(bouleId);
+            for (const name of ANALYTICS_BOULE_ENV_NAMES) {
+                const row = rows.find((e) => e.key === name && !e.is_preview);
+                if (row?.uuid) {
+                    try {
+                        await this.ports.coolify.deleteEnv(bouleId, row.uuid);
+                    }
+                    catch (error) {
+                        if (!isNotFoundError(error))
+                            throw error;
+                    }
+                }
+            }
+            await this.ports.coolify.restart(bouleId);
+            context.recordScopeId(ANALYTICS_BOULE_APPLIED_SCOPE_KEY, '');
+            return {};
+        }
+        if (!appsOn(org))
+            throw new Error(`${at}: the company's Boule runs no apps (org.boule.apps)`);
+        const backendId = recorded[`coolify:analytics:${org.id}`];
+        if (!backendId)
+            throw new Error(`${at}: the analytics backend is not recorded yet`);
+        const operatorKey = await this.analyticsOperatorKey(org, context);
+        try {
+            await this.ports.coolify.bulkUpsertEnvs(bouleId, [
+                { key: 'ANALYTICS_URL', value: analyticsUrlFor(org), literal: true },
+                { key: ANALYTICS_OPERATOR_KEY_ENV, value: operatorKey, literal: true },
+            ]);
+            await this.ports.coolify.restart(bouleId);
+        }
+        catch (error) {
+            throw new Error(redactSecrets(error instanceof Error ? error.message : String(error), [operatorKey]));
+        }
+        context.recordScopeId(ANALYTICS_BOULE_APPLIED_SCOPE_KEY, analyticsBouleMarker(org, backendId));
+        return {};
+    }
+    /**
+     * `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.
+     */
+    async analyticsEntryKey(action, org, context) {
+        const entryKey = action.key.slice(org.id.length + 1);
+        const at = `analytics:key for ${org.slug} entry '${entryKey}'`;
+        const analytics = this.ports.analytics;
+        if (!analytics)
+            throw new Error(`${at}: this executor was built without an analytics port`);
+        const desired = action.desired;
+        const recorded = context.recordedIds();
+        const appId = recorded[`coolify:app:${action.key}`];
+        const baseUrl = analyticsUrlFor(org);
+        const tolerate = async (call, gone) => {
+            try {
+                return await call();
+            }
+            catch (error) {
+                if (!isNotFoundError(error))
+                    throw error;
+                return gone;
+            }
+        };
+        if (desired.mode === 'retire') {
+            const mainId = recorded[`analytics:key:${action.key}`];
+            const undelivered = recorded[entryAnalyticsUndeliveredScopeKey(entryKey)];
+            const ids = [...new Set([mainId, undelivered].filter((id) => Boolean(id)))];
+            if (ids.length > 0) {
+                const operatorKey = await this.analyticsOperatorKey(org, context);
+                for (const keyId of ids) {
+                    await tolerate(() => analytics.revokeSiteKey({ baseUrl, operatorKey, keyId }), undefined);
+                }
+            }
+            if (appId) {
+                const rows = await tolerate(() => this.ports.coolify.listEnvs(appId), []);
+                let removed = false;
+                for (const name of ['ANALYTICS_URL', 'ANALYTICS_SITE_KEY']) {
+                    const row = rows.find((e) => e.key === name && !e.is_preview);
+                    if (row?.uuid) {
+                        const uuid = row.uuid;
+                        await tolerate(() => this.ports.coolify.deleteEnv(appId, uuid), undefined);
+                        removed = true;
+                    }
+                }
+                if (removed)
+                    await tolerate(() => this.ports.coolify.restart(appId), undefined);
+            }
+            context.recordScopeId(entryAnalyticsUndeliveredScopeKey(entryKey), '');
+            context.recordScopeId(entryAnalyticsAppliedScopeKey(entryKey), '');
+            if (mainId ?? undelivered) {
+                context.recordScopeId(entryAnalyticsRetiredScopeKey(entryKey), (mainId ?? undelivered));
+            }
+            return {};
+        }
+        if (!org.hosting.entries.some((e) => e.key === entryKey && e.uses?.analytics)) {
+            throw new Error(`${at}: the entry no longer declares uses.analytics`);
+        }
+        if (!appId)
+            throw new Error(`${at}: the entry's app is not recorded yet`);
+        if (desired.mode === 'url') {
+            await this.ports.coolify.bulkUpsertEnvs(appId, [
+                { key: 'ANALYTICS_URL', value: baseUrl, literal: true },
+            ]);
+            await this.ports.coolify.restart(appId);
+            context.recordScopeId(entryAnalyticsAppliedScopeKey(entryKey), baseUrl);
+            return {};
+        }
+        if (recorded[entryAnalyticsUndeliveredScopeKey(entryKey)]) {
+            throw new Error(`${at}: a key was minted and never delivered; it is not minted again`);
+        }
+        const operatorKey = await this.analyticsOperatorKey(org, context);
+        let minted;
+        try {
+            minted = await analytics.mintSiteKey({
+                baseUrl,
+                operatorKey,
+                name: desired.name,
+                environment: 'production',
+            });
+        }
+        catch (error) {
+            const status = error?.status;
+            throw new Error(`${at}: the backend did not mint a key${typeof status === 'number' ? ` (status ${status})` : ''}`);
+        }
+        this.handledSecrets.add(minted.secret);
+        context.recordScopeId(entryAnalyticsUndeliveredScopeKey(entryKey), minted.id);
+        await context.persistScopeIds();
+        const rows = [
+            { key: 'ANALYTICS_URL', value: baseUrl, literal: true },
+            { key: 'ANALYTICS_SITE_KEY', value: minted.secret, literal: true },
+        ];
+        let lastError;
+        for (let attempt = 1; attempt <= ENTRY_ANALYTICS_KEY_DELIVERY_ATTEMPTS; attempt++) {
+            try {
+                await this.ports.coolify.bulkUpsertEnvs(appId, rows);
+                await this.ports.coolify.restart(appId);
+                context.recordScopeId(entryAnalyticsAppliedScopeKey(entryKey), baseUrl);
+                context.recordScopeId(entryAnalyticsUndeliveredScopeKey(entryKey), '');
+                return { resourceId: minted.id };
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        throw new Error(`${at}: key ${minted.id} was minted but could not be written to the app's env after ${ENTRY_ANALYTICS_KEY_DELIVERY_ATTEMPTS} attempts (${lastError instanceof Error ? lastError.name : 'error'})`);
+    }
     // ---- kosmos (foundry#949) --------------------------------------------------
     /**
      * `plan/diff.ts`'s `planKosmos`: provisions the org's own kosmos

package/dist/plan/hostnames.js

@@ -2,6 +2,7 @@ import { INBOX_HOST_PREFIX, WORKSPACE_HOST_PREFIX } from '../hosted-label.js';
 import { APPS_DOMAIN, isMainEntry, mainEntry } from '../org.js';
 import { workerAppHostnameOf } from '../worker-app-config.js';
 import { agoraHostnameFor } from './agora.js';
+import { analyticsHostnameFor, analyticsWanted } from './analytics.js';
 import { bouleHostnameFor } from './boule.js';
 import { workspaceWorkerParent } from './workspace-worker.js';
 /**
@@ -154,6 +155,9 @@ export function tunnelIngressHostnames(org, loginHost = null) {
         hostnames.push(agoraHostnameFor(org));
         // #161: and Boule moves onto `boule.<domain>` the same way.
         hostnames.push(bouleHostnameFor(org));
+        // The analytics backend's route, only while something uses it.
+        if (analyticsWanted(org))
+            hostnames.push(analyticsHostnameFor(org));
     }
     const share = filesShareHostname(org);
     if (share)

package/dist/plan/index.d.ts

@@ -1,4 +1,6 @@
 export type { KeysRegistrarPort } from './keys-registrar.js';
+export type { AnalyticsPort } from './analytics.js';
+export { httpAnalytics } from './analytics.js';
 export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, PlatformCloudflareReader, PlatformCoolifyReader, PlatformLiveReaders, } from './live.js';
 export { readLiveResources, readLivePlatformResources } from './live.js';
 export type { StepAction, PlannedStep, PlanDetail, OrgPostgresPlan } from './diff.js';

package/dist/plan/index.js

@@ -1,3 +1,4 @@
+export { httpAnalytics } from './analytics.js';
 export { readLiveResources, readLivePlatformResources } from './live.js';
 export { computePlanDetail, toPlan } from './diff.js';
 export { stepSystemOf } from './step-system.js';

package/dist/plan/live.d.ts

@@ -42,7 +42,7 @@ export interface LiveResource {
      * see that function's own doc comment for why "always planned" broke
      * `bootstrapPlatform`.
      */
-    system: 'zitadel' | 'coolify' | 'cloudflare' | 'files' | 'ai' | 'cms' | 'jobs' | 'sfu' | 'edge' | 'heartbeats' | 'github' | 'audit';
+    system: 'zitadel' | 'coolify' | 'cloudflare' | 'files' | 'ai' | 'cms' | 'jobs' | 'sfu' | 'edge' | 'heartbeats' | 'github' | 'audit' | 'analytics';
     kind: string;
     key: string;
     config: Record<string, unknown>;

package/dist/plan/locked-hostnames.js

@@ -1,6 +1,7 @@
 import { kosmosOn, ownsServices } from '../org.js';
 import { OWN_SERVICE_LABELS } from '../service-labels.js';
 import { agoraHostnameFor } from './agora.js';
+import { analyticsHostnameFor } from './analytics.js';
 import { bouleHostnameFor } from './boule.js';
 import { cmsStudioHostnameFor, siteHostnameFor } from './hostnames.js';
 import { kosmosHostnameFor } from './kosmos.js';
@@ -32,6 +33,8 @@ export function lockedHostnames(org, platformHostnames) {
     }
     locked.add(agoraHostnameFor(org));
     locked.add(bouleHostnameFor(org));
+    // Reserved always, planned only while something uses analytics (`analyticsWanted`).
+    locked.add(analyticsHostnameFor(org));
     if (kosmosOn(org))
         locked.add(kosmosHostnameFor(org));
     if (org.site.enabled)

package/dist/plan/org-names.d.ts

@@ -6,13 +6,13 @@ export type OrgNameSource = 'own' | 'hosting';
  * hosting entries: Agora, Boule, the tunnel and its connector, and chat,
  * calls and the cms site while they are on.
  */
-export declare function companyServiceNames(org: Pick<DeclaredOrg, 'slug' | 'chat' | 'calls' | 'site' | 'kosmos'>): string[];
+export declare function companyServiceNames(org: Pick<DeclaredOrg, 'slug' | 'chat' | 'calls' | 'site' | 'kosmos' | 'boule' | 'hosting'>): string[];
 /**
  * Every container name, network alias, database, tunnel and bucket name that
  * foundry derives for an org: its own-service names when it owns services,
  * and its hosting-entry and database names.
  */
-export declare function orgDerivedNames(org: Pick<DeclaredOrg, 'slug' | 'domain' | 'services' | 'hosting' | 'chat' | 'calls' | 'site' | 'kosmos'>): {
+export declare function orgDerivedNames(org: Pick<DeclaredOrg, 'slug' | 'domain' | 'services' | 'hosting' | 'chat' | 'calls' | 'site' | 'kosmos' | 'boule'>): {
     name: string;
     source: OrgNameSource;
 }[];
@@ -26,5 +26,5 @@ export interface NameClash {
     source: OrgNameSource;
 }
 /** Every name `org` derives that another org or the platform also derives. */
-export declare function findNameClashes(org: Pick<DeclaredOrg, 'slug' | 'domain' | 'services' | 'hosting' | 'chat' | 'calls' | 'site' | 'kosmos'>, others: readonly Pick<DeclaredOrg, 'slug' | 'domain' | 'services' | 'hosting' | 'chat' | 'calls' | 'site' | 'kosmos'>[]): NameClash[];
+export declare function findNameClashes(org: Pick<DeclaredOrg, 'slug' | 'domain' | 'services' | 'hosting' | 'chat' | 'calls' | 'site' | 'kosmos' | 'boule'>, others: readonly Pick<DeclaredOrg, 'slug' | 'domain' | 'services' | 'hosting' | 'chat' | 'calls' | 'site' | 'kosmos' | 'boule'>[]): NameClash[];
 export declare function nameClashMessage(slug: string, clash: NameClash): string;

package/dist/plan/org-names.js

@@ -1,5 +1,6 @@
 import { kosmosOn, ownsServices } from '../org.js';
 import { entryHasDatabase } from '../worker-app-config.js';
+import { analyticsWanted } from './analytics.js';
 import { chatInternalNames, chatRekeyedInternalNames } from './chat-matrix.js';
 import { workerAppHostname, workspaceHost, workspaceInboxHost } from './hostnames.js';
 import { orgTarget, platformTarget } from './own-services.js';
@@ -20,6 +21,8 @@ export function companyServiceNames(org) {
         `${s}-tunnel`,
         `${s}-cloudflared`,
     ];
+    if (analyticsWanted(org))
+        names.push(`${s}-analytics`, `${s}-analytics-db`);
     if (kosmosOn(org))
         names.push(`${s}-kosmos`, `${s}-kosmos-db`);
     if (org.chat?.enabled) {

package/dist/plan/own-limits.d.ts

@@ -113,6 +113,12 @@ export declare const LIMITS: {
         autoDeploy: false | "declared";
         capabilities: CapabilityTier;
     };
+    readonly analytics: {
+        memory: string;
+        dbMemory: string;
+        autoDeploy: false | "declared";
+        capabilities: CapabilityTier;
+    };
     readonly companyOther: {
         memory: string;
         dbMemory: string;