@wtfalch/foundry 0.76.0 → 0.77.0

package/dist/plan/registered-app-env.js

@@ -0,0 +1,63 @@
+/**
+ * ADR 0003 (auth ADR 0008): what an entry whose customers and team both sign in was answered by the sign-in
+ * broker's registrar, as recorded. A leaf module: the readers of the app's sign-in env (`broker-entries.ts`,
+ * `workspace-sign-in.ts`) and the step itself (`registered-app.ts`) all read it here, so they agree.
+ */
+import { signsInBoth } from '../org.js';
+/** The env names the broker's answer gives the app beside `AUTH_ISSUER` and `AUTH_APP_KEY`. */
+export const REGISTERED_APP_ENV_NAMES = [
+    'AUTH_ORGANIZATION_ID',
+    'AUTH_CLIENT_ID',
+    'AUTH_TEAM_CLIENT_ID',
+    'AUTH_TEAM_ORGANIZATION_ID',
+];
+/** The team's two env names, which only an app both sign in to holds. */
+export const TEAM_ENV_NAMES = ['AUTH_TEAM_CLIENT_ID', 'AUTH_TEAM_ORGANIZATION_ID'];
+/**
+ * Scope id holding {@link RegisteredAppEnv} as JSON for one copy (`<entry>` live, `<entry>-work` the
+ * workspace), recorded once the app's env holds it.
+ */
+export const registeredAppEnvScopeKey = (clientKey) => `registered_app_env.${clientKey}`;
+/** Scope id holding the registration last sent for one copy (JSON, no key); a different want plans the step again. */
+export const registeredAppAppliedScopeKey = (clientKey) => `registered_app_applied.${clientKey}`;
+/** The recorded answer of one copy, or `null` when none is recorded or it does not read as one. */
+export function registeredAppEnv(recorded, clientKey) {
+    const raw = recorded[registeredAppEnvScopeKey(clientKey)];
+    if (!raw)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const values = parsed;
+    for (const name of REGISTERED_APP_ENV_NAMES) {
+        if (typeof values[name] !== 'string' || values[name] === '')
+            return null;
+    }
+    return {
+        AUTH_ORGANIZATION_ID: values.AUTH_ORGANIZATION_ID,
+        AUTH_CLIENT_ID: values.AUTH_CLIENT_ID,
+        AUTH_TEAM_CLIENT_ID: values.AUTH_TEAM_CLIENT_ID,
+        AUTH_TEAM_ORGANIZATION_ID: values.AUTH_TEAM_ORGANIZATION_ID,
+    };
+}
+/** The client ids (the customers' and the team's) of the live copy of every entry both sign in to, as recorded. */
+export function liveRegisteredClientIds(org, recorded) {
+    const clientIds = [];
+    const teamClientIds = [];
+    for (const entry of org.hosting.entries) {
+        if (!signsInBoth(entry.uses?.auth))
+            continue;
+        const env = registeredAppEnv(recorded, entry.key);
+        if (!env)
+            continue;
+        clientIds.push(env.AUTH_CLIENT_ID);
+        teamClientIds.push(env.AUTH_TEAM_CLIENT_ID);
+    }
+    return { clientIds: clientIds.sort(), teamClientIds: teamClientIds.sort() };
+}

package/dist/plan/registered-app.d.ts

