@wtfalch/foundry 0.7.1 → 0.9.0

package/dist/plan/platform-diff.js

@@ -1,3 +1,6 @@
+import { VERSIONS } from '../bootstrap/versions.js';
+import { APP_ENTRY_KEY } from '../org.js';
+import { VERSION_CHANGE_KIND, } from '../plan.js';
 /**
  * The `Plan` (#19's public contract) a {@link PlatformPlanDetail} carries,
  * mirroring `diff.ts`'s `toPlan`. There is no separate platform-shaped `Plan`
@@ -12,6 +15,7 @@ export function toPlatformPlan(detail, ownerOrgId) {
         orgId: ownerOrgId,
         steps: detail.plannedSteps.map((p) => p.step),
         unmanaged: detail.unmanaged,
+        versionChanges: detail.versionChanges,
     };
 }
 function resourceKey(system, kind, key) {
@@ -25,6 +29,72 @@ function resourceKey(system, kind, key) {
  * an org's own (which is keyed by that org's id).
  */
 export const PLATFORM_AUTH_KEY = 'platform:auth';
+/**
+ * #251: the ZITADEL image tag the last successful auth run actually set
+ * live. `provisionPlatformAuth` records this only when it set the tag --
+ * today that is creation alone, `findOrCreatePlatformApp`'s own
+ * `justCreated`, since nothing yet patches `docker_registry_image_tag` on
+ * an app found already running (unlike mail, which does). Recording it on
+ * every run regardless, the way the app id itself is recorded, would make
+ * {@link versionNotAppliedLine} compare the pinned version against a value
+ * that was never actually applied.
+ */
+export const PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY = 'auth_zitadel_applied_image_tag';
+/**
+ * #251: the Synapse/MAS image tags an org's calls Matrix stack last
+ * successful apply actually set live. `coolifyCalls` (`executor.ts`)
+ * records these only at creation, for the same reason
+ * {@link PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY} is: nothing yet
+ * patches either tag on an app `findOrCreateCallsApp` found already
+ * running.
+ */
+export const CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY = 'calls_synapse_applied_image_tag';
+export const CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY = 'calls_mas_applied_image_tag';
+/**
+ * One line for a service whose own step genuinely redeploys when its
+ * recorded applied ref differs from the declared or pinned one (mail,
+ * archon, ai, files, integrations) -- `from` undefined (nothing applied
+ * yet, a first-ever apply) or already equal to `to` means nothing to
+ * report.
+ */
+export function versionChangeLine(service, from, to, note) {
+    if (!from || from === to)
+        return null;
+    return {
+        kind: VERSION_CHANGE_KIND,
+        service,
+        description: `${service}: ${from} -> ${to} (${note})`,
+    };
+}
+/**
+ * One line for a service whose own step never patches a running app's
+ * image tag once created -- zitadel, synapse, mas. #251 round 3: a prior
+ * attempt worded this line the same as {@link versionChangeLine}'s
+ * "X -> Y (image, redeploy)", which promised a redeploy `apply` can never
+ * actually perform for these three. `appLive` false means nothing live yet
+ * to compare against (no line, the same first-apply case
+ * {@link versionChangeLine} has); a live app with no recorded `applied`
+ * value predates this tracking and is reported as `running tag unknown`
+ * rather than silently showing nothing.
+ */
+export function versionNotAppliedLine(service, appLive, applied, pinned) {
+    if (!appLive)
+        return null;
+    if (!applied) {
+        return {
+            kind: VERSION_CHANGE_KIND,
+            service,
+            description: `${service}: pinned ${pinned}, running tag unknown`,
+        };
+    }
+    if (applied === pinned)
+        return null;
+    return {
+        kind: VERSION_CHANGE_KIND,
+        service,
+        description: `${service}: pinned ${pinned}, running ${applied} (not applied by foundry)`,
+    };
+}
 /**
  * Scope keys (colon-free, so never mistaken for a `system:kind:key` resource
  * id) for foundry's ZITADEL admin machine user. The delivered key is the guard
@@ -67,6 +137,10 @@ export const PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY = 'archon_applied_broker_a
 export const PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY = 'archon_gate_closed';
 export const PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY = 'zitadel_platform_admin_user_id';
 export const PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY = 'zitadel_platform_admin_user_undelivered';
+/** #283: the created instance's id, recorded once its owner token is delivered. */
+export const PLATFORM_AUTH_INSTANCE_SCOPE_KEY = 'zitadel_platform_instance_id';
+/** #283: an instance that may exist without a delivered owner token; blocks creating another. */
+export const PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY = 'zitadel_platform_instance_undelivered';
 /**
  * #216 (building on #209/#215): the `IAM_LOGIN_CLIENT` machine user minted
  * for the login app and the broker, mirroring
@@ -274,24 +348,34 @@ export function platformMailMxHost(apex) {
 export const ORG_MAIL_APPLIED_APEX_SCOPE_KEY = 'mail_applied_apex';
 export const ORG_MAIL_APPLIED_HOST_SCOPE_KEY = 'mail_applied_host';
 /**
- * #243: the org's `hosting.appEnv` values the last `coolify:app` apply pushed,
- * recorded as one JSON object (env name to value; ids and a domain, never a
- * secret). `planApp` plans the step again when {@link resolveAppEnv} differs
- * from it, so a changed map reaches an app that is already live.
+ * The key of an org's `app` hosting entry in a `coolify:app` or
+ * `cloudflare:access` step and in the ids recorded for it:
+ * `<orgId>:<entry key>`, so a second entry cannot collide with the first.
+ */
+export function appStepKey(org) {
+    return `${org.id}:${APP_ENTRY_KEY}`;
+}
+/**
+ * #243: the org's `app` entry's `env` values the last `coolify:app` apply
+ * pushed, recorded as one JSON object (env name to value; ids and a domain,
+ * never a secret). `planApp` plans the step again when {@link resolveAppEnv}
+ * differs from it, so a changed map reaches an app that is already live. The
+ * `.app` suffix is the entry key; a scope key holds no `:`, so
+ * `storeRecordedIds` still filters it out.
  */
