@wtfalch/foundry 0.9.0 → 0.11.0

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

@@ -316,26 +316,67 @@ export declare function platformMailMxHost(apex: string): string;
 export declare const ORG_MAIL_APPLIED_APEX_SCOPE_KEY = "mail_applied_apex";
 export declare const ORG_MAIL_APPLIED_HOST_SCOPE_KEY = "mail_applied_host";
 /**
- * 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.
+ * The key of a 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 declare function appStepKey(org: DeclaredOrg): string;
+export declare function appStepKey(org: DeclaredOrg, entryKey?: string): string;
 /**
- * #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.
+ * The Coolify name of a hosting entry's app: `<slug>` for the `app` entry, so
+ * the move to a list finds the app that runs today, `<slug>-<key>` for any
+ * other.
  */
-export declare const APP_ENV_APPLIED_SCOPE_KEY = "app_env_applied.app";
+export declare function appNameFor(org: DeclaredOrg, entry: HostingEntry): string;
+/**
+ * #243: the 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 `.<key>`
+ * suffix is the entry key; a scope key holds no `:`, so `storeRecordedIds`
+ * still filters it out.
+ */
+export declare function appEnvAppliedScopeKey(entryKey: string): string;
 /**
  * #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 declare const DB_ENV_APPLIED_SCOPE_KEY = "db_env_applied.app";
+export declare function dbEnvAppliedScopeKey(entryKey: string): string;
+/**
+ * The settings `coolifyApp` owns on an entry's app (`folder`, `port`,
+ * `autoDeploy`) as the JSON the marker below holds. `coolifyApp` records it
+ * on create and after it patches the app, and `planApp` plans the step again
+ * when the declared settings differ from it.
+ */
+export interface AppSettings {
+    folder: string | null;
+    port: number | null;
+    autoDeploy: boolean;
+}
+export declare function appSettingsOf(entry: HostingEntry): AppSettings;
+/** What an app that predates the marker has: Coolify's own defaults, so it plans no change. */
+export declare const DEFAULT_APP_SETTINGS: AppSettings;
+export declare function appSettingsAppliedScopeKey(entryKey: string): string;
+/**
+ * Set before an adopted app's settings are patched, cleared once its deploy
+ * succeeded (an empty value is not pending): a failed deploy replans whatever
+ * the markers say (#311).
+ */
+export declare function appDeployPendingScopeKey(entryKey: string): string;
+/** The settings the app has: the marker, or the defaults when there is none. */
+export declare function appliedAppSettings(recorded: Readonly<Record<string, string>>, entryKey: string): AppSettings;
+/**
+ * The names `coolifyApp` last put in the entry's Coolify `domains`, as a JSON
+ * array (`[]` for an internal entry). `planApp` plans the step again, with a
+ * redeploy, when {@link entryHostnames} differs from it.
+ */
+export declare function appDomainsAppliedScopeKey(entryKey: string): string;
+/**
+ * The names the app has: the marker, or for an app that predates it the one
+ * name it was created with (the `app` entry's address, nothing for any other
+ * entry), so an app that runs today plans no change.
+ */
+export declare function appliedAppDomains(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, entryKey: string): string[];
 /**
  * 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
@@ -510,11 +551,23 @@ export interface PlanPlatformOptions {
      * include list is not the declared one. `auth` (#216 round 4): the
      * login-client PAT recorded under
      * {@link PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY} is no longer the sole
-     * live PAT on that ZITADEL machine user.
+     * live PAT on that ZITADEL machine user. `backupStorage` (#257 fix round
+     * 2): the registered R2 storage's live fingerprint no longer matches the
+     * host's configured bucket/endpoint/key/secret, or the recorded storage
+     * uuid is no longer in Coolify's live list -- see `planBackups`'s own doc
+     * comment for why this is the one drift flag that can fire even once
+     * every per-service backup step is claimed. `backupStorageBlocked` (#257
+     * fix round 4, point 4): set instead of `backupStorage` when the liveness
+     * check itself failed (Coolify unreachable, credentials revoked) -- the
+     * plan is never failed over it, but it is reported in `unmanaged` rather
+     * than only logged, so a persistent failure is visible instead of silently
+     * retried forever.
      */
     drifted?: {
         archon?: boolean;
         auth?: boolean;
+        backupStorage?: boolean;
+        backupStorageBlocked?: string;
     };
 }
 /**

package/dist/plan/platform-diff.js

@@ -1,6 +1,7 @@
 import { VERSIONS } from '../bootstrap/versions.js';
 import { APP_ENTRY_KEY } from '../org.js';
 import { VERSION_CHANGE_KIND, } from '../plan.js';
+import { legacyAppHostname } from './hostnames.js';
 /**
  * The `Plan` (#19's public contract) a {@link PlatformPlanDetail} carries,
  * mirroring `diff.ts`'s `toPlan`. There is no separate platform-shaped `Plan`
@@ -348,28 +349,80 @@ 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';
 /**
- * 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.
+ * The key of a 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}`;
+export function appStepKey(org, entryKey = APP_ENTRY_KEY) {
+    return `${org.id}:${entryKey}`;
 }
 /**
- * #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.
+ * The Coolify name of a hosting entry's app: `<slug>` for the `app` entry, so
+ * the move to a list finds the app that runs today, `<slug>-<key>` for any
+ * other.
  */