@@ -0,0 +1,121 @@
+import { type DeclaredOrg, type HostingEntry } from '../org.js';
+import type { UnmanagedItem } from '../plan.js';
+import type { BrokerEntryInput } from './broker-entries.js';
+import type { DraftStep } from './diff.js';
+import { type RegisteredAppEnv } from './registered-app-env.js';
+/**
+ * ADR 0003 (auth ADR 0008, wtfalch/foundry#1109): an entry whose customers and team both sign in
+ * (`uses.auth.users: ['customers', 'staff']`) is not an `AUTH_APPS` entry with a client foundry makes. It is
+ * registered at the sign-in broker through the company's registrar (`PUT <registrar>/apps/<organisation>/<name>`,
+ * the key foundry holds at `registrarRef(org.id)`), in the customers organisation, with
+ * `users: ['customers', 'staff']`. The broker makes both clients (the customers' in that organisation, the team's
+ * in the company's own) and answers the app's env, `AUTH_TEAM_CLIENT_ID` and `AUTH_TEAM_ORGANIZATION_ID`
+ * included. A workspace copy (`<key>-work`) is registered the same way in the test customers organisation, with
+ * its own two clients. The team signs in at the registrar record's `loginHost`, which is the company's own sign-in
+ * host, bound to the company's organisation; until that host's binding is applied the login pins the team's client
+ * to the company's organisation on the shared host.
+ *
+ * Every PUT mints a new `AUTH_APP_KEY` and the broker keeps the one it replaces valid for a window, so a repeat
+ * PUT is how a key that did not reach the app is delivered: there is nothing to record before the call.
+ */
+/** The step's kind: `coolify:registered-app`, keyed `<org id>:<entry>` (live) or `<org id>:<entry>-work`. */
+export declare const REGISTERED_APP_KIND = "registered-app";
+/** Milliseconds one registrar call may take. */
+export declare const REGISTRAR_API_TIMEOUT_MS = 20000;
+export type RegisteredCopy = 'live' | 'workspace';
+/** The body of the registration: what `PUT /apps/:organizationId/:name` takes (auth ADR 0003, 0008). */
+export interface RegisteredAppBody {
+    name: string;
+    origins: string[];
+    from: string;
+    registration: boolean;
+    users: ['customers', 'staff'];
+    /** Present when the entry declares `signIn`, as its broker entry would say. */
+    emailLink?: boolean;
+}
+/** What one copy's registration must say, without any key. Recorded as JSON once the app holds the answer. */
+export interface RegisteredAppWant {
+    copy: RegisteredCopy;
+    /** `<entry>` or `<entry>-work`: the name of the recorded answer. */
+    clientKey: string;
+    /** The organisation the app is registered in: the customers organisation, or the test customers one. */
+    organizationId: string;
+    /** The company's own organisation, where the broker makes the team's client. */
+    teamOrganizationId: string;
+    /** The registered name, the path's last part. */
+    name: string;
+    /** The registrar record's login host: where the team signs in (the company's own sign-in host). */
+    loginHost: string;
+    body: RegisteredAppBody;
+}
+/** The registered name of a copy: the `AUTH_APPS` name it would have had. */
+export declare const registeredAppName: (org: DeclaredOrg, clientKey: string) => string;
+/** The copies an entry has: live while it is live, a workspace copy while it has a server workspace. */
+export declare function registeredCopies(entry: HostingEntry): RegisteredCopy[];
+export declare const copyClientKey: (entry: HostingEntry, copy: RegisteredCopy) => string;
+/**
+ * Where the team of a company signs in: its own sign-in host once that host is bound to the company's
+ * organisation (an own org's sign-in applied, or a shared org's login-host step applied at it), else `null`:
+ * the login then pins the team's client to the company's organisation on the shared host.
+ */
+export declare function teamSignInHost(org: DeclaredOrg, recorded: Readonly<Record<string, string>>): string | null;
+/** What one copy's registration says, or each value still missing and the step that records it. */
+export declare function wantedRegisteredApp(org: DeclaredOrg, entry: HostingEntry, copy: RegisteredCopy, recorded: Readonly<Record<string, string>>): {
+    want: RegisteredAppWant;
+} | {
+    missing: BrokerEntryInput[];
+};
+/**
+ * One `coolify:registered-app` step per copy of an entry both sign in to, after the copy's app (live: the entry's
+ * `coolify:app`; workspace: the stage the workspace step made) and once the company's registrar is at the broker.
+ * Idempotent on the recorded want. Blocked, not planned (rule 2), while the host has not wired the registrar port,
+ * the issuer is unknown, the registrar is neither applied nor planned, or a value is neither recorded nor produced
+ * by a step in this plan.
+ */
+export declare function planRegisteredApps(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], host: {
+    registrarApi: boolean;
+    authIssuer: string | null;
+}): {
+    steps: DraftStep[];
+    blocked: UnmanagedItem[];
+};
+/** The company's registrar at the broker, as the step calls it. Foundry defines it; the host wires it. */
+export interface RegistrarApiPort {
+    /**
+     * `PUT <url>` with `Authorization: Bearer <registrarKey>` and the JSON body; answers the status and the parsed
+     * JSON body (or `null`). Must not log the key, the body or the answer, which holds the app's key.
+     */
+    putApp(input: {
+        url: string;
+        registrarKey: string;
+        body: RegisteredAppBody;
+    }): Promise<{
+        status: number;
+        body: unknown;
+    }>;
+}
+/** {@link RegistrarApiPort} over `fetch`, with a {@link REGISTRAR_API_TIMEOUT_MS} limit and no redirects. */
+export declare function httpRegistrarApi(options?: {
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}): RegistrarApiPort;
+/** `<registrar>/apps/<organisation>/<name>`, each part encoded. */
+export declare const registeredAppUrl: (registrarUrl: string, want: RegisteredAppWant) => string;
+/**
+ * Sends one copy's registration and reads the answer. Answers the ids to record and the app's key, which is
+ * registered for redaction (`secret`) before it is returned. The answer must be for the organisations asked for,
+ * carry the key twice and name two different clients, neither of them one of `refusedClientIds` (a workspace copy
+ * passes the live ones). Every error is fixed text with the status at most: never the key or the answer.
+ */
+export declare function sendRegistration(input: {
+    want: RegisteredAppWant;
+    registrarUrl: string;
+    registrarKey: string;
+    api: RegistrarApiPort;
+    secret: (value: string) => void;
+    refusedClientIds?: readonly string[];
+    label: string;
+}): Promise<{
+    env: RegisteredAppEnv;
+    appKey: string;
+}>;

