@wtfalch/foundry 0.6.0 → 0.8.0

package/dist/plan/platform-diff.js

@@ -1,3 +1,5 @@
+import { VERSIONS } from '../bootstrap/versions.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 +14,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 +28,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
@@ -273,6 +342,41 @@ 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.
+ */
+export const APP_ENV_APPLIED_SCOPE_KEY = 'app_env_applied';
+/**
+ * #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';
+/**
+ * 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.
+ */
+export function resolveAppEnv(org, recorded) {
+    const sources = {
+        filesOrganisationId: recorded[`files:organisation:${org.id}`],
+        aiOrganisationId: recorded[`ai:organisation:${org.id}`],
+        mailDomain: recorded.mail_domain,
+    };
+    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];
+        if (value)
+            values[name] = value;
+        else
+            unresolved.push([name, source]);
+    }
+    return { values, unresolved };
+}
 /**
  * #172: the resource key `planAi` plans under and `FoundryPlatformStepExecutor`
  * dispatches on, the same `platform:<service>` shape as
@@ -455,6 +559,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) => ({
@@ -481,7 +619,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
@@ -575,6 +714,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

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
@@ -291,7 +304,7 @@ export interface PlatformMailRuntime {
  * {@link PlatformStepExecutionContext}, bundled like {@link PlatformAuthDeps}.
  */
 export interface PlatformArchonDeps {
-    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'requireGithubApp' | 'createGithubAppApplication' | 'createDockerfileApplication' | 'createPostgresDatabase' | 'getDatabase' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy'>;
+    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'requireGithubApp' | 'createGithubAppApplication' | 'createDockerfileApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy'>;
     cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'findTunnelByName' | 'createTunnel' | 'putTunnelConfig' | 'getTunnelToken' | 'findDnsRecord' | 'createDnsRecord' | 'updateDnsRecord' | 'listAccessApps' | 'createAccessApp' | 'listAccessPolicies' | 'createAccessPolicy' | 'deleteAccessApp'>;
     /** Must target the platform's own ZITADEL instance, or `zitadelForInstance` must be set. */
     zitadel: Pick<ZitadelPort, 'findOrCreateOrg' | 'findOrCreateProject' | 'createOidcApp' | 'listApps' | 'deleteApp'>;
@@ -580,6 +593,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 +644,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 {};