-export const APP_ENV_APPLIED_SCOPE_KEY = `app_env_applied.${APP_ENTRY_KEY}`;
+export function appNameFor(org, entry) {
+    return entry.key === APP_ENTRY_KEY ? org.slug : `${org.slug}-${entry.key}`;
+}
+/**
+ * #243: the 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 `.<key>`
+ * suffix is the entry key; a scope key holds no `:`, so `storeRecordedIds`
+ * still filters it out.
+ */
+export function appEnvAppliedScopeKey(entryKey) {
+    return `app_env_applied.${entryKey}`;
+}
 /**
  * #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.${APP_ENTRY_KEY}`;
+export function dbEnvAppliedScopeKey(entryKey) {
+    return `db_env_applied.${entryKey}`;
+}
+export function appSettingsOf(entry) {
+    return { folder: entry.folder, port: entry.port, autoDeploy: entry.autoDeploy };
+}
+/** What an app that predates the marker has: Coolify's own defaults, so it plans no change. */
+export const DEFAULT_APP_SETTINGS = { folder: null, port: null, autoDeploy: true };
+export function appSettingsAppliedScopeKey(entryKey) {
+    return `app_settings_applied.${entryKey}`;
+}
+/**
+ * Set before an adopted app's settings are patched, cleared once its deploy
+ * succeeded (an empty value is not pending): a failed deploy replans whatever
+ * the markers say (#311).
+ */
+export function appDeployPendingScopeKey(entryKey) {
+    return `app_deploy_pending.${entryKey}`;
+}
+/** The settings the app has: the marker, or the defaults when there is none. */
+export function appliedAppSettings(recorded, entryKey) {
+    const marker = recorded[appSettingsAppliedScopeKey(entryKey)];
+    return marker ? JSON.parse(marker) : DEFAULT_APP_SETTINGS;
+}
+/**
+ * The names `coolifyApp` last put in the entry's Coolify `domains`, as a JSON
+ * array (`[]` for an internal entry). `planApp` plans the step again, with a
+ * redeploy, when {@link entryHostnames} differs from it.
+ */
+export function appDomainsAppliedScopeKey(entryKey) {
+    return `app_domains_applied.${entryKey}`;
+}
+/**
+ * The names the app has: the marker, or for an app that predates it the one
+ * name it was created with (the `app` entry's address, nothing for any other
+ * entry), so an app that runs today plans no change.
+ */
+export function appliedAppDomains(org, recorded, entryKey) {
+    const marker = recorded[appDomainsAppliedScopeKey(entryKey)];
+    if (marker)
+        return JSON.parse(marker);
+    return entryKey === APP_ENTRY_KEY ? [legacyAppHostname(org)] : [];
+}
 /**
  * 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
@@ -576,7 +629,7 @@ export function planPlatform(platform, live, options = {}) {
         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);
+    const backups = planBackups(byKey, claimed, recordedIds, blocked.backupExecutorMissing ?? false, drifted.backupStorage ?? false, drifted.backupStorageBlocked);
     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).
@@ -778,15 +831,36 @@ export const PLATFORM_BACKUP_SERVICE_KEYS = [
  * 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.
+ *
+ * #257 fix round 2: that "claimed, never re-planned" rule is exactly why a
+ * rotated R2 credential would otherwise never reach Coolify again once every
+ * service's own backup is live -- nothing left in this loop ever calls
+ * `ensurePlatformBackupStorage` (`platform-providers.ts`) again. `storageDrifted`
+ * (the host's own `driftedSteps`, read fresh each plan) is the signal that
+ * self-heal is needed; when it is true, this plans exactly one extra
+ * `coolify:backup-storage:platform` step, independent of every per-service
+ * step's own claimed status, so the self-heal runs again whether or not any
+ * service step is also being (re)planned this round. It is never itself
+ * "claimed" against a live resource -- there is nothing to read live for a
+ * storage push, only to react to -- so it simply stops being planned the
+ * moment `storageDrifted` goes false again.
+ *
+ * #257 fix round 4, point 4: `storageBlocked`, when set, means the host's own
+ * `driftedSteps` could not even tell whether the storage is drifted (a
+ * Coolify read failed) -- reported in `blocked` instead of planning the
+ * self-heal step, so a persistent failure is visible in the plan rather than
+ * only logged and retried silently forever.
  */