package/dist/plan/registered-app.js

@@ -0,0 +1,262 @@
+import { isLiveEntry, ownsServices, signsInBoth, } from '../org.js';
+import { ZITADEL_ORG_SCOPE_KEY } from './agora.js';
+import { bgKey } from './blue-green.js';
+import { REGISTRAR_APPLIED_SCOPE_KEY } from './broker-registrar.js';
+import { entryHostnames, workspaceHost } from './hostnames.js';
+import { loginHostnameFor, ownAuthApplied } from './login-host.js';
+import { appStepKey } from './platform-diff.js';
+import { REGISTERED_APP_ENV_NAMES, registeredAppAppliedScopeKey, } from './registered-app-env.js';
+import { testCustomersOrgKey, workspaceClientKey } from './workspace-client.js';
+import { isServerWorkspace } from './workspace.js';
+/**
+ * ADR 0003 (auth ADR 0008, wtfalch/foundry#1109): an entry whose customers and team both sign in
+ * (`uses.auth.users: ['customers', 'staff']`) is not an `AUTH_APPS` entry with a client foundry makes. It is
+ * registered at the sign-in broker through the company's registrar (`PUT <registrar>/apps/<organisation>/<name>`,
+ * the key foundry holds at `registrarRef(org.id)`), in the customers organisation, with
+ * `users: ['customers', 'staff']`. The broker makes both clients (the customers' in that organisation, the team's
+ * in the company's own) and answers the app's env, `AUTH_TEAM_CLIENT_ID` and `AUTH_TEAM_ORGANIZATION_ID`
+ * included. A workspace copy (`<key>-work`) is registered the same way in the test customers organisation, with
+ * its own two clients. The team signs in at the registrar record's `loginHost`, which is the company's own sign-in
+ * host, bound to the company's organisation; until that host's binding is applied the login pins the team's client
+ * to the company's organisation on the shared host.
+ *
+ * Every PUT mints a new `AUTH_APP_KEY` and the broker keeps the one it replaces valid for a window, so a repeat
+ * PUT is how a key that did not reach the app is delivered: there is nothing to record before the call.
+ */
+/** The step's kind: `coolify:registered-app`, keyed `<org id>:<entry>` (live) or `<org id>:<entry>-work`. */
+export const REGISTERED_APP_KIND = 'registered-app';
+/** Milliseconds one registrar call may take. */
+export const REGISTRAR_API_TIMEOUT_MS = 20_000;
+/** The registered name of a copy: the `AUTH_APPS` name it would have had. */
+export const registeredAppName = (org, clientKey) => `${org.slug}-${clientKey}`;
+/** The copies an entry has: live while it is live, a workspace copy while it has a server workspace. */
+export function registeredCopies(entry) {
+    if (!signsInBoth(entry.uses?.auth))
+        return [];
+    return [
+        ...(isLiveEntry(entry) ? ['live'] : []),
+        ...(isServerWorkspace(entry) ? ['workspace'] : []),
+    ];
+}
+export const copyClientKey = (entry, copy) => copy === 'live' ? entry.key : workspaceClientKey(entry.key);
+/**
+ * Where the team of a company signs in: its own sign-in host once that host is bound to the company's
+ * organisation (an own org's sign-in applied, or a shared org's login-host step applied at it), else `null`:
+ * the login then pins the team's client to the company's organisation on the shared host.
+ */
+export function teamSignInHost(org, recorded) {
+    const host = loginHostnameFor(org);
+    if (ownsServices(org))
+        return ownAuthApplied(org, recorded) ? host : null;
+    return recorded[`zitadel:login-host:${org.id}`] === host ? host : null;
+}
+/** What one copy's registration says, or each value still missing and the step that records it. */
+export function wantedRegisteredApp(org, entry, copy, recorded) {
+    const auth = entry.uses?.auth;
+    const clientKey = copyClientKey(entry, copy);
+    const organizationId = copy === 'live'
+        ? recorded[`zitadel:customers:${org.id}`]
+        : recorded[testCustomersOrgKey(org.id)];
+    const teamOrganizationId = recorded[ZITADEL_ORG_SCOPE_KEY];
+    const mailDomain = recorded.mail_domain;
+    const origins = copy === 'live'
+        ? entryHostnames(org, entry).map((host) => `https://${host}`)
+        : [`https://${workspaceHost(org.slug, entry.key)}`];
+    const missing = [];
+    if (!organizationId) {
+        missing.push(copy === 'live'
+            ? { what: 'the customers organisation id', producedBy: ['zitadel', 'customers'] }
+            : { what: 'the test customers organisation id', producedBy: ['zitadel', 'customers-test'] });
+    }
+    if (!teamOrganizationId) {
+        missing.push({ what: "the org's ZITADEL org id", producedBy: ['zitadel', 'issuer'] });
+    }
+    if (!mailDomain)
+        missing.push({ what: 'the org mail domain', producedBy: ['coolify', 'mail'] });
+    if (origins.length === 0) {
+        missing.push({ what: 'its public address', producedBy: ['coolify', 'app'] });
+    }
+    if (!auth || !organizationId || !teamOrganizationId || !mailDomain || origins.length === 0) {
+        return { missing };
+    }
+    const name = registeredAppName(org, clientKey);
+    return {
+        want: {
+            copy,
+            clientKey,
+            organizationId,
+            teamOrganizationId,
+            name,
+            loginHost: loginHostnameFor(org),
+            body: {
+                name,
+                origins,
+                from: `${org.mail.noReplyLocalPart || 'noreply'}@${mailDomain}`,
+                registration: auth.registration === 'open',
+                users: ['customers', 'staff'],
+                ...(auth.signIn ? { emailLink: auth.signIn === 'email-code' } : {}),
+            },
+        },
+    };
+}
+/**
+ * One `coolify:registered-app` step per copy of an entry both sign in to, after the copy's app (live: the entry's
+ * `coolify:app`; workspace: the stage the workspace step made) and once the company's registrar is at the broker.
+ * Idempotent on the recorded want. Blocked, not planned (rule 2), while the host has not wired the registrar port,
+ * the issuer is unknown, the registrar is neither applied nor planned, or a value is neither recorded nor produced
+ * by a step in this plan.
+ */
+export function planRegisteredApps(org, recordedIds, plannedSteps, host) {
+    const steps = [];
+    const blocked = [];
+    const planned = (system, kind, key) => plannedSteps.some((p) => p.action.system === system &&
+        p.action.kind === kind &&
+        (key === undefined || p.action.key === key));
+    for (const entry of org.hosting.entries) {
+        for (const copy of registeredCopies(entry)) {
+            const clientKey = copyClientKey(entry, copy);
+            const key = appStepKey(org, clientKey);
+            const at = `${org.slug}'s ${clientKey} registration at the sign-in broker`;
+            const block = (why) => blocked.push({
+                description: `${at} is blocked, not planned: ${why}`,
+                key: `coolify:${REGISTERED_APP_KIND}:${clientKey}`,
+            });
+            if (!host.registrarApi) {
+                block('the host has not wired the registrar API port (registrarApi)');
+                continue;
+            }
+            if (!host.authIssuer) {
+                block('the sign-in issuer is not known yet');
+                continue;
+            }
+            if (!recordedIds[REGISTRAR_APPLIED_SCOPE_KEY] && !planned('coolify', 'broker-registrar')) {
+                block("the company's registrar is not at the sign-in broker yet");
+                continue;
+            }
+            const appReady = copy === 'live'
+                ? Boolean(recordedIds[`coolify:app:${appStepKey(org, entry.key)}`]) ||
+                    planned('coolify', 'app', appStepKey(org, entry.key))
+                : recordedIds[bgKey.stageState(entry.key)] === 'ok' ||
+                    plannedSteps.some((p) => p.action.system === 'coolify' &&
+                        p.action.kind === 'workspace' &&
+                        p.action.desired.entry === entry.key);
+            if (!appReady) {
+                block(copy === 'live' ? 'its app is not made yet' : "the workspace's app is not made yet");
+                continue;
+            }
+            // An app made again holds no key the broker gave: its copy is registered again.
+            const appRecorded = copy === 'live'
+                ? Boolean(recordedIds[`coolify:app:${appStepKey(org, entry.key)}`])
+                : recordedIds[bgKey.stageState(entry.key)] === 'ok';
+            const wanted = wantedRegisteredApp(org, entry, copy, recordedIds);
+            if ('want' in wanted) {
+                if (appRecorded &&
+                    recordedIds[registeredAppAppliedScopeKey(clientKey)] === JSON.stringify(wanted.want)) {
+                    continue;
+                }
+            }
+            else {
+                const unplanned = wanted.missing.filter(({ producedBy: [system, kind] }) => !planned(system, kind));
+                if (unplanned.length > 0) {
+                    block(`${unplanned.map((m) => m.what).join(', ')} not recorded yet`);
+                    continue;
+                }
+            }
+            const where = teamSignInHost(org, recordedIds);
+            steps.push({
+                action: {
+                    system: 'coolify',
+                    kind: REGISTERED_APP_KIND,
+                    key,
+                    desired: { copy, entry: entry.key, authIssuer: host.authIssuer },
+                },
+                step: {
+                    description: `register ${org.slug}'s ${clientKey} at the sign-in broker for its customers and its team (the team signs in at ${where ?? `the shared sign-in host, pinned to ${org.slug}'s organisation`}), and give the app its sign-in env`,
+                    destroys: false,
+                    migrates: false,
+                },
+            });
+        }
+    }
+    return { steps, blocked };
+}
+/** {@link RegistrarApiPort} over `fetch`, with a {@link REGISTRAR_API_TIMEOUT_MS} limit and no redirects. */
+export function httpRegistrarApi(options = {}) {
+    return {
+        async putApp({ url, registrarKey, body }) {
+            const res = await (options.fetch ?? fetch)(url, {
+                method: 'PUT',
+                headers: {
+                    Authorization: `Bearer ${registrarKey}`,
+                    'Content-Type': 'application/json',
+                    Accept: 'application/json',
+                },
+                body: JSON.stringify(body),
+                redirect: 'error',
+                signal: AbortSignal.timeout(options.timeoutMs ?? REGISTRAR_API_TIMEOUT_MS),
+            });
+            return { status: res.status, body: await res.json().catch(() => null) };
+        },
+    };
+}
+/** `<registrar>/apps/<organisation>/<name>`, each part encoded. */
+export const registeredAppUrl = (registrarUrl, want) => `${registrarUrl.replace(/\/+$/, '')}/apps/${encodeURIComponent(want.organizationId)}/${encodeURIComponent(want.name)}`;
+/**
+ * Sends one copy's registration and reads the answer. Answers the ids to record and the app's key, which is
+ * registered for redaction (`secret`) before it is returned. The answer must be for the organisations asked for,
+ * carry the key twice and name two different clients, neither of them one of `refusedClientIds` (a workspace copy
+ * passes the live ones). Every error is fixed text with the status at most: never the key or the answer.
+ */
+export async function sendRegistration(input) {
+    const { want, label } = input;
+    let answer;
+    try {
+        answer = await input.api.putApp({
+            url: registeredAppUrl(input.registrarUrl, want),
+            registrarKey: input.registrarKey,
+            body: want.body,
+        });
+    }
+    catch {
+        throw new Error(`${label}: the sign-in broker did not answer the registration; apply again`);
+    }
+    if (answer.status !== 200) {
+        throw new Error(`${label}: the sign-in broker refused the registration (status ${answer.status})`);
+    }
+    const body = answer.body;
+    const key = body?.key;
+    const env = body?.env;
+    if (typeof key !== 'string' || key.length < 32 || typeof env !== 'object' || env === null) {
+        throw new Error(`${label}: the sign-in broker's answer has no key or env`);
+    }
+    input.secret(key);
+    const values = env;
+    if (values.AUTH_APP_KEY !== key) {
+        throw new Error(`${label}: the sign-in broker's answer is not for the key it gave`);
+    }
+    for (const name of REGISTERED_APP_ENV_NAMES) {
+        if (typeof values[name] !== 'string' || values[name] === '') {
+            throw new Error(`${label}: the sign-in broker's answer has no ${name}`);
+        }
+    }
+    const answered = {
+        AUTH_ORGANIZATION_ID: values.AUTH_ORGANIZATION_ID,
+        AUTH_CLIENT_ID: values.AUTH_CLIENT_ID,
+        AUTH_TEAM_CLIENT_ID: values.AUTH_TEAM_CLIENT_ID,
+        AUTH_TEAM_ORGANIZATION_ID: values.AUTH_TEAM_ORGANIZATION_ID,
+    };
+    if (answered.AUTH_ORGANIZATION_ID !== want.organizationId) {
+        throw new Error(`${label}: the sign-in broker's answer is for another organisation`);
+    }
+    if (answered.AUTH_TEAM_ORGANIZATION_ID !== want.teamOrganizationId) {
+        throw new Error(`${label}: the sign-in broker's answer puts the team in another organisation than the company's own`);
+    }
+    if (answered.AUTH_CLIENT_ID === answered.AUTH_TEAM_CLIENT_ID) {
+        throw new Error(`${label}: the sign-in broker's answer gives the customers and the team one client`);
+    }
+    const refused = input.refusedClientIds ?? [];
+    if (refused.includes(answered.AUTH_CLIENT_ID) || refused.includes(answered.AUTH_TEAM_CLIENT_ID)) {
+        throw new Error(`${label}: the sign-in broker's answer names a client of the live app`);
+    }
+    return { env: answered, appKey: key };
+}

