@wtfalch/foundry 0.65.0 → 0.67.0

package/dist/org.d.ts

@@ -301,7 +301,7 @@ export type AccessRule = {
 /** The key of the entry that is today's one app: the Coolify app named `<slug>`. */
 export declare const APP_ENTRY_KEY = "app";
 /** Why a validator refused. `code` is stable and never reworded; `message` is for people. */
-export type OrgRefusalCode = 'hosting_tunnel_needs_hosting' | 'issuer_app_name_missing' | 'issuer_app_name_not_unique' | 'issuer_app_kind_unknown' | 'issuer_app_name_reserved_agora' | 'issuer_app_name_reserved_boule' | 'issuer_app_name_reserved_kosmos' | 'hosting_needs_entry' | 'hosting_main_count' | 'entry_key_not_unique' | 'entry_image_invalid' | 'ai_webhook_path_not_unique' | 'worker_route_not_unique' | 'database_not_unique' | 'access_hostname_not_unique' | 'access_hostname_invalid' | 'access_needs_hosting' | 'access_kind_unknown' | 'access_service_token_name_missing' | 'access_hostname_locked' | 'access_hostname_not_served' | 'gate_limit_invalid' | 'hosting_repo_invalid' | 'hosting_github_invalid' | 'gate_needs_domain' | 'gate_key_invalid' | 'gate_key_not_unique' | 'gate_needs_hostname' | 'gate_hostname_not_entry_hostname' | 'gate_hostname_held_twice' | 'gate_hostname_locked' | 'gate_limit_exceeded' | 'wildcard_needs_domain' | 'wildcard_held_twice' | 'hostnames_need_domain' | 'hostname_needed' | 'hostname_invalid' | 'hostname_not_unique' | 'hostname_locked' | 'hosted_name_invalid' | 'hosted_name_not_unique' | 'hosted_name_worker_app' | 'entry_workspace_invalid' | 'entry_workspace_unsupported' | 'entry_live_needs_workspace' | 'entry_live_commit_invalid' | 'gate_key_taken_by_workspace' | 'gate_key_taken_by_private_page' | 'private_page_invalid' | 'private_page_path_invalid' | 'private_page_duplicate' | 'private_page_limit' | 'private_page_needs_hosting' | 'private_page_roles_invalid' | 'private_page_people_invalid' | 'entry_key_invalid' | 'entry_key_reserved' | 'entry_repo_invalid' | 'entry_folder_invalid' | 'entry_branch_empty' | 'entry_build_pack_unknown' | 'entry_build_pack_unavailable' | 'entry_port_invalid' | 'entry_health_path_invalid' | 'entry_capabilities_invalid' | 'entry_database_needs_hosting' | 'blue_green_needs_hostname' | 'env_name_empty' | 'env_name_reserved' | 'env_source_platform_mail_key' | 'env_source_unknown' | 'env_shared_secret_name_invalid' | 'env_held_secret_name_mismatch' | 'env_held_secret_name_invalid' | 'env_looks_like_secret' | 'builtin_app_invalid' | 'blue_green_not_object' | 'blue_green_steps_length' | 'blue_green_steps_range' | 'blue_green_steps_order' | 'blue_green_steps_end' | 'blue_green_hold_invalid' | 'blue_green_advance_invalid' | 'blue_green_min_requests_invalid' | 'blue_green_error_margin_invalid' | 'blue_green_staff_first_invalid' | 'volumes_not_list' | 'volumes_too_many' | 'volume_name_invalid' | 'volume_name_logs' | 'volume_name_not_unique' | 'volume_mount_path_invalid' | 'volume_mount_path_too_long' | 'volume_mount_path_log_dir' | 'volume_mount_path_forbidden' | 'volume_mount_path_not_unique' | 'auth_needs_hosting' | 'auth_users_invalid' | 'auth_registration_invalid' | 'registration_open_needs_customers' | 'auth_replaces_broker_entry_invalid' | 'auth_replaces_broker_entry_owned' | 'auth_needs_exact_hostname' | 'mcp_needs_open_customers' | 'mcp_path_invalid' | 'mcp_onboarding_path_invalid' | 'auth_sign_in_invalid' | 'email_code_needs_customers' | 'auth_room_invalid' | 'auth_room_needs_customers' | 'auth_room_not_unique' | 'client_name_taken' | 'workspaces_needs_customers' | 'workspaces_needs_server' | 'workspaces_roles_invalid' | 'workspaces_role_reserved' | 'workspaces_invite_path_invalid' | 'workspaces_env_clash' | 'ai_needs_hosting' | 'ai_offerings_invalid' | 'ai_permissions_invalid' | 'ai_webhook_path_invalid' | 'ai_webhook_needs_exact_hostname' | 'ai_env_clash' | 'files_needs_hosting' | 'files_collections_invalid' | 'files_permissions_invalid' | 'files_share_host_invalid' | 'files_share_host_needs_domain' | 'files_env_clash' | 'worker_needs_hosting' | 'worker_needs_repo' | 'worker_needs_own_repo' | 'worker_key_too_long' | 'worker_artifact_invalid' | 'worker_route_invalid' | 'worker_route_off_domain' | 'worker_rate_limit_name_missing' | 'worker_rate_limit_namespace_missing' | 'worker_rate_limit_invalid' | 'worker_rate_limit_period_invalid' | 'worker_app_invalid' | 'edge_not_true' | 'edge_needs_hosting' | 'edge_needs_domain' | 'edge_env_clash' | 'mail_not_true' | 'mail_needs_hosting' | 'mail_env_clash' | 'jobs_not_true' | 'jobs_needs_hosting' | 'jobs_env_clash' | 'customer_grants_not_true' | 'customer_grants_needs_customers' | 'customer_grants_env_clash' | 'repo_use_invalid' | 'repo_use_needs_repo' | 'repo_use_env_clash' | 'audit_not_true' | 'audit_needs_hosting' | 'audit_needs_worker_database' | 'customers_invalid' | 'customers_sign_up_needs_enabled' | 'registration_open_needs_sign_up';
+export type OrgRefusalCode = 'hosting_tunnel_needs_hosting' | 'issuer_app_name_missing' | 'issuer_app_name_not_unique' | 'issuer_app_kind_unknown' | 'issuer_app_name_reserved_agora' | 'issuer_app_name_reserved_boule' | 'issuer_app_name_reserved_kosmos' | 'hosting_needs_entry' | 'hosting_main_count' | 'entry_key_not_unique' | 'entry_image_invalid' | 'ai_webhook_path_not_unique' | 'worker_route_not_unique' | 'database_not_unique' | 'access_hostname_not_unique' | 'access_hostname_invalid' | 'access_needs_hosting' | 'access_kind_unknown' | 'access_service_token_name_missing' | 'access_hostname_locked' | 'access_hostname_not_served' | 'gate_limit_invalid' | 'hosting_repo_invalid' | 'hosting_github_invalid' | 'gate_needs_domain' | 'gate_key_invalid' | 'gate_key_not_unique' | 'gate_needs_hostname' | 'gate_hostname_not_entry_hostname' | 'gate_hostname_held_twice' | 'gate_hostname_locked' | 'gate_limit_exceeded' | 'wildcard_needs_domain' | 'wildcard_held_twice' | 'hostnames_need_domain' | 'hostname_needed' | 'hostname_invalid' | 'hostname_not_unique' | 'hostname_locked' | 'hosted_name_invalid' | 'hosted_name_not_unique' | 'hosted_name_worker_app' | 'entry_workspace_invalid' | 'entry_workspace_unsupported' | 'entry_live_needs_workspace' | 'entry_live_commit_invalid' | 'gate_key_taken_by_workspace' | 'gate_key_taken_by_private_page' | 'private_page_invalid' | 'private_page_path_invalid' | 'private_page_duplicate' | 'private_page_limit' | 'private_page_needs_hosting' | 'private_page_roles_invalid' | 'private_page_people_invalid' | 'entry_key_invalid' | 'entry_key_reserved' | 'entry_repo_invalid' | 'entry_folder_invalid' | 'entry_branch_empty' | 'entry_build_pack_unknown' | 'entry_build_pack_unavailable' | 'entry_port_invalid' | 'entry_health_path_invalid' | 'entry_capabilities_invalid' | 'entry_database_needs_hosting' | 'blue_green_needs_hostname' | 'env_name_empty' | 'env_name_reserved' | 'env_source_platform_mail_key' | 'env_source_unknown' | 'env_shared_secret_name_invalid' | 'env_held_secret_name_mismatch' | 'env_held_secret_name_invalid' | 'env_looks_like_secret' | 'builtin_app_invalid' | 'blue_green_not_object' | 'blue_green_steps_length' | 'blue_green_steps_range' | 'blue_green_steps_order' | 'blue_green_steps_end' | 'blue_green_hold_invalid' | 'blue_green_advance_invalid' | 'blue_green_min_requests_invalid' | 'blue_green_error_margin_invalid' | 'blue_green_staff_first_invalid' | 'volumes_not_list' | 'volumes_too_many' | 'volume_name_invalid' | 'volume_name_logs' | 'volume_name_not_unique' | 'volume_mount_path_invalid' | 'volume_mount_path_too_long' | 'volume_mount_path_log_dir' | 'volume_mount_path_forbidden' | 'volume_mount_path_not_unique' | 'auth_needs_hosting' | 'auth_users_invalid' | 'auth_registration_invalid' | 'registration_open_needs_customers' | 'auth_replaces_broker_entry_invalid' | 'auth_replaces_broker_entry_owned' | 'auth_needs_exact_hostname' | 'mcp_needs_open_customers' | 'mcp_path_invalid' | 'mcp_onboarding_path_invalid' | 'auth_sign_in_invalid' | 'email_code_needs_customers' | 'auth_room_invalid' | 'auth_room_needs_customers' | 'auth_room_not_unique' | 'client_name_taken' | 'workspaces_needs_customers' | 'workspaces_needs_server' | 'workspaces_roles_invalid' | 'workspaces_role_reserved' | 'workspaces_invite_path_invalid' | 'workspaces_env_clash' | 'ai_needs_hosting' | 'ai_offerings_invalid' | 'ai_permissions_invalid' | 'ai_webhook_path_invalid' | 'ai_webhook_needs_exact_hostname' | 'ai_env_clash' | 'files_needs_hosting' | 'files_collections_invalid' | 'files_permissions_invalid' | 'files_share_host_invalid' | 'files_share_host_needs_domain' | 'files_env_clash' | 'worker_needs_hosting' | 'worker_needs_repo' | 'worker_needs_own_repo' | 'worker_key_too_long' | 'worker_artifact_invalid' | 'worker_route_invalid' | 'worker_route_off_domain' | 'worker_rate_limit_name_missing' | 'worker_rate_limit_namespace_missing' | 'worker_rate_limit_invalid' | 'worker_rate_limit_period_invalid' | 'worker_app_invalid' | 'edge_not_true' | 'edge_needs_hosting' | 'edge_needs_domain' | 'edge_env_clash' | 'mail_not_true' | 'mail_needs_hosting' | 'mail_env_clash' | 'jobs_not_true' | 'jobs_needs_hosting' | 'jobs_env_clash' | 'analytics_not_true' | 'analytics_needs_hosting' | 'analytics_env_clash' | 'customer_grants_not_true' | 'customer_grants_needs_customers' | 'customer_grants_env_clash' | 'repo_use_invalid' | 'repo_use_needs_repo' | 'repo_use_env_clash' | 'audit_not_true' | 'audit_needs_hosting' | 'audit_needs_worker_database' | 'customers_invalid' | 'customers_sign_up_needs_enabled' | 'registration_open_needs_sign_up';
 /**
  * One refusal: a stable `code`, the dotted `path` into {@link DeclaredOrg} it is about
  * (`hosting.entries.terminal.uses.auth.registration`) and the sentence for people.
@@ -732,9 +732,17 @@ export interface HostingEntryUses {
     repo?: {
         access: 'read' | 'write';
     };
+    /**
+     * The app counts its visitors in the company's own analytics backend. A server entry gets its own site key
+     * (`ANALYTICS_URL`, `ANALYTICS_SITE_KEY`; `plan/entry-analytics-key.ts`), and its stage another. A Worker
+     * app gets its keys from Boule, which installs them per copy, so foundry only plans the backend for it.
+     */
+    analytics?: true;
 }
 /** The env names `uses.edge` writes; `env` may not name them (#317). */
 export declare const EDGE_ENTRY_ENV_NAMES: readonly ["EDGE_URL", "EDGE_API_KEY"];