-export const APP_ENV_APPLIED_SCOPE_KEY = 'app_env_applied';
+export const APP_ENV_APPLIED_SCOPE_KEY = `app_env_applied.${APP_ENTRY_KEY}`;
 /**
  * #239: set to '1' once an app has been restarted after its database URLs
  * were pushed. Not a URL. Without it a crash between the push and the restart
  * would leave a stale container that no plan notices.
  */
-export const DB_ENV_APPLIED_SCOPE_KEY = 'db_env_applied';
+export const DB_ENV_APPLIED_SCOPE_KEY = `db_env_applied.${APP_ENTRY_KEY}`;
 /**
- * The `hosting.appEnv` entries whose source has a recorded value, in env-name
- * order, and the env names whose source has none yet. Shared by `planApp` and
- * the executor's `pushAppEnv` so both read the same recorded ids.
+ * The entry's `env` values that have a value, in env-name order, and the env
+ * names whose source has none yet. Shared by `planApp` and the executor's
+ * `pushAppEnv` so both read the same recorded ids.
  */
-export function resolveAppEnv(org, recorded) {
+export function resolveAppEnv(org, entry, recorded) {
     const sources = {
         filesOrganisationId: recorded[`files:organisation:${org.id}`],
         aiOrganisationId: recorded[`ai:organisation:${org.id}`],
@@ -299,12 +383,12 @@ export function resolveAppEnv(org, recorded) {
     };
     const values = {};
     const unresolved = [];
-    for (const [name, source] of Object.entries(org.hosting.appEnv).sort(([a], [b]) => a < b ? -1 : 1)) {
-        const value = sources[source];
+    for (const [name, declared] of Object.entries(entry.env).sort(([a], [b]) => (a < b ? -1 : 1))) {
+        const value = typeof declared === 'string' ? declared : sources[declared.from];
         if (value)
             values[name] = value;
-        else
-            unresolved.push([name, source]);
+        else if (typeof declared !== 'string')
+            unresolved.push([name, declared.from]);
     }
     return { values, unresolved };
 }
@@ -490,6 +574,40 @@ export function planPlatform(platform, live, options = {}) {
     const archon = planArchon(platform, recordedIds, blocked.archon, authReady, drifted.archon);
     if (archon.step)
         plannedSteps.push(archon.step);
+    // #257: after every service above, so a database any of them just
+    // recorded is already visible to `recordedIds` on this same plan.
+    const backups = planBackups(byKey, claimed, recordedIds, blocked.backupExecutorMissing ?? false);
+    plannedSteps.push(...backups.steps);
+    // #251: one line per service whose recorded applied ref no longer matches
+    // what the next apply would use (or, for zitadel, what is actually live).
+    // Never pushed into `plannedSteps` -- see `VersionChangeItem`'s own doc
+    // comment (`plan.ts`) for why. Withheld exactly where that service's own
+    // step is blocked: advertising a version it cannot run yet, or cannot be
+    // read for, is premature, not informational.
+    const versionChanges = [];
+    for (const change of [
+        mail.blocked
+            ? null
+            : versionChangeLine('mail', recordedIds[PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY], platform.mail.gitRef, 'image, redeploy'),
+        archon.blocked
+            ? null
+            : versionChangeLine('archon', recordedIds[PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY], platform.archon.gitRef, 'git ref, redeploy'),
+        ai.blocked
+            ? null
+            : versionChangeLine('ai', recordedIds[PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY], platform.ai.gitRef, 'git ref, redeploy'),
+        files.blocked
+            ? null
+            : versionChangeLine('files', recordedIds[PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY], platform.files.gitRef, 'git ref, redeploy'),
+        integrations.blocked
+            ? null
+            : versionChangeLine('integrations', recordedIds[PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY], platform.integrations.gitRef, 'git ref, redeploy'),
+        auth.blocked
+            ? null
+            : versionNotAppliedLine('zitadel', Boolean(recordedIds[resourceKey('coolify', 'app', PLATFORM_AUTH_KEY)]), recordedIds[PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY], VERSIONS.zitadel),
+    ]) {
+        if (change)
+            versionChanges.push(change);
+    }
     const unmanaged = live
         .filter((r) => !claimed.has(resourceKey(r.system, r.kind, r.key)))
         .map((r) => ({
@@ -516,7 +634,8 @@ export function planPlatform(platform, live, options = {}) {
         unmanaged.push({ description: ai.blocked, key: 'ai' });
     if (archon.blocked)
         unmanaged.push({ description: archon.blocked, key: 'archon' });
-    return { plannedSteps, unmanaged };
+    unmanaged.push(...backups.blocked);
+    return { plannedSteps, unmanaged, versionChanges };
 }
 /**
  * The platform's own Cloudflare zone for its shared apex (`platform.ts`'s
@@ -610,6 +729,98 @@ function planJobs(platform, byKey, claimed, observable) {
         },
     };
 }
+/**
+ * #257: the six platform databases foundry itself creates, each keyed by
+ * the scope id `platform-providers.ts`'s own `createPostgresDatabase` call
+ * site records once that service's database exists --
+ * `JOBS_DATABASE_SCOPE_KEY`, `PLATFORM_AUTH_DB_SCOPE_KEY`,
+ * `PLATFORM_ARCHON_DB_SCOPE_KEY`, `PLATFORM_AI_DB_SCOPE_KEY`,
+ * `PLATFORM_FILES_DB_SCOPE_KEY`, `INTEGRATIONS_DATABASE_SCOPE_KEY`. Those
+ * constants stay module-private in `platform-providers.ts`, grouped with
+ * each service's other scope keys; the string values here are a second,
+ * documented copy rather than an import, so `planBackups` below never
+ * reaches into that file and `platform-providers.ts` keeps importing *from*
+ * this one, never the other way (every other scope key constant already
+ * flows that direction). `platform-providers.test.ts`'s own
+ * `coolify:backup` suite exercises both the executor's real constants and
+ * this planner end to end, so a renamed key on either side shows up as a
+ * database the planner can no longer see -- reported blocked, per rule 2,
+ * never a wrong step.
+ */
+export const PLATFORM_BACKUP_DATABASE_SCOPE_KEYS = {
+    jobs: 'coolify_jobs_database',
+    auth: 'coolify_platform_auth_database',
+    archon: 'coolify_platform_archon_database',
+    ai: 'coolify_platform_ai_database',
+    files: 'coolify_platform_files_database',
+    integrations: 'coolify_integrations_database',
+};
+export const PLATFORM_BACKUP_SERVICE_KEYS = [
+    'jobs',
+    'auth',
+    'archon',
+    'ai',
+    'files',
+    'integrations',
+];
+/**
+ * #257: a nightly backup for each platform database foundry itself creates,
+ * one `coolify:backup:<service>` step per service -- unconditional, the
+ * same "no enabled toggle, always wanted" shape {@link planApexZone} has,
+ * since a database that exists always wants a backup whether or not its own
+ * service is currently `enabled` (platform-steps rule 2, this repo's
+ * CLAUDE.md: blocked, not failing). A service with no database recorded yet
+ * has nothing to back up, so it is reported blocked rather than planned --
+ * the same way `planJobs` blocks rather than plans with no Coolify reader --
+ * and so is every service once a database exists but `executorMissing` says
+ * the host built the platform executor without backup dependencies (the
+ * R2/S3 credentials `FoundryPlatformStepExecutorOptions.backup` carries).
+ * Once a step's own `coolify:backup:<service>` resource is live, it is
+ * claimed and never re-planned: like every other provision-only step here,
+ * there is no park branch for a backup already scheduled.
+ */
+function planBackups(byKey, claimed, recordedIds, executorMissing) {
+    const steps = [];
+    const blocked = [];
+    for (const service of PLATFORM_BACKUP_SERVICE_KEYS) {
+        const key = resourceKey('coolify', 'backup', service);
+        const live = byKey.get(key);
+        if (live) {
+            claimed.add(key);
+            continue;
+        }
+        // No database yet is not reported: unlike a Coolify reader or a backup
+        // executor missing (below), there is nothing here for a host to fix --
+        // the database arrives on its own once that service's own step is
+        // enabled and applied, and this step simply follows next time. Reporting
+        // it would make every platform with a service not yet applied carry a
+        // standing "blocked" note nobody can act on.
+        const databaseId = recordedIds[PLATFORM_BACKUP_DATABASE_SCOPE_KEYS[service]];
+        if (!databaseId)
+            continue;
+        if (executorMissing) {
+            blocked.push({
+                description: `platform:backup:${service} is blocked, not planned: the host built the platform executor without its backup dependencies`,
+                key: `backup:${service}`,
+            });
+            continue;
+        }
+        steps.push({
+            action: {
+                system: 'coolify',
+                kind: 'backup',
+                key: service,
+                desired: { databaseId },
+            },
+            step: {
+                description: `schedule a nightly R2 backup of the platform's ${service} database`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    return { steps, blocked };
+}
 /**
  * The platform's shared calls SFU (#170), keyed `sfu:livekit:platform` --
  * there is exactly one, so `key` names the platform itself rather than a
@@ -803,6 +1014,16 @@ function planAuth(platform, recordedIds, executorBlocked, executorMissing, authD
             blocked: `the platform's sign-in is blocked, not planned: the admin key of ZITADEL machine user ${undelivered} was minted but never delivered and cannot be shown again; delete that user in ZITADEL and remove the recorded key ${PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY} to mint a new one`,
         };
     }
+    // #283: an instance may exist whose owner token never reached the host.
+    const instanceLost = recordedIds[PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY];
+    if (instanceLost &&
+        !recordedIds[PLATFORM_AUTH_INSTANCE_SCOPE_KEY] &&
+        !recordedIds[PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY]) {
+        return {
+            step: null,
+            blocked: `the platform's sign-in is blocked, not planned: a ZITADEL instance (${instanceLost}) may exist without a delivered owner token; delete it with the system API (DELETE /system/v1/instances/{id}) or redeploy the ZITADEL database, then remove the recorded key ${PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY}`,
+        };
+    }
     // #211 round 6: the executor itself is unusable on this host -- nothing to
     // plan, whatever the broker's recorded state says.
     if (executorMissing)

package/dist/plan/platform-providers.d.ts

@@ -102,6 +102,13 @@ export interface FoundryPlatformStepExecutorOptions {
      * -- optional for the same reason as {@link auth}.
      */
     archon?: PlatformArchonDeps;
+    /**
+     * #257: dependencies for every `coolify:backup:<service>` step -- optional
+     * for the same reason as `auth`; a service whose database already exists
+     * without this set has its backup step reported blocked rather than
+     * planned.
+     */
+    backup?: PlatformBackupDeps;
 }
 /**
  * The real {@link PlatformStepExecutor} for the two steps built so far:
@@ -159,6 +166,10 @@ export interface FoundryPlatformStepExecutorOptions {
  * #175 adds `coolify:app` keyed {@link PLATFORM_ARCHON_KEY}, Archon itself
  * ({@link provisionPlatformArchon}), once a host passes
  * {@link PlatformArchonDeps}.
+ *
+ * #257 adds `coolify:backup:<service>`, a nightly R2 backup of each
+ * platform database ({@link provisionPlatformBackup}), once a host passes
+ * {@link PlatformBackupDeps}.
  */
 export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor {
     private readonly cloudflare;
@@ -172,6 +183,7 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
     private readonly files?;
     private readonly ai?;
     private readonly archon?;
+    private readonly backup?;
     constructor(cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'createZone'>, declaredOrgStore: Pick<DeclaredOrgStore, 'findOrgIdForZone' | 'list'>, options?: FoundryPlatformStepExecutorOptions);
     blockedSteps(platform: DeclaredPlatform, recordedIds?: Readonly<Record<string, string>>): Promise<{
         auth?: string;
@@ -182,6 +194,7 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
         ai?: string;
         archon?: string;
         mail?: string;
+        backupExecutorMissing?: boolean;
     }>;
     /**
      * Whether Archon's live Access policy lets through anyone but the declared
@@ -210,6 +223,13 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
     private executeSfu;
     private coolifyJobs;
 }
+/**
+ * #283: the ref the new instance's IAM_OWNER machine token (a PAT) is
+ * delivered under, once. A host reads it back to build `zitadelForInstance`
+ * (see {@link provisionPlatformAuth}'s doc comment). Distinct from the admin
+ * key delivered under `zitadel:platform:admin`.
+ */
+export declare const PLATFORM_AUTH_INSTANCE_BEARER_REF = "zitadel:platform:instanceBearer";
 /**
  * The fixed description Stalwart's admin API key is minted under
  * (`StalwartClient.createApiKey`'s own signature returns only the secret,
@@ -580,6 +600,28 @@ export declare const INTEGRATIONS_MANAGEMENT_ISSUER = "foundry";
  * its signed request; fixed, since there is one key until rotation is built.
  */
 export declare const INTEGRATIONS_MANAGEMENT_KEY_ID = "foundry-1";
+/**
+ * #257: everything {@link provisionPlatformBackup} needs beyond
+ * {@link PlatformStepExecutionContext} -- the narrow Coolify slice for the
+ * backup calls themselves, and the R2 (or any S3-compatible) bucket every
+ * platform database's dump lands in. A person creates or confirms the
+ * bucket and these credentials by hand (the issue's own "Human steps"); this
+ * package only ever registers the bucket with Coolify and schedules the
+ * dump, never creates or reads the bucket itself.
+ */
+export interface PlatformBackupDeps {
+    coolify: Pick<CoolifyPort, 'listS3Storages' | 'createS3Storage' | 'listDatabaseBackups' | 'createDatabaseBackup'>;
+    r2: {
+        endpoint: string;
+        bucket: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+        /** R2 takes `'auto'` (`CoolifyPort.createS3Storage`'s own doc comment). Default `'auto'`. */
+        region?: string;
+    };
+    /** A cron string or one of Coolify's names (`daily`, `weekly`, ...). Default `'daily'`. */
+    frequency?: string;
+}
 /**
  * The real {@link PlatformCloudflareReader}: the platform's apex zone as
  * `planApexZone` expects to see it, and nothing else. The zone's DNS records
@@ -609,7 +651,7 @@ export declare class ProvidersPlatformCloudflareReader implements PlatformCloudf
 export declare class ProvidersPlatformCoolifyReader implements PlatformCoolifyReader {
     private readonly client;
     private readonly platformStore;
-    constructor(client: Pick<CoolifyPort, 'getApplication'>, platformStore: Pick<PlatformStore, 'getServiceIds'>);
+    constructor(client: Pick<CoolifyPort, 'getApplication' | 'listDatabaseBackups'>, platformStore: Pick<PlatformStore, 'getServiceIds'>);
     listResources(): Promise<LiveResource[]>;
 }
 export {};