package/dist/plan/release-host.js

@@ -7,6 +7,7 @@ import { applyBlueGreenWeights, copiedEnv } from './blue-green-apply.js';
 import { ACTIONS_KEY_ENV, DEFAULT_WEIGHTS, LB_COLOR_HEADER, LB_PIN_HEADER, bgKey, formatWeights, mintPinKey, parseWeights, readPinKey, reportingEnv, } from './blue-green.js';
 import { waitForDeploymentFinished, waitForNewDeployment, } from './deploy-health.js';
 import { isNotFoundError } from './executor.js';
+import { isColorReportingEnv } from './reporting.js';
 import { runStageCopyRequest } from './stage-copy-host.js';
 const COMMIT = /^[0-9a-f]{40}$/;
 const APP_RELEASE_ENV = ['APP_TAG', 'APP_RELEASE', 'APP_MINIMUM_RELEASE'];
@@ -172,7 +173,7 @@ export function createReleaseHost(input) {
                         if (env.uuid &&
                             !keep.has(env.key) &&
                             (appId !== input.primaryBlueAppId || env.key === 'APP_MINIMUM_RELEASE') &&
-                            !env.key.startsWith('REPORTING_') &&
+                            !isColorReportingEnv(env.key) &&
                             env.key !== ACTIONS_KEY_ENV) {
                             await coolify.deleteEnv(appId, env.uuid);
                         }

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

@@ -0,0 +1,18 @@
+import { type DeclaredOrg } from '../org.js';
+import type { DraftStep } from './diff.js';
+/**
+ * While the company's Boule runs apps (`org.boule.apps`) and its reporting backend is applied, Boule's env
+ * holds `REPORTING_URL` and `REPORTING_OPERATOR_KEY` (the two names Boule's errors reader reads, wtfalch/boule
+ * PR 571). Boule mints a site key for each app copy with the operator key (site = the app key, environment
+ * `production` for live and `stage` for the workspace) and reads the app's errors 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 error reporting.
+ *
+ * One `coolify:reporting-boule` step keyed by the org id. `reporting_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 REPORTING_BOULE_APPLIED_SCOPE_KEY = "reporting_boule_applied";
+export declare const REPORTING_BOULE_ENV_NAMES: readonly ["REPORTING_URL", "REPORTING_OPERATOR_KEY"];
+export declare const reportingBouleMarker: (org: DeclaredOrg, backendAppId: string) => string;
+export declare function planReportingBoule(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[]): DraftStep[];

package/dist/plan/reporting-boule.js

@@ -0,0 +1,44 @@
+import { appsOn } from '../org.js';
+import { REPORTING_DEPLOYED_SCOPE_KEY, reportingUrlFor } from './reporting.js';
+/**
+ * While the company's Boule runs apps (`org.boule.apps`) and its reporting backend is applied, Boule's env
+ * holds `REPORTING_URL` and `REPORTING_OPERATOR_KEY` (the two names Boule's errors reader reads, wtfalch/boule
+ * PR 571). Boule mints a site key for each app copy with the operator key (site = the app key, environment
+ * `production` for live and `stage` for the workspace) and reads the app's errors 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 error reporting.
+ *
+ * One `coolify:reporting-boule` step keyed by the org id. `reporting_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 REPORTING_BOULE_APPLIED_SCOPE_KEY = 'reporting_boule_applied';
+export const REPORTING_BOULE_ENV_NAMES = ['REPORTING_URL', 'REPORTING_OPERATOR_KEY'];
+export const reportingBouleMarker = (org, backendAppId) => `${reportingUrlFor(org)}|${backendAppId}`;
+export function planReportingBoule(org, recordedIds, plannedSteps) {
+    const draft = (mode, description) => ({
+        action: { system: 'coolify', kind: 'reporting-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[REPORTING_BOULE_APPLIED_SCOPE_KEY];
+    if (!appsOn(org)) {
+        if (!marker || !recordedIds[`coolify:boule:${org.id}`])
+            return [];
+        return [
+            draft('retire', `take the reporting address and key out of ${org.slug}'s Boule env (the company's Boule runs no apps)`),
+        ];
+    }
+    if (!bouleKnown)
+        return [];
+    const backendApp = recordedIds[`coolify:reporting:${org.id}`];
+    const applied = Boolean(backendApp) && Boolean(recordedIds[REPORTING_DEPLOYED_SCOPE_KEY]);
+    if (!applied && !planned('reporting'))
+        return [];
+    if (applied && marker === reportingBouleMarker(org, backendApp))
+        return [];
+    return [
+        draft('write', `write REPORTING_URL and REPORTING_OPERATOR_KEY to ${org.slug}'s Boule env, restart Boule`),
+    ];
+}

package/dist/plan/reporting.d.ts

@@ -0,0 +1,90 @@
+import { type DeclaredOrg } from '../org.js';
+/**
+ * A company's own reporting backend (https://github.com/wtfalch/reporting, ADR 0002, `docs/plans/backend.md`
+ * slice 5): one Coolify app and one database per company, built from that repo's root Dockerfile, the same shape
+ * as the analytics backend (`plan/analytics.ts`). It is planned only while something uses it: a hosting entry
+ * declares `uses.reporting`, 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`), `REPORTING_OPERATOR_KEY` (generated once here), `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 `APP_URL`. 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.reporting`, or Boule runs apps: the backend is wanted. */
+export declare const reportingWanted: (org: Pick<DeclaredOrg, "boule" | "hosting">) => boolean;
+/** `reporting.<domain>`, or `<slug>-reporting.oikos.host` for a company without a domain. */
+export declare function reportingHostnameFor(org: Pick<DeclaredOrg, 'domain' | 'slug'>): string;
+/** The public address apps and Boule send to, `REPORTING_URL`. */
+export declare const reportingUrlFor: (org: Pick<DeclaredOrg, "domain" | "slug">) => string;
+/** The backend's database uuid, recorded beside the app's own id. */
+export declare const REPORTING_DATABASE_SCOPE_KEY = "coolify_reporting_database";
+/** Recorded once the app was deployed, as `coolify_boule_deployed` is for Boule. */
+export declare const REPORTING_DEPLOYED_SCOPE_KEY = "coolify_reporting_deployed";
+/** The env name the backend reads its operator key from; also Boule's name for it. */
+export declare const REPORTING_OPERATOR_KEY_ENV = "REPORTING_OPERATOR_KEY";
+/** The env names `desiredReportingEnv` writes, so the live reader knows which to read back. */
+export declare const REPORTING_MANAGED_ENV_KEYS: readonly ["APP_URL", "AUTH_ORGANIZATION_ID", "MAIL_FROM"];
+/**
+ * The Lettermint token the backend sends error alerts with (reporting#103): the company's `<slug>-app` token,
+ * joined as a consumer like a `uses.mail` entry. A secret: the executor writes it, the live reader says only
+ * whether it is there (`config.mailTokenHeld`), and no plan carries its value.
+ */
+export declare const REPORTING_MAIL_TOKEN_ENV = "LETTERMINT_API_TOKEN";
+/**
+ * The backend's sender, `Name <address>`: the company's display name and the same no-reply address the main
+ * app and Boule send from. The name is one line, and quoted when it holds a character an address header
+ * gives a meaning to.
+ */
+export declare function reportingMailFrom(org: DeclaredOrg, mailDomain: string): string;
+/**
+ * The `REPORTING_*` names foundry's reporting steps write: an entry's address and site key, and Boule's
+ * address and operator key. Every other `REPORTING_*` name on a blue/green color is the color's own
+ * (`REPORTING_COLOR`, `REPORTING_RELEASE`, `REPORTING_HEALTH_TOKEN`), so these are the ones a color copies from
+ * blue like any other env.
+ */
+export declare const REPORTING_SHARED_ENV_NAMES: readonly string[];
+/** Whether a `REPORTING_*` name belongs to one blue/green color and is never copied or removed by the copy. */
+export declare const isColorReportingEnv: (key: string) => boolean;
+/**
+ * What the backend's env must hold. `mailDomain` (the company's recorded mail domain, given only while its
+ * mail is on and not blocked) adds `MAIL_FROM`; the token is never here.
+ */
+export declare function desiredReportingEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, mailDomain?: string | null): {
+    env: Record<string, string>;
+    missing: string[];
+};
+export declare function reportingEnvDrift(desired: Readonly<Record<string, string>>, live: Readonly<Record<string, string>>): string[];
+export type ReportingEnvironment = 'production' | 'stage';
+/** The backend's operator API. Every call carries the company's own base URL and operator key. */
+export interface ReportingPort {
+    /**
+     * Mints a site key bound to `site` and `environment`; the secret is shown once. The same `name` again
+     * replaces the older key.
+     */
+    mintSiteKey(input: {
+        baseUrl: string;
+        operatorKey: string;
+        name: string;
+        site: string;
+        environment: ReportingEnvironment;
+    }): 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 ReportingPort}: `POST <baseUrl>/v1/site-keys` with `{ name, site, environment }` answers 201
+ * `{ id, secret, site, environment }`; `DELETE <baseUrl>/v1/site-keys/<id>` answers 204. A 201 that binds the
+ * key to another site or environment than asked is refused, so a key never reports where Boule does not read.
+ * Errors carry the status only, never a body, the key or the secret.
+ */
+export declare function httpReporting(options?: {
+    fetch?: typeof fetch;
+}): ReportingPort;