+/** The env names `uses.analytics` writes on a server entry; `env` may not name them. */
+export declare const ANALYTICS_ENTRY_ENV_NAMES: readonly ["ANALYTICS_URL", "ANALYTICS_SITE_KEY"];
 /** The env names `uses.mail` writes; `env` may not name them. */
 export declare const MAIL_ENTRY_ENV_NAMES: readonly ["LETTERMINT_API_TOKEN", "MAIL_FROM"];
 /** The env names `uses.jobs` writes; `env` may not name them. */

package/dist/org.js

@@ -60,6 +60,8 @@ export const FILES_ENTRY_ENV_NAMES = [
 export const filesCollectionEnvName = (name) => `FILES_COLLECTION_${name}_ID`;
 /** The env names `uses.edge` writes; `env` may not name them (#317). */
 export const EDGE_ENTRY_ENV_NAMES = ['EDGE_URL', 'EDGE_API_KEY'];
+/** The env names `uses.analytics` writes on a server entry; `env` may not name them. */
+export const ANALYTICS_ENTRY_ENV_NAMES = ['ANALYTICS_URL', 'ANALYTICS_SITE_KEY'];
 /** The env names `uses.mail` writes; `env` may not name them. */
 export const MAIL_ENTRY_ENV_NAMES = ['LETTERMINT_API_TOKEN', 'MAIL_FROM'];
 /** The env names `uses.jobs` writes; `env` may not name them. */
@@ -1275,11 +1277,12 @@ function validateEntryCustomerGrants(entry) {
     }
     return null;
 }