-function planBackups(byKey, claimed, recordedIds, executorMissing) {
+function planBackups(byKey, claimed, recordedIds, executorMissing, storageDrifted, storageBlocked) {
     const steps = [];
     const blocked = [];
+    let anyDatabase = false;
     for (const service of PLATFORM_BACKUP_SERVICE_KEYS) {
         const key = resourceKey('coolify', 'backup', service);
         const live = byKey.get(key);
         if (live) {
             claimed.add(key);
+            anyDatabase = true;
             continue;
         }
         // No database yet is not reported: unlike a Coolify reader or a backup
@@ -798,6 +872,7 @@ function planBackups(byKey, claimed, recordedIds, executorMissing) {
         const databaseId = recordedIds[PLATFORM_BACKUP_DATABASE_SCOPE_KEYS[service]];
         if (!databaseId)
             continue;
+        anyDatabase = true;
         if (executorMissing) {
             blocked.push({
                 description: `platform:backup:${service} is blocked, not planned: the host built the platform executor without its backup dependencies`,
@@ -819,6 +894,33 @@ function planBackups(byKey, claimed, recordedIds, executorMissing) {
             },
         });
     }
+    // #257 fix round 4, point 4: a blocked liveness check is reported instead
+    // of planning the self-heal step -- there is nothing to push until the
+    // read itself works again.
+    if (!executorMissing && storageBlocked && anyDatabase) {
+        blocked.push({ description: storageBlocked, key: 'backup-storage' });
+    }
+    else if (
+    // #257 fix round 2: same "nothing to report yet" gate every other branch
+    // above follows -- a platform with no database yet has no storage to
+    // self-heal either, whatever a stale `storageDrifted` reading says.
+    !executorMissing &&
+        storageDrifted &&
+        anyDatabase) {
+        steps.push({
+            action: {
+                system: 'coolify',
+                kind: 'backup-storage',
+                key: 'platform',
+                desired: {},
+            },
+            step: {
+                description: "self-heal the platform's R2 backup storage registered with Coolify (a rotated credential or a changed bucket/endpoint)",
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
     return { steps, blocked };
 }
 /**

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

@@ -5,6 +5,7 @@ import type { StepAction } from './diff.js';
 import type { CloudflarePort, CoolifyPort, FoundryStepExecutorPorts, ZitadelPort } from './executor.js';
 import type { LiveResource, PlatformCloudflareReader, PlatformCoolifyReader } from './live.js';
 import type { PlatformStepExecutionContext, PlatformStepExecutor } from './plan-apply.js';
+import { type BrokerDeployRecord } from './platform-diff.js';
 import { type CallsSfuPlatformDeps } from './platform-sfu.js';
 /**
  * #168: everything {@link provisionPlatformAuth} needs beyond
@@ -206,6 +207,8 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
     driftedSteps(platform: DeclaredPlatform, recordedIds?: Readonly<Record<string, string>>): Promise<{
         archon?: boolean;
         auth?: boolean;
+        backupStorage?: boolean;
+        backupStorageBlocked?: string;
     }>;
     execute(action: StepAction, context: PlatformStepExecutionContext): Promise<{
         resourceId?: string;
@@ -368,6 +371,40 @@ export declare const PLATFORM_ARCHON_ACCESS_APP_NAME = "foundry:platform:archon"
 export declare const PLATFORM_ZITADEL_ORG_SCOPE_KEY = "zitadel_platform_org";
 /** Archon's OIDC client id: public, not a secret, so a plain scope id. */
 export declare const PLATFORM_ARCHON_CLIENT_ID_SCOPE_KEY = "zitadel_platform_archon_client_id";
+/**
+ * One `AUTH_APPS` entry, read back. Only the fields this step itself reads or
+ * writes are named; every other field `wtfalch/auth/broker/src/apps.ts`'s
+ * `App` knows about (`from`, `productName`, `locale`, `registration`,
+ * `emailLink`) rides along unnamed through the index signature, so merging an
+ * entry (see `provisionPlatformArchon`) never has to know the broker's full
+ * shape to avoid dropping a field it does not itself set.
+ */
+type BrokerAppEntry = Record<string, unknown> & {
+    organizationId: string;
+    key: string;
+    name: string;
+    clientIds: string[];
+    origins: string[];
+};
+/**
+ * One `AUTH_APPS[index]` entry, checked the way
+ * `wtfalch/auth/broker/src/apps.ts`'s own `parseApps`/`parseAppFields`
+ * (https://github.com/wtfalch/auth/blob/main/broker/src/apps.ts) check it at
+ * boot, in the same order: a `key` of at least 32 characters and a non-empty
+ * `organizationId`; a `name` that passes the broker's own `isSafeText` rule
+ * (#218); a `productName`, when present, that is a string and also passes it
+ * (#218); a `from` that passes {@link isValidSenderFrom}; a `locale` of
+ * `'en'` or `'nb'` when present; non-blank `clientIds`; and `origins` each in
+ * {@link isCanonicalOrigin} form. #211 round 2: on a bad
+ * entry this throws naming the broker app id and the entry's index, never
+ * the value -- `key` may hold another organisation's secret, and even
+ * `organizationId`/`name` are not this step's to print in an error only an
+ * operator reads. `entry` may be anything at all (`null`, a string, an
+ * array): every check below is a `typeof`/`Array.isArray` guard first, so a
+ * malformed entry never reaches a property read on a non-object and throws a
+ * `TypeError` instead of this named error.
+ */
+export declare function validateBrokerAppEntry(entry: unknown, brokerAppId: string, index: number): BrokerAppEntry;
 /**
  * #172/#201: mints Archon's own AI management key -- the plain bearer key
  * (`wtfk_...`) `AiOrganisationPort` (`executor.ts`) authenticates with,
@@ -500,6 +537,51 @@ export declare function createAiManagementKeyMinter(options: {
     fetchImpl?: typeof fetch;
     now?: () => number;
 }): AiManagementKeyMinter;
+/**
+ * #211: names of the envs the platform's sign-in broker (`wtfalch/auth`'s
+ * `broker/server.ts`) refuses to start without, that `provisionPlatformAuth`
+ * itself has no way to supply yet -- `ZITADEL_SERVICE_USER_TOKEN`/`_FILE`
+ * (#209 mints and pushes this once it lands) and `RESEND_API_TOKEN` (#210,
+ * blocked on `wtfalch/auth#138`). Read from the broker's own live env, not a
+ * recorded scope id: whichever of #209/#210 lands first (or a human, setting
+ * either directly on the app) is enough to clear that one input, in either
+ * order, with no coupling to this step's own execution.
+ *
+ * #211 round 3: `AUTH_APPS` is a third required input -- the broker's own
+ * `parseApps` refuses to start with no `AUTH_APPS` set or an empty array
+ * (`wtfalch/auth/broker/src/apps.ts`), and this check used to name only the
+ * other two, so a deploy could go ahead with a broker that still would not
+ * come up. Also treat `null`/`undefined` as missing, not only `''`: the
+ * `CoolifyPort.listEnvs` doc comment already warns a live value does not
+ * always match its declared `string` type.
+ */
+export declare function missingBrokerInputs(coolify: Pick<CoolifyPort, 'listEnvs'>, brokerAppId: string): Promise<string[]>;
+/**
+ * #211 round 5: the one rule `provisionPlatformAuth` and
+ * `provisionPlatformArchon` both call to decide whether the broker needs a
+ * (re)deploy -- replacing the two ad hoc "was it ever ostensibly deployed"
+ * booleans each function used to keep, which is what let a recreated broker,
+ * and a crash between writing `AUTH_APPS` and deploying, both go unnoticed
+ * (the round 5 issue text's own diagnosis: "they share one cause"). `false`
+ * while any required input is still missing -- deploying a broker that
+ * cannot start is pointless regardless of what changed. Otherwise `true`
+ * when nothing has ever been recorded, when the broker that was deployed is
+ * a different app (recreated under a new id), or when the `AUTH_APPS` that
+ * was deployed is not the `AUTH_APPS` that is live/about-to-be-live now.
+ * `authAppsRaw` is that exact string -- read live by `provisionPlatformAuth`,
+ * which never writes `AUTH_APPS` itself, or supplied by
+ * `provisionPlatformArchon` as the string it already knows it just wrote (or
+ * left unchanged), so neither caller needs a second read to agree with
+ * itself about what is now true of the app.
+ */
+export declare function brokerDeployNeeded(missingInputs: readonly string[], brokerAppId: string, authAppsRaw: string | undefined, recordedDeploy: BrokerDeployRecord | null): boolean;
+/**
+ * #211 round 5: the {@link BrokerDeployRecord} JSON a successful deploy
+ * writes under {@link PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY} (via each
+ * caller's own `record()`), replacing the plain broker-id string round 2-4
+ * wrote there. Paired with {@link brokerDeployNeeded}, which reads it back.
+ */
+export declare function brokerDeployRecordValue(brokerAppId: string, authAppsRaw: string | undefined): string;
 /**
  * #171: everything {@link provisionPlatformFiles} needs beyond
  * {@link PlatformStepExecutionContext}, bundled for the same reason as
@@ -607,10 +689,21 @@ export declare const INTEGRATIONS_MANAGEMENT_KEY_ID = "foundry-1";
  * 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.
+ * dump, never creates or reads the bucket itself. `raw` carries the S3
+ * storage update call, `PATCH /s3-storages/{uuid}` -- checked against the
+ * same live Coolify 4.3.8 instance `@wtfalch/providers`' own CLAUDE.md
+ * records as the last version this estate verified its `{uuid}` routes
+ * against (that package's own "Known traps": the bundled `openapi.yaml`
+ * omits every one of them, so `routes/api.php`-level comments are what to
+ * trust). `raw` also carries the schedule-repoint call (#257 fix round 3),
+ * `PATCH /databases/{uuid}/backups/{backup_uuid}`, documented in Coolify's
+ * public API reference ("Update database backup") as taking an
+ * `s3_storage_uuid` field. `CoolifyPort` has not wrapped either route with a
+ * typed method, so both go through the same `raw` escape hatch `coolifyApp`'s
+ * own stop/start calls use for a REST route the port has not wrapped yet.
  */
 export interface PlatformBackupDeps {
-    coolify: Pick<CoolifyPort, 'listS3Storages' | 'createS3Storage' | 'listDatabaseBackups' | 'createDatabaseBackup'>;
+    coolify: Pick<CoolifyPort, 'listS3Storages' | 'createS3Storage' | 'listDatabaseBackups' | 'createDatabaseBackup' | 'raw'>;
     r2: {
         endpoint: string;
         bucket: string;