-/** `uses.mail` and `uses.jobs`: `true`, `hosting.enabled`, and no `env` entry that names a value they write. */
+/** `uses.mail`, `uses.jobs` and `uses.analytics`: `true`, `hosting.enabled`, and no `env` entry that names a value they write. */
 function validateEntryMailJobs(entry, hosting) {
     for (const [use, written, code] of [
         ['mail', MAIL_ENTRY_ENV_NAMES, 'mail'],
         ['jobs', JOBS_ENTRY_ENV_NAMES, 'jobs'],
+        ['analytics', ANALYTICS_ENTRY_ENV_NAMES, 'analytics'],
     ]) {
         const value = entry.uses?.[use];
         if (value === undefined)

package/dist/plan/analytics-boule.d.ts

@@ -0,0 +1,17 @@
+import { type DeclaredOrg } from '../org.js';
+import type { DraftStep } from './diff.js';
+/**
+ * C2: while the company's Boule runs apps (`org.boule.apps`) and its analytics backend is applied, Boule's env
+ * holds `ANALYTICS_URL` and `ANALYTICS_OPERATOR_KEY`. Boule mints a site key for each app copy with the
+ * operator key and reads each release's visitors and page views with it. The key is read from the backend's own
+ * env and written to Boule's env; it is never held, recorded or planned. Without the backend Boule installs
+ * apps without analytics.
+ *
+ * One `coolify:analytics-boule` step keyed by the org id. `analytics_boule_applied` holds
+ * `<address>|<backend app id>` and is recorded last, so a new backend app (a new key) writes again. Turning
+ * apps off takes both names out of Boule's env.
+ */
+export declare const ANALYTICS_BOULE_APPLIED_SCOPE_KEY = "analytics_boule_applied";
+export declare const ANALYTICS_BOULE_ENV_NAMES: readonly ["ANALYTICS_URL", "ANALYTICS_OPERATOR_KEY"];
+export declare const analyticsBouleMarker: (org: DeclaredOrg, backendAppId: string) => string;
+export declare function planAnalyticsBoule(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[]): DraftStep[];

package/dist/plan/analytics-boule.js

@@ -0,0 +1,43 @@
+import { appsOn } from '../org.js';
+import { ANALYTICS_DEPLOYED_SCOPE_KEY, analyticsUrlFor } from './analytics.js';
+/**
+ * C2: while the company's Boule runs apps (`org.boule.apps`) and its analytics backend is applied, Boule's env
+ * holds `ANALYTICS_URL` and `ANALYTICS_OPERATOR_KEY`. Boule mints a site key for each app copy with the
+ * operator key and reads each release's visitors and page views with it. The key is read from the backend's own
+ * env and written to Boule's env; it is never held, recorded or planned. Without the backend Boule installs
+ * apps without analytics.
+ *
+ * One `coolify:analytics-boule` step keyed by the org id. `analytics_boule_applied` holds
+ * `<address>|<backend app id>` and is recorded last, so a new backend app (a new key) writes again. Turning
+ * apps off takes both names out of Boule's env.
+ */
+export const ANALYTICS_BOULE_APPLIED_SCOPE_KEY = 'analytics_boule_applied';
+export const ANALYTICS_BOULE_ENV_NAMES = ['ANALYTICS_URL', 'ANALYTICS_OPERATOR_KEY'];
+export const analyticsBouleMarker = (org, backendAppId) => `${analyticsUrlFor(org)}|${backendAppId}`;
+export function planAnalyticsBoule(org, recordedIds, plannedSteps) {
+    const draft = (mode, description) => ({
+        action: { system: 'coolify', kind: 'analytics-boule', key: org.id, desired: { mode } },
+        step: { description, destroys: mode === 'retire', migrates: false },
+    });
+    const planned = (kind) => plannedSteps.some((p) => p.action.system === 'coolify' && p.action.kind === kind && p.action.key === org.id);
+    const bouleKnown = Boolean(recordedIds[`coolify:boule:${org.id}`]) || planned('boule');
+    const marker = recordedIds[ANALYTICS_BOULE_APPLIED_SCOPE_KEY];
+    if (!appsOn(org)) {
+        if (!marker || !recordedIds[`coolify:boule:${org.id}`])
+            return [];
+        return [
+            draft('retire', `take the analytics address and key out of ${org.slug}'s Boule env (the company's Boule runs no apps)`),
+        ];
+    }
+    if (!bouleKnown)
+        return [];
+    const backendApp = recordedIds[`coolify:analytics:${org.id}`];
+    const applied = Boolean(backendApp) && Boolean(recordedIds[ANALYTICS_DEPLOYED_SCOPE_KEY]);
+    if (!applied && !planned('analytics'))
+        return [];
+    if (applied && marker === analyticsBouleMarker(org, backendApp))
+        return [];
+    return [
+        draft('write', `write ANALYTICS_URL and ANALYTICS_OPERATOR_KEY to ${org.slug}'s Boule env, restart Boule`),
+    ];
+}

package/dist/plan/analytics.d.ts

@@ -0,0 +1,58 @@
+import { type DeclaredOrg } from '../org.js';
+/**
+ * A company's own analytics backend (https://github.com/wtfalch/analytics): one Coolify app and one database
+ * per company, built from that repo's root Dockerfile. It is planned only while something uses it: a hosting
+ * entry declares `uses.analytics`, or the company's Boule runs apps (`org.boule.apps`).
+ *
+ * What the host (`apps/host`) reads to start: `DATABASE_URL` and `DATABASE_URL_OWNER` (written by
+ * `pushDatabaseUrl`), `ANALYTICS_OPERATOR_KEY` (generated once here) and `AUTH_ORGANIZATION_ID` (the company's
+ * sign-in organisation; the tenant id of every key and row derives from it, and without it minting answers 503
+ * and the release series answers `not_configured`). It reads no other `AUTH_*` name yet, so no sign-in client is
+ * made for it. When its screens need `AUTH_ISSUER` and `AUTH_CLIENT_ID`, add the client then.
+ */
+/** True while some entry declares `uses.analytics`, or Boule runs apps: the backend is wanted. */
+export declare const analyticsWanted: (org: Pick<DeclaredOrg, "boule" | "hosting">) => boolean;
+/** `analytics.<domain>`, or `<slug>-analytics.oikos.host` for a company without a domain. */
+export declare function analyticsHostnameFor(org: Pick<DeclaredOrg, 'domain' | 'slug'>): string;
+/** The public address apps and Boule send to, `ANALYTICS_URL`. */
+export declare const analyticsUrlFor: (org: Pick<DeclaredOrg, "domain" | "slug">) => string;
+/** The backend's database uuid, recorded beside the app's own id. */
+export declare const ANALYTICS_DATABASE_SCOPE_KEY = "coolify_analytics_database";
+/** Recorded once the app was deployed, as `coolify_boule_deployed` is for Boule. */
+export declare const ANALYTICS_DEPLOYED_SCOPE_KEY = "coolify_analytics_deployed";
+/** The env name the backend reads its operator key from; also Boule's name for it (C2). */
+export declare const ANALYTICS_OPERATOR_KEY_ENV = "ANALYTICS_OPERATOR_KEY";
+/** The env names `desiredAnalyticsEnv` writes, so the live reader knows which to read back. */
+export declare const ANALYTICS_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ORGANIZATION_ID"];
+export declare function desiredAnalyticsEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>): {
+    env: Record<string, string>;
+    missing: string[];
+};
+export declare function analyticsEnvDrift(desired: Readonly<Record<string, string>>, live: Readonly<Record<string, string>>): string[];
+/** The backend's operator API. Every call carries the company's own base URL and operator key. */
+export interface AnalyticsPort {
+    /** Mints a site key; the secret is shown once. The same `name` again replaces the older key. */
+    mintSiteKey(input: {
+        baseUrl: string;
+        operatorKey: string;
+        name: string;
+        environment: 'production' | 'stage';
+    }): Promise<{
+        id: string;
+        secret: string;
+    }>;
+    /** Revokes a key. An unknown id is not an error. */
+    revokeSiteKey(input: {
+        baseUrl: string;
+        operatorKey: string;
+        keyId: string;
+    }): Promise<void>;
+}
+/**
+ * The real {@link AnalyticsPort}: `POST <baseUrl>/v1/site-keys` with `{ name, environment }` answers 201
+ * `{ id, secret }`; `DELETE <baseUrl>/v1/site-keys/<id>` answers 204. Errors carry the status only, never a
+ * body, the key or the secret.
+ */
+export declare function httpAnalytics(options?: {
+    fetch?: typeof fetch;
+}): AnalyticsPort;

package/dist/plan/analytics.js

@@ -0,0 +1,89 @@
+import { appsOn } from '../org.js';
+import { ZITADEL_ORG_SCOPE_KEY } from './agora.js';
+/**
+ * A company's own analytics backend (https://github.com/wtfalch/analytics): one Coolify app and one database
+ * per company, built from that repo's root Dockerfile. It is planned only while something uses it: a hosting
+ * entry declares `uses.analytics`, or the company's Boule runs apps (`org.boule.apps`).
+ *
+ * What the host (`apps/host`) reads to start: `DATABASE_URL` and `DATABASE_URL_OWNER` (written by
+ * `pushDatabaseUrl`), `ANALYTICS_OPERATOR_KEY` (generated once here) and `AUTH_ORGANIZATION_ID` (the company's
+ * sign-in organisation; the tenant id of every key and row derives from it, and without it minting answers 503
+ * and the release series answers `not_configured`). It reads no other `AUTH_*` name yet, so no sign-in client is
+ * made for it. When its screens need `AUTH_ISSUER` and `AUTH_CLIENT_ID`, add the client then.
+ */
+/** True while some entry declares `uses.analytics`, or Boule runs apps: the backend is wanted. */
+export const analyticsWanted = (org) => appsOn(org) || org.hosting.entries.some((e) => e.uses?.analytics === true);
+/** `analytics.<domain>`, or `<slug>-analytics.oikos.host` for a company without a domain. */
+export function analyticsHostnameFor(org) {
+    return org.domain ? `analytics.${org.domain}` : `${org.slug}-analytics.oikos.host`;
+}
+/** The public address apps and Boule send to, `ANALYTICS_URL`. */
+export const analyticsUrlFor = (org) => `https://${analyticsHostnameFor(org)}`;
+/** The backend's database uuid, recorded beside the app's own id. */
+export const ANALYTICS_DATABASE_SCOPE_KEY = 'coolify_analytics_database';
+/** Recorded once the app was deployed, as `coolify_boule_deployed` is for Boule. */
+export const ANALYTICS_DEPLOYED_SCOPE_KEY = 'coolify_analytics_deployed';
+/** The env name the backend reads its operator key from; also Boule's name for it (C2). */
+export const ANALYTICS_OPERATOR_KEY_ENV = 'ANALYTICS_OPERATOR_KEY';
+/** The env names `desiredAnalyticsEnv` writes, so the live reader knows which to read back. */
+export const ANALYTICS_MANAGED_ENV_KEYS = ['APP_URL', 'AUTH_ORGANIZATION_ID'];
+export function desiredAnalyticsEnv(org, recorded) {
+    const zitadelOrgId = recorded[ZITADEL_ORG_SCOPE_KEY];
+    const env = { APP_URL: analyticsUrlFor(org) };
+    if (zitadelOrgId)
+        env.AUTH_ORGANIZATION_ID = zitadelOrgId;
+    return { env, missing: zitadelOrgId ? [] : ['zitadelOrgId'] };
+}
+export function analyticsEnvDrift(desired, live) {
+    return Object.entries(desired)
+        .filter(([key, value]) => live[key] !== value)
+        .map(([key]) => key);
+}
+const CALL_TIMEOUT_MS = 20_000;
+/**
+ * The real {@link AnalyticsPort}: `POST <baseUrl>/v1/site-keys` with `{ name, environment }` answers 201
+ * `{ id, secret }`; `DELETE <baseUrl>/v1/site-keys/<id>` answers 204. Errors carry the status only, never a
+ * body, the key or the secret.
+ */
+export function httpAnalytics(options = {}) {
+    const fetchImpl = options.fetch ?? fetch;
+    const call = async (url, init, what) => {
+        try {
+            return await fetchImpl(url, {
+                ...init,
+                redirect: 'error',
+                signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
+            });
+        }
+        catch {
+            throw new Error(`the analytics backend did not answer when asked to ${what}`);
+        }
+    };
+    return {
+        async mintSiteKey({ baseUrl, operatorKey, name, environment }) {
+            const response = await call(`${baseUrl}/v1/site-keys`, {
+                method: 'POST',
+                headers: { authorization: `Bearer ${operatorKey}`, 'content-type': 'application/json' },
+                body: JSON.stringify({ name, environment }),
+            }, 'mint a site key');
+            if (response.status !== 201) {
+                throw Object.assign(new Error(`the analytics backend refused to mint a site key (status ${response.status})`), { status: response.status });
+            }
+            const body = await response.json().catch(() => undefined);
+            const fields = typeof body === 'object' && body !== null ? body : {};
+            if (typeof fields.id !== 'string' ||
+                !fields.id ||
+                typeof fields.secret !== 'string' ||
+                !fields.secret) {
+                throw new Error('the analytics backend answered 201 but sent no key id and secret');
+            }
+            return { id: fields.id, secret: fields.secret };
+        },
+        async revokeSiteKey({ baseUrl, operatorKey, keyId }) {
+            const response = await call(`${baseUrl}/v1/site-keys/${encodeURIComponent(keyId)}`, { method: 'DELETE', headers: { authorization: `Bearer ${operatorKey}` } }, 'revoke a site key');
+            if (response.status !== 204) {
+                throw Object.assign(new Error(`the analytics backend refused to revoke a site key (status ${response.status})`), { status: response.status });
+            }
+        },
+    };
+}

package/dist/plan/boule.js

@@ -177,6 +177,8 @@ export const BOULE_MANAGED_ENV_KEYS = [
     BOULE_PEER_PASSWORD_ENV,
     BOULE_BRIDGE_SECRET_ENV,
     BOULE_OWNER_SEED_SECRET_ENV,
+    // Deprecated (foundry#987): kept in the list so the live reader still sees it, which is how
+    // `planBoule` finds a stale one to take away. Goes with `NATIVE_BUILD_KEY_ENV` next release.
     NATIVE_BUILD_KEY_ENV,
     BOULE_ARCHON_ORG_ID_ENV,
     BOULE_ARCHON_CREDENTIAL_ENV,

package/dist/plan/company-backups.js

@@ -1,4 +1,5 @@
 import { ORG_POSTGRES_SERVER_SCOPE_KEY, ORG_SERVICE_SCHEMAS, orgServiceDatabase, } from '../org.js';
+import { ANALYTICS_DATABASE_SCOPE_KEY } from './analytics.js';
 import { BOULE_DATABASE_SCOPE_KEY } from './boule.js';
 import { CHAT_REKEY_MAS_DB_SCOPE_KEY, CHAT_REKEY_SYNAPSE_DB_SCOPE_KEY } from './executor.js';
 import { MAIL_DATABASE_NAME, MAIL_DATABASE_SCOPE_KEY } from './mail-store.js';
@@ -29,6 +30,7 @@ export function companyDatabaseKeys(org) {
         chat_synapse: 'coolify_chat_synapse_database',
         chat_mas: 'coolify_chat_mas_database',
         boule: BOULE_DATABASE_SCOPE_KEY,
+        analytics: ANALYTICS_DATABASE_SCOPE_KEY,
         chat_rekey_synapse: CHAT_REKEY_SYNAPSE_DB_SCOPE_KEY,
         chat_rekey_mas: CHAT_REKEY_MAS_DB_SCOPE_KEY,
         postgres: ORG_POSTGRES_SERVER_SCOPE_KEY,

package/dist/plan/diff.d.ts

@@ -83,8 +83,12 @@ export interface PlanOrgOptions {
     workerAppKeysUrl?: string;
     /** F7: the keys service's registrar address, when the executor has a `KeysRegistrarPort`. */
     keysRegistrarUrl?: string;
+    /** The executor was built with an `analytics` port; without it each `uses.analytics` key is blocked. */
+    analyticsPort?: boolean;
     /** C2: true when the executor was built with a `WorkerAppDatabasePort`; a `workerApp.database` is blocked without it. */
     workerAppDatabase?: boolean;
+    /** True when that port has `deletableTables`; a `workerApp.database.noDelete` is blocked without it. */
+    workerAppNoDeleteCheck?: boolean;
     /** ADR 0002: the platform's Cloudflare account id; a container image must live in its registry. */
     workerAppRegistryAccountId?: string;
     /** The executor was built with an `ownerInviteMail` port; without it each owner's invite is blocked. */

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';
@@ -30,7 +33,7 @@ import { planKeysRegistrar } from './keys-registrar.js';
 import { desiredKosmosEnv, kosmosEnvDrift } from './kosmos.js';
 import { APP_GONE_KIND } from './live.js';
 import { lockedHostnames } from './locked-hostnames.js';
-import { LOGIN_BINDING_SCOPE_KEY, LOGIN_CLIENT_ORGS_SCOPE_KEY, OWN_CUSTOMERS_BASE_URI_SCOPE_KEY, agoraIssuerHostFor, clientOrganizationsState, companyLoginTunnelHost, customersClientOrganizations, inAppApps, loginBindingState, loginHostClientIds, loginHostServesAgora, loginHostnameFor, ownAuthApplied, ownCustomersAppState, pendingRemovalHosts, } from './login-host.js';
+import { LOGIN_BASE_URI_SWEEP_SCOPE_KEY, LOGIN_BASE_URI_SWEEP_VERSION, LOGIN_BINDING_SCOPE_KEY, LOGIN_CLIENT_ORGS_SCOPE_KEY, OWN_CUSTOMERS_BASE_URI_SCOPE_KEY, agoraIssuerHostFor, clientOrganizationsState, companyLoginTunnelHost, customersClientOrganizations, inAppApps, loginBindingState, loginHostClientIds, loginHostServesAgora, loginHostnameFor, ownAuthApplied, ownCustomersAppState, pendingRemovalHosts, } from './login-host.js';
 import { planMachineBypasses } from './machine-paths.js';
 import { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, parseMailCopyCompleted, } from './mail-copy.js';
 import { mailStoreSwitchChange } from './mail-store.js';
@@ -723,6 +726,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.
@@ -835,6 +846,9 @@ export function computePlanDetail(declaredOrg, live, recordedIds = {}, agoraHost
             : {}),
         canHoldSecrets: platformReadiness.canHoldSecrets === true,
         issuer: authIssuer,
+        ...(platformReadiness.workerAppSecrets
+            ? { heldSecrets: platformReadiness.workerAppSecrets }
+            : {}),
         ...(options.workerAppDatabase
             ? {
                 database: {
@@ -844,6 +858,7 @@ export function computePlanDetail(declaredOrg, live, recordedIds = {}, agoraHost
                     tunnelReady: Boolean(recordedIds[`cloudflare:tunnel:${org.id}`]) ||
                         plannedSteps.some((s) => s.action.system === 'cloudflare' && s.action.kind === 'tunnel'),
                     accessReady: edgeNeeded(platformReadiness, ['access', 'tunnels', 'dns', 'zones']) === null,
+                    noDeleteCheck: options.workerAppNoDeleteCheck === true,
                 },
             }
             : {}),
@@ -991,6 +1006,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)
@@ -1627,7 +1645,14 @@ function planOwnLoginHost(org, recordedIds, gates) {
     const customersOwed = Boolean(recordedIds[SIGN_IN_LOGIN_APP_SCOPE_KEY]) &&
         ownCustomersAppState(org, recordedIds) !==
             (recordedIds[OWN_CUSTOMERS_BASE_URI_SCOPE_KEY] ?? '');
-    if (!inAppSignIn(org) && !recordedIds[SIGN_IN_IN_APP_SCOPE_KEY] && !mapOwed && !customersOwed) {
+    // With in-app sign-in applied `loginV2.required` is off: every app of the instance owes a base URI until swept.
+    const sweepOwed = Boolean(recordedIds[SIGN_IN_IN_APP_SCOPE_KEY]) &&
+        recordedIds[LOGIN_BASE_URI_SWEEP_SCOPE_KEY] !== LOGIN_BASE_URI_SWEEP_VERSION;
+    if (!inAppSignIn(org) &&
+        !recordedIds[SIGN_IN_IN_APP_SCOPE_KEY] &&
+        !mapOwed &&
+        !customersOwed &&
+        !sweepOwed) {
         return none;
     }
     // The company's own sign-in is reported on its own line (`coolify:own-auth`).
@@ -1646,6 +1671,7 @@ function planOwnLoginHost(org, recordedIds, gates) {
         (recordedIds[SIGN_IN_IN_APP_SCOPE_KEY] ?? '') === targets.active &&
         !mapOwed &&
         !customersOwed &&
+        !sweepOwed &&
         pendingRemovalHosts(recordedIds).length === 0) {
         return { step: null, blocked: waiting };
     }
@@ -3200,6 +3226,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
@@ -3388,7 +3486,9 @@ function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonU
         drift.push(BOULE_BRIDGE_SECRET_ENV);
     if (!liveEnv[BOULE_OWNER_SEED_SECRET_ENV])
         drift.push(BOULE_OWNER_SEED_SECRET_ENV);
-    if (!liveEnv[NATIVE_BUILD_KEY_ENV])
+    // foundry#987: nothing reads this any more (Boule calls Archon's org build route with its
+    // own org credential instead). A live one is drift, so the step removes it rather than minting it.
+    if (liveEnv[NATIVE_BUILD_KEY_ENV])
         drift.push(NATIVE_BUILD_KEY_ENV);
     // Secrets written but Boule not restarted since: plan the step so it restarts, minting nothing.
     if (platformOwner && !recordedIds[BOULE_SECRETS_RESTARTED_SCOPE_KEY]) {

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 {};